> ## 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/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/faq/max-tokens.md)
>
> 参数含义、命名演变和各模型的默认值

> [card] [流式与非流式怎么选？](https://docs.apiyi.com/faq/streaming-vs-non-streaming.md)
>
> 长响应和推理模型优先用流式

> [card] [模型调用报错怎么排查？](https://docs.apiyi.com/faq/model-error-troubleshooting.md)
>
> 400、401、429、503 等错误的通用排查路径

> [card] [怎么看懂日志里的计费金额？](https://docs.apiyi.com/faq/log-billing-explained.md)
>
> 确认请求是否计费、扣了多少


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