Kimi K3 实操指南：新参数与 API 支持矩阵

本文涵盖了 Kimi K3 的新参数和使用说明。在 AIHubMix 上，K3 可通过聊天完成、响应和 Claude 兼容消息 API 使用。另请参见：Moonshot 官方平台文档。

每个部分中的“验证”结论和示例响应来自于 2026-07-17 通过 AIHubMix API（聊天完成/响应/消息）进行的实际调用。

1. 模型规格一览

验证：两个 stop 限制已被验证，超出任一限制将返回 400；消息 API 对 stop_sequences 应用相同的验证。

❗ 当触发停止序列时，消息 API 不遵循 Anthropic 语义：在测试中，stop_reason 为 "end_turn"（而不是 "stop_sequence"），stop_sequence 为 null，并且停止词之前的可见文本可能为空。依赖这两个字段来检测截断的客户端应注意。

# 使用 6 个条目的停止 / 一个 33 字节的条目 -> HTTP 400
"无效请求：停止数组过长。预期最大长度为 5 的数组，但实际得到的数组长度为 6"
"无效请求：停止序列不得超过 32，但实际得到 33"

2. 思维模式：reasoning_effort 仅支持 max

K3 的思维默认开启，reasoning_effort 仅支持一个级别："max"。

多轮对话必须逐字传回思维历史：根据 Moonshot 的官方文档，K3 是在保留思维的情况下训练的，因此在多轮对话中，之前的助手消息必须完整且未修改地传回（包括思维内容）。缺失的思维历史会导致输出质量不稳定。如果您使用会话管理框架或代理层，请确认思维内容未被截断地传回。
聊天完成

思维内容在响应的 reasoning_content 字段中返回；在多轮对话中，逐字传回之前的助手消息（包括 reasoning_content）。

from openai import OpenAI

client = OpenAI(
    base_url="https://aihubmix.com/v1",
    api_key="<AIHUBMIX_API_KEY>",
)

completion = client.chat.completions.create(
    model="kimi-k3",
    reasoning_effort="max",
    messages=[
        {"role": "user", "content": "一只蜗牛在 10 米深的井底。它每天爬升 3 米，但每晚滑回 2 米。它需要多少天才能到达井口？"}
    ],
)

print(completion.choices[0].message.reasoning_content)
print(completion.choices[0].message.content)

# 多轮：逐字传回之前的助手消息
messages = [
    {"role": "user", "content": "法国的首都是什么？"},
    {"role": "assistant", "content": "巴黎。", "reasoning_content": "<来自上一个响应的 reasoning_content>"},
    {"role": "user", "content": "那它的人口呢？"},
]

验证：响应返回 reasoning_content；在逐字传回之前的助手消息（包括 reasoning_content）后，后续轮次正常回答。
响应

思维内容作为 reasoning 输出项返回；在多轮对话中，将之前轮次的输出项（reasoning + message）逐字附加回 input。

from openai import OpenAI

client = OpenAI(
    base_url="https://aihubmix.com/v1",
    api_key="<AIHUBMIX_API_KEY>",
)

response = client.responses.create(
    model="kimi-k3",
    input="用一个词回答：法国的首都",
)

# 观察到的 response.output 项类型：["reasoning", "message"]; 文本："巴黎"
# 多轮：input = [第一条用户消息] + response.output + [下一条用户消息]
# 观察到的第二轮回答输出项传回："柏林"

消息

思维内容作为原生 thinking 内容块返回；在多轮对话中，逐字传回之前的助手内容块（包括思维块）。

from anthropic import Anthropic

client = Anthropic(
    api_key="<AIHUBMIX_API_KEY>",
    base_url="https://aihubmix.com"
)

response = client.messages.create(
    model="kimi-k3",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "用一个词回答：法国的首都"}
    ],
)

# 观察到的 response.content 块类型：["thinking", "text"]; 文本："巴黎"
# 多轮：逐字传回 response.content 作为助手消息

3. 采样参数是固定的

K3 的采样参数由模型提供者固定：temperature 1.0，top_p 0.95，n 1，以及 presence_penalty / frequency_penalty 0。官方建议在请求中省略这些参数。

注意：固定的采样值是官方规格的一部分，无法通过响应信号进行验证；请遵循官方建议，省略这些参数。

4. 工具调用和动态工具加载

tools 支持最多 128 个工具；tool_choice 支持强制和禁用工具调用。K3 还支持动态工具加载：通过系统消息的 tools 字段在对话中注入新工具（这是特定于聊天 API 的消息形状）。
聊天完成

tool_choice 支持 auto / none / required；required 强制模型调用工具。动态工具加载：注入工具的系统消息不带 content，注入的工具对后续轮次生效，且该消息必须在每个请求中再次包含。

messages = [
    {"role": "system", "content": "你是一个有帮助的助手。"},
    {"role": "user", "content": "你好。"},
    {"role": "assistant", "content": "嗨，我能帮你什么？"},
    # 在对话中间注入新工具：仅工具字段，无内容
    {
        "role": "system",
        "tools": [
            {
                "type": "function",
                "function": {
                    "name": "get_time",
                    "description": "获取当前时间",
                    "parameters": {"type": "object", "properties": {}},
                },
            }
        ],
    },
    {"role": "user", "content": "现在几点了？"},
]

# tool_choice="required" 与提示 "你好" -> 模型被强制调用工具
"finish_reason": "tool_calls",
"tool_calls": [{"function": {"name": "get_weather", "arguments": "{\"city\":\"New York\"}"}}]

验证：tool_choice: "required" 即使对于无关提示也会强制调用工具；"none" 抑制工具调用；通过没有 content 的系统消息在对话中注入的工具可以正常调用。
响应

工具定义使用扁平结构（name 在顶层）；强制调用同样使用 tool_choice: "required"，调用作为 function_call 输出项返回。动态工具加载支持正在进行中；目前，请在顶层 tools 参数中声明所有工具。

response = client.responses.create(
    model="kimi-k3",
    input="你好",
    tools=[{
        "type": "function",
        "name": "get_weather",
        "description": "获取城市天气",
        "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
    }],
    tool_choice="required",
)

# 观察到的输出包含：{"type": "function_call", "name": "get_weather", "arguments": "{\"city\":\"London\"}"}

消息

工具使用 Anthropic 格式（input_schema）；使用 tool_choice: {"type": "any"} 强制调用，并使用 {"type": "none"} 禁用调用。❗ Kimi K3 的官方消息（Anthropic 兼容）端点不支持动态工具加载：在测试中，注入消息返回 200，但注入的工具没有效果（模型无法调用它）。在顶层 tools 参数中声明所有工具。

response = client.messages.create(
    model="kimi-k3",
    max_tokens=4096,
    tools=[{
        "name": "get_weather",
        "description": "获取城市天气",
        "input_schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
    }],
    tool_choice={"type": "any"},
    messages=[{"role": "user", "content": "你好"}],
)

# 观察到：stop_reason "tool_use"; 内容包含调用 get_weather 的 tool_use 块

5. 结构化输出

结构化输出使模型返回严格符合给定 JSON Schema 的内容。
聊天完成

response_format 支持 json_schema 且为 strict 模式。

completion = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "user", "content": "巴黎是法国的首都。提取城市名称。"}
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "extract",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        },
    },
)

# 观察到的响应内容：{"city":"巴黎"}

验证：输出是符合模式的有效 JSON。
响应

结构化输出通过 text.format 声明。

response = client.responses.create(
    model="kimi-k3",
    input="巴黎是法国的首都。提取城市名称。",
    text={
        "format": {
            "type": "json_schema",
            "name": "extract",
            "strict": True,
            "schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
        }
    },
)

# 观察到的输出文本：{"city":"巴黎"}

消息

❗ Kimi K3 的官方消息（Anthropic 兼容）端点不支持结构化输出：结构化输出字段会被静默忽略：请求返回 HTTP 200 和自由格式文本，没有错误或回退通知，后续的 JSON 解析将失败。当您需要结构化输出时，请使用聊天完成或响应 API。

6. 上下文缓存是自动的

K3 的上下文缓存自动启用，无需参数。当重复的长前缀命中缓存时，命中数量会在使用情况中报告（字段名称因 API 而异）。缓存定价在 模型页面 上。
聊天完成

# 使用相同长前缀的第二次调用的使用情况
"prompt_tokens_details": {"cached_tokens": 1536}

验证：使用相同长前缀的第二次请求在 usage.prompt_tokens_details.cached_tokens 中报告命中。
响应

# 使用相同长指令的第二次响应调用的使用情况
"input_tokens_details": {"cached_tokens": 1536}

消息

# 使用相同长系统提示的第二次消息调用的使用情况
"cache_read_input_tokens": 1536

7. partial 前缀完成

前缀完成使模型从给定前缀继续生成，非常适合代码完成和格式控制输出。
聊天完成

在最后的助手消息中传递 "partial": true。

messages = [
    {"role": "user", "content": "写一首关于海的俳句。"},
    {"role": "assistant", "content": "波浪折叠成泡沫，", "partial": True},
]

# 前缀："波浪折叠成泡沫，"  -> 模型返回的续写
# 盐在空气中飘荡—
# 月亮将潮水拉回家。

验证：生成从给定前缀继续，而不重复前缀。
响应

将前缀作为助手消息传递到 input 数组的末尾；不需要 partial 参数。

response = client.responses.create(
    model="kimi-k3",
    input=[
        {"role": "user", "content": "写一首关于海的俳句。"},
        {"role": "assistant", "content": "波浪折叠成泡沫，"},
    ],
)

# 观察到的续写："盐在空气中飘荡— / 月亮将潮水拉回家。"

消息

通过协议的原生助手预填充实现相同的功能，无需 partial 参数：将前缀作为最后的助手消息传递。

response = client.messages.create(
    model="kimi-k3",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "写一首关于海的俳句。"},
        {"role": "assistant", "content": "波浪折叠成泡沫，"},
    ],
)

# 观察到的续写："盐风带来了海鸥的哭声— / 潮水拉动..."

8. 视觉输入

图像以 base64 形式传递；内容块格式因 API 而异。
聊天完成

messages = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "这张图像的主色是什么？一个词。"},
            {"type": "image_url", "image_url": {"url": "data:image/png;base64,<BASE64>"}},
        ],
    }
]

# 观察到的响应内容："红色"  （输入：一个 64x64 的纯红色 PNG）

验证：base64 图像输入有效，模型正确描述了测试图像。
响应

input = [
    {
        "role": "user",
        "content": [
            {"type": "input_text", "text": "这张图像的主色是什么？一个词。"},
            {"type": "input_image", "image_url": "data:image/png;base64,<BASE64>"},
        ],
    }
]

# 观察到的输出文本："红色"

消息

messages = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "这张图像的主色是什么？一个词。"},
            {"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": "<BASE64>"}},
        ],
    }
]

# 观察到的响应文本："红色"

9. 验证参考：长单次调用任务的延迟和使用情况

K3 的思维固定在最大级别，因此复杂任务的单次请求所需时间显著长于典型模型。从单文件 HTML 游戏生成任务（一个提示和一个参考图像，一次生成，无需迭代）测得的数据：单次请求耗时 2,541 秒（约 42 分钟），生成了 74,994 个完成令牌，其中 54,486 个（73%）为思维令牌；最终输出为 1,275 行可直接运行的代码，finish_reason 为 stop。

客户端建议：

• 将客户端超时设置为几分钟或更长，并优先考虑长任务的流式处理；
• 在 max_completion_tokens 中留出充足的余地：在这种情况下，思维单独消耗了 54,486 个令牌。

10. 能力 × API 支持矩阵

下表中的每个单元格均在 2026-07-17 通过实际调用 AIHubMix 生产 API 进行验证；每个单元格显示相应 API 的参数/字段语法。

常见问题

K3 在 AIHubMix 上支持哪些 API？
聊天完成（/v1/chat/completions）、响应（/v1/responses）和 Claude 兼容消息 API（/v1/messages）。

思维可以禁用或降低吗？
不能。K3 的思维默认开启，reasoning_effort 仅支持单一的 "max" 级别。

为什么在多轮对话中必须传回 reasoning_content？
K3 是在保留思维的情况下训练的；Moonshot 要求之前的助手消息必须完整且未修改地传回。缺失的思维历史会导致输出质量不稳定。

stop 参数的限制是什么？
最多 5 个停止序列，每个不超过 32 字节；超出任一限制将返回 400 错误。

消息 API 支持结构化输出吗？
❗ 不支持。Kimi K3 的官方消息（Anthropic 兼容）端点静默忽略结构化输出字段（返回 200 和自由格式文本，没有错误）。对于结构化输出，请在聊天完成或响应中使用 response_format 或 text.format。

为什么单个 K3 请求耗时这么长？
K3 的思维固定在最大级别，思维令牌在复杂任务中占很大比例（在测量的情况下占 73% 的完成令牌）。将客户端超时设置为几分钟或更长，并使用流式处理。

有关定价和实时状态，请参见 Kimi K3 模型页面；有关更多模型，请访问 模型库。

最后更新：2026-07-17