Effort

effort 參數讓您能夠控制 Claude 在回應請求時花費 token 的積極程度。您可以使用單一模型在回應完整性與 token 效率之間進行取捨。effort 參數在所有支援的模型上皆可使用，無需 beta 標頭。



effort 的運作方式

預設情況下，Claude 使用 high effort，會花費所需的任何 token 數量以獲得優異的結果。您可以將 effort 等級提高至 max 以獲得絕對最高的能力，或降低等級以更保守地使用 token，在接受部分能力降低的同時針對速度和成本進行最佳化。

effort 參數會影響回應中的所有 token，包括：

• 文字回應和說明
• 工具呼叫和函式引數
• 擴展思考（啟用時）

此方法有兩個主要優點：

1. 不需要啟用思考功能。
2. 可以影響所有 token 花費，包括工具呼叫。例如，較低的 effort 意味著 Claude 會進行較少的工具呼叫。這提供了對效率更大程度的控制。



Effort 等級



Claude Sonnet 5 的建議 effort 等級

Claude Sonnet 5 預設為 high effort。

• High effort（預設）： 適用於複雜推理、程式編寫和代理任務，在這些情境中品質比速度或成本更重要。
• Xhigh effort： 適用於最困難的程式編寫和代理任務。請參閱 Claude Sonnet 5 的提示技巧。
• Medium effort： 從預設值降級以節省成本。相當於 Claude Sonnet 4.6 在 high effort 下的表現。
• Low effort： 適用於高流量或對延遲敏感的工作負載。適合優先考慮快速回應的聊天和非程式編寫使用情境。
• Max effort： 適用於需要絕對最高能力且對 token 花費沒有限制的任務。



Sonnet 4.6 的建議 effort 等級

Sonnet 4.6 預設為 high effort。使用 Sonnet 4.6 時請明確設定 effort，以避免非預期的延遲：

• Medium effort（建議預設值）：對大多數應用程式而言，在速度、成本和效能之間取得最佳平衡。適用於代理程式編寫、大量使用工具的工作流程和程式碼生成。
• Low effort： 適用於高流量或對延遲敏感的工作負載。適合優先考慮快速回應的聊天和非程式編寫使用情境。
• High effort： 適用於複雜推理以及品質比速度或成本更重要的任務。
• Max effort： 適用於需要絕對最高能力且對 token 花費沒有限制的任務。



Claude Opus 4.7 的建議 effort 等級

對於程式編寫和代理使用情境，請從 xhigh 開始，並將 high 作為大多數對智慧敏感工作負載的最低設定。對於成本敏感的工作負載可降至 medium，只有當您的評估顯示在 xhigh 下仍有可測量的提升空間時才升至 max。

API 預設值為 high。若要使用 xhigh，請明確設定 effort；您傳遞的值會覆寫預設值。

Claude Opus 4.7 也比 Claude Opus 4.6 更嚴格地遵守 effort 等級，特別是在 low 和 medium 等級。在較低的 effort 等級下，模型會將工作範圍限定在所要求的內容，而不會超出預期。如果您在使用 Claude Opus 4.7 處理複雜問題時觀察到推理過於淺顯，請提高 effort 而非透過提示來繞過此問題。如果您必須為了延遲而保持低 effort，請加入針對性的指引，例如「此任務涉及多步驟推理。請在回應前仔細思考。」

在 xhigh 或 max effort 下執行 Claude Opus 4.7 時，請設定較大的 max_tokens，讓模型有足夠空間在子代理和工具呼叫之間進行思考和行動。從 64k token 開始並據此調整是合理的預設值。



Claude Opus 4.8 的建議 effort 等級

Claude Opus 4.7 的指引同樣適用於 Claude Opus 4.8。對於程式編寫和代理使用情境，請從 xhigh 開始，對於大多數其他對智慧敏感的工作負載使用 high，只有當您已測量確認較低等級在您的評估中能維持品質時，才降至 medium 或 low。

API 預設值為 high。若要使用不同的等級，請明確設定 effort；您傳遞的值會覆寫預設值。

在 xhigh 或 max effort 下執行 Claude Opus 4.8 時，請設定較大的 max_tokens，讓模型有足夠空間在子代理和工具呼叫之間進行思考和行動。從 64k token 開始並據此調整是合理的預設值。



Claude Fable 5 的建議 effort 等級

Effort 是在 Claude Fable 5 上權衡智慧、延遲和成本的主要控制項。對於大多數任務，請從預設值 high 開始，對於最需要能力的工作負載使用 xhigh，對於例行工作則降至 medium 或 low。Claude Fable 5 上較低的 effort 設定仍能表現良好，且通常超越先前模型在 xhigh 下的效能。在 high 和 xhigh 下，請設定較大的 max_tokens：這是總輸出（思考加上回應文字）的硬性限制。請參閱成本控制。

如果任務完成但花費時間超過必要，或您想要更快速、更具互動性的工作方式，請降低 effort。相同的建議也適用於 Claude Mythos 5。如需更完整的指引，請參閱 Claude Fable 5 的提示技巧。



基本用法

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Analyze the trade-offs between microservices and monolithic architectures",
        }
    ],
    output_config={"effort": "medium"},
)

print(response.content[0].text)



何時調整 effort 參數

• 當您需要絕對最高能力且沒有任何限制時，請使用 max effort：最徹底的推理和最深入的分析。適用於 Claude Fable 5、Claude Mythos 5、Claude Opus 4.8、Claude Mythos Preview、Claude Opus 4.7、Claude Opus 4.6、Claude Sonnet 5 和 Claude Sonnet 4.6。
• 對於需要擴展探索的進階程式編寫和複雜代理工作（例如重複的工具呼叫和詳細搜尋），請使用 xhigh effort。適用於 Claude Fable 5、Claude Mythos 5、Claude Opus 4.8、Claude Opus 4.7 和 Claude Sonnet 5。
• 對於複雜推理、細緻分析、困難的程式編寫問題，或任何品質比速度或成本更重要的任務，請使用 high effort（預設值）。
• 當您想要穩定的效能但不需要 high effort 的完整 token 花費時，請使用 medium effort 作為平衡選項。
• 當您針對速度（因為 Claude 以較少 token 回答）或成本進行最佳化時，請使用 low effort。例如，簡單的分類任務、快速查詢，或邊際品質改善不足以證明額外延遲或花費合理的高流量使用情境。



Effort 與工具使用

使用工具時，effort 參數會同時影響工具呼叫周圍的說明以及工具呼叫本身。較低的 effort 等級傾向於：

• 將多個操作合併為較少的工具呼叫
• 進行較少的工具呼叫
• 直接採取行動而不加前言
• 完成後使用簡潔的確認訊息

較高的 effort 等級可能會：

• 進行更多工具呼叫
• 在採取行動前說明計畫
• 提供變更的詳細摘要
• 包含更全面的程式碼註解



Effort 與擴展思考

effort 參數可與「extended thinking」（擴展思考）搭配使用。其行為取決於模型：

• Claude Fable 5 和 Claude Mythos 5 使用 adaptive thinking（自適應思考），此功能始終開啟（無需 thinking 設定）。thinking: {type: "disabled"} 會被拒絕。Effort 控制思考深度的方式與 Opus 4.8 和 Opus 4.7 相同。
• Claude Opus 4.8 使用 adaptive thinking（thinking: {type: "adaptive"}），其中 effort 是控制思考深度的建議方式。不支援手動擴展思考（thinking: {type: "enabled", budget_tokens: N}），會回傳 400 錯誤。模型會根據每個請求決定何時以及思考多少，因此只在需要時觸發思考。在 high、xhigh 和 max effort 下，Claude 幾乎總是會深入思考。在較低等級下，對於較簡單的問題可能會跳過思考。設定 thinking: {type: "adaptive"} 以啟用思考；若未設定，請求將在不思考的情況下執行。
• Claude Mythos Preview 預設使用 adaptive thinking（無需 thinking 設定）。thinking: {type: "disabled"} 會被拒絕。Effort 控制思考深度的方式與 Opus 4.7 和 Opus 4.6 相同。
• Claude Opus 4.7 使用 adaptive thinking（thinking: {type: "adaptive"}），其中 effort 是控制思考深度的建議方式。Opus 4.7 不再支援手動擴展思考（thinking: {type: "enabled", budget_tokens: N}）；請改用搭配 effort 的自適應思考。在 high、xhigh 和 max effort 下，Claude 幾乎總是會深入思考。在較低等級下，對於較簡單的問題可能會跳過思考。
• Claude Opus 4.6 使用 adaptive thinking（thinking: {type: "adaptive"}），其中 effort 是控制思考深度的建議方式。雖然 Opus 4.6 仍接受 budget_tokens，但它已被棄用，並將在未來版本中移除。在 high 和 max effort 下，Claude 幾乎總是會深入思考。在較低等級下，對於較簡單的問題可能會跳過思考。
• Claude Sonnet 5 使用 adaptive thinking，此功能預設開啟（無需 thinking 設定），且 effort 是控制思考深度的建議方式。不支援手動擴展思考（thinking: {type: "enabled", budget_tokens: N}），會回傳 400 錯誤。傳遞 thinking: {type: "disabled"} 可關閉思考。在 high（預設）、xhigh 和 max effort 下，Claude 幾乎總是會深入思考。在較低等級下，對於較簡單的問題可能會跳過思考。
• Claude Sonnet 4.6 使用 adaptive thinking（其中 effort 控制思考深度）。使用 interleaved mode（交錯模式）的手動思考（thinking: {type: "enabled", budget_tokens: N}）仍可運作但已被棄用。
• Claude Opus 4.5 使用手動思考（thinking: {type: "enabled", budget_tokens: N}），其中 effort 與思考 token 預算搭配運作。請為您的任務設定 effort 等級，然後根據任務複雜度設定思考 token 預算。

effort 參數可在啟用或不啟用擴展思考的情況下使用。在不啟用思考的情況下使用時，它仍會控制文字回應和工具呼叫的整體 token 花費。



最佳實務

1. 明確設定 effort： API 預設為 high，但正確的起點取決於您的模型和工作負載。
2. 對速度敏感或簡單的任務使用 low： 當延遲很重要或任務較為簡單時，low effort 可以大幅減少回應時間和成本。
3. 測試您的使用情境： effort 等級的影響因任務類型而異。在部署前，請針對您的特定使用情境評估效能。
4. 考慮動態 effort： 根據任務複雜度調整 effort。簡單的查詢可能適合 low effort，而代理程式編寫和複雜推理則受益於 high effort。



後續步驟