KO ▾

unfilteredaiapi.comhttps://api.unfilteredaiapi.com/v1

Unfiltered AI

개발자를 위한 원시 무검열 LLM API.

Unfiltered AIAPI 키 받기

LLM API 응답이 비어 있는 경우? 원인 및 해결 방법

LLM API 응답이 비어 있는 오류가 발생하면 서버가 응답을 보냈지만, 응답 읽기 방식 때문에 빈 문자열이 반환되는 경우가 대부분입니다. 각 원인이 나타나는 빈도 순으로 체크리스트를 정리했습니다.

빈 말풍선 쪽으로 흐르는 데이터, 렌즈로 숨겨진 가지가 드러나는 모습

주요 포인트

  • 먼저 원시 JSON을 출력하세요. 대부분의 빈 응답은 서비스 중단이 아닌 파싱 문제입니다.
  • finish_reason을 확인하세요: length, stop, tool_calls는 각각 빈 content 필드를 설명합니다.
  • 스트림에서는 delta.content를 방어적으로 읽고 선택지가 없는 청크는 건너뜁니다.
  • 429 오류 또는 SSE를 버퍼링하는 프록시는 일부 클라이언트에서 빈 답변처럼 보일 수 있습니다.

원시 응답부터 확인하세요

설정을 변경하기 전에 반환된 내용을 정확히 캡처하세요. 래퍼 라이브러리는 원인을 숨깁니다. 단순한 print(response.choices[0].message.content)은 본문이 비어 있거나, 도구 호출을 포함하거나, 길이 제한으로 종료되었거나, 도착하지 않은 경우 모두 None 또는 빈 문자열을 표시합니다.

클라이언트 코드가 방해되지 않도록 curl을 사용하고 -i 헤더를 포함하세요:

curl -i https://api.unfilteredaiapi.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [{"role": "user", "content": "Say hello in five words."}]
  }'

결과에서 세 가지를 읽으세요. 첫째, 상태 라인: 200은 완성이 생성되었음을, 429는 제한에 도달했음을, 401과 같은 인증 오류는 일반적으로 키를 가리킵니다. 둘째, choices[0].finish_reason입니다. 셋째, 응답 헤더입니다. 특히 support에 문의할 때 유지해야 할 X-Request-Id와 계정에 크레딧이 남아 있는지 보여주는 X-Balance-USD가 중요합니다. 이 curl 호출이 텍스트를 반환하면 서비스가 정상 작동 중이며 문제는 클라이언트에 있습니다. 오류 본문을 반환하면 이미 원인을 파악한 것입니다.

원인 1: 메시지에 텍스트가 아닌 도구 호출이 포함되어 있음

tools를 전달하고 모델이 함수를 호출하기로 결정하면 어시스턴트 메시지에는 tool_calls가 포함되고 content는 null이거나 비어 있습니다. content만 읽는 코드는 빈 응답을 보게 됩니다. 해결 방법은 먼저 함수 호출 여부를 확인하고, 함수를 실행한 후 결과를 role: "tool" 역할의 메시지로 추가한 뒤 API를 다시 호출하는 것입니다.

from openai import OpenAI

client = OpenAI(base_url="https://api.unfilteredaiapi.com/v1", api_key="YOUR_KEY")

resp = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "What is the weather in Oslo?"}],
    tools=[{
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get current weather for a city",
            "parameters": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        },
    }],
)

msg = resp.choices[0].message
if msg.tool_calls:
    print("tool call:", msg.tool_calls[0].function.name, msg.tool_calls[0].function.arguments)
else:
    print(msg.content)

도구를 제공하려는 의도가 없다면 tools 및 tool_choice 필드를 제거하세요. 이전 실험에서 남은 도구 정의는 빈 텍스트의 흔한 이유입니다.

원인 2: 응답이 잘렸거나 시작되지 않음

finish_reason이 나머지 대부분을 설명합니다.

  • length. 완성이 토큰 제한에 도달했습니다. max_tokens을 1 또는 10과 같이 매우 낮게 설정했을 수 있습니다. 이 파라미터는 선택 사항입니다. 완성은 100,000개의 토큰 창에 남은 것을 사용할 수 있으므로 가장 간단한 해결책은 이를 제거하는 것입니다. 제한이 필요한 경우 여유를 두고 설정하세요.
  • stop. 모델이 정상적으로 종료되었거나 stop 문자열 중 하나를 생성했습니다. 새 줄과 같은 중지 시퀀스는 첫 번째 줄 바꿈에서 응답을 중지하여 모델이 빈 줄로 시작하면 아무것도 남지 않을 수 있습니다. 시퀀스를 제거하거나 느슨하게 설정하세요.
  • tool_calls. 이전 섹션을 참조하세요.

컨텍스트 오버플로는 다른 길이 문제입니다. 창은 프롬프트와 완성을 합쳐 100,000개의 토큰입니다. 대화 기록이 이를 거의 채울 정도로 커졌다면 답변할 공간이 거의 없습니다. 오래된 턴을 줄이거나 요약하세요. 대화 메모리 및 긴 컨텍스트 창 페이지는 기록을 관리하는 방법을 보여줍니다. 요청 본문도 8 MB를 초과할 수 없습니다.

또 다른 작은 함정: JSON 모드. response_format을 json_object로 설정하면 지시에 JSON 단어를 포함하고 원하는 형태를 설명하세요. 모호한 프롬프트와 JSON 모드는 키를 추출하면 비어 보이는 얇거나 피상적인 출력을 생성합니다.

원인 3: 스트림이 잘못 읽힘

SSE를 통한 스트리밍은 많은 작은 청크를 보냅니다. 모든 청크가 텍스트를 포함하지는 않습니다. 첫 번째 청크에는 종종 role만 있고, 마지막 콘텐츠 청크는 빈 delta를 가진 finish_reason을 포함하며, 사용량을 보고하는 마지막 청크는 빈 choices 목록으로 도착할 수 있습니다. 모든 청크에 choices[0]을 인덱싱하는 코드는 충돌하고, 텍스트가 없는 청크를 전체 응답으로 처리하는 코드는 아무것도 출력하지 않습니다.

from openai import OpenAI

client = OpenAI(base_url="https://api.unfilteredaiapi.com/v1", api_key="YOUR_KEY")

stream = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Write two sentences about rain."}],
    stream=True,
)

parts = []
for chunk in stream:
    if not chunk.choices:
        continue
    delta = chunk.choices[0].delta
    if delta.content:
        parts.append(delta.content)

text = "".join(parts)
print(text if text else "[no content received]")

두 가지 환경 문제도 빈 스트림처럼 보입니다. 응답을 버퍼링하는 역방향 프록시 또는 CDN은 모든 청크를 마지막까지 보유하므로 브라우저는 오랫동안 아무것도 보지 않다가 한 번에 모든 것을 보거나, 먼저 타임아웃이 발생합니다. 프록시에서 스트리밍 라우트의 응답 버퍼링을 끄세요. 또한 스트림은 종료될 때까지 동시성 슬롯을 점유하므로, 중단된 스트림(닫힌 탭, 누락된 close())은 8개의 슬롯을 점차 소모합니다. 다음 요청은 텍스트 대신 429를 받습니다. 전체 서버 예제는 SSE 스트리밍이 포함된 FastAPI 백엔드를 참조하세요.

원인 4: 클라이언트가 숨긴 오류

일부 HTTP 래퍼는 200이 아닌 상태에서도 예외를 발생시키지 않고 빈 문자열을 반환합니다. 모든 실패에 대해 상태 코드와 본문을 로깅하세요. 중요한 사례:

상태 또는 코드의미대응 방법
429, rate_limited전용 키의 경우 분당 300개 이상 요청 (시험용은 60개)속도를 줄이고 큐 추가
429, concurrency전용 키의 경우 동시에 8개 이상 요청 (시험용은 2개)작업자 제한
429 및 Retry-After: 5일시적 과부하5초 대기 후 재시도
401일반적으로 누락되거나 잘못된 키Authorization: Bearer 헤더를 확인하세요
404일반적으로 잘못된 경로 또는 Base URLBase URL은 /v1에서 끝나야 합니다.

간단한 재시도 래퍼는 몇 줄로 작성할 수 있으며, 빈 응답의 전체 클래스를 제거합니다:

import time
from openai import OpenAI, RateLimitError

client = OpenAI(base_url="https://api.unfilteredaiapi.com/v1", api_key="YOUR_KEY")

def ask(messages, tries=4):
    for attempt in range(tries):
        try:
            r = client.chat.completions.create(model="uncensored", messages=messages)
            return r.choices[0].message.content or ""
        except RateLimitError as e:
            wait = 5
            retry_after = getattr(e.response, "headers", {}).get("retry-after")
            if retry_after:
                wait = int(retry_after)
            time.sleep(wait)
    raise RuntimeError("still limited after retries")

실패하거나 거부된 요청에는 요금이 부과되지 않으므로 재시도 루프로 인해 중복으로 비용이 발생하지 않습니다. 실패한 호출 전후의 X-Balance-USD을 비교하여 확인할 수 있습니다.

원인 5: 잘못된 엔드포인트, 모델 또는 키

심각한 오류가 아닌 이상한 결과를 생성하는 구성 실수의 짧은 체크리스트:

  1. Base URL은 https://api.unfilteredaiapi.com/v1입니다. /v1이 누락되거나 중복되면 관대한 클라이언트가 빈 응답으로 변환할 수 있는 404 본문을 제공할 수 있습니다.
  2. 모델 이름은 uncensored이며 철자가 정확해야 합니다. 다른 제공업체의 카탈로그에서 모델을 설정하는 것은 흔한 복사-붙여넣기 실수입니다.
  3. POST /v1/chat/completions와 GET /v1/models만 존재합니다. 레거시 완료 엔드포인트, 임베딩 및 이미지 경로는 사용할 수 없으므로 해당 엔드포인트를 호출하는 라이브러리는 유용한 결과를 얻지 못합니다.
  4. 키는 Bearer 토큰으로 전송되며 env 파일의 여분 공백이나 따옴표가 없습니다.

연결성 테스트로 GET /v1/models를 키와 함께 호출하세요. 모델이 나열되면 Base URL과 키가 정확하며 문제는 요청 본문에 있습니다. 빠른 시작에는 비교할 최소 작동 요청이 포함되어 있고, 자주 묻는 질문에는 접근, 제한 및 청구 정보가 포함되어 있습니다.

다음 사고를 줄이는 로깅

이후에 빈 응답을 디버깅하기 어려운 이유는 서버가 무엇을 보냈는지 아무도 기록하지 않았기 때문입니다. 몇 줄의 로깅으로 미스터리가 명확한 원인으로 바뀝니다.

  1. 성공 여부와 상관없이 모든 호출에 대해 X-Request-Id 응답 헤더를 로깅하세요.
  2. finish_reason, usage 카운트 및 반환된 텍스트의 길이를 로깅하세요.
  3. 스트리밍의 경우, 도착한 청크 수와 텍스트를 포함한 청크 수를 로깅하세요. 텍스트를 포함한 청크가 0개이고 정상적으로 종료된 경우 파서 문제를 의미합니다. 청크가 전혀 없는 경우 네트워크 또는 프록시 문제를 의미합니다.
  4. 단일 이벤트가 아닌 빈 응답과 총 호출의 비율에 대해 알림을 설정하세요. 1,000개 중 1개의 빈 응답은 노이즈입니다. 5%는 버그입니다.

실패한 호출과 성공한 호출을 비교할 때, 먼저 요청 본문의 diff를 확인하세요. 변경된 시스템 프롬프트, 추가된 stop 목록, 줄어든 max_tokens 또는 교체된 모델 이름이 대부분의 회귀 원인을 설명합니다. 개인 데이터를 제거한 후 요청 본문을 로그에 저장하세요.

여러 사용자가 동시에 빈 응답을 보고하고 curl 테스트도 실패하는 경우, 원인은 코드가 아닐 가능성이 높습니다. 일시적 과부하가 이 방식으로 신호를 보내므로 먼저 Retry-After가 있는 429 응답을 확인하고 명시된 지연 시간 후에 재시도하세요. curl 테스트가 성공하고 앱이 실패하는 경우, 위의 섹션을 사용하여 클라이언트 측에서 작업하세요.

응답이 비어있는 것이 아니라 짧은 경우

때로는 원하는 페이지 대신 한 줄짜리 답변을 받을 수 있습니다. 이는 전송 문제보다 프롬프트 문제입니다. 원하는 길이와 형식("최소 400단어, 3개 단락")을 요청하고, 지시사항을 시스템 메시지에 넣으세요. 모델이 간결하게 응답한다면 temperature을 약간 높여보세요. 모델은 합법적인 성인 사용에 대해 콘텐츠 거부 없이 응답하도록 조정되었으므로, 짧은 응답은 거부가 아니라 요청이 불충분한 경우가 많습니다. 미성년자를 포함한 성 콘텐츠는 유일한 하드 리밋이며 항상 거부됩니다.

여전히 문제가 해결되지 않나요? 실패한 응답의 X-Request-Id, 대략적인 시간, 그리고 키가 제거된 요청 본문을 지원팀에 보내세요. 그러면 해당 호출을 정확히 찾을 수 있습니다. 서비스를 처음 사용한다면 키 페이지에서 체험 크레딧을 청구할 수 있으며, 이는 수십 번의 디버깅 호출에 충분한 양입니다.

질문과 답변

message.content이 null인 이유는 무엇입니까?

대부분의 경우 모델이 텍스트 대신 tool_calls를 반환했거나 스트림이 잘못 읽혔습니다. 오류로 처리하기 전에 메시지에서의 finish_reason과 tool_calls를 확인하세요.

빈 응답에도 비용이 발생합니까?

실패하거나 거부된 요청에는 요금이 부과되지 않습니다. 호출이 성공하고 토큰이 생성된 경우 사용량 카운트를 확인할 수 있으며, 헤더의 X-Balance-USD를 통해 잔액을 확인할 수 있습니다.

전체 컨텍스트 창이 빈 출력을 유발할 수 있습니까?

네. 프롬프트와 응답은 100,000개의 토큰을 공유하므로, 거의 가득 찬 대화 기록은 응답에 거의 또는 전혀 여유 공간을 남기지 않습니다. 이전 턴을 줄이거나 요약하세요.

스트림이 아무것도 표시되지 않다가 한 번에 모든 것이 표시되는 이유는 무엇입니까?

프록시 또는 CDN이 SSE 응답을 버퍼링하고 있을 가능성이 높습니다. 해당 라우트에 대해 버퍼링을 비활성화하여 청크가 도착하는 대로 통과되도록 하세요.

키는 양식 하나만 작성하면 받을 수 있습니다

계정을 생성하고 키를 복사한 후 기본 URL을 변경하세요. 설정은 이것으로 끝입니다.

API 키 받기문서 읽기