集成指南核验于 2026 年 7 月 20 日
使用 OpenAI SDK 调用 Kimi K3 API
使用 Moonshot 的 OpenAI 兼容端点和 kimi-k3 模型 ID，完成一个最小且可验证的 Python 集成。
Python兼容 OpenAI已开启推理
难度：入门约 10 分钟
准备条件
发起请求前，先准备最小且安全的运行环境。
- Python 3.9 或更高版本
- Moonshot 平台 API Key
- 本地环境变量；不要把 Key 提交到代码仓库
- 能够访问 api.moonshot.cn
实施步骤
安装 SDK、配置客户端并发起一次流式请求。
- 1
安装 OpenAI SDK
使用 Moonshot 兼容层支持的官方 Python 客户端。
终端python3 -m pip install --upgrade 'openai>=1.0' - 2
保存 API Key
把凭证保存在源码控制之外，并从进程环境中读取。
终端export MOONSHOT_API_KEY='replace-with-your-key' - 3
创建客户端并流式输出响应
设置 Moonshot Base URL，选择 kimi-k3，并请求当前支持的 max 推理强度。
Pythonimport os from openai import OpenAI client = OpenAI( api_key=os.environ["MOONSHOT_API_KEY"], base_url="https://api.moonshot.cn/v1", ) stream = client.chat.completions.create( model="kimi-k3", messages=[ {"role": "user", "content": "Plan a safe migration for this service."} ], reasoning_effort="max", stream=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) - 4
保留完整 assistant 消息
进行工具调用或后续轮次时，要附加完整 assistant 消息对象，包括推理和工具调用字段，不能只重建可见文本。
验证集成
只得到成功 HTTP 响应还不够，还要检查 Agent 所依赖的字段。
- 返回模型或请求配置明确指向 kimi-k3
- 流式响应持续输出内容增量并正常结束
- 请求接受 reasoning_effort=max
- 已采集 Usage 数据，用于监控成本和延迟
故障排查
先检查文档中的约束，不要一开始就增加重试或包装层。
| 现象 | 可能原因 | 直接修复 |
|---|---|---|
| 401 或鉴权错误 | Key 缺失、无效或来自错误平台 | 重新生成 Moonshot Key，并检查当前 Shell 中的 MOONSHOT_API_KEY |
| 不支持的参数错误 | 采样值或推理强度超出当前契约 | 使用文档规定的固定采样值和 reasoning_effort=max |
| 工具循环丢失状态 | 只附加了 assistant 可见文本 | 把完整 assistant 消息传入下一次请求 |
官方参考
API 发生变化时，以这些页面作为实时契约。
API 常见问题
首次生产集成时需要明确的问题。