简介:本文说明 Kimi API 的接入准备、Python 调用与流式输出,解释 Token 计费与参数设置,并列出 401、429、400 等常见错误的排查步骤。读者可以按步骤跑通首个请求,再结合成本与稳定性要求完成生产化改造。
Kimi API 由北京月之暗面科技股份有限公司提供。它把大模型能力封装成接口,开发者不需要自己训练或部署模型,只要通过后端服务发送请求,就能拿到模型返回的结果。
常见用途包括:
如果业务需要同时接入多个模型,例如长文本任务用 Kimi,低成本任务用其他模型,可以先了解 百度智能云词元所。它提供模型发现、选型、价格性能对比和多模型统一 API 接入。
开始调用前,通常需要完成以下四件事。
moonshot-v1-8k,上下文窗口为 8k Token。模型列表和计费规则会调整,发布前请以官方文档(platform.moonshot.cn)为准。本文示例使用 openai Python SDK 1.x 版本,安装命令如下:
pip install --upgrade openai
先把 API Key 写入环境变量,不要直接写在代码里。
Linux 或 macOS:
export MOONSHOT_API_KEY="你的密钥"
Windows PowerShell:
$env:MOONSHOT_API_KEY="你的密钥"
下面是一个非流式调用的完整示例:
import osfrom openai import OpenAIclient = OpenAI(api_key=os.environ["MOONSHOT_API_KEY"],base_url="https://api.moonshot.cn/v1",)response = client.chat.completions.create(model="moonshot-v1-8k",messages=[{"role": "system", "content": "你是一名专业的技术文档助手,回答要简洁、准确。"},{"role": "user", "content": "请用三点总结大模型 API 接入的关键步骤。"},],temperature=0.3,max_tokens=512,stream=False,)print(response.choices[0].message.content)
如果环境变量没有设置,os.environ["MOONSHOT_API_KEY"] 会直接抛出 KeyError,问题会在启动时暴露,不会等到请求失败才发现。
如果需要流式输出,把 stream 设为 True,然后逐块读取内容:
stream = client.chat.completions.create(model="moonshot-v1-8k",messages=[{"role": "user", "content": "请写一段关于 AI Agent 的简短介绍。"}],temperature=0.5,max_tokens=300,stream=True,)for chunk in stream:if not chunk.choices:continuedelta = chunk.choices[0].delta.contentif delta:print(delta, end="", flush=True)
流式输出适合聊天界面和实时问答。用户能边生成边阅读,等待感明显低于一次性返回。
| 参数 | 作用 | 使用建议 |
|---|---|---|
model |
指定模型 | 按任务复杂度、上下文长度和成本选择 |
messages |
对话消息列表 | 通常包含 system、user、assistant 角色 |
temperature |
控制输出随机性 | 事实问答取较低值,创意生成可适当提高 |
max_tokens |
限制输出长度 | 设置过大会增加成本,过小会截断回答 |
stream |
是否流式返回 | 聊天类应用建议开启 |
top_p |
控制采样范围 | 通常只调整 temperature 或 top_p 其中之一,同时大幅调整两者会让输出难以预测 |
messages 的写法会直接影响输出质量。下面是一个适合知识库场景的结构:
[{"role": "system","content": "你是企业知识库助手,只能根据提供的资料回答,资料中没有的内容请直接说明,不要编造事实。"},{"role": "user","content": "请根据以下资料总结三条要点:{资料内容}"}]
在 system 中明确“不知道就说不知道”,能减少模型编造内容的情况。
大模型 API 通常按 Token 计费。Token 是模型处理文本的基本单位。同样一段话,中文、英文、代码或 JSON 切分出的 Token 数量可能不同,所以估算时应以实际返回的用量为准。
费用主要取决于以下因素:
可以用下面的公式粗略估算单次调用成本:
单次调用成本 = 输入 Token 数 × 输入单价 + 输出 Token 数 × 输出单价
举例来说,一次调用输入 2000 Token、输出 500 Token,若输入单价为 a 元/千 Token、输出单价为 b 元/千 Token,则成本约为 (2000 × a + 500 × b) ÷ 1000 元。单价以官方计费页面为准,使用前请确认当天价格。
降低成本的常用做法有以下几种:
max_tokens:只需要短答案时,不要允许模型输出长文。常见原因包括 API Key 填错、Key 已过期或被删除、环境变量名称不一致。
先确认密钥是否存在:
echo $MOONSHOT_API_KEY
Windows PowerShell 可以用 echo $env:MOONSHOT_API_KEY。如果是手写 HTTP 请求,请求头应为:
Authorization: Bearer YOUR_API_KEY
使用 SDK 时,SDK 会自动添加这个请求头,通常只需要检查 Key 和环境变量。
429 通常表示触发了频率或并发限制。处理方法包括降低并发、加入重试、把非实时任务放入异步队列,并检查代码中是否有异常循环调用。
重试时使用指数退避,间隔逐次加长,并加入随机抖动,避免大量请求同时重试:
import randomimport timefrom openai import RateLimitErrordef call_with_retry(client, messages, max_retries=5):for attempt in range(max_retries):try:return client.chat.completions.create(model="moonshot-v1-8k",messages=messages,max_tokens=512,)except RateLimitError:if attempt == max_retries - 1:raisetime.sleep(min(2 ** attempt, 30) + random.uniform(0, 1))
有两点需要注意。第一,如果账户额度已经用尽,重试无法解决问题,需要到控制台检查余额和额度。第二,纯文本生成没有副作用,重试是安全的。但如果调用链路中的工具会写入数据库、下单或发送消息,重试前必须先做幂等校验,否则同一操作可能执行多次。
常见原因包括 messages 结构不正确、model 名称不存在、max_tokens 超出允许范围、temperature 或 top_p 取值不合法、请求体 JSON 格式错误。
排查时先用最小请求验证接口可用,例如只传一条 user 消息,确认能返回结果后,再逐个加入参数。
回答不完整时,先检查返回结果中的 finish_reason:
choice = response.choices[0]if choice.finish_reason == "length":print("输出因 max_tokens 上限被截断")
如果值为 length,说明输出达到了上限。可以调高 max_tokens,但输入加输出的总长度不能超过模型的上下文窗口。也可以在提示词中要求模型分段输出,或把任务拆成多次调用。
长上下文不等于可以无限制输入。超长文档通常效果会下降,常见的改进方法有:
这样既能降低 Token 消耗,也能提高回答的准确性。
典型流程如下:
用户提问↓问题改写与意图识别↓知识库检索↓拼接提示词↓调用 Kimi API↓返回答案并附带引用来源
在 RAG 场景中,检索质量和模型能力同样重要。建议对文档做清洗、切分和向