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。
首次将旧结果替换为占位文本时,被替换消息及其后续内容会发生变化,可能影响 上下文缓存 命中。评估清理效果时,应同时检查缓存命中情况。
如果某些工具结果包含后续仍需遵循的指令(如技能说明),可以按工具名豁免这类结果,不参与清理。