跳转到主要内容
工具调用产生的搜索结果、日志和代码输出会保存在对话历史中,并随后续请求重复发送。如果不清理,这些旧结果会持续增加请求的输入 token 数,占用上下文窗口。对于内容较长、后续不再需要完整原文的旧结果,可以在客户端将请求中的这些内容替换为占位文本,只保留近期工具结果的原文。 本文通过 Python 示例实现这一流程:完整结果先保存到本地 JSONL 文件,再清理并更新模型当前使用的 messages。占位文本记录归档文件路径和记录编号,便于业务系统回查。

实现工具结果清理函数

清理策略由两个 token 阈值控制: 保护窗口从最新一条工具结果开始,由近及远累计 token 数,直到累计值达到窗口大小;计入的结果都保留原文,包括使累计值达到窗口大小的那一条。因此,无论窗口设多小,最新的工具结果都保留原文。 例如,历史中有四条工具结果,从最新一条开始累计的 token 数依次为 10000、35000、43000 和 71000,保护窗口为 40000:累计到 43000 时达到窗口大小,前三条保留原文;最旧的一条在窗口外,旧结果共 28000 token(71000-43000),超过触发阈值 20000,替换为占位文本。 以下代码以单进程、单对话场景演示归档和清理流程。实际应用应为每个对话使用独立归档;历史较多时,可以改用数据库保存完整结果。 运行前请在环境变量 MOONSHOT_API_KEY 中配置 API Key:
代码中各组成部分的作用如下:

调用清理函数更新消息历史

本示例用 messages 保存模型当前使用的消息历史,用 new_tool_messages 保存本轮新得到的工具结果。 首次接入尚未归档的历史时,先逐条归档 messages 中已有的工具结果;如果加载的是此前已经清理并归档过的历史,则跳过这一步。对于仍保留原文的待清理结果,函数会核对归档记录及内容,检查失败时会报错并停止清理。 每个对话使用独立的归档文件:
之后每轮收齐工具结果,先将它们追加到 messages 并归档,再清理旧结果并更新 messages。发送请求时沿用应用原有的 tools:
如果批量归档中途失败,重试前应按 tool_call_id 跳过已经追加到 messages 的结果,避免重复追加消息。 本示例设置保护窗口 protect_recent_tokens 为 40000 token,触发阈值 min_clearable_tokens 为 20000 token。可以按任务需要调整这两个值,例如将 min_clearable_tokens 设为 0 时,每轮都会清理窗口外的旧结果。

选择保护窗口和触发阈值

后续仍需使用较早结果时,应调大保护窗口;不再依赖这些结果时可以调小。建议根据实际任务比较回答质量和 usage.prompt_tokens。 首次将旧结果替换为占位文本时,被替换消息及其后续内容会发生变化,可能影响 上下文缓存 命中。评估清理效果时,应同时检查缓存命中情况。 如果某些工具结果包含后续仍需遵循的指令(如技能说明),可以按工具名豁免这类结果,不参与清理。