컨텍스트 창 초과란?
model_context_window_exceeded 문자열은 일부 클라이언트, SDK 및 API가 특정 실패를 표시하는 방식입니다: 전송한 텍스트와 답변에 필요한 공간이 한 번의 요청에 모델이 처리할 수 있는 크기보다 큽니다. 도구마다 메시지 문구가 다르므로 이름에 의존하기보다 클라이언트가 표시하는 전체 오류 본문을 읽으세요. 원인은 항상 동일합니다.
이 API에서 컨텍스트 창은 프롬프트와 응답을 합쳐 100,000 토큰입니다. 프롬프트가 95,000 토큰을 사용하면 응답에 남는 것은 약 5,000 토큰입니다. max_tokens를 8,000으로 설정하면 창이 허용하는 것보다 많은 토큰을 요청하게 됩니다. max_tokens 필드는 선택 사항이며, 이를 생략하면 응답은 남은 공간을 모두 사용합니다.
이렇게 실패하는 요청은 응답 대신 오류를 반환합니다. 실패한 요청에는 요금이 청구되지 않으므로 한도에 도달해도 왕복 통신 비용만 발생합니다. 해결책은 사용자 측에 있습니다: 더 적은 데이터를 보내거나 더 적은 양을 요청하세요.
100,000 토큰은 얼마나 큰가요?
토큰은 텍스트의 일부분으로, 짧은 단어 또는 긴 단어의 일부인 경우가 많습니다. 일반적인 영어 문장에서는 대략 4자당 1개의 토큰, 또는 단어의 약 3/4에 해당하는 양이 토큰으로 간주됩니다. 이 규칙에 따르면 100,000개의 토큰은 약 75,000단어에 해당하며, 이는 분량이 많은 소설 수준입니다. 코드, JSON, 표 및 비영어권 텍스트는 문자당 더 많은 토큰으로 분할되므로, 동일한 문자 수라도 토큰 수는 훨씬 커질 수 있습니다. 이러한 경험칙은 보증을 위한 것이 아니라 계획을 세우기 위한 참고 수치로 여겨야 합니다.
정확한 토큰 수는 모델 자체의 토크나이저에서 결정됩니다. API는 응답에서 실제 사용량을 보고합니다: usage 객체는 프롬프트 및 완료 토큰을 나열하며, 스트리밍 응답의 경우 사용량 정보가 마지막에 전송됩니다. 이것이 가장 신뢰할 수 있는 데이터이므로 반드시 로그에 기록해야 합니다.
| 콘텐츠 | 대략적인 크기 |
|---|---|
| 두 문장의 채팅 메시지 | 40~60 토큰 |
| 영어 텍스트 1페이지 (500단어) | 약 670 토큰 |
| 10,000단어 문서 | 약 13,000 토큰 |
| 3 MB JSON 덤프 | 종종 100,000개 토큰을 초과하여 원본 그대로 전송하기에는 너무 큽니다. |
요청 본문에는 토큰 제한과 별개로 8 MB의 크기 제한도 있습니다. 큰 입력은 둘 중 하나에서 실패할 수 있으며, 토큰 제한이 거의 항상 먼저 도달하는 제한입니다.
채팅 앱이 제한에 부딪히는 이유
API는 호출 간에 메모리를 유지하지 않습니다. 대화를 계속하려면 코드에서 매번 전체 메시지 목록을 전송합니다. 각 턴마다 사용자 메시지와 응답이 추가되므로 프롬프트는 모든 교환마다 커집니다. 1시간 동안 잘 작동하다가 실패하기 시작하는 봇은 전형적인 징후입니다.
에이전트에서도 같은 일이 발생합니다. 모든 도구 결과는 기록에 추가되며, 하나의 함수가 큰 레코드를 반환하면 한 단계에서 수천 토큰이 추가될 수 있습니다. 검색 설정은 세 번째 원인을 추가합니다: 프롬프트에 20개의 문서 청크를 붙여 넣으면 기존 기록이 없어도 요청당 기본 비용이 이미 큽니다.
무언가를 수정하기 전에 세 가지 중 무엇이 증가하고 있는지 파악해야 합니다. 각 호출 후 usage에서 프롬프트 토큰 수를 출력하세요. 각 턴마다 거의 동일한 양만큼 증가한다면 이는 대화 기록(history)입니다. 특정 단계 이후에 급증한다면 이는 도구 출력(tool output) 또는 검색된 텍스트입니다.
전송 전에 기록을 줄이세요
가장 간단하고 신뢰할 수 있는 해결 방법은 오래된 턴을 제거하여 추정치가 예산에 맞을 때까지 하는 함수입니다. 시스템 메시지는 항상 유지하고 최신 사용자 메시지도 항상 유지하세요. 예산은 응답을 위한 공간을 남겨야 하므로 프롬프트에 80,000 토큰을 사용하고 나머지는 응답 공간으로 두세요.
from openai import OpenAI
client = OpenAI(
base_url="https://api.uncensoredmodelhub.com/v1",
api_key="YOUR_API_KEY",
)
def estimate_tokens(text: str) -> int:
return len(text) // 4 + 4 # rough: 4 characters per token plus overhead
def trim(messages, budget=80_000):
system = [m for m in messages if m["role"] == "system"]
rest = [m for m in messages if m["role"] not in ("system",)]
total = sum(estimate_tokens(m["content"]) for m in system + rest)
while total > budget and len(rest) > 1:
dropped = rest.pop(0) # oldest turn goes first
total -= estimate_tokens(dropped["content"])
return system + rest
history = [{"role": "system", "content": "You are a helpful assistant."}]
def ask(user_text):
history.append({"role": "user", "content": user_text})
resp = client.chat.completions.create(
model="uncensored",
messages=trim(history),
max_tokens=2000,
)
reply = resp.choices[0].message.content
history.append({"role": "assistant", "content": reply})
print(resp.usage.prompt_tokens, resp.usage.completion_tokens)
return reply
가능하면 사용자 및 어시스턴트 턴을 쌍으로 유지하세요. 쌍의 한 쪽만 제거하면 모델이 혼란스러워할 수 있습니다. 도구 메시지도 비슷합니다: role: "tool" 메시지는 해당 요청을 보낸 어시스턴트 턴과 함께 유지되어야 하므로 함께 제거하세요. 추정치가 대략적이므로 예산과 실제 창 사이에 20%의 여유를 두면 안전한 마진이 됩니다.
오래된 턴 제거보다 나은 옵션
요약 후 계속하기
기록이 임계값을 넘으면 가장 오래된 절반을 모델에 보내 수백 단어로 요약하라는 지시를 내린 후, 해당 턴을 요약문으로 시스템 또는 사용자 메시지로 교체하세요. 세부 정보는 손실되지만 대화 흐름은 유지됩니다. 이 단계를 실시간 응답 경로 외부에서 실행하여 사용자가 기다리지 않도록 하세요.
유지해야 할 사실 고정하기
이름, 결정 및 설정과 같은 지속적인 메모 블록을 유지하고 모든 요청의 맨 위에 다시 삽입하세요. 오래된 턴이 여전히 표시될 것으로 기대하는 것보다 더 잘 작동합니다.
투입량 축소하기
도구 결과를 중요한 필드로 잘라내세요. 더 적은 청크를 검색하고 각각을 관련 단락으로 자르세요. 매우 긴 문서의 경우 부분을 나누어 각 부분을 처리한 후 최종 짧은 호출에서 결과를 결합하세요.
max_tokens 의도적으로 설정하기
답변이 일반적으로 짧은 경우 제품과 맞는 값에 max_tokens을 설정하세요. 상한선은 예산을 보호하지만 너무 낮은 상한선은 문장 중간에 응답을 잘라내므로 먼저 로그에서 실제 답변 길이를 확인하세요.
줄이면 비용도 절약됩니다
입력 토큰은 100만 토큰당 $0.15, 출력 토큰은 100만 토큰당 $0.50이며 선불 크레딧에서 청구됩니다. 채팅은 기록을 다시 전송하므로 대화당 비용은 길이보다 빠르게 증가합니다. 각 교환마다 기록에 500 토큰을 추가하는 채팅을 고려해 보세요. 대화는 100 턴 동안 실행됩니다.
- 줄이지 않으면 n번째 턴은 500 x n 토큰을 전송합니다. 100 턴의 합계는 500 x 5,050 = 2,525,000 입력 토큰이며, 이는 2.525 x $0.15 = $0.379의 비용이 듭니다.
- 20,000개 토큰의 제한이 있는 경우, 처음 40번의 턴은 동일합니다(500 x 820 = 410,000개 토큰). 나머지 60번의 턴은 각각 20,000개씩 전송하므로 총 1,200,000개입니다. 총합은 1,610,000개 토큰이며, 이는 1.61 x $0.15 = $0.242에 해당합니다.
이 제한으로 인해 약 3분의 1을 절약할 수 있으며, 채팅 길이가 길어질수록 그 차이는 더 벌어집니다. 극단적인 경우, 100,000개 토큰의 프롬프트는 요청당 0.1 x $0.15 = $0.015의 비용이 듭니다. 이는 자체적으로는 저렴하지만, 다수의 사용자를 처리하는 봇에서는 비용이 누적됩니다. 가격 책정 세부 사항과 충전 보너스는 가격 페이지에 있습니다. 크레딧은 만료되지 않습니다.
코드에서 오류 처리하기
줄이더라도 실패를 대비하세요. API 오류를 캐치하고 메시지가 컨텍스트 길이를 가리키는지 확인한 후 요청을 축소하고 한 번 재시도하세요. 동일한 요청을 다시 시도하지 마세요. 같은 방식으로 실패할 것입니다.
from openai import BadRequestError
def safe_ask(messages, budget=80_000):
try:
return client.chat.completions.create(
model="uncensored", messages=trim(messages, budget)
)
except BadRequestError as err:
if "context" in str(err).lower() and budget > 10_000:
return safe_ask(messages, budget // 2)
raise
클라이언트가 크기가 너무 큰 요청으로 받는 실제 상태 코드와 메시지를 확인하고 테스트를 조정하세요. 위의 문자열 매칭은 시작점일 뿐입니다. 속도 제한은 별개입니다: HTTP 429 응답에서 rate_limited 또는 concurrency은 토큰이 아닌 요청 수가 많음을 의미하며, 429 응답에 Retry-After: 5가 포함되면 일시적인 과부하 상태입니다. 문서에는 요청 필드 목록이, 무검열 모델 설명에는 모델의 정의가 나와 있으며, 실제 사용량 수치를 통해 이를 테스트하려면 API 키를 발급받으세요.
