长程任务的上下文预算怎么定：从思考到缓存

模型能一次跑几小时之后，账就从「一次问答多少钱」变成「一个任务多少钱」。按官方文档走一遍：先量 token 足迹，再按统一上限拆输入与输出预算，改造提示让隐式缓存命中，长输出改后台执行，多轮状态交给服务端，最后给每个任务装一道预算闸门。

这篇教程解决什么

十月第四周有一个不显眼但影响不小的变化：长上下文已经从卖点变成默认值。10 月 23 日 Moonshot 发布 Kimi K3.1 Pro，上下文窗口升到 100 万 token；Google 的官方文档里，Gemini 4 Argon 的统一输入输出 token 限制同样是 1,048,576，且这个上限由输入和输出共同占用——输出里还包括思考、函数调用与最终回答。

窗口变大的直接后果是：账的算法变了。以前一次问答的成本基本等于「提示多长 + 回答多长」，现在一个任务可能跑几十轮工具调用、产出几十万 token 的思考过程，而输出 token 的单价通常高于输入。「每次调用便宜」和「每个任务便宜」是两件事，长程任务里后者才是预算口径。

本篇要解决的就是这一件：给一个会跑很久的智能体任务，装一套可执行的上下文与输出预算。读完你应该能答出四个问题——这一趟任务把 token 花在了哪里、哪些部分本来可以打折、长输出该怎么提交才不会被截断、以及在什么位置设闸门才能拦住失控的任务。

先说清不覆盖什么：

• 不比较各家模型的能力与价格，也不给具体金额。价格按月变动，一律以官网定价页为准。
• 不提供基准成绩，也不转述官方公布的效果提升幅度。
• 不替代计费后台的对账工作。本篇讲的是在提交请求这一层能控制的变量，账单口径以各平台官方说明为准。

示例参数以 Google 官方 Gemini API 文档为准；其他厂商的参数名不同，但「预算拆分、缓存、长输出、会话状态、闸门」这五步的思路是通用的。凡官方文档标注「以当前版本为准」的地方，本篇同样标注。

开始前的准备

开工前把下面几件事备齐，缺一项都会在后面某一步卡住：

1. 一个能跑起来的调用入口。 任意一个支持长上下文的模型端点即可，本篇示例用 Gemini API（gemini-4-argon）。控制台与密钥的获取方式以官方文档为准。
2. 能读到用量字段的调用方式。 官方文档写明，缓存命中的 token 数可以从响应的 usage.total_cached_tokens 字段读取（Python 与 JavaScript 均提供）。如果用的是封装过的 SDK 或中间层，先确认这个字段没有被吞掉——看不到它，后面所有优化都无法验证。
3. 一段真实的、会跑很久的任务。 建议挑一个真实存在长尾的任务（批量处理文档、跨多个文件的重构、长时间的资料汇总），不要用「你好」这类样例。预算只有对着真实任务才有意义。
4. 一份记录表。 三列就够：输入 token、输出 token（含思考）、缓存命中 token。不需要复杂的监控，能逐次记下来即可。
5. 一个版本的官方文档在手边。 本篇引用的参数名与阈值以 2026 年 10 月的官方文档为准；模型的 API 惯例会随版本调整，动手前先打开 Gemini API 官方文档核一眼。

前置成本说明：本篇的操作本身不产生额外费用，但跑基线这一步会真实消耗额度——尤其开启高思考等级、跑长输出时。建议先用一个小样本跑通，确认记录表能拿到数之后，再放大到完整任务。

步骤详解

第 1 步：先量一次基线，把 token 花在哪看清楚

做什么：不加任何优化，按现有提示把任务完整跑一遍，把每次调用的输入 token、输出 token 与缓存命中 token 记进表里，并算出总任务里各项的占比。

看到什么算成功：表里出现三列数字，且能回答「这个任务的大头在输入、在输出、还是在思考」这三个问题中的至少一个。如果缓存命中那一列全程为 0，说明提示还没进入可缓存的状态——这是第 3 步要解决的。

为什么要先做这一步：长程任务的成本结构常常和直觉相反。多数人预期的「提示太长」，实测下来往往不是大头；反复重发的上下文与长思考过程才是。在没量过之前做优化，多半是在优化一个不存在的瓶颈。

注意：输出 token 里包含思考部分，官方文档对此有明确说明。所以「输出很长」不一定是废话太多，也可能是思考等级开得偏高——这两者的处理方式完全不同。

第 2 步：按统一上限拆输入与输出的预算

做什么：先确认目标模型的上限口径，再反推你的预算。按官方文档，Gemini 4 Argon 的输入与输出共享 1,048,576 的统一限制，输出部分包含思考、函数调用与最终回答；单次请求的输出上限是 65,536 token（非流式的直接 HTTP 请求则是 32,768）。

在这个口径下做三件事：

• 给输出留出明确额度。 输入和输出抢同一份额度，输入铺满就等于没有输出空间。按任务预期产出的长度，先划出输出的上限，剩下的才是输入可用量。
• 把 max_output_tokens 提到足够高。 官方文档建议至少设为 32,768，理由是模型可能把较多额度用于思考。沿用旧模型的小上限，会表现为「回答被截断」，而实际是被自己的设置截断的。
• 设思考等级并实测三档。 官方提供的思考等级为 low、medium（默认）与 high，文档建议在所有等级上测试工作负载。做法是同一任务跑三遍，记录输出 token 与结果可用度，挑出性价比拐点，而不是默认用中档。

看到什么算成功：你手上有一张「输入 / 输出 / 思考等级」对应的三行记录，且能说出这个任务该用哪一档。价格部分不写金额——官方文档写明初次体验价截止 2026 年 11 月 30 日，之后上调，具体数字以官网定价页为准。

第 3 步：把提示改造成能命中隐式缓存的形状

做什么：按官方文档的要求，把请求改造成缓存友好的形态。要点四条：

• 移除显式上下文缓存的调用。 Gemini 4 Argon 不支持显式缓存（cachedContents / caches.create），请求里创建或引用 cached_content 的调用都要删掉。
• 改用隐式缓存。 提示的共享前缀达到一定长度后，系统默认启用隐式缓存并在命中时对缓存的输入 token 给予折扣。官方给出的下限是 4,096 token（Gemini API 侧）；Agent Platform 的文档写的是 6,144 token 及以上的共享前缀，并默认启用持久缓存。两侧阈值不同，以你实际使用的入口对应的官方文档为准，不要拿其中一边当通例。
• 调整内容顺序。 官方文档给出的建议是：把较大且常见的内容放在提示的开头，并尽量在短时间内发送具有相似前缀的请求。系统提示、工具说明、长期背景这类稳定内容前置，易变的查询与状态放在后面。
• 移除会被忽略的参数。 temperature、top_p、top_k 在这一模型上会被系统忽略，留着不报错但也没用，删掉更干净。

看到什么算成功：下一轮调用里，缓存命中的 token 计数从 0 变成非零，且这个数随着任务推进逐步增大。

第 4 步：确认缓存真的命中了

做什么：在每次响应里读 usage.total_cached_tokens，把它和输入 token 一起记进表。跑完一轮后算一下命中占输入的比例。

看到什么算成功：稳定任务跑到第二三轮之后，命中比例明显上升，且不再随调用次数剧烈波动。

没命中时的排查顺序：先确认前缀长度是否达到官方阈值；再确认多次调用之间前缀是否真的完全一致（哪怕一个时间戳、一个随机 ID 都会破坏前缀）；最后确认是否在两次调用之间改动了系统提示或工具列表。这一步的常见错误是「以为缓存了」——没有数字支撑的判断在长程任务里会一直错下去。

第 5 步：长输出改用后台执行

做什么：当任务的预计输出超过 64K token 时，按官方文档把 background 设为 true，并把 max_output_tokens 设为大于 65,536。同时把 HTTP 客户端的超时时间提到至少 15 分钟——文档明确提到难度高的提示可能需要几分钟，沿用几十秒的默认超时会在服务端还在算的时候就被客户端断开。

如果走的是 Agent Platform，官方文档说明：单次请求的生成上限可被 continuation_token 跨请求续接，使用 Google Gen AI SDK 时会自动处理，也可以自己在续传循环里管理。

看到什么算成功：长任务不再因为超时或单次输出上限被截断，结果能完整取回；续接由 SDK 或你自己的循环接管，不需要人工把上半段重新贴回去。

第 6 步：多轮状态交给服务端，别自己拼历史

做什么：多轮对话与函数调用对话改用 previous_interaction_id，让服务端保留对话状态，不要自己在客户端把历史消息拼成越来越长的数组再整包重发。

看到什么算成功：随着轮次增加，输入 token 不再线性膨胀；配合第 3 步的前缀设计，缓存命中比例保持在高位。

这一条容易被低估：自己拼历史的写法，每一轮都会把前面所有内容重新发一遍，输入量随轮次线性增长；交给服务端后，重复的部分有机会走缓存，成本结构从线性变成近似常数。

第 7 步：给每个任务装一道预算闸门

做什么：在调用层设三道阈值，并在触发时记日志而不是静默继续：

• 单轮上限：单次的输入 token 与输出 token 各设一个上限，超出即中断当前轮并把上下文交给人工或降级流程。
• 总任务上限：整个任务的累计输出 token 设一个预算，触顶即停止并留下已完成部分的产物。
• 轮次上限：工具调用轮次设上限，避免任务在反复重试里空转。

看到什么算成功：人为构造一个会失控的任务（例如故意给出互相矛盾的指令），闸门能在预算内把它拦停，并留下可追溯的日志。

装闸门的价值不在省钱，而在让异常变得可见。长程任务里真正烧钱的往往不是正常跑完的那几次，而是少数几个卡在循环里跑了几十轮的任务。

常见坑与排错

• 显式缓存的残留调用。 从别的模型迁过来时，请求里常留着创建或引用 cached_content 的代码。目标模型不支持显式缓存，这类调用要删干净；留着会让你以为「缓存配好了」，实际请求直接失败或被忽略。
• 采样参数被静默忽略。 temperature、top_p、top_k 在这一模型上会被忽略——不报错，只是没效果。调了半天输出没变化，先检查是不是在调这几个参数。
• 非流式请求的输出上限更低。 同一模型的单次输出上限，非流式直接 HTTP 请求是 32,768，流式是 65,536。用非流式跑长任务会先撞到更低的那一档，现象是「换流式就好了」。
• 客户端超时短于服务端耗时。 默认几十秒的超时在长任务上一定不够，官方文档的建议是至少 15 分钟，或直接用后台执行。
• 缓存前缀被无意的变量破坏。 提示里插了时间戳、请求 ID、随机序号，都会让前缀每次都不同，缓存永远命中不了。把易变内容挪到提示末尾是见效最快的改法。
• 输入铺满导致输出没额度。 输入输出共享统一上限，输入一侧压满之后，表现为输出被截断或思考被压缩。先划输出额度再填输入，顺序不要反。
• 把发布价当成长期预算。 官方文档写明初次体验价有截止日期，之后上调。做预算时按长期口径估，不要按当期口径估。

进阶用法

• 按任务类型分别设思考等级。 把任务按「要不要深度推理」分两类：需要推演的用高档，格式化搬运类的用低档。同一套系统里跑多档比全局设一档省钱，代价是要维护一份任务分级表。
• 把稳定知识放进前缀，把动态检索结果放后面。 检索增强的顺序会影响缓存命中率：把长期稳定的说明放前面、每轮变化的检索片段放后面，比混在一起更容易命中。
• 用缓存命中率当回归指标。 上线之后把「缓存命中占输入的比例」做成一个随版本跟踪的指标。它下降通常意味着有人改了系统提示或工具列表——这类改动对成本的影响往往比改一两句提示词大得多。
• 长任务拆成可断点续跑的段。 配合第 6 步的服务端会话状态，把长任务切成若干段并在每段结束落盘，中途失败时从上一段继续，而不是从头重跑。

常见问题

隐式缓存需要手动开启吗？

不需要。官方文档写明，对 Gemini 2.5 及更新的模型，隐式缓存默认启用，命中时自动计费折扣，无需配置。需要手动做的是调整提示结构让它容易命中——把稳定内容前置、保持前缀一致。

为什么我明明重复发了同样的内容，缓存还是没命中？

最常见的原因是前缀不完全一致：时间戳、请求 ID、随机序号、每次重排的工具列表都会破坏前缀。其次是长度没达到官方阈值。先用响应的缓存 token 字段确认到底命中了多少，再改提示，不要凭感觉调整。

长输出一定要用后台执行吗？

取决于预计长度。官方文档的口径是：需要超过 64K token 的任务才把 background 设为 true。短任务用后台执行反而增加取结果的复杂度。判断方法是先看第 1 步量出来的输出规模，再决定是否切换。

上下文窗口变大了，是不是可以不用管检索了？

不建议这么换。窗口变大解决的是「装不下」，没解决「每次都要重发」——重发的部分要付费，装得越多付得越多。检索的作用是把真正相关的内容挑出来，与窗口大小是互补关系，不是替代关系。

预算闸门会不会误杀正常任务？

会，所以阈值要按第 1 步的实测基线来设，而不是拍一个数。建议先按基线的若干倍设一个宽松值跑一段时间，观察触发记录里有没有正常任务被拦，再逐步收紧。

相关工具与内容

• Gemini 工具页：本篇示例所用模型对应的产品入口。
• Kimi 工具页：本周把上下文窗口提到 100 万 token 的另一条产品线。
• AI编程分类页：长程任务最常见的落地场景之一。
• AI智能体分类页：编排与执行层的工具清单。
• Gemini 4 Argon 发布快讯：本篇引用的官方参数所对应的发布事件。
• Kimi K3.1 Pro 发布快讯：长上下文成为常态的另一条一手来源。
• 把智能体的追踪接进 OTLP 后端：预算闸门之后，下一步是把每次调用看清。
• Cursor 工具页：日常长程编码任务的一个接入口。