文档索引
获取完整的文档索引： https://docs.aihubmix.com/llms.txt
使用此文件在进一步探索之前发现所有可用页面。

2026年7月 Kimi K3 指南：reasoning_effort 最大值、思维历史、动态工具加载、结构化输出、自动缓存、部分前缀和视觉输入。

本文涵盖了 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`）。

```text theme={null}
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)
```

```text theme={null}
# 多轮：逐字传回之前的助手消息
messages = [
    {"role": "user", "content": "法国的首都是什么？"},
    {"role": "assistant", "content": "巴黎。", "reasoning_content": "<reasoning_content from the previous response>"},
    {"role": "user", "content": "那它的人口呢？"},
]
```

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

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

```text theme={null}
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` 内容块返回；在多轮对话中，逐字传回之前助手内容块（包括思维块）。

```text theme={null}
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`，注入的工具在后续轮次生效，并且该消息必须在每个请求中再次包含。

```text theme={null}
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": "现在几点了？"},
]
```

```text theme={null}
# 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` 参数中声明所有工具。

```text theme={null}
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` 参数中声明所有工具。

```text theme={null}
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` 模式。

```text theme={null}
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` 声明。

```text theme={null}
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 而异）。缓存定价在 模型页面 上。

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

> **验证**：第二个请求使用相同长前缀时在 `usage.prompt_tokens_details.cached_tokens` 中报告命中。

```text theme={null} # 使用相同长指令的第二次响应调用 "input_tokens_details": {"cached_tokens": 1536} ``` ```text theme={null} # 使用相同长系统提示的第二次消息调用 "cache_read_input_tokens": 1536 ```

7. partial 前缀完成

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

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

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

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

> **验证**：生成从给定前缀继续，而不重复它。

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

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

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

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

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

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

8. 视觉输入

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

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

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

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

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

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

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

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

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