temperature=0 にすれば毎回同じ答えが返ってくる——そう信じてテストを組んでいたとき、まったく同じリクエストで微妙に違う出力が返ってきて困惑した経験があります。原因を調べてみると、Claude のサンプリングには他のモデルと少し異なる特性があることが分かりました。
ここではClaude API の temperature と top_p パラメータの仕組みを整理し、タスクの種類ごとにどう設定すれば良いかを実際に試した結果を交えながら解説していきます。
temperature=0 でも完全に決定論的にならない理由
多くのドキュメントに「temperature=0 で決定論的な出力」と書かれていますが、Anthropic の公式ドキュメントには重要な注釈があります。
システム側の変更（モデルの更新、インフラの変更）によって、同一リクエストでも出力が変わる場合があります。
つまり temperature=0 は「現時点での実装において最も確率の高いトークンを選択する」という意味であり、Anthropic がいつモデルを更新しても完全に同じ出力を保証する約束ではないのです。
実際に私が経験した挙動を整理すると：
- 短いプロンプト + 短い出力:
temperature=0でほぼ毎回同じ結果 - 長い出力（1000トークン超）:
temperature=0でも末尾付近でわずかな揺れが発生 - コード生成: 変数名の命名が微妙に変わることがある
本番システムでハッシュ比較やスナップショットテストをしている場合は、完全一致ではなくセマンティックな検証に切り替えた方が安全です。
temperature と top_p の仕組みと Claude での特性
temperature の役割
temperature はトークン選択の「ランダム性」を制御します。値が高いほど確率の低いトークンが選ばれやすくなり、低いほど確率の高いトークンが選ばれます。
- 0.0: 最も確率の高いトークンを選択（グリーディデコーディング）
- 0.5〜0.7: バランス型（多くのタスクのデフォルト）
- 1.0: モデルのデフォルト確率分布をそのまま使用
- 1.0超: より多様で予測しにくい出力
Claude API のデフォルト値は 1.0 です。GPT-4 系のデフォルト（1.0）と同じですが、実際の挙動には違いがあります。Claude は長文でも一貫性を保ちやすい傾向があるため、temperature=0.7 前後でも安定した構造の出力が得られます。
top_p の役割
top_p（nucleus sampling）は、選択肢となるトークン群を「累積確率で絞り込む」パラメータです。
たとえば top_p=0.9 の場合、累積確率が 90% になるまでのトークン群の中からサンプリングします。高確率のトークンが少数に集中しているときは選択肢が絞られ、確率が分散しているときは選択肢が広がる、という動的な絞り込みが特徴です。
temperature と top_p の使い分けのポイント:
- 基本的には どちらか一方を調整する（両方を同時に大きく変えると効果の予測が難しくなります）
- コード生成・構造化出力には
temperatureを下げる方が直感的 - 文体の多様性を保ちながら品質を維持したい場合は
top_pを下げる
なお、ChatGPT で使える top_k は Claude API では非対応です。代わりに top_p を使ってください。
タスク別 temperature 推奨設定（実測ベース）
実際にいくつかのタスクで temperature を変えながら検証した結果です。あくまで私の環境での傾向であり、プロンプトの設計によっても最適値は変わります。
コード生成・デバッグ
temperature: 0.0〜0.2
top_p: デフォルト（1.0）
コードは正確さが最優先のため、低 temperature が基本です。ただし temperature=0 のみに頼るのではなく、プロンプトで「型注釈を必ず付ける」「エラーハンドリングを必ず含める」などの制約を明示する方が品質に直結します。
要約・分析・Q&A
temperature: 0.2〜0.5
top_p: 0.9
事実に基づく作業は低め設定が安定します。temperature=0.3 あたりでは、同じドキュメントを複数回要約してもほぼ同じ構造の出力が返ってきました。
翻訳
temperature: 0.1〜0.3
top_p: 0.9
日英翻訳では temperature=0.2 が自然な表現と一貫性のバランスが取れた印象です。temperature=0 だと少し機械的な訳になる場合があります。
創作・アイデア出し・マーケティングコピー
temperature: 0.7〜1.0
top_p: 0.9〜1.0
多様なバリエーションが欲しい場合は temperature=0.9 前後が使いやすいです。temperature=1.0 超はかなり奇抜な出力になることがあるため、ブレインストーミングの初期フェーズなどに限定して使っています。
RAG（検索拡張生成）
temperature: 0.0〜0.3
top_p: 0.9
RAG では取得した文書の内容を忠実に反映させることが重要なため、低 temperature が適しています。temperature=0.2 前後で、引用の正確さと自然な文章のバランスが取れます。
Python SDK でパラメータを設定するコード例
import anthropic
client = anthropic.Anthropic()
# コード生成タスク（低 temperature）
def generate_code(prompt: str) -> str:
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=2048,
temperature=0.1, # 低めに設定して一貫性を確保
messages=[
{"role": "user", "content": prompt}
]
)
return response.content[0].text
# 創作タスク（高 temperature）
def generate_creative(prompt: str, n_variants: int = 3) -> list[str]:
"""複数のバリエーションを生成する"""
results = []
for i in range(n_variants):
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=512,
temperature=0.9, # バリエーションのために高めに設定
top_p=0.95, # 高確率トークンを広めに取る
messages=[
{"role": "user", "content": prompt}
]
)
results.append(response.content[0].text)
return results
# RAGタスク（コンテキスト忠実型）
def answer_with_context(question: str, context: str) -> str:
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
temperature=0.2, # 文書の内容を忠実に反映
system="与えられたコンテキストの情報のみを使って回答してください。コンテキストに情報がない場合は「分かりません」と答えてください。",
messages=[
{
"role": "user",
"content": f"コンテキスト:\n{context}\n\n質問: {question}"
}
]
)
return response.content[0].text
# 使用例
if __name__ == "__main__":
# コード生成（期待する出力: 型注釈付きのPythonコード）
code = generate_code("二分探索を実装してください。型注釈とdocstringを付けてください。")
print("=== コード生成 ===")
print(code)
# クリエイティブ（3バリエーション生成）
taglines = generate_creative("AIツールの紹介文を1文で書いてください。")
print("\n=== タグライン候補 ===")
for i, t in enumerate(taglines, 1):
print(f"{i}. {t}")このコードで注目してほしいのは、generate_creative() が同じプロンプトを複数回呼び出している点です。temperature=0.9 であれば、3回呼び出すたびに異なる表現の文章が返ってきます。temperature=0.1 では3回呼んでもほぼ同じ出力になります。
よくある間違いと落とし穴
実際に遭遇したり、コミュニティで見かけたりしたミスを整理します。
1. コード生成に temperature=1.0（デフォルト）を使い続ける
Claude のデフォルトが 1.0 であるため、明示的に設定しないとコード生成でも temperature=1.0 が使われます。コード生成では temperature=0.0〜0.2 を明示するか、システムプロンプトで「deterministic な回答」を指示した方が安定します。
2. temperature と top_p を両方極端な値に設定する
temperature=0.1 かつ top_p=0.1 のように両方を絞ると、選択肢が極端に狭まり、出力が単調になりすぎることがあります。どちらか一方を調整するのが基本です。
3. Extended Thinking モードでの temperature 設定の誤解
thinking ブロックを使う場合（Extended Thinking）、temperature は内部の思考プロセスには影響せず、最終的な回答の出力部分にのみ適用されます。思考の深さを調整したい場合は budget_tokens を使います。
4. 同じ temperature でモデルを変えて同じ挙動を期待する
claude-haiku-4-5 と claude-sonnet-4-6 で同じ temperature を設定しても、出力の多様性は異なります。モデルを変更したときは temperature の再調整を行うことをお勧めします。
全体を振り返って
temperature と top_p の設定は、「とりあえずデフォルト」から「タスクに合わせた設定」に変えるだけで出力品質が実感できるくらい変わります。
まずは手元のプロジェクトで最も使っているタスク（コード生成か要約か）の temperature を 0.1 か 0.3 に設定して挙動を確認してみてください。1つ設定を変えるだけで、再現性や品質の安定感が上がるはずです。
APIのパラメータ設定についてさらに深く学びたい方には、Claude API 完全コスト最適化ガイドやPrompt Caching でコストを半減させる実践記録も参考になると思います。