Kimi 的 Partial Mode 是什么：怎么让它按你给的开头往下写

2026-08-25

数据截至 2026-08，价格与限额以各官网为准。本文只讲计费与接入机制，不列具体价格数字。

一句话说完：Partial Mode 不是一个开关参数，而是一种消息构造技巧——你在 messages 数组的最后追加一条 role 为 assistant、partial 为真的消息，把希望模型”接着说”的那半句话放进它的 content，模型就会被强制从这段内容开头往下生成。Kimi 官方 API 参考里给它的另一个名字是 Prefill，也就是预填输出前缀。它最常用在三件事上：把回复的开头固定成某个话术或某种格式、在 finish_reason 为 length 时续写被截断的长输出、配合 name 字段稳住角色扮演的口吻。要注意的地方也有三个：模型返回的内容里不包含你喂进去的前缀，得自己拼；思考模型续写时必须把上一轮的 reasoning_content 一起回传；官方明确不建议把它和 response_format 的 JSON 对象模式混用。

它改的是 messages，不是请求参数

很多人第一次看到 Partial Mode 会去请求体顶层找开关，找不到就以为要换端点。其实不用。官方文档给的用法只有一句话：在 messages 列表尾部追加一条额外的 message，把 role 设成 assistant、partial 设成真值，再把想让模型顺着往下说的内容放到这条消息的 content 字段里。

这个设计的含义是：正常对话里 messages 的最后一条通常是 user 消息，模型从零开始组织回复；而 Partial Mode 相当于你替模型把回复的第一段先写好了，模型接手的是一个”已经开了头的句子”，它只能顺着往下续。Kimi 官方文档里对这个动作有个很形象的说法，是把话喂到模型嘴里，让它接着这句话继续往下说。

在 Chat Completions 的接口说明里，这条能力被写进了接口的能力描述——该接口支持标准聊天、Partial Mode 和工具调用三类用法。所以它不是某个 SDK 的封装糖，而是服务端消息协议的一部分，用官方 SDK、用别的兼容 OpenAI 协议的客户端，甚至直接拼 JSON 发 HTTP 请求，都是同一套写法。

官方示例里的客户端初始化没什么特别：base_url 指向 Kimi 的 v1 接口地址，api_key 从 MOONSHOT_API_KEY 环境变量读。示例默认用的模型是 kimi-k3，官方也说明了换成其他模型时只需替换 model 字段，但各模型的参数配置存在差异，具体差异要看官方的模型参数参考页。

completion = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "system", "content": "……"},
        {"role": "user", "content": "你好？"},
        {
            "partial": True,          # 开启 Partial Mode
            "role": "assistant",      # 追加在用户提问之后
            "content": "尊敬的用户您好，",
        },
    ],
)

最容易忘的一步：返回值里没有你喂进去的那半句

这是新手第一次用 Partial Mode 最容易踩的坑，也是官方文档专门用一整条要点强调的事情：你放在 content 里的前缀，模型不会再重复输出一遍。接口返回的 choices[0].message.content 里只有”续写出来的那部分”。

所以官方给的完整用法是三步，缺一步结果就不对：

在 messages 末尾加那条 role 为 assistant、partial 为真的消息；
把要喂的内容放进 content，模型会强制以它开头生成回复；
把第二步里的 content 拼接到模型生成的内容之前，才组成完整的回复。

官方示例代码里那行打印语句，就是把固定话术和 completion.choices[0].message.content 用加号拼起来再输出的。如果你的业务是把模型返回值直接落库或者直接推给前端，记得在这一层补上拼接，否则用户看到的回复会莫名其妙地少了个开头。

顺带说一个格式向的用法，官方 API 参考里给了个很实用的例子：把前缀设成代码块的起始标记加换行，模型就会从这个标记之后直接开始生成代码，而不是先输出一段解释文字再写代码。同理，想让模型直接吐一个 JSON 对象，可以把左花括号预填进去。这类”卡格式”的场景，比在提示词里反复叮嘱模型不要说废话要可靠得多——因为它不是在请求模型配合，而是物理上把开头占掉了。

用它续写被截断的输出：先看 finish_reason

第二个高频场景是补全被截断的长输出。官方的判断依据很明确：如果对输入输出 Token 数量的预估出现偏差，导致最大输出 Token 的上限被设置得过低，模型就没法完整输出，此时响应里 finish_reason 的值是 length。

Kimi 的排障文档对这个字段的解释更细一层：finish_reason 为 length 表明生成内容所占的 Token 数超过了请求中的 max_completion_tokens，接口只会返回上限那么多 Token 的内容，多余的部分会被直接丢弃。这里有个细节值得留意——Partial Mode 的使用指南里示例写的还是 max_tokens，而 API 参考里 max_tokens 已被标注为弃用、建议改用 max_completion_tokens。两个字段名在文档不同页面里并存，写代码时以 API 参考页的当前版本为准。

续写流程本身不复杂：

第一次请求返回后，检查 choices[0].finish_reason 是不是 length；
是的话，把 choices[0].message.content 取出来当作 prefix；
用同样的 messages 再发一次请求，末尾追加一条 role 为 assistant、content 为 prefix、partial 为真的消息；
这一次把输出上限设得足够大，让模型能把剩下的内容写完。

官方对第四步的提醒是把上限设为一个较大的值以确保能完整输出。至于多大算够，排障页给了个可操作的办法：用 estimate-token-count 接口先算出输入内容占多少 Token，再从所选模型支持的最大上下文窗口里扣掉这部分，剩下的就是输出可用的空间。这比拍脑袋填一个数靠谱。

思考模型的两个额外条件

如果你用的是会输出思考内容的模型，续写这件事上有两个坑，官方都写在了醒目位置。

第一，上一轮返回的 reasoning_content 必须一起回传。官方示例里那条续写用的 assistant 消息，除了 content 和 partial，还带了 reasoning_content 字段，注释直说思考模式需要它。这和 Kimi 思考模型文档里保留式思考的要求是一致的——多轮对话和工具调用要把 API 返回的完整 assistant message 原样回传，包括 reasoning_content。想了解这套机制的全貌，可以看Kimi 思考模型怎么用。

第二，输出上限会优先被思考消耗。官方在这一节挂了一条注意事项：kimi-k3 默认开启思考，输出上限设得较小时，截断点可能落在思考阶段——这时候 content 仍然是空的，而 finish_reason 已经是 length 了。如果你的代码只判断 finish_reason，就会拿一个空字符串当前缀发出去，结果是模型从头重新生成，续写完全没起作用。官方给的对策是把上限设得足够大，确保截断发生在正文阶段。

工程上更稳妥的做法是在第二步加一道判断：prefix 为空就不要走续写分支，直接换成”加大上限重新生成”的分支。这个分支判断官方文档没写，是从上面那条注意事项推出来的处理方式，你可以按自己的业务决定要不要加。关于输出长度这件事本身，站内另有一篇API 输出长度控制讲通用做法。

name 字段：让模型以某个身份开口

name 是 Partial Mode 里的一个特殊字段。官方对它的定义是：强化模型对角色的认知，强制模型以 name 指定的角色的口吻输出内容，并且明确说了**name 字段是输出内容前缀的一部分**。

后半句才是关键。既然 name 本身就充当前缀，那 content 就不一定要写东西——官方那个角色扮演示例里，content 给的是空字符串，只靠 name 指定角色名，模型就会以该角色的身份开始输出。这是一种比”在 content 里写死开场白”更轻的引导方式：你不规定它说什么，只规定它是谁。

{
    "partial": True,
    "role": "assistant",
    "name": "凯尔希",
    "content": "",
}

在 Chat Completions 的接口示例里，name 是标准消息结构里本来就有的字段，默认可以为空。所以它不是 Partial Mode 专属的新字段，而是在 Partial Mode 下被赋予了额外含义。

别和 JSON 对象模式混用

这一条是官方明确写出来的限制，值得单独拎出来：请勿将 Partial Mode 与把 response_format 设为 JSON 对象模式的做法混用，否则可能获得预期外的模型回复。官方给的替代路径有两条——要么直接用 Structured Output，也就是走 JSON Schema 那条路；要么就单独设置 partial 为真并预填左花括号，不要两边一起上。

在专门讲 response_format 的那一页里，官方把兼容性说得更细，而且是按模型分开说的：面向代码场景的那个思考模型在简单 schema 下与 partial 为真混用通常正常，但复杂 schema 仍可能破坏结构约束；而 kimi-k2.6 在 partial 为真时更容易输出 schema 之外的字段，因此官方不建议在该模型上混用。同一页还提到，kimi-k2.6 在复杂 schema 下本身就偶有不稳定表现，建议优先用简单 schema 并在业务层做二次校验。

这里要小心不要把结论扩大：官方说的是”这两个模型在这两种情况下的表现”，不是”所有模型都不能混用”，也不是”简单 schema 就一定安全”。要混用的话，自己那套 schema 得在业务层留校验。

顺便澄清一个容易被张冠李戴的说法：官方在 response_format 页里写的”是否设置 response_format 不会破坏前缀缓存”，说的是 response_format 这个参数，不是 Partial Mode。Partial Mode 对缓存命中的影响，官方文档里没有找到相关说明。缓存计费的通用机制可以看API 缓存计费机制，但别把那篇里的结论直接套到 Partial Mode 上。

长对话里角色跑偏，官方给的是提示词层面的办法

Partial Mode 加 name 能稳住”这一轮”的口吻，但对话轮次一多，角色还是会飘。官方在同一页给了四条通用方法，都属于提示词工程而不是参数开关：

提供清晰的角色描述，把个性、背景以及可能具有的具体特征或怪癖介绍详细；
增加关于角色的细节，包括说话的语气、风格、个性，甚至背景故事和动机；
指导角色在各种情况下如何行动，预计会遇到的特定输入要在系统提示词里给明确指令；
定期强化角色设定，轮次非常长时可以重新用系统提示词把设定再说一遍，尤其是模型开始偏离的时候。

第四条官方还配了示例代码，做法是在多轮对话之后、在那条 Partial Mode 消息之前，再插入一条内容相同的 system 消息，然后才追加带 name 的 assistant 前缀消息。这个顺序不能颠倒——系统提示词要在前面，前缀消息始终是 messages 的最后一条。

最后：三个最容易栽的地方

第一是忘了拼前缀，返回值直接用，用户看到的回复缺头。第二是思考模型续写时漏传 reasoning_content，或者没判断 content 是不是空就当前缀发出去。第三是和 JSON 对象模式硬凑，出了怪结果再回头怀疑模型能力。

这三件事都不是”效果好不好”的问题，是”写法对不对”的问题，看一遍官方文档的要点清单就能全部避开。真正需要你自己拿主意的只有一件：这个场景到底该用 Partial Mode 卡开头，还是该用 Structured Output 卡结构。前者管的是”从哪儿开始说”，后者管的是”最终长成什么形状”，别拿一个去干另一个的活。想先把 Kimi 的基础调用跑通，可以从Kimi API 怎么接入那篇开始。