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