> ## 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 が思考に消費されています。3つの確認事項と3つの解決策。

## 簡単な回答

これは API の失敗ではありません。**思考バジェットが出力バジェットを使い果たしている**ことが原因です。

`gpt-6.1-sol` などの推論モデルは、まず推論トレースを生成し、その後で回答を書き込みます。両方の処理で `max_tokens` の上限を**共有**します。思考中にバジェットを使い切ると、回答の生成が始まる前に途中で打ち切られるため、空の結果が返されます。

`max_tokens` を引き上げる（まずは 1000 以上が安全です）か、推論の強度を下げると、この問題は解消します。

## 確認できる内容

よくある形式は2つあります。

**1つは明示的なエラー**で、HTTP ステータスは 429 または 500 です（`message` フィールドはローカライズされる場合があるため、一部のレスポンスでは中国語のメッセージが表示されます）。

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

**もう1つは、コンテンツが空の 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]
>
> 呼び出しログではリクエストが成功し、課金されたことが示されていますが、これは矛盾ではありません。モデルはコンテンツ（推論トレース）を実際に生成しており、表示可能なテキストがなかっただけです。

## これが起こる理由

推論モデルの出力には、2つの段階があります。

| 段階 | 内容 | 返されるか |
| - | - | - |
| 思考 | 推論トークン、内部での思考 | 一部のモデルでは`reasoning_content`として公開されます。通常は表示されません |
| 回答 | テキストトークン、表示される出力 | はい |

`max_tokens`（または`max_completion_tokens`、`max_output_tokens`）は、表示される回答の長さではなく、**両方の段階を合わせた長さ**を制限します。

そのため、`max_tokens`が200～500のように小さく設定されていて、タスクに十分な推論が必要な場合、思考中に予算を使い切ってしまいます。`finish_reason`が`length`になり、内容が空になります。

## 3つの確認

**1. ステップ1: finish\_reasonを確認する**

`length`の場合、出力が途中で切り詰められています。モデルが回答を拒否したわけではありません。`stop`の場合でもコンテンツが空のままであれば、ステップ2と3に進んでください。

**2. ステップ2: usage内のreasoning\_tokensを確認する**

`usage.completion_tokens_details.reasoning_tokens`を確認し、`completion_tokens`と比較します。2つの値が近い、または等しい場合、予算の大部分が思考に使われています。

**3. ステップ3: リクエスト内のmax\_tokensを確認する**

`max_tokens`を小さい値（例えば300）に明示的に設定している場合、それがほぼ確実に原因です。設定していない場合は、SDKまたはフレームワークによって小さいデフォルト値が設定されていないか確認してください。

このスクリプトは、3つのシグナルを同時に出力します。

```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`（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] 単純に再試行すれば解決しますか？
>
> 通常は解決しません。同じ prompt と同じ `max_tokens` では、モデルは再び予算を推論に使う可能性が高くなります。再試行するより、パラメータを変更するほうがはるかに効果的です。

> [accordion] 空のレスポンスでも課金されますか？
>
> はい。推論用の tokens は実際に消費されるため、出力 tokens として課金されます。正確な量は[呼び出しログ](https://docs.apiyi.com/ja/faq/log-billing-explained.md)で確認できます。

> [accordion] すべてのモデルがこのように動作しますか？
>
> いいえ。この問題が発生するのは、思考ステージを持つ推論モデルだけです。`gpt-4o` や `deepseek-chat` などの通常の非推論モデルは、`max_tokens` の全体を表示用の出力に使います。

> [accordion] max\_tokens の値が大きいと、料金は高くなりますか？
>
> いいえ。`max_tokens` は上限であり、実際の消費量ではありません。モデルは処理が完了すると停止し、実際に生成された tokens に対してのみ支払います。

## 関連

> [card] [max\_tokensとは何ですか？](https://docs.apiyi.com/ja/faq/max-tokens.md)
>
> パラメータの意味、命名の経緯、モデルごとのデフォルト値

> [card] [ストリーミングと非ストリーミング](https://docs.apiyi.com/ja/faq/streaming-vs-non-streaming.md)
>
> 長いレスポンスや推論モデルではストリーミングを推奨

> [card] [モデルエラーのトラブルシューティング方法](https://docs.apiyi.com/ja/faq/model-error-troubleshooting.md)
>
> 400、401、429、503の一般的な切り分け

> [card] [ログで課金を確認する方法](https://docs.apiyi.com/ja/faq/log-billing-explained.md)
>
> リクエストが課金されたかどうかと、その金額を確認


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