> ## 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，或返回 200 但正文為空。多數是 max_tokens 被思考過程吃光，三步確認、三種解法。

## 簡短回答

這不是介面故障，是**思考預算把輸出額度用光了**。

推理模型（如 `gpt-6.1-sol`）會先生成一段思考過程（reasoning tokens）再寫正文，這兩部分**共用** `max_tokens` 額度。當思考還沒結束額度就用完，正文還沒來得及寫就被截斷，於是你收到的是一個空結果。

把 `max_tokens` 調大（建議 1000 以上），或降低推理強度，問題就會消失。

## 問題現象

通常有兩種表現：

**一種是直接收到錯誤**，HTTP 狀態碼 429 或 500：

```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]
>
> 後臺日誌會顯示這次呼叫"成功"並已扣費，這和你看到的報錯並不矛盾：模型確實生成了內容（思考過程），只是沒有輸出你可見的正文。

## 為什麼會這樣

推理模型的輸出分兩段：

| 階段 | 內容 | 是否返回給你 |
| - | - | - |
| 思考 | reasoning tokens，模型的內部推理 | 部分模型會以 `reasoning_content` 返回，多數場景不可見 |
| 回答 | text tokens，你最終看到的正文 | 是 |

`max_tokens`（或 `max_completion_tokens`、`max_output_tokens`）限制的是**兩段之和**，不是正文長度。

所以當 `max_tokens` 設成 200\~500 這種偏小的值，而任務又需要較多推理時，額度會在思考階段就耗盡，`finish_reason` 變成 `length`，正文為空。

## 三步確認

**1. 第一步：看 finish\_reason**

如果是 `length`，說明輸出被截斷了，不是模型拒絕回答。如果是 `stop` 卻仍然為空，再看第二步和第三步。

**2. 第二步：看 usage 裡的 reasoning\_tokens**

找到 `usage.completion_tokens_details.reasoning_tokens`，和 `completion_tokens` 比較。兩者接近或相等，說明額度基本都被思考吃掉了。

**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": "你的問題"}],
    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`（Chat）、`max_output_tokens`（Responses） | `reasoning_effort` |
| Claude 思考模式 | `max_tokens` | `thinking.budget_tokens` |
| Gemini 思考模式 | `maxOutputTokens` | `thinkingConfig.thinkingBudget` |

> [!WARNING]
>
> 部分推理模型不接受 `max_tokens`，必須用 `max_completion_tokens`。如果引數名寫錯，可能直接報引數錯誤，也可能被忽略後走預設值，導致行為和預期不一致。

## 常見問題

> [accordion] 為什麼後臺日誌顯示成功，我卻收到了報錯？
>
> 日誌記錄的是"上游完成了生成並結算"，它不判斷正文是否為空。這兩件事是分開的：生成成功不代表正文有內容。

> [accordion] 原樣重試有用嗎？
>
> 基本沒用。同樣的提示詞、同樣的 `max_tokens`，模型大機率仍然把額度花在思考上。調整引數比重試有效。

> [accordion] 這種空響應會扣費嗎？
>
> 會。思考 token 也是真實消耗，通常按輸出 token 計費。可以用 [呼叫日誌](https://docs.apiyi.com/zh-Hant/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/zh-Hant/faq/max-tokens.md)
>
> 引數含義、命名演變和各模型的預設值

> [card] [流式與非流式怎麼選？](https://docs.apiyi.com/zh-Hant/faq/streaming-vs-non-streaming.md)
>
> 長響應和推理模型優先用流式

> [card] [模型呼叫報錯怎麼排查？](https://docs.apiyi.com/zh-Hant/faq/model-error-troubleshooting.md)
>
> 400、401、429、503 等錯誤的通用排查路徑

> [card] [怎麼看懂日誌裡的計費金額？](https://docs.apiyi.com/zh-Hant/faq/log-billing-explained.md)
>
> 確認請求是否計費、扣了多少


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