자주 겪는 문제 & 해결 (실전 노트)
OpenAI 호환 LLM 위에 서비스를 만들 때 실제로 부딪히는 문제들과 해결책을 정리했습니다. 대부분 범용적으로 통하는 이슈라, 다른 스택에서도 그대로 적용됩니다.
인증 · 접근
| 증상 | 원인 | 해결 |
|---|---|---|
401 / 403 |
키 없음·무효·만료 | Authorization: Bearer <key> 확인. 키를 환경변수로 주입 |
로컬은 되는데 배포하면 403 |
배포 환경에 키 미주입 | 시크릿 매니저/.env로 주입. 프론트엔드에 키 넣지 말 것 |
429 Too Many Requests |
분당 요청(RPM)·토큰(TPM) 한도 초과 | 지수 백오프 재시도 + 요청 배치 · 한도 상향 요청 |
모델 · 응답
| 증상 | 원인 | 해결 |
|---|---|---|
404 model not found |
모델 id 오타·미서빙 | GET /v1/models로 실제 id 확인 |
503 간헐 |
백엔드 모델 일시 불가·재기동 | 재시도(백오프) + 헬스 기반 폴백 모델 |
| 응답이 중간에 잘림 | max_tokens 부족 · finish_reason: length |
max_tokens 상향 · 응답에서 finish_reason 확인 |
| 답이 근거를 무시하고 지어냄 | 컨텍스트 미주입·프롬프트 약함 | 근거를 프롬프트에 명시 + "근거에 없으면 모른다고 답하라" 지시 |
스트리밍
- 프록시/게이트웨이에서 스트림이 안 나오고 한 번에 옴 → 중간 계층의 버퍼링 때문. 프록시에서
Content-Type: text/event-stream패스스루 + 버퍼링 비활성(X-Accel-Buffering: no,flush). - SDK 스트림 파싱:
data: [DONE]종료 신호와 빈delta조각을 건너뛰세요.
도구 호출 (function calling)
- 모델이 도구를 안 부르고 일반 답을 함(
used_tool: false) → 일부 서빙 설정은 네이티브 tool-calling이 꺼져 있음. 서버에서 tool-choice 파서를 켜야 하거나(관리자), 프롬프트 기반 ReAct 폴백을 쓰세요 (모델에게TOOL: name({json})형식으로 요청하게 하고, 앱이 파싱·실행·결과 주입). - 자세히: 도구 호출 가이드.
다국어 (한국어) 함정
- 추론(reasoning) 모델의 사고 과정이 영어/중국어로 샌다 — 증류형 추론 모델은 지시해도 내부 사고를 EN/ZH로 하는 경향이 있습니다. 최종 답변 생성은 별도(작성용) 모델로 하고, 사고 원문은 사용자에게 그대로 노출하지 마세요. 자세히: 다국어 가이드.
설정 파일 (YAML) 함정
off/on/yes/no가 boolean으로 파싱됨 (YAML 1.1). 예:safetyMode: off→False. 문자열이어야 하면 따옴표로:safetyMode: "off".- 문자열 안의
콜론+공백(:) 이 매핑으로 오인됨 → 그 값을 따옴표로 감싸세요. - 버전은 문자열로:
version: "1.0.0"(숫자로 파싱되면1.0이 될 수 있음).
생성 코드 재생성 시 내 코드가 사라짐
- 코드 생성기를 쓴다면 생성 영역과 사용자 영역을 분리하세요 (
src/generated/vssrc/extensions/). 재생성은 생성 영역만 덮어쓰고 사용자 영역은 보존. 진실원천은 스펙(AppSpec) 하나로.
임베딩 · RAG 품질
- 청크가 너무 크면 관련 없는 내용까지 섞여 검색 정밀도 하락 → 문단/문장 경계로 400~800자 권장.
- 임베딩만으론 순위가 부정확 → 임베딩 top-N 후 리랭커로 재정렬(2단계). 자세히: RAG 가이드.
문제가 계속되면 FAQ와 프로덕션 체크리스트도 참고하세요.