Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Messages上下文管理
壓縮
用於管理接近上下文視窗限制的長對話的伺服器端上下文壓縮。
關於「zero data retention」（零資料保留），即 ZDR 如何適用於此功能，請參閱 API 與資料保留。
伺服器端壓縮是在長時間執行的對話和代理工作流程中管理上下文的建議策略。它會自動處理上下文管理，無需客戶端的摘要程式碼。
「Compaction」（壓縮）透過在接近上下文視窗限制時自動摘要較舊的上下文，來延長長時間執行的對話和任務的有效上下文長度。它也能保持活躍上下文的精簡：隨著對話增長，回應品質會下降，因此壓縮會以簡潔的摘要取代較舊的內容。
若要深入了解為什麼長上下文會導致品質下降以及壓縮如何提供幫助，請參閱 有效的上下文工程。
這非常適合用於：
- 以聊天為基礎的多輪對話，您希望使用者長時間使用同一個聊天
- 需要大量後續工作（通常是工具使用）且可能超出上下文視窗的任務導向提示
壓縮功能目前處於測試階段。請在您的 API 請求中包含 beta 標頭 compact-2026-01-12 以使用此功能。
支援的模型
支援的模型
以下模型支援壓縮功能：
- Claude Fable 5 (claude-fable-5)
- Claude Mythos 5 (claude-mythos-5)
- Claude Mythos Preview (claude-mythos-preview)
- Claude Opus 5 (claude-opus-5)
- Claude Opus 4.8 (claude-opus-4-8)
- Claude Opus 4.7 (claude-opus-4-7)
- Claude Opus 4.6 (claude-opus-4-6)
- Claude Sonnet 5 (claude-sonnet-5)
- Claude Sonnet 4.6 (claude-sonnet-4-6)
壓縮的運作方式
壓縮的運作方式
啟用壓縮後，當對話達到設定的 token 閾值時，Claude 會自動摘要您的對話。API 會：
- 偵測 input tokens 何時達到您指定的觸發閾值。
- 產生目前對話的摘要。
- 建立包含摘要的
compaction區塊。 - 使用壓縮後的上下文繼續回應。
在後續的請求中，將回應附加到您的訊息中。API 會自動捨棄 compaction 區塊之前的所有內容區塊，並從摘要繼續對話。
基本用法
基本用法
透過在 Messages API 請求的 context_management.edits 中加入 compact_20260112 策略來啟用壓縮。
client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Help me build a website"}]
response = client.beta.messages.create(
betas=["compact-2026-01-12"],
model="claude-opus-5",
max_tokens=4096,
messages=messages,
context_management={"edits": [{"type": "compact_20260112"}]},
)
# 將回應（包括任何壓縮區塊）附加到對話中以繼續對話
messages.append({"role": "assistant", "content": response.content})參數
參數
| 參數 | 類型 | 預設值 | 說明 |
|---|---|---|---|
type | string | 必填 | 必須為 "compact_20260112" |
trigger | object | {"type": "input_tokens", "value": 150000} | 何時觸發壓縮。input_tokens 是唯一支援的觸發類型。value 必須至少為 50,000 個 token。 |
pause_after_compaction | boolean | false | 是否在產生壓縮摘要後暫停 |
instructions | string | null | 自訂摘要提示。提供時會完全取代預設提示。 |
觸發設定
觸發設定
使用 trigger 參數設定壓縮的觸發時機：
client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
betas=["compact-2026-01-12"],
model="claude-opus-5",
max_tokens=4096,
messages=messages,
context_management={
"edits": [
{
"type": "compact_20260112",
"trigger": {"type": "input_tokens", "value": 150000},
}
]
},
)自訂摘要指示
自訂摘要指示
預設的摘要提示因模型而異。每個預設提示都會指示 Claude 在 <summary></summary> 標籤內撰寫摘要，其中包含在未來的上下文視窗中繼續任務所需的資訊。例如，某些模型使用以下提示：
You have written a partial transcript for the initial task above. Please write a summary of the transcript. The purpose of this summary is to provide continuity so you can continue to make progress towards solving the task in a future context, where the raw history above may not be accessible and will be replaced with this summary. Write down anything that would be helpful, including the state, next steps, learnings etc. You must wrap your summary in a <summary></summary> block.您可以透過 instructions 參數提供自訂指示。自訂指示不會補充預設提示，而是完全取代它：
client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
betas=["compact-2026-01-12"],
model="claude-opus-5",
max_tokens=4096,
messages=messages,
context_management={
"edits": [
{
"type": "compact_20260112",
"instructions": "Focus on preserving code snippets, variable names, and technical decisions.",
}
]
},
)壓縮後暫停
壓縮後暫停
使用 pause_after_compaction 讓 API 在產生壓縮摘要後暫停。這讓您可以在 API 繼續回應之前加入額外的內容區塊（例如保留最近的訊息或特定的指示導向訊息）。
啟用後，API 會在產生壓縮區塊後回傳帶有 compaction 停止原因的訊息：
client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
betas=["compact-2026-01-12"],
model="claude-opus-5",
max_tokens=4096,
messages=messages,
context_management={
"edits": [{"type": "compact_20260112", "pause_after_compaction": True}]
},
)
# 檢查壓縮是否觸發了暫停
if response.stop_reason == "compaction":
# 回應僅包含壓縮區塊
messages.append({"role": "assistant", "content": response.content})
# 繼續該請求
response = client.beta.messages.create(
betas=["compact-2026-01-12"],
model="claude-opus-5",
max_tokens=4096,
messages=messages,
context_management={"edits": [{"type": "compact_20260112"}]},
)強制執行總 token 預算
強制執行總 token 預算
當模型處理包含許多工具使用迭代的長時間任務時，總 token 消耗量可能會大幅增長。您可以將 pause_after_compaction 與壓縮計數器結合使用，以估算累計用量，並在達到預算時優雅地結束任務。
此範例僅出現在 SDK 語言中：其價值在於請求周圍的預算追蹤邏輯。原始請求結合了觸發設定中的 trigger 與壓縮後暫停中的 pause_after_compaction。
client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
TRIGGER_THRESHOLD = 100_000
TOTAL_TOKEN_BUDGET = 3_000_000
n_compactions = 0
response = client.beta.messages.create(
betas=["compact-2026-01-12"],
model="claude-opus-5",
max_tokens=4096,
messages=messages,
context_management={
"edits": [
{
"type": "compact_20260112",
"trigger": {"type": "input_tokens", "value": TRIGGER_THRESHOLD},
"pause_after_compaction": True,
}
]
},
)
if response.stop_reason == "compaction":
n_compactions += 1
messages.append({"role": "assistant", "content": response.content})
# 估算已消耗的總 token 數；若超出預算則提示收尾
if n_compactions * TRIGGER_THRESHOLD >= TOTAL_TOKEN_BUDGET:
messages.append(
{
"role": "user",
"content": "Please wrap up your current work and summarize the final state.",
}
)使用壓縮區塊
使用壓縮區塊
當觸發壓縮時，API 會在助理回應的開頭回傳一個 compaction 區塊。
長時間執行的對話可能會產生多次壓縮。最後一個壓縮區塊反映提示的最終狀態，以產生的摘要取代其之前的內容。
Output
{
"content": [
{
"type": "compaction",
"content": "Summary of the conversation: The user requested help building a web scraper..."
},
{
"type": "text",
"text": "Based on our conversation so far..."
}
]
}回傳壓縮區塊
回傳壓縮區塊
您必須在後續的請求中將 compaction 區塊傳回給 API，才能以縮短後的提示繼續對話。最簡單的方法是將整個回應內容附加到您的訊息中：
client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
betas=["compact-2026-01-12"],
model="claude-opus-5",
max_tokens=4096,
messages=messages,
context_management={"edits": [{"type": "compact_20260112"}]},
)
# 收到包含 compaction 區塊的回應後
messages.append({"role": "assistant", "content": response.content})
# 繼續對話
messages.append({"role": "user", "content": "Now add error handling"})
response = client.beta.messages.create(
betas=["compact-2026-01-12"],
model="claude-opus-5",
max_tokens=4096,
messages=messages,
context_management={"edits": [{"type": "compact_20260112"}]},
)當 API 收到 compaction 區塊時，其之前的所有內容區塊都會被忽略。您可以選擇：
- 在您的清單中保留原始訊息，讓 API 處理移除已壓縮的內容
- 手動捨棄已壓縮的訊息，只包含壓縮區塊之後的內容
串流
串流
壓縮區塊的串流方式與文字區塊不同。您會收到一個 content_block_start 事件，接著是一個包含完整摘要內容的單一 content_block_delta（沒有中間串流），然後是一個 content_block_stop 事件。
client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
with client.beta.messages.stream(
betas=["compact-2026-01-12"],
model="claude-opus-5",
max_tokens=4096,
messages=messages,
context_management={"edits": [{"type": "compact_20260112"}]},
) as stream:
for event in stream:
if event.type == "content_block_start":
if event.content_block.type == "compaction":
print("Compaction started...")
elif event.content_block.type == "text":
print("Text response started...")
elif event.type == "content_block_delta":
if event.delta.type == "compaction_delta":
print(f"Compaction complete: {len(event.delta.content or '')} chars")
elif event.delta.type == "text_delta":
print(event.delta.text, end="", flush=True)
# 取得最終累積的訊息
message = stream.get_final_message()
messages.append({"role": "assistant", "content": message.content})提示快取
提示快取
壓縮與提示快取可以良好搭配。您可以在壓縮區塊上加入 cache_control 中斷點來快取摘要後的內容。
{
"role": "assistant",
"content": [
{
"type": "compaction",
"content": "[summary text]",
"cache_control": { "type": "ephemeral" }
},
{
"type": "text",
"text": "Based on our conversation..."
}
]
}使用系統提示最大化快取命中率
使用系統提示最大化快取命中率
當壓縮發生時，摘要會成為需要寫入快取的新內容。如果沒有額外的快取中斷點，這也會使任何已快取的系統提示失效，需要與壓縮摘要一起重新快取。
若要最大化快取命中率，請在系統提示的結尾加入 cache_control 中斷點。這會讓系統提示與對話分開快取，因此當壓縮發生時：
- 系統提示快取仍然有效，並從快取中讀取
- 只有壓縮摘要需要作為新的快取項目寫入
client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
betas=["compact-2026-01-12"],
model="claude-opus-5",
max_tokens=4096,
system=[
{
"type": "text",
"text": "You are a helpful coding assistant...",
"cache_control": {
"type": "ephemeral"
}, # Cache the system prompt separately
}
],
messages=messages,
context_management={"edits": [{"type": "compact_20260112"}]},
)這可以讓長系統提示在整個對話中的多次壓縮事件之間保持快取狀態。
了解用量
了解用量
壓縮需要額外的取樣步驟，這會計入速率限制和計費。API 會在回應中回傳詳細的用量資訊：
Output
{
"usage": {
"input_tokens": 23000,
"output_tokens": 1000,
"iterations": [
{
"type": "compaction",
"input_tokens": 180000,
"output_tokens": 3500
},
{
"type": "message",
"input_tokens": 23000,
"output_tokens": 1000
}
]
}
}iterations 陣列顯示每次取樣迭代的用量。當壓縮發生時，您會看到一個 compaction 迭代，接著是主要的 message 迭代。在此範例中，頂層的 input_tokens 和 output_tokens 與 message 迭代完全相符，因為只有一個非壓縮迭代。最後一個迭代的 token 計數反映了壓縮後的有效上下文大小。
頂層的 input_tokens 和 output_tokens 不包含壓縮迭代的用量。它們反映所有非壓縮迭代的總和。若要計算請求消耗和計費的總 token 數，請加總 usage.iterations 陣列中的所有項目。
如果您先前依賴 usage.input_tokens 和 usage.output_tokens 進行成本追蹤或稽核，在啟用壓縮時，您需要更新追蹤邏輯以彙總 usage.iterations。啟用壓縮測試版後，每個回應都會包含 usage.iterations，即使沒有發生壓縮。只有在請求期間觸發新的壓縮時，才會出現 compaction 項目。重新套用先前的 compaction 區塊不會產生額外的壓縮成本，在這種情況下，頂層的用量欄位仍然準確。
與其他功能結合
與其他功能結合
伺服器工具
伺服器工具
使用伺服器工具（例如網頁搜尋）時，會在每次取樣迭代開始時檢查壓縮觸發條件。根據您的觸發閾值和產生的輸出量，壓縮可能會在單一請求中發生多次。
Token 計數
Token 計數
Token 計數端點（/v1/messages/count_tokens）會套用您提示中現有的 compaction 區塊，但不會觸發新的壓縮。使用它來檢查先前壓縮後的有效 token 計數：
client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
count_response = client.beta.messages.count_tokens(
betas=["compact-2026-01-12"],
model="claude-opus-5",
messages=messages,
context_management={"edits": [{"type": "compact_20260112"}]},
)
print(f"Current tokens: {count_response.input_tokens}")
print(f"Original tokens: {count_response.context_management.original_input_tokens}")範例
範例
以下是使用壓縮的長時間執行對話的完整範例：
client = anthropic.Anthropic()
messages: list[dict] = []
def chat(user_message: str) -> str:
messages.append({"role": "user", "content": user_message})
response = client.beta.messages.create(
betas=["compact-2026-01-12"],
model="claude-opus-5",
max_tokens=4096,
messages=messages,
context_management={
"edits": [
{
"type": "compact_20260112",
"trigger": {"type": "input_tokens", "value": 100000},
}
]
},
)
# 附加回應（壓縮區塊會自動包含在內）
messages.append({"role": "assistant", "content": response.content})
# 回傳文字內容
return next(block.text for block in response.content if block.type == "text")
# 執行長對話
print(chat("Help me build a Python web scraper"))
print(chat("Add support for JavaScript-rendered pages"))
print(chat("Now add rate limiting and error handling"))
# 只要對話有需要，就持續呼叫 chat()以下範例使用 pause_after_compaction 逐字保留先前的交流和目前的使用者訊息（共三則訊息），而不是將它們摘要：
from typing import Any
client = anthropic.Anthropic()
messages: list[dict[str, Any]] = []
def chat(user_message: str) -> str:
messages.append({"role": "user", "content": user_message})
response = client.beta.messages.create(
betas=["compact-2026-01-12"],
model="claude-opus-5",
max_tokens=4096,
messages=messages,
context_management={
"edits": [
{
"type": "compact_20260112",
"trigger": {"type": "input_tokens", "value": 100000},
"pause_after_compaction": True,
}
]
},
)
# 檢查是否發生壓縮並暫停
if response.stop_reason == "compaction":
# 從回應中取得壓縮區塊
compaction_block = response.content[0]
# 保留先前的對話往返 + 目前的使用者訊息（3 則訊息）
# 方法是將它們放在壓縮區塊之後
preserved_messages = messages[-3:] if len(messages) >= 3 else messages
# 建立新的訊息清單：壓縮區塊 + 保留的訊息
new_assistant_content = [compaction_block]
messages_after_compaction = [
{"role": "assistant", "content": new_assistant_content}
] + preserved_messages
# 使用壓縮後的上下文 + 保留的訊息繼續請求
response = client.beta.messages.create(
betas=["compact-2026-01-12"],
model="claude-opus-5",
max_tokens=4096,
messages=messages_after_compaction,
context_management={"edits": [{"type": "compact_20260112"}]},
)
# 更新我們的訊息清單以反映壓縮結果
messages.clear()
messages.extend(messages_after_compaction)
# 附加最終回應
messages.append({"role": "assistant", "content": response.content})
# 回傳文字內容
return next(block.text for block in response.content if block.type == "text")
# 執行一段長對話
print(chat("Help me build a Python web scraper"))
print(chat("Add support for JavaScript-rendered pages"))
print(chat("Now add rate limiting and error handling"))
# 只要對話有需要，就持續呼叫 chat()目前的限制
目前的限制
-
**摘要使用相同模型：**您請求中指定的模型會用於摘要。無法選擇使用不同的（例如較便宜的）模型來產生摘要。
-
**定義工具時壓縮可能會失敗：**當您的請求包含
tools時，模型偶爾會在內部摘要步驟中呼叫工具而不是撰寫摘要。發生這種情況時，回應會包含一個content: null的compaction區塊。若要防止這種情況，請將instructions設定為明確告知模型不要呼叫工具的提示，例如：Summarize the transcript inside <summary></summary> tags. Include relevant information in the summary for continuing the task in the next context window. Do not call any tools while writing this summary; respond with text only.
後續步驟
後續步驟
使用上下文編輯自動管理隨著對話增長的上下文。
了解上下文視窗大小和管理策略。
探索一個實用的實作，使用背景執行緒和提示快取，透過即時工作階段記憶壓縮來管理長時間執行的對話。
Was this page helpful?