跳到主要内容

把旧 Kimi K2 / Moonshot V1 迁移到 Kimi K3（单次文本调用版）

你手上的脚本、集成或本地工具还在调 kimi-k2-0711-preview 或 moonshot-v1-*，突然发现“模型不可用”或者返回了一堆不兼容的错误。这篇教程只解决一件事：把一次简单的文本生成调用，从已下线的旧型号平滑迁移到当前 Kimi K3 API。

读完之后，你应该能：

  • 确认自己是不是在用即将/已经退役的旧型号；
  • 在中国版和国际版里正确配置 API Key 与端点；
  • 运行一个 Python 脚本，拿到完整文本回答，并读懂它的成败信号；
  • 知道自己的应用接下来需要改哪几处。

后续的多轮对话、工具循环、图像输入以及自托管部署，会在官方文档或其他教程展开。这里只聚焦“一次文本调用”的最小可行迁移路径。

一、先搞清楚：哪些型号真的下线了？​

不同平台、不同资料的模型列表经常打架，我们只采信当前官方文档（截至编写时）：

关键时间点与型号（适用于官方托管 API；权重下载、第三方服务等另算）：

  • 2026 年 5 月 25 日下线：旧 K2 系列
    • kimi-k2-0711-preview
    • kimi-k2-0905-preview
    • kimi-k2-turbo-preview
    • kimi-k2-thinking
    • kimi-k2-thinking-turbo
  • 2026 年 8 月 31 日下线：
    • moonshot-v1-*（包括 auto、vision-preview 等变体）
    • kimi-k2.5

注意：

  • “K2 下线” ≠ “所有带 K2 的型号都退役”。
    现行如 kimi-k3、kimi-k2.6、kimi-k2.7-code 等仍按当前生命周期管理，本文迁移目标是 当前 kimi-k3。
  • 旧 K2 最大上下文约 128K（K2 Instruct 0905 / Thinking 约 256K），K3 则是 1,048,576 tokens。
    容量变大不代表你可以直接把整个代码仓库扔进去；那是架构问题，不是模型切换问题。

结论：如果你的调用里还出现上述旧 ID，它们已经拿不到官方托管服务了，必须迁移。

二、选择平台与端点：中国版 vs 国际版​

Kimi 分两个独立平台，端点不同、计费币种也不同。不要把中国的 Key 配到国际端点，反之亦然。

你只需要做两件事：

  1. 在对应平台创建并复制 API Key；
  2. 在你的脚本里把 MOONSHOT_BASE_URL 固定成同一个区域的端点。

不要把 MOONSHOT_BASE_URL 写成动态拼接或从多个候选里随机选，鉴权失败时最容易踩在这里。

三、环境准备：Python 版本与 SDK 要求​

前提：

  • Python 3.10+（这是固定要求；Kimi 通用 quickstart 里写的 3.9 最低要求不能直接套到这里）
  • macOS / Linux / WSL 环境，使用普通 Shell 即可

一键准备命令（在中国版示例）：

python3 -m venv .venv
source .venv/bin/activate
python -m pip install "openai==3.26.0"
export MOONSHOT_API_KEY="your-api-key"
export MOONSHOT_BASE_URL="https://api.moonshot.cn/v1"

如果使用国际版平台：

  • 只改 MOONSHOT_BASE_URL 那一行：
export MOONSHOT_BASE_URL="https://api.moonshot.ai/v1"

版本号 openai==3.26.0 是为了保证与 Kimi 官方 quickstart 生态兼容；通常更新版本也工作，但写教程必须可复现。

四、最小可运行脚本：一次文本调用​

下面这版代码直接复制粘贴即可运行，它只做一件事：用 kimi-k3 生成一句代码审查的说明，并验证回答是否“完整”。

kimi_text.py · verify_offline.py

保存为 kimi_text.py（当前工作目录）：

import os

from openai import OpenAI

with OpenAI(
    api_key=os.environ["MOONSHOT_API_KEY"],
    base_url=os.environ["MOONSHOT_BASE_URL"],
) as client:
    completion = client.chat.completions.create(
        model="kimi-k3",
        reasoning_effort="low",
        max_completion_tokens=4096,
        messages=[
            {"role": "user", "content": "Describe a code review in one sentence."}
        ],
    )

choice = completion.choices[0]
if choice.finish_reason != "stop" or not choice.message.content:
    raise RuntimeError(f"No complete text answer: finish_reason={choice.finish_reason}")

print(choice.message.content)

运行：

python kimi_text.py

你会看到类似（不保证逐字相同）：

A code review is a systematic examination of source code to detect defects, verify correctness, assess readability, and ensure consistency with established guidelines before merging.

说明与要点（逐条解读，避免踩坑）：

1) 正常流程与费用​

  • 使用有效凭据运行，脚本会向所选端点发送真实请求并产生按量计费。
  • 输出即为模型生成的最终文本。

2) 如何判断“回答是否完整”​

脚本里这两行是关键：

if choice.finish_reason != "stop" or not choice.message.content:
    raise RuntimeError(...)
  • finish_reason == "stop"：表示模型自然结束生成（理想情况）。
  • 若为 "length"：说明响应触及了 max_completion_tokens 上限；脚本会抛错，不把截断内容当成完整回答。
  • 代码不会分析回答语义、正确性或异常文本，因此一段非空但答非所问的回应仍会被视为“完整”。

3) max_completion_tokens=4096 的真实含义​

  • 这是初始的 completion budget（生成 token 预算），不是保证你能得到 4096 个可见回答 token。
  • K3 始终进行推理，推理过程本身也会占用这份额度。
  • 遇到未完成结果时：
    • 先看 finish_reason 是否为 "stop"
    • 再看是否有正文
    • 再根据任务复杂度调整预算

4) reasoning_effort 是什么？​

  • 支持值："low" / "high" / "max"，默认 "max"。
  • 这里的简单文本请求显式使用 "low"。
    它不是“关闭思考”的开关，只是告诉模型这次以较低推理强度生成回答，更适合短文本、快速回复类场景。

5) 那些旧参数要不要删？​

如果你是从旧 K2 / V1 代码迁移过来，很可能会看到类似：

temperature=0.2, top_p=0.3, presence_penalty=..., frequency_penalty=...

对当前 kimi-k3 文本调用来说：

  • 直接省略这些参数。
  • K3 模型使用固定的采样参数，而非可调范围：
    • temperature 固定为 1.0，控制生成发散度。
    • top_p 固定为 0.95，作为核采样阈值。
    • n 固定为 1，每次调用返回一条响应。
    • 存在性惩罚（presence penalty）与频率惩罚（frequency penalty）均被设为 0，不再抑制重复词或常见语式。
  • 因此旧 .2 / .3 这类参数只能被显式删除，不应当作可按需微调的设置留给调用者。

6) 为什么用 OpenAI SDK + base_url？​

  • Kimi 官方 quickstart 推荐使用 OpenAI 兼容的 SDK 接入方式。
  • 旧代码里 from moonshot import Moonshot 这类导入不是当前推荐的路径（至少对这次迁移而言）。
  • 核心就两点：正确 API Key + 正确 base_url，然后走 chat.completions.create。

7) 鉴权失败的常见排查点​

如果脚本报错或返回 401/403：

  1. 确认 API Key 来自与你所用端点同一区域平台（中国 vs 国际）。
  2. 检查环境变量是否被其他脚本覆盖；bool(os.environ.get("MOONSHOT_API_KEY")) 能直接打印出来核对。
  3. 鉴权或推理错误中仍出现退役模型名：
    • 确认本次文本调用确实指向 kimi-k3。

五、计费速览：K3 与旧 K2 怎么不一样？​

很多老项目里还有“¥168/月无限 K2 API”之类的记忆，K3 时代按量计费更细：

价格单位均为 每 1,000,000 tokens（注意：是 100 万 tokens，不是模型的 1,048,576-token 上下文）。

K3 API 地区输入未命中缓存输入命中缓存输出缓存写入：5 分钟 / 1 小时
中国版，人民币¥20¥2¥100¥20 / ¥40
国际版，美元$3$0.30$15$3 / $6

要点：

  • K3 对输入、输出和缓存写入分别计费。
  • 缓存命中会续期，不会重复收“写入费”。
  • 国际版报价不含适用税费。
  • 旧会员套餐的额度不能直接用来预算新的按量调用。

具体价格与规则以官方定价页为准：

六、迁移清单：你接下来要改哪里？​

对照你的现有代码/集成，按这个顺序改：

  1. 确认模型 ID

    • 查找所有调用处是否使用 kimi-k2-* / moonshot-v1-* / kimi-k2.5。
    • 全部替换为当前 kimi-k3（或者你实际选用的 K3 型号）。

  2. 统一 SDK 与端点

    • 将导入改为 OpenAI 兼容的 client = OpenAI(...)。
    • 设置正确的 base_url，且不要混用中国/国际端点。

  3. 清理旧参数

    • 删除或注释掉 temperature=0.x、presence_penalty、frequency_penalty 等。
    • 如需控制生成行为，改用 reasoning_effort、max_completion_tokens、messages 结构等。

  4. 验证“完整回答”

    • 像脚本里那样检查：
      • finish_reason == "stop"
      • message.content 非空
    • 对长任务，根据结果调整 max_completion_tokens。

  5. 计费与预算

    • 明确你使用哪个区域平台，按对应价格表估算单次调用成本。
    • 把“每月无限”这种旧认知从你的预算表里划掉。

七、下一步往哪里走？（自然延伸）​

这次教程只覆盖“一次文本调用”。当你跑通之后：

  • 多轮对话 / 工具循环
    需要保留完整的 assistant 消息历史，并可能涉及推理字段与函数调用格式；继续参考官方 Kimi K3 quickstart 的对话与 agent 指南。
  • 图像输入
    K3 使用 image_url 内容对象，值可为 base64 或 ms:// 文件引用，不支持公网图片 URL；细节会在官方示例与 image quickstart 中展开。
  • 终端 Agent 而非 API 集成
    如果你更想用命令行的 Kimi Code CLI 做本地智能助手，可继续看对应的指南（如 Kimi Code CLI 教程）。

八、官方文档与参考链接​

现在，去改你那个还在调用旧 K2 / V1 的脚本吧。先跑通这一句，再把复杂度一点点加回来。