第02课：30分钟跑通 Kimi API

“第一次跑通 API 是个心理关卡，不是技术关卡。大多数人卡的地方不是代码，而是注册流程里哪步需要点哪里。”

---

2.1 注册 Kimi 开放平台（5分钟）

第一步：访问开发者平台

打开浏览器访问 platform.kimi.ai，注意这是开发者平台，不是普通用户聊天的 kimi.ai。

用手机号注册，国内号码直接可用，全程无需梯子。

第二步：创建 API Key

登录后点击左侧「API Key 管理」→「新建 API Key」。

给 Key 起名（如"副业工具"），点击确认，立即复制保存——系统只显示一次完整 Key，关掉弹窗后就只能看到脱敏版本。

Key 格式类似：sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

安全原则：Key 不要出现在任何 .py 文件里、不要提交到 GitHub、不要发给任何人。后面会讲安全读取方式。

第三步：查看免费额度

新用户通常有免费 token 赠送，在控制台「额度管理」可以查看。本书所有代码案例加起来的 API 消耗不超过 300 万 token，节省着用绰绰有余。

---

2.2 配置 Python 环境（10分钟）

安装 Python（如已安装跳过）

访问 python.org 下载 Python 3.10 或以上。Windows 安装时勾选「Add Python to PATH」。

验证：

python --version
# 输出类似：Python 3.11.9

安装 openai 库

Kimi 使用 OpenAI 兼容接口，直接用官方 openai 库，无需安装任何专属 SDK：

pip install openai

验证：

python -c "import openai; print(openai.__version__)"
# 输出类似：1.52.0

配置 API Key（环境变量，最安全的方式）

Windows：

setx MOONSHOT_API_KEY "sk-你的完整Key"

设置后关闭并重新打开命令提示符才生效。

Mac / Linux：

echo 'export MOONSHOT_API_KEY="sk-你的完整Key"' >> ~/.bashrc
source ~/.bashrc

验证是否生效：

python -c "import os; print(os.environ.get('MOONSHOT_API_KEY', '未找到'))"

---

2.3 第一个调用（10分钟）

最小可运行代码

新建文件 hello_kimi.py：

import os
from openai import OpenAI

# 用环境变量读取 Key，不要直接写在代码里
client = OpenAI(
    api_key=os.environ.get("MOONSHOT_API_KEY"),
    base_url="https://api.moonshot.ai/v1",  # 这一行是关键，指向 Kimi
)

response = client.chat.completions.create(
    model="moonshot-v1-32k",  # 先用便宜模型测试
    messages=[
        {
            "role": "user",
            "content": "帮我写一条50字以内的蓝牙耳机产品广告语，突出主动降噪功能"
        }
    ]
)

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

运行：

python hello_kimi.py

预期输出类似：

沉浸纯粹，隔绝世界——主动降噪耳机，让每一刻专属于你。

费用：这次调用消耗约 80 token，成本不到 $0.0001（一分钱都不到）。

---

2.4 理解调用结构

response = client.chat.completions.create(
    model="kimi-k2.6",          # 选择模型
    messages=[                   # 对话消息列表
        {
            "role": "system",    # 系统指令（设定角色和行为规则）
            "content": "你是专业的法律顾问助手，擅长合同风险识别"
        },
        {
            "role": "user",      # 用户消息
            "content": "请分析这份合同第三条款的风险..."
        }
    ],
    temperature=0.3,             # 0=最确定，1=最随机；分析任务用低值
    max_tokens=2000,             # 最大输出 token 数
    stream=False                 # True=流式输出（打字机效果）
)

# 提取输出
content = response.choices[0].message.content

# 查看本次用量
usage = response.usage
print(f"输入：{usage.prompt_tokens} tokens，输出：{usage.completion_tokens} tokens")

temperature 实用设置：

任务类型	推荐值	原因
合同/文档分析	0.1–0.3	需要确定性输出
代码生成	0.2–0.4	逻辑需要稳定
内容创作/文案	0.7–0.9	需要创意多样性
头脑风暴	0.9–1.0	越随机越好

---

2.5 四种常用调用模式

模式一：流式输出（打字机效果）

适合有界面的工具，让用户看到实时输出，体验更好：

response = client.chat.completions.create(
    model="kimi-k2.6",
    messages=[{"role": "user", "content": "写一份500字的市场分析报告"}],
    stream=True  # 开启流式
)

for chunk in response:
    delta = chunk.choices[0].delta
    if delta.content:
        print(delta.content, end="", flush=True)
print()  # 结尾换行

模式二：多轮对话

让模型记住上下文，支持追问和修改：

messages = [
    {"role": "system", "content": "你是专业的商业计划书顾问"}
]

# 第一轮
messages.append({"role": "user", "content": "帮我为一个宠物洗护店写执行摘要"})
response = client.chat.completions.create(model="kimi-k2.6", messages=messages)
reply = response.choices[0].message.content
messages.append({"role": "assistant", "content": reply})  # 把AI的回复加入历史
print("第一稿：\n", reply)

# 第二轮（基于上文修改）
messages.append({"role": "user", "content": "字数缩短一半，重点突出差异化竞争优势"})
response = client.chat.completions.create(model="kimi-k2.6", messages=messages)
print("修改版：\n", response.choices[0].message.content)

模式三：JSON 结构化输出

做数据提取工具时必用，确保输出格式固定可解析：

import json

response = client.chat.completions.create(
    model="kimi-k2.6",
    messages=[{
        "role": "user",
        "content": """从以下合同条款中提取关键信息，输出 JSON 格式：

合同条款：甲方需在2026年8月31日前交付系统，验收周期30天，
逾期罚款为合同总价的0.5%/天，最高不超过10%。

输出格式：
{
  "deadline": "交付日期",
  "acceptance_days": 验收天数(整数),
  "penalty_rate": "罚款比例",
  "penalty_cap": "罚款上限"
}"""
    }],
    response_format={"type": "json_object"}  # 强制 JSON 输出
)

data = json.loads(response.choices[0].message.content)
print(data)
# 输出：{'deadline': '2026年8月31日', 'acceptance_days': 30, 'penalty_rate': '0.5%/天', 'penalty_cap': '10%'}

模式四：长文件处理（256K 上下文）

Kimi K2 的核心能力，直接喂入完整长文档：

# 读取本地文件
with open("contract.txt", "r", encoding="utf-8") as f:
    document = f.read()

response = client.chat.completions.create(
    model="kimi-k2.6",           # 256K 上下文
    messages=[
        {
            "role": "system",
            "content": "你是专业合同审查律师，专注于识别风险条款和不平等条款"
        },
        {
            "role": "user",
            "content": f"请审查以下合同，列出所有风险条款并给出修改建议：\n\n{document}"
        }
    ],
    temperature=0.2
)

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

---

2.6 常见报错速查

报错信息	原因	解决方法
AuthenticationError	API Key 无效或未设置	检查环境变量是否生效，Key 格式是否完整
ModuleNotFoundError: openai	库未安装	运行 pip install openai
APIConnectionError	网络问题	检查网络，api.moonshot.ai 无需梯子
RateLimitError	调用频率超限	加 time.sleep(1) 或减少并发
context_length_exceeded	输入超过上下文上限	换 K2.6 或 moonshot-v1-128k，或截短输入
输出质量差	system prompt 不够清晰	加明确的角色设定和输出格式要求

高频问题：Windows 环境变量设置后读不到

原因：setx 命令设置后，需要重新打开新的命令提示符才生效，当前窗口看不到新变量。

临时解决方案（开发调试期可用，生产环境禁止）：

import os
os.environ["MOONSHOT_API_KEY"] = "sk-你的Key"  # 仅当前进程有效

---

2.7 成本监控：养成好习惯

在每次 API 调用后打印用量，避免循环写错导致意外消耗：

def call_kimi(messages, model="kimi-k2.6"):
    response = client.chat.completions.create(
        model=model,
        messages=messages
    )
    
    usage = response.usage
    # 估算成本（K2.6 输入 $0.95/M，输出 $4.00/M）
    input_cost = usage.prompt_tokens * 0.95 / 1_000_000
    output_cost = usage.completion_tokens * 4.00 / 1_000_000
    total_cost = input_cost + output_cost
    
    print(f"[用量] 输入:{usage.prompt_tokens} 输出:{usage.completion_tokens} | 估算成本:${total_cost:.6f}")
    
    return response.choices[0].message.content

# 使用
result = call_kimi([{"role": "user", "content": "分析一下AI行业趋势"}])
print(result)

批量处理前先用单条测试：跑100条数据之前，先跑1条验证prompt和输出格式，再批量跑。

---

2.8 K2.7 Code 的第一次调用（特殊说明）

K2.7 Code 强制开启思考模式，首次调用时响应时间会比普通模型慢3-10秒，这是模型在"内部推理"，是正常现象：

import time

start = time.time()

response = client.chat.completions.create(
    model="kimi-k2.7-code",  # 代码专项模型
    messages=[{
        "role": "user",
        "content": "写一个 Python 函数，输入一个列表，返回去重后按频率降序排列的元素列表"
    }]
)

elapsed = time.time() - start
print(f"耗时：{elapsed:.1f}秒")
print(response.choices[0].message.content)

K2.7 Code 的输出会比普通模型更长——它会先解释思路，再给代码，通常还会有边界条件说明。对客户来说，这种交付质量是值钱的，也是你可以高报价的理由。

---

本课行动清单

• [ ] 注册 Kimi 开放平台，查看当前免费额度
• [ ] 创建 API Key 并安全保存到环境变量
• [ ] 运行 hello_kimi.py，看到第一次成功输出
• [ ] 测试一次 JSON 结构化输出模式
• [ ] 用 K2.7 Code 跑一次代码生成，感受思考模式的输出风格

---

→ 继续阅读：第03课_Kimi模型选型全景与成本计算.md