Skip to main content
三方模型調用教程

Kimi

本文檔介紹如何調用阿里雲百鍊部署的 Kimi 模型推理服務。

Moonshot-Kimi-K2-Instruct、kimi-k2-thinking 已於2026年7月9日下架。推薦轉用:qwen3.7-plusqwen3.8-maxqwen3.8-flash
支援的地區:新加坡、日本(東京)、美國(維吉尼亞)、華北2(北京)、德國(法蘭克福)、中國香港。 模型體驗:您可以前往模型體驗中心體驗 Kimi 模型效果。 不同地區的服務接入地址不同,請根據您選擇的地區配置對應的 Base URL。
  • OpenAI相容
  • DashScope
  • 新加坡
  • 美國(維吉尼亞)
  • 德國(法蘭克福)
  • 華北2(北京)
  • 日本(東京)
  • 中國香港
SDK 調用配置的base_urlhttps://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1HTTP 要求地址:POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions
調用時請將{WorkspaceId}替換為真實的業務空間ID 你需要已擷取與配置 API Key並完成配置API Key到環境變數。如果通過SDK調用,需要安裝SDK

快速開始

以下為純文字輸入樣本。多模態樣本請參見多模態調用樣本
  • OpenAI相容
  • DashScope
  • Anthropic相容
  • Python
  • Node.js
  • HTTP
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 以下為華北2(北京)地區的URL。請將 {WorkspaceId} 替換為您的百鍊業務空間ID,各地區的URL不同。
    base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
)

completion = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "你是誰"}],
    stream=True,
    extra_body={"enable_thinking": True},
)

reasoning_content = ""  # 完整思考過程
answer_content = ""     # 完整回複
is_answering = False    # 是否進入回複階段

print("\n" + "=" * 20 + "思考過程" + "=" * 20 + "\n")

for chunk in completion:
    if chunk.choices:
        delta = chunk.choices[0].delta
        # 只收集思考內容
        if hasattr(delta, "reasoning_content") and delta.reasoning_content is not None:
            if not is_answering:
                print(delta.reasoning_content, end="", flush=True)
            reasoning_content += delta.reasoning_content
        # 收到content,開始進行回複
        if hasattr(delta, "content") and delta.content:
            if not is_answering:
                print("\n" + "=" * 20 + "完整回複" + "=" * 20 + "\n")
                is_answering = True
            print(delta.content, end="", flush=True)
            answer_content += delta.content

返回結果

====================思考過程====================

使用者問"你是誰",這是一個關於身份的直接問題。我需要根據我的實際身份如實回答。

我是由月之暗面科技有限公司(Moonshot AI)開發的人工智慧助手,我的名字是Kimi。我應該清晰、簡潔地介紹自己,包括:
1. 我的身份:AI助手
2. 我的開發人員:月之暗面科技有限公司(Moonshot AI)
3. 我的名字:Kimi
4. 我的核心能力:長文本處理、智能對話、檔案處理、搜尋等

我應該保持友好、專業的語氣,避免過於技術化的術語,讓普通使用者也能理解。同時,我應該強調我是一個AI,沒有個人意識、情感或個人經歷。

回答結構:
- 直接回答身份
- 說明開發人員
- 簡要介紹核心能力
- 保持簡潔明了
====================完整回複====================

我是由月之暗面科技有限公司(Moonshot AI)開發的AI助手,名叫Kimi。我基於混合專家(MoE)架構,具備超長上下文理解、智能對話、檔案處理、代碼產生和複雜任務推理等能力。有什麼可以幫您的嗎?

多模態調用樣本

kimi-k2.7-code、kimi-k2.6、kimi-k2.5、kimi-k3 支援同時處理文本、映像或視頻輸入(kimi-k3 暫不可使用視訊輸入),並可通過 enable_thinking 參數開啟思考模式。以下樣本展示如何調用多模態能力。

開啟或關閉思考模式

kimi-k2.6、kimi-k2.5屬於混合思考模型,模型可以在思考後回複,也可直接回複;通過enable_thinking參數控制是否開啟思考模式:
  • true:開啟思考模式
  • false(預設):關閉思考模式
kimi-k2.7-code 與 kimi-k3為僅思考模型,始終開啟思考模式(enable_thinking預設為 true,不可關閉),preserve_thinking預設為 true kimi-k2.6 支援通過 preserve_thinking 參數在多輪對話中傳遞思考過程,詳情請參見傳遞思考過程 以下樣本展示如何使用映像 URL 並開啟思考模式,支援單圖輸入(主樣本)和多圖輸入(注釋代碼)。
  • OpenAI相容
  • DashScope
Python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 以下為華北2(北京)地區的URL。請將 {WorkspaceId} 替換為您的百鍊業務空間ID,各地區的URL不同。
    base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
)

# 單圖傳入樣本(開啟思考模式)
completion = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "圖中描繪的是什麼景象?"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241022/emyrja/dog_and_girl.jpeg"
                    }
                }
            ]
        }
    ],
    extra_body={"enable_thinking":True}  # 開啟思考模式
)

# 輸出思考過程
if hasattr(completion.choices[0].message, 'reasoning_content') and completion.choices[0].message.reasoning_content:
    print("\n" + "=" * 20 + "思考過程" + "=" * 20 + "\n")
    print(completion.choices[0].message.reasoning_content)

# 輸出回複內容
print("\n" + "=" * 20 + "完整回複" + "=" * 20 + "\n")
print(completion.choices[0].message.content)

# 多圖傳入樣本(開啟思考模式,取消注釋使用)
# completion = client.chat.completions.create(
#     model="kimi-k2.6",
#     messages=[
#         {
#             "role": "user",
#             "content": [
#                 {"type": "text", "text": "這些圖描繪了什麼內容?"},
#                 {
#                     "type": "image_url",
#                     "image_url": {"url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241022/emyrja/dog_and_girl.jpeg"}
#                 },
#                 {
#                     "type": "image_url",
#                     "image_url": {"url": "https://dashscope.oss-cn-beijing.aliyuncs.com/images/tiger.png"}
#                 }
#             ]
#         }
#     ],
#     extra_body={"enable_thinking":True}
# )
#
# # 輸出思考過程和回複
# if hasattr(completion.choices[0].message, 'reasoning_content') and completion.choices[0].message.reasoning_content:
#     print("\n思考過程:\n" + completion.choices[0].message.reasoning_content)
# print("\n完整回複:\n" + completion.choices[0].message.content)

視頻理解

kimi-k3 暫不可使用視訊輸入(僅支援文本與圖片輸入),本節視頻理解樣本不適用於 kimi-k3。
  • 視頻檔案
  • 映像列表
kimi-k2.7-code、kimi-k2.6、kimi-k2.5模型通過從視頻中提取幀序列進行內容分析。您可以通過以下兩個參數控制抽幀策略:
  • fps:控制抽幀頻率,每隔 f p s 1 ​秒抽取一幀。取值範圍為 [0.1, 10],預設值為 2.0。
    • 高速運動情境:建議設定較高的 fps 值,以捕捉更多細節
    • 靜態或長視頻:建議設定較低的 fps 值,以提高處理效率
  • max_frames:限制視頻抽取幀的上限,預設值和最大值均為2000。 當按 fps 計算的總幀數超過此限制時,系統將自動在 max_frames 內均勻抽幀。此參數僅在使用 DashScope SDK 時可用。
  • OpenAI相容
  • DashScope
使用OpenAI SDK或HTTP方式向模型直接輸入視頻檔案時,需要將使用者訊息中的"type"參數設為"video_url"
Python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 以下為華北2(北京)地區的URL。請將 {WorkspaceId} 替換為您的百鍊業務空間ID,各地區的URL不同。
    base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
)

completion = client.chat.completions.create(
    model="kimi-k2.6",
    messages=[
        {
            "role": "user",
            "content": [
                # 直接傳入的視訊檔案時,請將type的值設定為video_url
                {
                    "type": "video_url",
                    "video_url": {
                        "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241115/cqqkru/1.mp4"
                    },
                    "fps": 2
                },
                {
                    "type": "text",
                    "text": "這段視頻的內容是什麼?"
                }
            ]
        }
    ]
)

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

傳入本地檔案

以下樣本展示如何傳入本地檔案。OpenAI 相容介面僅支援 Base 64 編碼方式,DashScope 同時支援 Base 64 編碼和檔案路徑兩種方式。
  • OpenAI相容
  • DashScope
Base 64 編碼方式傳入需要構建 Data URL,構建方法請參見構建 Data URL
Python
from openai import OpenAI
import os
import base64

#  編碼函數: 將本地檔案轉換為 Base 64 編碼的字串
def encode_image(image_path):
    with open(image_path, "rb") as image_file:
        return base64.b64encode(image_file.read()).decode("utf-8")

# 將xxx/eagle.png替換為你本地映像的絕對路徑
base64_image = encode_image("xxx/eagle.png")

client = OpenAI(
    api_key=os.getenv('DASHSCOPE_API_KEY'),
    # 以下為華北2(北京)地區的URL。請將 {WorkspaceId} 替換為您的百鍊業務空間ID,各地區的URL不同。
    base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
)
completion = client.chat.completions.create(
    model="kimi-k2.6",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {"url": f"data:image/png;base64,{base64_image}"},
                },
                {"type": "text", "text": "圖中描繪的是什麼景象?"},
            ],
        }
    ],
)
print(completion.choices[0].message.content)

# 以下為傳入本地視頻檔案、本地映像列表的樣本

# 【本地視頻檔案】將本地視頻編碼為 Data URL 後傳入 video_url:
#   def encode_video_to_data_url(video_path):
#       with open(video_path, "rb") as f:
#           return "data:video/mp4;base64," + base64.b64encode(f.read()).decode("utf-8")

#   video_data_url = encode_video_to_data_url("xxx/local.mp4")
#   content = [{"type": "video_url", "video_url": {"url": video_data_url}, "fps": 2}, {"type": "text", "text": "這段視頻的內容是什麼?"}]

# 【本地映像列表】將多張本地圖片分別 Base64 後組成 video 列表傳入:
#   image_data_urls = [f"data:image/jpeg;base64,{encode_image(p)}" for p in ["xxx/f1.jpg", "xxx/f2.jpg", "xxx/f3.jpg", "xxx/f4.jpg"]]
#   content = [{"type": "video", "video": image_data_urls, "fps": 2}, {"type": "text", "text": "描述這個視頻的具體過程"}]

檔案限制

  • 映像限制
  • 視頻限制
  • 映像解析度:
    • 最小尺寸:映像的寬度和高度均須大於10像素。
    • 寬高比:映像長邊與短邊的比值不得超過 200:1
    • 像素上限:推薦將映像解析度控制在8K(7680x4320)以內。超過此解析度的映像可能因檔案過大、網路傳輸耗時過長而導致 API 呼叫逾時。
  • 支援的映像格式
    • 解析度在4K(3840x2160)以下,支援的映像格式如下:

      映像格式

      常見副檔名

      MIME Type

      BMP

      .bmp

      image/bmp

      JPEG

      .jpe, .jpeg, .jpg

      image/jpeg

      PNG

      .png

      image/png

      TIFF

      .tif, .tiff

      image/tiff

      WEBP

      .webp

      image/webp

      HEIC

      .heic

      image/heic

    • 解析度處於4K(3840x2160)8K(7680x4320)範圍,僅支援 JPEG、JPG 、PNG 格式。
  • 映像大小:
    • 以公網 URL 和本地路徑傳入時:單個映像的大小不超過10MB
    • 以 Base 64 編碼傳入時:編碼後的字串不超過10MB
    如需壓縮檔體積請參見如何將映像或視頻壓縮到滿足要求的大小
  • 支援傳入的圖片數量:傳入多張映像時,圖片數量受模型的最大輸入的限制,所有圖片和文本的總 Token 數必須小於模型的最大輸入。

其它功能

模型

多輪對話

深度思考

Function Calling

結構化輸出

連網搜尋

首碼續寫

上下文緩衝

kimi-k3

支援

支援

支援

支援

不支援

支援

支援

kimi-k2.7-code

支援

支援

支援

不支援

不支援

不支援

支援

kimi-k2.6

支援

支援

支援

不支援

不支援

不支援

支援

kimi-k2.5

支援

支援

支援

不支援

不支援

不支援

支援

kimi-k2-thinking

支援

支援

支援

支援

不支援

不支援

支援

Moonshot-Kimi-K2-Instruct

支援

不支援

支援

不支援

支援

不支援

支援

動態載入工具(Kimi-K3)

當應用需要掛載大量工具時,如果把所有工具的聲明一次性放進請求頂層的tools欄位,會遇到工具定義膨脹(Tool Definition Bloat)問題:每個請求都要攜帶全部工具的描述和參數 Schema,Token 消耗高;候選工具越多,模型也越容易選錯工具、構造出錯誤的調用參數。 動態載入工具(Dynamically Loaded Tools)允許在對話過程中按需注入工具:先只掛載少量核心工具,當對話進展到需要某個工具時,再把它動態插入messages中,從而降低 Token 消耗、提升工具選擇的準確性。
動態載入工具目前僅 kimi-k3 支援,在其他模型(如 kimi-k2.6)上請求會返回tokenization failed錯誤。

在 messages 中注入工具聲明

messages中插入一條rolesystem的訊息,並通過該訊息的tools欄位聲明要載入的工具。聲明格式與請求頂層tools欄位的格式完全一致,且需要提供工具的完整資訊(namedescriptionparameters)。
  • 攜帶toolssystem訊息與普通訊息地位相同:它出現在messages列表的哪個位置,工具就從哪個位置開始對模型可見。
  • 動態載入的工具與請求頂層tools欄位聲明的全域工具並存,模型可以同時看到兩類工具。
  • 動態注入的工具聲明必須是完整的工具定義,不能只傳工具名或引用全域已聲明的工具。
  • 攜帶toolssystem訊息不能再攜帶content欄位,否則請求會以 400 報錯。使用 OpenAI SDK 時可直接在messages中透傳tools欄位。
Python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 以下為華北2(北京)地區的URL。請將 {WorkspaceId} 替換為您的百鍊業務空間ID,各地區的URL不同。
    base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
)

completion = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "幫我計算一下 23 * 47 的結果。"},
        # 動態載入工具:在對話中插入一條攜帶 tools 欄位的 system 訊息
        {
            "role": "system",
            "tools": [
                {
                    "type": "function",
                    "function": {
                        "name": "Calculator",
                        "description": "計算機,只支援單個算術運算式的求值",
                        "parameters": {
                            "type": "object",
                            "properties": {
                                "expr": {
                                    "type": "string",
                                    "description": "算術運算式,支援四則運算、指數運算、對數函數、三角函數,使用 JavaScript 文法",
                                }
                            },
                            "required": ["expr"],
                        },
                    },
                }
            ],
        },
    ],
)

print(completion.choices[0].message.tool_calls)

結合搜尋工具實現按需載入

API 層面沒有專門的工具搜尋介面。如果工具數量很多,可以組合"自訂搜尋工具 + 動態載入工具"實現按需載入:
  1. 會話開始時,在請求頂層tools中只聲明一個由應用後端實現的search_tools工具(按關鍵詞返回匹配的工具名稱和簡介),以及少量每輪都可能用到的核心工具。
  2. 在 System Prompt 中聲明可被搜尋的關鍵詞(例如工具目錄、領域標籤),引導模型在需要工具時先調用search_tools。首輪請求可設定tool_choice: "required"強制模型先檢索再回答,檢索完成後將tool_choice恢複為"auto"。修改tool_choice不會破壞首碼緩衝。
  3. 根據search_tools返回的結果,由應用把對應工具的完整聲明通過一條攜帶toolssystem訊息動態插入messages
  4. 模型即可在後續產生中直接調用這些新載入的工具。
這樣無論工具總量有多大,每一輪請求中實際存在的工具聲明都只有少量幾個,上下文視窗和模型的選擇壓力都可控。

注意事項

  • 動態工具聲明按請求生效,不會被服務端記住。下一輪請求是否繼續攜帶,由接入方自行決定:繼續攜帶則工具仍然可用,也有利於命中首碼緩衝;不再攜帶則該工具聲明失效,如果工具未在其他位置聲明,模型將無法調用這個工具,且變更位置之後的首碼緩衝可能無法命中。
  • messages末尾追加動態工具聲明,不會影響已有首碼的緩衝;刪除或修改之前的工具聲明,可能影響變更位置之後的快取命中。在請求頂層tools欄位聲明全域工具同樣不影響快取命中。
  • 攜帶toolssystem訊息同樣會佔用上下文長度,請只對目前的交談真正需要的工具做動態注入。
  • 動態工具聲明與全域tools聲明格式完全統一,接入方無需維護兩套 Schema。

參數預設值

模型

enable_thinking

temperature

top_p

presence_penalty

fps

max_frames

kimi-k3

true(僅思考模式,不可關閉)

1.0

0.95

0.0

-

-

kimi-k2.7-code

true(僅思考模式,不可關閉)

1.0

0.95

0.0

2

2000

kimi-k2.6

false

思考模式:1.0

非思考模式:0.6

思考/非思考模式:0.95

思考/非思考模式:0.0

2

2000

kimi-k2.5

false

思考模式:1.0

非思考模式:0.6

思考/非思考模式:0.95

思考/非思考模式:0.0

2

2000

kimi-k2-thinking

-

1.0

-

-

-

-

Moonshot-Kimi-K2-Instruct

-

0.6

1.0

0

-

-

“-" 表示沒有預設值,也不支援設定。

模型列表與計費

Kimi 系列模型是由月之暗面公司(Moonshot AI)推出的大語言模型。
  • kimi-k3:Kimi 迄今能力最強的旗艦模型,始終進行推理並採用保留式思考(僅思考模式)。支援文本與圖片輸入(暫不可使用視訊輸入)、對話與 Agent 任務,並支援動態載入工具。
  • kimi-k2.7-code:Kimi 最強編程模型,長上下文指令遵循更可靠,編程任務成功率更高。支援文本、圖片與視頻輸入、思考模式、對話與 Agent 任務。
  • kimi-k2.6:Kimi最新最智能的模型,具備更強更穩的長程代碼編寫能力,指令遵循和自我錯誤修正能力顯著提升。同時支援文本、圖片與視頻輸入、思考與非思考模式、對話與 Agent 任務。
  • kimi-k2.5:在 Agent、代碼產生、視覺理解及一系列通用智慧工作提示上取得開源 SOTA 表現。同時支援映像、視頻與文本輸入、思考與非思考模式、對話與 Agent 任務。
  • kimi-k2-thinking:僅支援深度思考模式,並通過reasoning_content欄位展示思考過程,具有卓越的編碼和工具調用能力,適用於需要邏輯分析、規劃或深度理解的情境。
  • Moonshot-Kimi-K2-Instruct:不支援深度思考,直接產生回複,響應速度更快,適用於需要快速直接回答的情境。
kimi-k3 不支援 thinking_budget 參數,思考長度不可通過該參數限制。kimi-k3 暫不支援 OpenAI 相容 Responses 介面(coming soon),請使用 OpenAI 相容 Chat Completions 介面調用。
價格資訊請參見模型調用計費
模型上下文長度與價格資訊請參見百鍊控制台 按照模型的輸入與輸出 Token 數量計費。
思考模式下,思維鏈按照輸出 Token 計費。

錯誤碼

如果模型調用失敗並返回報錯資訊,請參見錯誤碼進行解決。
Token Plan
模型體驗
  • 音樂產生
用量統計與效能監控
資產中心
服務支援