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}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1HTTP 请求地址:POST https://{WorkspaceId}.cn-beijing.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 兼容接口仅支持 Base64 编码方式,DashScope 同时支持 Base64 编码和文件路径两种方式。
  • OpenAI兼容
  • DashScope
Base64 编码方式传入需要构建 Data URL,构建方法请参见构建 Data URL
Python
from openai import OpenAI
import os
import base64

#  编码函数: 将本地文件转换为 Base64 编码的字符串
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
    • 以 Base64 编码传入时:编码后的字符串不超过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 计费。

常见问题

Q:如何部署 Kimi-K2-Instruct 模型?

A:我们推荐您通过本文介绍的阿里云百炼 API 方式调用。如有私有化部署需求,请参见阿里云 Kimi K2 解决方案,涵盖了通过 PAI、GPU 云服务器等部署模型的方式。

错误码

如果模型调用失败并返回报错信息,请参见错误码进行解决。
Token Plan
模型体验
  • 3D模型生成
  • 音乐生成
模型调优
模型压缩目录节点
用量统计与性能监控
资产中心
服务支持