refs #749: compare HMM Select AI annotation profiles

docs/design/749-hmm-select-ai-no-annotation-profile/troubleshooting.md

@@ -0,0 +1,46 @@
+# 문제 해결
+
+[개요](README.md) · [비교 설계](architecture.md) · [실행 절차](cookbook.md) · [측정 결과](results.md)
+
+## 원본 프로파일이 없거나 소유자가 다름
+
+**증상**: `HMM_HR_DATA_GPT54_PROFILE` 조회 결과가 없거나 `CREATE_PROFILE` 권한 오류가 발생한다.
+
+**원인**: 다른 DB 또는 다른 사용자로 접속했거나 프로파일 소유자가 ADMIN이 아니다.
+
+**확인**: `DBA_CLOUD_AI_PROFILES`에서 owner와 profile name을 확인한다.
+
+**해결**: HMM ADB 지갑·service alias와 ADMIN 연결을 다시 확인한다. 이름이 비슷한 프로파일을 임의로
+대체하지 않는다.
+
+## 비교 프로파일이 이미 있지만 속성이 다름
+
+**증상**: 비교 프로파일은 존재하지만 모델, object list, temperature 또는 annotations 값이 설계와 다르다.
+
+**원인**: 이전 실험의 프로파일이 같은 이름으로 남아 있다.
+
+**확인**: `DBA_CLOUD_AI_PROFILE_ATTRIBUTES`에서 두 프로파일을 나란히 비교한다.
+
+**해결**: 기존 비교 프로파일을 덮어쓰지 않는다. 먼저 disable하고 이력·의존성을 확인한 뒤 새 버전
+이름을 사용하거나 별도 승인으로 정리한다.
+
+## 호출이 간헐적으로 실패하거나 시간이 크게 흔들림
+
+**증상**: 같은 프로파일에서도 회차별 `showsql` 시간이 크게 다르거나 LLM 오류가 발생한다.
+
+**원인**: 모델 endpoint 부하, 첫 호출 metadata cache, 생성형 SQL의 비결정성일 수 있다.
+
+**확인**: 두 프로파일을 번갈아 호출했는지, 각 3회 이상 결과가 있는지, 오류 코드가 프로파일 설정
+오류인지 외부 모델 오류인지 구분한다.
+
+**해결**: 실패 회차를 숨기지 않고 기록한다. 같은 조건으로 추가 회차를 실행하고 평균뿐 아니라
+중앙값·최솟값·최댓값을 함께 비교한다.
+
+## 한국어 질문이 깨져 SQL 품질이 달라짐
+
+**증상**: 질문의 한글이 깨지거나 관련 없는 SQL이 생성된다.
+
+**원인**: SQLcl을 통해 한국어 literal을 직접 전달했다.
+
+**해결**: UTF-8 질문을 Base64 ASCII로 전달하고 Oracle에서 `UTL_I18N.RAW_TO_CHAR`로 복원한다.
+직접 SQL string 또는 `q'[...]'`를 사용하지 않는다.