Kimi 的 reasoning_effort 怎么调：low/high/max 三档怎么选
数据截至 2026-08，价格与限额以各官网为准。本文只讲计费与接入机制，不列具体价格数字。
一句话：reasoning_effort 是 Kimi K3 请求顶层的一个字符串字段，可选 low / high / max，默认 max；它不是「开不开思考」的开关，因为 K3 的思考根本关不掉，它只决定思考得多深。 官方给的选档原则很朴素——任务越复杂选越高档位，简单任务用较低档位可以降低延迟和 token 消耗。真正容易栽跟头的不是怎么传这个字段，而是三件配套的事：档位一旦中途切换会破坏前缀缓存命中，所以官方建议在会话开始前就把档位定死；思考产生的 reasoning_content 是计入 token 消耗的；K3 的多轮对话和工具调用必须把 API 返回的完整 assistant message 原样回传，reasoning_content 和 tool_calls 一个都不能漏。把这三条记住，这个字段就没什么坑了。
先接受一个前提：K3 的思维链关不掉
很多人是抱着「怎么关掉思考省点钱」的念头找到这个字段的，先说结论：官方常见问题里写得很直白，K3 始终开启思考模式，目前关不了。如果你觉得思考过程太长，官方给的办法是把 reasoning_effort 设置为 low 来降低推理强度——注意措辞是「降低推理强度」，不是「关闭思考」。
所以在 K3 上，你手里能动的只有档位，没有开关。这跟 K2.x 那一代的心智模型完全不同：K2.6、K2.5 是通过 thinking 参数控制思考行为的，thinking.type 可以传 "enabled" 或 "disabled"，默认开启、可以按需关闭；K2.7 Code 则是始终开启思考，显式传 "disabled" 会报错。而 reasoning_effort 这个字段，按官方的模型参数参考，只有 kimi-k3 支持，K2.7 Code、K2.6、K2.5 一律标注为不支持。
反过来也成立：K3 不支持 thinking 参数。官方在推理强度文档里专门交代了迁移动作——从 K2.x 迁到 K3 时，移除 K2.x 的 thinking 配置，改为按需使用顶层 reasoning_effort。这两个字段是替代关系，不是并存关系，别想着同时传。
关于 K3 的「保留式思考（Preserved Thinking）」，官方的说法是始终开启，跟推理强度一样没有开关。K2.6 那边保留行为是靠 thinking.keep 控制的（默认不保留历史轮次的思考，传 "all" 才启用），K3 这边不需要你操心开关，但需要你操心回传，后面会展开。
它是顶层字段，不是嵌套字段
这是最容易写错的地方。reasoning_effort 放在 Chat Completions 请求的顶层，跟 model、messages 平级，而不是像 K2.x 的 thinking 那样再套一层对象。官方的 JSON 示例长这样：model 一行、messages 一行、reasoning_effort 一行，三个键并列。
按官方的字段说明表，它的类型是 string，必填一栏写的是「否」——也就是说你完全可以不传，不传就走默认的 max。这个默认值挺关键：不传等于选了最高档，而不是等于选了某个中间档位。所以如果你的场景是大批量的简单任务，什么都不写反而是最费的那个选择。
用 OpenAI 兼容 SDK 的话，官方 Python 示例是直接把它当成 client.chat.completions.create() 的一个参数传的，跟 model、messages 并列，客户端初始化时 base_url 指向 https://api.moonshot.cn/v1，api_key 从环境变量 MOONSHOT_API_KEY 读。不过并非所有上层框架都能直接透传顶层字段——官方在 Hermes Agent 的接入文档里给的 YAML 配置，就是把 reasoning_effort 放在 extra_body 下面传下去的。如果你用的框架不认识这个参数，去找它的「透传额外请求体」入口，而不是硬塞。
读取思考内容也有个小细节：官方示例里没有直接 message.reasoning_content 取值，而是先 hasattr(message, "reasoning_content") 判断存在再取。官方对 K3 的描述是「可能返回 reasoning_content」，用了「可能」两个字，所以照着官方示例做存在性判断是稳妥的写法，别默认它一定在。
三档怎么选：官方只给了定性原则
必须诚实地说：官方文档没有给出三个档位各自的量化差异——没有说 low 比 max 少用多少推理 token，也没有说延迟差多少。文档里能查到的只有定性原则，出自常见问题那一条：任务越复杂，建议选择越高档位；简单任务使用较低档位可以降低延迟和 Token 消耗。
推理强度文档开头那句概括也是同一个意思——这个字段调节的是推理深度、延迟与 token 消耗三者。换句话说，档位调高不是单纯「变聪明」，而是拿延迟和 token 去换深度。官方给的示例用的是一道数列通项公式的推导题，配的是 high，从示例本身也能看出它面向的是需要多步推演的任务。
所以实际选档，建议按任务形态而不是按「感觉」来分：格式转换、分类打标、抽字段这类答案几乎是确定的活儿，往低档走；需要多步推演、跨文件改代码、长链路 agent 规划的，往高档走。至于中间那些拿不准的，与其反复试档位，不如先把提示词和上下文结构理顺——推理强度救不了一个说不清需求的 prompt。
★ 中途切换档位会破坏前缀缓存
这条是整个字段最反直觉、也最值钱的一条，写在官方的模型参数参考里：切换档位会破坏前缀缓存命中，建议在会话开始前确定 effort 档位，避免中途切换。K3 工具调用最佳实践那一页也重复了同样的建议，并把「会话开始前确定顶层 reasoning_effort 配置」直接写进了推荐流程的最后一步。
为什么值钱？因为 Kimi 的上下文缓存是自动的——官方常见问题里明确说了不需要手动配置，不用创建 cache ID、不用设 TTL、不用加额外请求参数，平台会对重复的初始上下文自动尝试缓存，你要做的只是保持 system prompt、工具定义、长文档这类初始前缀稳定。既然你没有手动开关可以控制缓存，那么任何会隐性破坏前缀的行为都值得警惕，而档位切换就是其中一个，而且它长得完全不像会影响缓存的样子。
官方在同一份最佳实践里还顺手划清了几条边界，可以对照着记：在 messages 末尾追加动态工具声明，不会影响已有前缀的缓存；删除或修改之前的工具声明，可能影响变更位置之后的缓存命中；修改 tool_choice 不会破坏前缀缓存。另外还有一条门槛——前一个请求的 prompt token 数需要超过官方给出的下限，新请求才可能命中前缀缓存，低于该下限的请求不会被缓存而是被丢弃，具体数值以官方上下文缓存文档为准。
落到工程上就一句话：把档位当成会话级的启动参数，跟 model 一样在会话开始时定下来，不要做成可以随时调的运行时开关。想给用户提供「快速模式 / 深度模式」，那就让它开一个新会话，而不是在同一条对话里换档。缓存与计费的通用机制可以看API 缓存计费机制这一篇，Kimi 这边只是它的一种具体形态。
思考内容是要计费的，而且必须回传
官方对这一点没打马虎眼。思考模型文档的常见问题里直接问了「reasoning_content 会消耗额外的 token 吗」，答案是「是的」，它会计入输入/输出 token 消耗，具体计费方式指向官方定价页。文档里还专门提醒：开启保留式思考后，历史思考内容会持续占用上下文长度并计费，请酌情使用。
而 K3 的麻烦之处在于，保留式思考是始终开启的，你没有「不保留以省钱」这个选项。官方对 K3 的要求是硬性的，而且推理强度文档与 Agent 搭建文档都写了同一条。推理强度文档在字段说明后面直接补了一句：K3 的多轮对话和工具调用必须将 API 返回的完整 assistant message 原样回传到 messages，包括 reasoning_content 和 tool_calls。Agent 搭建文档则是在讲 K3 的 API 配置时把后果一并说清楚了——工具循环必须把 SDK 返回的完整 assistant message 追加到 messages，不能只复制 content 和 tool_calls，否则会丢失可能返回的 reasoning_content，破坏后续工具调用上下文。两处措辞不同，指向的却是同一件事：这个字段不是可选的调试信息，而是会话状态的一部分。
把这两条放在一起看，K3 的成本结构就清楚了：轮次越多，被反复回传的历史思考内容越厚，输入侧的账单就越往上走。这也是为什么前缀缓存对 K3 特别重要，也是为什么档位切换破坏缓存这件事的代价比看上去大。想系统地把这笔账管起来，可以配合API 成本监控怎么做那篇的方法，先把用量拆到会话粒度再谈优化。
顺带一提，K3 的上下文窗口官方标注为 1M tokens（以官方文档为准），窗口大不等于可以随便塞——塞进去的每一个 token 都还是要计的。至于 max_completion_tokens，官方给了默认值和可设上限，具体数值以官方文档当前版本为准。
从 K2.x 或 OpenAI 代码迁过来要改什么
官方模型参数参考里的常见问题几乎把迁移清单写好了，照抄即可：
从 kimi-k2.6 切到 kimi-k3，把 model 换掉，移除 K2.x 的 thinking 配置，需要显式设置推理强度就用顶层 reasoning_effort，并且要把完整 assistant message 原样回传。从 kimi-k2.7-code 切到 kimi-k3 更省事，替换 model 即可，继续原样回传完整 assistant message。
原来代码里用的是 OpenAI 那套 reasoning_effort 的，官方的回答是不需要改——K3 支持顶层 reasoning_effort，可选值为 low / high / max，默认 max。这是这个字段设计上最讨巧的地方：它借用了业界已有的参数名，让兼容层代码基本不用动。但要留意可选值集合未必与你原来那家一致，迁过来之后确认一下你传的值在这三档之内。
还有一个跟推理强度没直接关系、但迁移时一定会撞上的点：官方明确 kimi-k3 的 temperature 是固定值，传其他值会报错，并建议不要显式传入。老代码里习惯性带着 temperature 参数的，迁移时顺手删掉。K2.x 各系列的固定值规则各不相同，别互相套用。
最后，几个容易栽的地方
第一，别把 reasoning_effort 和 thinking 混着传，前者只属于 K3，后者只属于 K2.x。第二，别在同一个会话里动态调档，代价是缓存。第三，不传不等于省钱，默认就是最高档。第四，如果你还没能调通 K3，先确认账户条件——官方常见问题写的是在开放平台完成充值后即可解锁调用 Kimi K3，新用户注册认证赠送的代金券不可用于 Kimi K3，具体门槛与账户等级规则以官方充值与限速页面为准。
想把 K3 的思考行为、reasoning_content 的读取和多轮保留策略一次性搞明白，接着读Kimi 思考模型怎么用会更连贯——推理强度只是那套机制上的一个旋钮，旋钮之外的部分才是决定输出质量的主体。