文件索引
在此處獲取完整的文件索引：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