Claude API长对话怎么压缩？按需Compaction、签名块与续聊检查

API应用里的对话越来越长，每轮都重发历史，既占上下文，也可能让旧工具结果干扰后续任务。Claude提供按需Compaction：应用发起一次独立总结请求，然后用返回的签名块替换被总结的消息。本文解释最小闭环，不等同于Claude Code里的交互压缩命令。

第一步：先确认模型支持与调用时机

该功能当前为Beta，请求头为compact-2026-09-04。官方建议通过带此Beta头的Models API检查capabilities.compaction，不能仅凭模型名字推断。示例使用当前文档中的claude-opus-5-5；实际账号需要相应API访问权限，消费端订阅不能替代开发者API。

应在会话仍能放进上下文时压缩，超限之后不能指望压缩请求自动救回。若最后一条assistant消息有尚未返回结果的工具调用，先补齐工具结果。备份完整原始消息到应用原有受控存储，再发压缩请求，失败时仍保留可恢复历史。

第二步：请求独立摘要

import anthropic

client = anthropic.Anthropic()
history = [
    {"role": "user", "content": "练习项目只支持简体中文，预算单位为元。"},
    {"role": "assistant", "content": "已记录语言和单位约束。"},
]
summary = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    betas=["compact-2026-09-04"],
    messages=history,
    compaction={"type": "summarize"},
)

示例是人工练习历史，并非实测输出。SDK从标准环境读取凭据，代码中不写真实密钥。若原会话有system和tools，应发送相同定义；不要为了缩短请求随意移除。max_tokens覆盖本次调用，摘要请求本身也消耗token，需要单独记录。

第三步：核对响应后才替换历史

if summary.stop_reason != "compaction":
    raise RuntimeError("没有得到完整压缩结果，保留旧历史")
if len(summary.content) != 1 or summary.content[0].type != "compaction":
    raise RuntimeError("压缩块形状异常，保留旧历史")
new_history = [
    {"role": "assistant", "content": summary.content},
    {"role": "user", "content": "复述练习项目的语言和预算单位。"},
]
reply = client.beta.messages.create(
    model="claude-opus-5-5", max_tokens=2048,
    betas=["compact-2026-09-04"], messages=new_history,
)
print(reply.content)

保留整个返回块，包括可读content和signature。不能手工润色摘要后继续沿用原签名，也不能只复制摘要文字当作同一个压缩结果。压缩块放在messages最前面，后接新消息；被压缩的旧消息要移除，避免重复和位置错误。

第四步：处理限制与常见400

每次续聊仍携带Beta头和一个完整压缩块。若旧历史仍位于它之前，可能出现compaction_block_misplaced。压缩请求不能同时带context_management，不应带stop_sequences、结构化输出格式或强制any/tool选择；应先按官方限制构造单独请求。

没有得到摘要、遇到网络错误或输出截断时，不覆盖原历史，也不要把空结果写入数据库。先记录错误类型与请求标识，排查模型支持、参数和预算，确认完整结果后再原子替换。日志无需保存凭据或向前端展示签名内容。

第五步：用固定约束做续聊验收

练习应检查新一轮仍记得简体中文和元两个约束，并问一个依赖此前决策的问题。实际项目还要核对未完成任务、文件版本、明确禁止事项和来源标识。摘要会压缩细节，不能把“能继续回答”当成逐字历史无损保留。

验收记录：原消息数；模型能力检查；压缩stop_reason；返回块完整保存；续聊Beta头；原历史替换范围；关键约束核对；压缩与续聊各自usage；失败回滚状态。

先把同步完整替换流程跑通，再考虑保留最近轮次或后台压缩。那些流程还涉及并发消息和保留thinking的前缀条件，不能直接套用本例后悄悄改变system或tools。

应用应把压缩请求针对的历史版本号一起保存。摘要写回前，检查期间是否又追加了新轮次；若已经变化，不能把后来消息一并删除。本例是同步等待，最容易先验证。生产接入时将状态替换与会话锁或版本检查结合，避免两次并发压缩互相覆盖。原历史备份和摘要状态应沿用业务系统既有访问控制。

官方资料

资料核对日期：2026年11月11日。

• Anthropic：Compaction on demand
• Anthropic：Compaction overview