핵심 요약
- Context windows combine prompt and completion, so long histories drain limits faster than expected.
- 스트리밍은 손상된 JSON 또는 손실된 토큰을 피하기 위해 SSE 이벤트를 신중하게 처리해야 합니다.
- JSON mode demands strict schema adherence; malformed responses cause silent parsing failures.
- 선불형 암호화폐 과금 방식에서는 오류가 무료이지만, 예기치 않은 상황을 피하려면 토큰 카운팅이 정확해야 합니다.
API 키가 거부될 수 있는 이유
API 키는 클라이언트가 잘못된 형식의 헤더를 보내거나 요청 본문 한도를 초과할 때 거부됩니다. 서버는 모든 로직을 처리하기 전에 인증 헤더를 검증합니다. 헤더가 누락되거나 불필요한 공백이 포함되어 있으면 요청이 즉시 실패합니다.
다른 일반적인 원인은 8MB 본문 크기 제한을 초과하는 페이로드를 전송하는 것입니다. 많은 메시지를 포함하는 큰 컨텍스트 윈도우는 이 임계값을 쉽게 초과할 수 있습니다. 전송하기 전에 메시지 배열 길이와 토큰 수를 확인하세요.
- Authorization 헤더에 'Bearer' 접두어가 올바르게 사용되었는지 확인하세요.
- Verify the request body size stays under 8 MB.
- API 키가 활성화되어 있고 만료되지 않았는지 확인합니다.
컨텍스트 윈도우 제한 이해하기
컨텍스트 윈도우는 입력 프롬프트와 생성된 응답을 모두 포함합니다. 당사 API는 100,000 토큰의 윈도우를 지원하지만, 양쪽을 모두 고려해야 합니다. 컨텍스트로 80,000 토큰을 전송하면 응답에 사용할 수 있는 토큰은 20,000개만 남습니다.
지정하지 않으면 대부분의 모델은 작은 출력 제한을 기본값으로 사용합니다. max_tokens 이 긴 답변을 예상치 못하게 잘라낼 수 있습니다. 잘림을 방지하려면 max_tokens 을 원하는 길이로 설정하세요. 이 제한은 프롬프트뿐만 아니라 전체 요청에 적용된다는 점을 기억하세요.
스트리밍 중단 처리
서버 전송 이벤트(SSE)를 통한 스트리밍은 강력한 오류 처리가 필요합니다. 연결이 끊기면 마지막 토큰이나 사용량 메타데이터를 잃을 수 있습니다. 항상 들어오는 청크를 버퍼링하고 클라이언트 측에서 전체 응답을 복원하세요.
토큰 사용 데이터는 일반적으로 스트림의 마지막 청크에 전송됩니다. 연결을 조기에 종료하면 정확한 토큰 수를 놓칠 수 있습니다. 이는 선불 시스템의 청구 정확도에 영향을 미칩니다. 일시적인 네트워크 문제를 처리하기 위해 지수 백오프(retry mechanism with exponential backoff) 재시도 메커니즘을 구현하세요.
SSE 파싱을 자동으로 처리하는 전용 스트리밍 클라이언트를 사용하세요. 이렇게 하면 파싱 오류의 위험을 줄이고 모든 데이터를 캡처할 수 있습니다.
JSON 모드 구문 분석 오류
response_format: {"type": "json_object"}를 사용할 때, 모델은 유효한 JSON을 반환해야 합니다. 이 규칙에서 벗어나면 애플리케이션에서 파싱 오류가 발생할 수 있습니다. 프롬프트에서 모델이 JSON만 출력하도록 명시적으로 지시해야 합니다.
때때로 모델은 JSON 주변에 마크다운 코드 블록을 포함하는데, 이는 엄격한 파서를 깨뜨립니다. 구문 분석 전에 래퍼를 제거하세요. 또한 데이터를 사용하기 전에 클라이언트 측에서 JSON 구조를 검증하세요.
스키마 검증 라이브러리를 사용하여 오류를 조기에 포착하세요. 이는 모델이 예상치 못한 키나 타입을 반환할 때 충돌이 발생하는 것을 방지합니다.
토큰 계산 및 청구 관련 놀라움
선불 요금제는 실제 토큰 사용량에 대해서만 요금이 부과됩니다. 오류 및 거절은 무료이므로 구독 모델에 비해 큰 장점이 있습니다. 그러나 전체 컨텍스트를 고려하지 않으면 토큰 카운팅이 까다로울 수 있습니다.
대화 기록의 각 메시지는 입력 토큰 제한에 포함됩니다. 긴 대화는 예상보다 빠르게 선불 크레딧을 소모합니다. 세션 중 크레딧이 부족해지는 것을 방지하려면 사용량을 정기적으로 모니터링하세요.
낮은 크레딧 잔액에 대한 알림을 설정하세요. 이렇게 하면 요청이 실패하기 전에 충전할 수 있습니다. 크레딧은 만료되지 않으므로 언제든지 편리할 때 충전할 수 있습니다.
NSFW 프롬프트에서 부드러운 거부 피하기
소프트 리퓨절은 모델이 망설이거나 직접적인 답변 대신 부분적인 답변을 제공할 때 발생합니다. 이는 종종 논쟁적이거나 성인 관련 주제에서 일어납니다. 검열 없는 모델에서도 특정 트리거가 망설임을 유발할 수 있습니다.
temperature 매개변수를 조정하여 무작위성을 줄이세요. 낮은 온도는 모델을 더 결정론적으로 만들고, 모호하게 답변할 가능성을 줄입니다. 또한 프롬프트를 명확하고 직접적으로 작성하세요. 모델이 혼란스러워할 수 있는 모호한 언어를 피하세요.
소프트 거부가 자주 발생한다면 프롬프트를 조금 다르게 표현해 보세요. 문구를 약간 바꾸는 것만으로도 망설임을 넘어 직접적인 답변을 얻을 수 있는 경우가 많습니다.
Rate limit spikes and backoff strategies
API는 분당 300회 요청과 키당 8개의 동시 요청을 허용합니다. 트래픽 급증 시 이러한 제한에 빠르게 도달할 수 있으므로, 지수 백오프를 구현하여 속도 제한 오류를 우아하게 처리하세요.
429 상태 코드를 받으면 재시도하기 전에 기다리세요. 짧은 지연 시간으로 시작하고, 각 재시도마다 지연 시간을 늘리세요. 이렇게 하면 피크 시간 동안 서버가 과부하되는 것을 방지할 수 있습니다.
요청률을 모니터링하고 이에 따라 동시성 수준을 조정하세요. 많은 동시 요청을 보내고 있다면, 시간이 지나도록 요청을 분산하는 것을 고려하세요. 이렇게 하면 한계에 도달하지 않고도 안정적인 처리량을 보장할 수 있습니다.
함수 호출 페이로드 구조
함수 호출은 특정 페이로드 구조를 필요로 합니다. tools 매개변수에서 함수를 정의하고 tool_choice를 지정하세요. 모델은 적절한 응답이라고 판단할 경우 함수 호출을 반환합니다.
함수 정의가 정확하고 완전한지 확인하세요. 매개변수가 누락되거나 유형이 잘못되면 모델이 잘못된 호출을 생성할 수 있습니다. 실행하기 전에 항상 함수 호출 인수를 검증하세요.
tool_choice 매개변수를 사용하여 모델이 함수를 호출할 시기를 제어하세요. 함수 호출을 강제하거나, 모델이 결정하도록 하거나, 함수 호출을 완전히 비활성화할 수 있습니다. 이를 통해 모델의 동작을 세밀하게 제어할 수 있습니다.
400 및 500 오류 디버깅
400 오류는 유효하지 않은 JSON이나 누락된 매개변수 등 클라이언트 측 문제를 나타냅니다. 500 오류는 내부 오류나 타임아웃 등 서버 측 문제를 시사합니다. 두 오류를 구분하면 디버깅 속도를 높일 수 있습니다.
400 오류의 경우, 응답에 제공된 오류 메시지를 확인하세요. 일반적으로 해당 메시지가 문제의 원인을 직접적으로 가리킵니다. 500 오류의 경우, 짧은 지연 후 요청을 다시 시도하세요. 오류가 지속되면 요청 ID와 함께 지원팀에 문의하세요.
각 오류에 대한 요청 및 응답 세부 정보를 모두 로깅하세요. 이는 패턴과 반복되는 문제를 식별하는 데 도움이 됩니다. 로깅 서비스를 사용하여 시간이 지남에 따라 오류를 추적하고 API 통합을 개선하세요.
