> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 추론 모델이 빈 콘텐츠를 반환하는 이유는 무엇입니까?

> empty_response가 반환되거나, HTTP 200과 함께 텍스트가 비어 있습니까? 일반적으로 max_tokens가 thinking에 소진된 경우입니다. 세 가지 확인 사항과 세 가지 해결 방법을 살펴봅니다.

## 짧은 답변

이는 API 오류가 아닙니다. **추론 예산이 출력 예산을 소진하는 것**입니다.

`gpt-6.1-sol`와 같은 추론 모델은 먼저 추론 추적을 생성한 다음 답변을 작성합니다. 두 부분 모두 `max_tokens` 허용량을 **공유**합니다. 생각하는 동안 예산이 소진되면 답변을 시작하기도 전에 잘리므로 빈 결과를 받게 됩니다.

`max_tokens`를 높이거나(1000 이상부터 시작하는 것이 안전합니다) 추론 강도를 낮추면 문제가 해결됩니다.

## 확인하게 될 내용

일반적으로 두 가지 형태가 있습니다.

**하나는 명시적인 오류**이며, HTTP 상태 코드는 429 또는 500입니다(`message` 필드는 지역화될 수 있으므로 일부 응답에서는 중국어 메시지가 표시될 수 있습니다).

```json theme={null}
{
  "error": {
    "message": "上游返回了空响应。",
    "type": "shell_api_error",
    "code": "empty_response"
  }
}
```

**다른 하나는 콘텐츠가 비어 있는 HTTP 200 응답**입니다.

```json theme={null}
{
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "" },
      "finish_reason": "length"
    }
  ],
  "usage": {
    "prompt_tokens": 1500,
    "completion_tokens": 300,
    "completion_tokens_details": { "reasoning_tokens": 300, "text_tokens": 0 }
  }
}
```

사용량 블록을 확인해 보십시오. `completion_tokens`은 300이고, `reasoning_tokens`은 300이며, `text_tokens`은 0입니다. — **모델이 300개의 token을 생성하고, 모두 사고에 사용했으며, 출력 단어는 단 하나도 작성하지 않았습니다.**

> [!NOTE]
>
> 호출 로그에는 요청이 성공했고 과금되었다고 표시되며, 이는 모순이 아닙니다. 모델은 콘텐츠(추론 트레이스)를 실제로 생성했지만, 표시되는 텍스트는 생성하지 않았기 때문입니다.

## 이 문제가 발생하는 이유

추론 모델의 출력에는 두 단계가 있습니다.

| 단계 | 내용 | 반환되는 내용 |
| - | - | - |
| 사고 | 추론 token, 내부 숙고 | 일부 모델에서는 `reasoning_content`로 노출되며, 일반적으로 표시되지 않음 |
| 답변 | 텍스트 token, 사용자에게 표시되는 출력 | 예 |

`max_tokens`(또는 `max_completion_tokens`, `max_output_tokens`)은 표시되는 답변의 길이가 아니라 **두 단계를 합한 길이**를 제한합니다.

따라서 `max_tokens`가 200\~500처럼 작은 값으로 설정되어 있고 작업에 상당한 추론이 필요한 경우, 사고 단계에서 쿼터가 소진됩니다. 그러면 `finish_reason`는 `length`이 되고 콘텐츠는 비어 있게 됩니다.

## 세 가지 확인

**1. 1단계: finish\_reason 읽기**

값이 `length`이면 출력이 잘린 것입니다. 모델이 답변을 거부한 것이 아닙니다. 값이 `stop`인데 콘텐츠가 여전히 비어 있으면 2단계와 3단계를 계속 진행합니다.

**2. 2단계: usage에서 reasoning\_tokens 읽기**

`usage.completion_tokens_details.reasoning_tokens`을 찾아 `completion_tokens`와 비교합니다. 두 값이 비슷하거나 같으면 대부분의 예산이 사고에 사용된 것입니다.

**3. 3단계: 요청에서 max\_tokens 읽기**

`max_tokens`를 작은 값(예: 300)으로 명시적으로 설정했다면 이것이 원인일 가능성이 매우 높습니다. 설정하지 않았다면 SDK 또는 프레임워크가 작은 기본값을 입력했는지 확인합니다.

이 스크립트는 세 가지 신호를 한 번에 출력합니다.

```python theme={null}
import json
from openai import OpenAI

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

resp = client.chat.completions.create(
    model="gpt-6.1-sol",
    messages=[{"role": "user", "content": "your question"}],
    max_tokens=2000,
)

choice = resp.choices[0]
usage = resp.usage
print("finish_reason:", choice.finish_reason)
print("content:", repr(choice.message.content)[:100])
print("completion_tokens:", usage.completion_tokens)
print("reasoning_tokens:", getattr(usage.completion_tokens_details, "reasoning_tokens", None))
```

## 수정 방법

> [card] max\_tokens 늘리기
>
> 직접적인 해결 방법입니다. 일반적인 채팅에는 1000–2000을 사용하고, 고난도 추론이나 긴 형식의 출력에는 4000 이상을 사용합니다. 추론 오버헤드는 예상보다 훨씬 클 수 있습니다.

> [card] 추론 수준 낮추기
>
> 모델이 `reasoning_effort`을 지원한다면 `high`에서 `medium` 또는 `low`으로 낮춥니다. 사고에 사용되는 양이 눈에 띄게 줄어듭니다.

> [card] 스트리밍으로 전환하기
>
> `stream`을 `true`로 설정합니다. 추론 추적이 별도의 이벤트로 도착하므로 모델이 수행하는 작업을 확인할 수 있으며, 답변이 조용히 사라지는 일도 없습니다.

### 모델 제품군별 매개변수 참조

| 모델 제품군 | 출력 예산 매개변수 | 추론 수준 매개변수 |
| - | - | - |
| OpenAI 추론 모델(o 시리즈, GPT-5/6 시리즈) | `max_completion_tokens` (채팅), `max_output_tokens` (응답) | `reasoning_effort` |
| Claude 사고 모드 | `max_tokens` | `thinking.budget_tokens` |
| Gemini 사고 모드 | `maxOutputTokens` | `thinkingConfig.thinkingBudget` |

> [!WARNING]
>
> 일부 추론 모델은 `max_tokens`을 거부하고 `max_completion_tokens`을 요구합니다. 매개변수 이름이 잘못되면 오류가 발생하거나, 조용히 무시되어 모델이 의도와 일치하지 않는 기본값으로 대체될 수 있습니다.

## FAQ

> [accordion] 로그에는 성공으로 표시되는데 왜 오류가 발생합니까?
>
> 로그에는 업스트림이 생성을 완료하고 과금을 정산했다는 내용이 기록됩니다. 표시되는 텍스트가 비어 있는지는 확인하지 않습니다. 생성 성공과 답변이 비어 있지 않은 것은 서로 다른 문제입니다.

> [accordion] 단순히 재시도하면 해결됩니까?
>
> 대개 해결되지 않습니다. 동일한 prompt와 동일한 `max_tokens`을 사용하면 모델은 다시 추론에 예산을 사용할 가능성이 높습니다. 재시도하는 것보다 파라미터를 변경하는 편이 훨씬 효과적입니다.

> [accordion] 빈 응답에도 과금됩니까?
>
> 예. 추론 token은 실제 사용량이며 출력 token으로 과금됩니다. 정확한 사용량은 [호출 로그](https://docs.apiyi.com/ko/faq/log-billing-explained.md)에서 확인하십시오.

> [accordion] 모든 모델이 이런 방식으로 작동합니까?
>
> 아닙니다. 추론 단계가 있는 추론 모델에만 이 문제가 발생합니다. `gpt-4o` 또는 `deepseek-chat`와 같은 일반 비추론 모델은 전체 `max_tokens`을 표시되는 출력에 사용합니다.

> [accordion] max\_tokens가 크면 비용이 더 많이 듭니까?
>
> 아닙니다. `max_tokens`은 실제 사용량이 아니라 상한입니다. 모델은 작업을 완료하면 중지하며, 실제로 생성된 token에 대해서만 비용을 지불합니다.

## 관련 문서

> [card] [max\_tokens란 무엇입니까?](https://docs.apiyi.com/ko/faq/max-tokens.md)
>
> 매개변수의 의미, 명명 이력 및 모델별 기본값

> [card] [스트리밍과 비스트리밍](https://docs.apiyi.com/ko/faq/streaming-vs-non-streaming.md)
>
> 긴 응답 및 추론 모델에는 스트리밍을 권장합니다

> [card] [모델 오류 문제를 해결하는 방법](https://docs.apiyi.com/ko/faq/model-error-troubleshooting.md)
>
> 400, 401, 429 및 503 오류에 대한 일반적인 진단

> [card] [로그에서 과금 정보를 확인하는 방법](https://docs.apiyi.com/ko/faq/log-billing-explained.md)
>
> 요청이 과금되었는지와 과금 금액을 확인합니다


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.