Tracks
面向开发者的 AI 工程师助理
26小时
2026 年 7 月 16 日，Moonshot AI 发布了 Kimi K3，一款拥有 2.8 万亿参数、100 万 token 上下文窗口并原生支持视觉的模型，令开源模型竞赛再度提速。这是 Moonshot 迄今规模最大的开源模型，远超 Kimi K2，也是他们首次称之为迈入 3 万亿参数级别的产品。
如果您想了解发布故事、架构深潜、基准图表、与 Claude、GPT 及其他中国产研实验室的对比，以及 Moonshot 自述的局限列表，请查看我们的Kimi K3 博文。本教程侧重实操：如何获取与实际使用表现。我将演示五个小例子，其中四个通过 API，展示真实的 token 用量与成本，另有两个在 kimi.com 网页应用中完成。它们涵盖 K3 如何处理：
- 调用工具并返回严格 JSON
- 按需动态加载工具定义
- 借助自动缓存降低长上下文成本
- 读取截图并修复布局问题
- 用一句提示生成交互式仪表板
四个 API 示例均在 2026 年 7 月 17 日使用 kimi-k3 模型运行，冷启动约花费 11 美分，启用缓存后则降至几美分。
如何访问 Kimi K3
最快的试用方式是访问 kimi.com，网页与移动端应用可直接使用 Kimi K3 处理通用智能体任务，无需配置。
对于报表、看板等更重的工作，有桌面应用 Kimi Work 可用。
如果您常驻终端，Kimi Code 是可通过 npm 安装的编码智能体，包名为 @moonshot-ai/kimi-code，可用 /model 命令选择模型。在 Kimi Code 中使用 K3 需要付费会员，使用完整 100 万 token 窗口则需更高档位。
本教程聚焦原生 API 与网页应用；若您偏好终端，亦可选择该智能体。
不过，K3 并未取代同系其他模型。下表展示了当前产品线的分工。
|
模型 |
上下文窗口 |
最佳适用场景 |
|
|
1,048,576 tokens |
旗舰型工作：长代码、视觉、知识型任务 |
|
|
262,144 tokens |
专用编程，且提供更快的高速选项 |
|
|
262,144 tokens |
通用文本、图像与视频对话 |
简而言之，当任务混合了代码、工具、文档与图像，或确实需要 100 万 token 窗口时，K3 是首选。若是纯代码生成且更看重速度而非上下文，kimi-k2.7-code 依然更稳妥；别想当然地以为最新模型总是最佳选择。
设置 Kimi K3 API
该 API 兼容 OpenAI SDK，如果您用过它，这里几乎没有新内容。您需要 Python 3.9 或更高版本，以及一个 API 密钥。
步骤一：生成 API 密钥
先登录 Kimi 平台，在控制台打开API Keys 页面。创建密钥并复制保存一次，之后将无法再次查看。您还需要在账户中充值少量余额以便发起调用，本教程全程几美元足够。
创建 Kimi K3 API 密钥。图片作者供图。
步骤二：安装 SDK
接着在您的环境中安装 OpenAI SDK，一条命令即可。
python -m pip install --upgrade "openai>=1.0"这会拉取后续示例所用的客户端库，无需安装任何 Kimi 特定组件。
步骤三：存储密钥并初始化客户端
将密钥存入环境变量比直接粘贴到代码更安全。请在 shell 或 .env 文件中设置 MOONSHOT_API_KEY，然后将客户端指向 Moonshot 的基础 URL。
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["MOONSHOT_API_KEY"],
base_url="https://api.moonshot.ai/v1",
)与标准 OpenAI 配置不同的只有两点：base_url 与模型名（kimi-k3）。就绪后即可发起调用。
步骤四：发起首次调用
下面是第一次请求。我让模型用一句话介绍自己，结果得到一个颇为诚实的瞬间。
completion = client.chat.completions.create(
model="kimi-k3",
messages=[{"role": "user", "content": "Introduce Kimi K3 in one sentence."}],
max_completion_tokens=800,
)
print(completion.choices[0].message.content)回复是礼貌的拒答：模型表示在自身发布前完成训练，对 Kimi K3 缺乏可靠信息，并建议查看 Moonshot 的公告。这提醒我们：模型并不“了解自己”。我刚刚的这次 API 调用约花费 0.7 美分。注意我设置了 max_completion_tokens 上限；本教程的每次调用我都加了上限，防止冗长输出推高账单。
Kimi K3 首次 API 调用输出。图片作者供图。
示例一：推理流式输出与最终答案
K3 始终会进行推理，API 会在与答案分离的通道返回推理内容。流式传输时，每个分片可包含 reasoning_content、最终 content，或两者兼有，方便您将“思考过程”与“答案”分别呈现。
stream = client.chat.completions.create(
model="kimi-k3",
messages=[{"role": "user", "content": "A bat and a ball cost $1.10 together. The bat costs $1.00 more than the ball. How much is the ball?"}],
max_completion_tokens=1200,
stream=True,
stream_options={"include_usage": True},
)
for chunk in stream:
if not chunk.choices:
continue
delta = chunk.choices[0].delta
reasoning = getattr(delta, "reasoning_content", None)
if reasoning:
print(reasoning, end="", flush=True)
if delta.content:
print(delta.content, end="", flush=True)模型先流式输出了思路：识别出“球棒与球”是经典的认知反思测试题，点出直觉但错误的 $0.10 答案，然后列式解出球价 $0.05，并核对 $1.05 加 $0.05 等于 $1.10。关键在于分离：在真实应用中，您通常向用户展示 content，而将 reasoning_content用于日志记录，因为在生产环境直接展示原始推理并不常见。本次调用输出 488 个 token，成本不足 1 美分。
先流式推理，再给最终答案。图片作者供图。
示例二：带结构化输出的工具调用
Kimi K3 是产品线中支持 tool_choice="required" 的模型，可强制当轮至少进行一次工具调用。这在您希望模型先取数再作答、而非凭空猜测时很实用。这里我提供了两个模拟工具：价格查询与库存检查，强制调用工具，在本地运行工具后，再用 response_format 请求以严格 JSON 返回结果。
first = client.chat.completions.create(
model="kimi-k3",
messages=messages,
tools=TOOLS,
tool_choice="required",
max_completion_tokens=2500,
)
assistant_message = first.choices[0].message
messages.append(assistant_message)
for tool_call in assistant_message.tool_calls or []:
args = json.loads(tool_call.function.arguments)
messages.append({"role": "tool", "tool_call_id": tool_call.id, "content": run_tool(tool_call.function.name, args)})模型用正确的产品编码调用了两个工具，随后返回了干净的订单摘要 JSON：5 把机械键盘，单价 $89，总价 $445，库存标记为 true。两点细节关乎实用：在添加工具结果前，必须先将完整的助理消息附回对话；且只应从 content 解析 JSON，切勿解析推理字段。这两次调用合计成本不足 1 美分。
工具调用与结构化 JSON 输出。图片作者供图。
示例三：动态加载工具
当您有大量工具时，每次请求都发送其定义会浪费 token、让提示词臃肿。Kimi K3 允许在对话中途通过一个携带 tools 字段、但无 content 的 system 消息注入工具定义。该工具自此可用，从而在工具真正需要之前，将大型工具目录排除在缓存前缀之外。
messages = [
{"role": "user", "content": "Convert 100 US dollars to euros at a rate of 0.92."},
{"role": "system", "tools": [{
"type": "function",
"function": {
"name": "convert_currency",
"description": "Convert an amount from one currency to another",
"parameters": {
"type": "object",
"properties": {"amount": {"type": "number"}, "rate": {"type": "number"}},
"required": ["amount", "rate"],
},
},
}]},
]
completion = client.chat.completions.create(model="kimi-k3", messages=messages)
print(completion.choices[0].message.tool_calls)K3 识别到了新加载的工具，并按预期以金额 100、汇率 0.92 调用了 convert_currency。需注意服务端不会替您长期保存定义，如需工具持续可用，后续请求需重发该 system 消息。这是整组中最便宜的一次，约 0.2 美分。
调用动态加载的货币换算工具。图片作者供图。
示例四：用缓存降低长上下文成本
这是 100 万 token 窗口变得实用的地方。上下文缓存是自动的，无需管理缓存 ID 或 TTL。您发送一个大型前缀，并在后续请求中保持字节级完全一致，那么重复部分将按“命中价”而非“未命中价”计费。为让差异更直观，我使用了约 3.3 万 token 的知识库并据此提问。
knowledge = Path("knowledge_base.md").read_text(encoding="utf-8")
completion = client.chat.completions.create(
model="kimi-k3",
messages=[
{"role": "system", "content": knowledge},
{"role": "user", "content": "What is the rated payload of the Atlas robot?"},
],
max_completion_tokens=600,
)第一次发送该前缀时，没有任何缓存，约 33,000 个输入 token 成本大约 9.9 美分。此前缀被记录后，再次相同请求在全部 32,512 个前缀 token 上命中缓存，成本约 1.1 美分，接近 9 倍下降。原因在价差：缓存命中的输入按每百万 token $0.30 计价，未命中则为 $3.00。我遇到的一个小特点是缓存写入是异步的，紧接着的立即重复请求可能还未命中；稍后请求即可命中，因此两次运行脚本、相隔一分钟，就能看到先未命中、后命中的差异。
缓存未命中与命中成本对比。图片作者供图。
示例五：在截图中定位布局 Bug
K3 原生支持视觉，API 使用体验也很简洁，但不接受公共图像 URL。您需以 base64 data URL 发送图片，并将消息的 content 设为对象数组：一段图像、一段文本。我渲染了一个带少量刻意布局 Bug 的小仪表板，保存截图后请 K3 找出问题。
带有刻意布局 Bug 的仪表板。图片作者供图。
import base64
from pathlib import Path
image_data = base64.b64encode(Path("broken_dashboard.png").read_bytes()).decode()
completion = client.chat.completions.create(
model="kimi-k3",
messages=[{
"role": "user",
"content": [
{"type": "image_url", "image_url": {"url": f"data:image/png;base64,{image_data}"}},
{"type": "text", "text": "List the layout and alignment problems you can see, and give a short CSS fix for each."},
],
}],
max_completion_tokens=3500,
)
print(completion.choices[0].message.content)K3 对图像理解不错。它找出了那张位置偏低且与相邻卡片重叠的卡片、压在数字上的徽章（甚至把被遮住的 3,910 读成了 5,910，反而从侧面印证了 Bug）、最后一张卡片前的间距不匀、柱状条向上“漏到”上方卡片、以及覆盖在柱子上的提示框，并分别给出了简短 CSS 修复建议，比如将卡片统一进一个网格。不过，它忽略了几乎不可见的低对比度副标题——视觉更容易捕捉显眼问题，而非细微之处。本次调用约 2 美分。
Kimi K3 的局限
API 示例整体顺利，但有些小瑕疵值得提前说明，免得您措手不及。我大多亲身遇到过：
-
目前仅支持
reasoning_effort="max"，暂无法下调思考强度以节省成本。 -
采样设置是固定的，诸如
temperature、top_p及各类惩罚项都被锁定，因此请不要在请求中调整这些值。 -
输出可能很长且昂贵。请像示例中那样设置
max_completion_tokens上限，并校验任何 Agent 循环。 -
API 暂不支持公共图像 URL，若需视觉功能，请使用 base64 或上传文件。
这些都不至于影响使用，但会影响您的集成方式。最需要关注的是输出成本。
结语
在我的测试中，有两点尤为突出：工具调用与结构化输出无需重试；缓存的重要性超出预期，因为重复使用同一长前缀能让“大请求”再次发送变得很便宜。因此，对于仓库级分析、重复的长上下文调用或多模态工程，K3 是合乎情理的默认选择；若追求快速低成本对话或精细的采样控制，较小的模型更顺手。至于我先前提到的开源权重与许可细节，预计会在 7 月 27 日发布后更为明晰。
如需了解这些示例背后的通用模式，我们的Developing AI Systems with the OpenAI API 课程涵盖了 Python 中的函数调用与模型外接工具的实践。
主题