52 lines
3.3 KiB
Markdown
52 lines
3.3 KiB
Markdown
# OpenAI Chat Completions API — 出力トークン数制御パラメータ仕様
|
||
|
||
- **Source**: https://platform.openai.com/docs/api-reference/chat/create
|
||
- **Supplementary**: https://learn.microsoft.com/en-us/azure/foundry/openai/how-to/reasoning
|
||
- **Retrieved**: 2026-04-28
|
||
|
||
---
|
||
|
||
## 1. `max_tokens` と `max_completion_tokens` の関係
|
||
|
||
| パラメータ | 状態 | 対応モデル |
|
||
|---|---|---|
|
||
| `max_tokens` | **Deprecated** | GPT-3.5, GPT-4 系など旧モデルでは動作する |
|
||
| `max_completion_tokens` | 現行・推奨 | 全モデル（旧モデルにも後方互換あり） |
|
||
|
||
- `max_tokens` は o1 系以降では **受け付けられない**（エラーまたは無視）。
|
||
- 変更の背景: 旧来の `max_tokens` は「返却トークン = 生成トークン = 課金トークン」を前提にしていた。o1 系で推論トークン（reasoning tokens）が導入されたことでこの前提が崩れ、新パラメータが設計された。
|
||
- `max_completion_tokens` は旧モデルでも機能するため、**新規実装では `max_completion_tokens` を使うべき**。
|
||
|
||
## 2. 必須か任意か
|
||
|
||
- **任意（optional）**。
|
||
- 指定しない場合はモデルのコンテキスト上限まで生成する（デフォルト: `null`）。
|
||
|
||
## 3. 型と範囲
|
||
|
||
- **型**: `integer | null`
|
||
- **範囲**: `1` 以上、モデルのコンテキストウィンドウの残りトークン数以下。上限値はモデルごとに異なり、ドキュメント上に固定の最大値は明示されていない。
|
||
- `null` を渡すと制限なし（モデル上限に従う）。
|
||
|
||
## 4. Reasoning モデルでの reasoning tokens のカウント
|
||
|
||
- `max_completion_tokens` の上限には **reasoning tokens（推論トークン）を含む**。
|
||
- reasoning tokens: モデルが内部で生成するが API レスポンスには含まれない隠しトークン。
|
||
- 課金対象は reasoning tokens + visible output tokens の合計。
|
||
- レスポンスの `usage.completion_tokens_details.reasoning_tokens` で内訳を確認できる。
|
||
- したがって、`max_completion_tokens = 5000` と設定しても、推論に多くのトークンを使った場合、目に見える出力は 5000 より少なくなる。
|
||
|
||
## 5. Ollama の OpenAI compat API での扱い（補助情報）
|
||
|
||
- Ollama の `/v1/chat/completions` は現時点で **`max_tokens` のみを公式サポート**している（内部的に `num_predict` にマッピング）。
|
||
- `max_completion_tokens` サポートは Issue #7125 / PR #14464 で議論中だが、2026-04-28 時点では公式ドキュメント上に記載なし。
|
||
- **Ollama に対しては `max_tokens` を使う**のが安全な選択。ただし将来的に `max_completion_tokens` に移行される見込み。
|
||
|
||
## 6. ドキュメント URL
|
||
|
||
- [OpenAI Chat Completions API Reference](https://platform.openai.com/docs/api-reference/chat/create)
|
||
- [Azure OpenAI Reasoning Models (GPT-5, o3, o1)](https://learn.microsoft.com/en-us/azure/foundry/openai/how-to/reasoning)
|
||
- [Ollama OpenAI Compatibility](https://docs.ollama.com/api/openai-compatibility)
|
||
- [Ollama Issue #7125 — max_completion_tokens support](https://github.com/ollama/ollama/issues/7125)
|
||
- [OpenAI Community — Why max_tokens changed to max_completion_tokens](https://community.openai.com/t/why-was-max-tokens-changed-to-max-completion-tokens/938077)
|