Kimi K3: The Complete Developer Guide

python3 -m pip install --upgrade 'together>=2.0.0'

import os
from together import Together

MODEL = "moonshotai/Kimi-K3"

client = Together(
    api_key=os.environ["TOGETHER_API_KEY"],
)

completion = client.chat.completions.create(
    model=MODEL,
    messages=[{"role": "user", "content": "用一句话介绍 Kimi K3。"}],
    max_tokens=130_000,
)
print(completion.choices[0].message.content)

# 调整深度： "low" | "high" | "max"
completion = client.chat.completions.create(
    model=MODEL,
    reasoning_effort="max",
    messages=[{"role": "user", "content": "证明根号2是无理数。"}],
    max_tokens=8192,
)

# 即时模式，完全不计费思考令牌
fast = client.chat.completions.create(
    model=MODEL,
    messages=[{"role": "user", "content": "法国的首都是哪里？"}],
    reasoning={"enabled": False},
    max_tokens=256,
)

stream = client.chat.completions.create(
    model=MODEL,
    messages=[{"role": "user", "content": "解释为什么天空是蓝色的。"}],
    max_tokens=4096,
    stream=True,
)

in_answer = False
for chunk in stream:
    if not chunk.choices:
        continue
    delta = chunk.choices[0].delta
    thinking = getattr(delta, "reasoning_content", None) or getattr(delta, "reasoning", None)
    if thinking:
        print(thinking, end="", flush=True)
    if delta.content:
        if not in_answer:
            print("\n--- answer ---")
            in_answer = True
        print(delta.content, end="", flush=True)

import base64
from pathlib import Path

# 选项A：通过URL传递图片
IMAGE_URL = "https://raw.githubusercontent.com/pytorch/pytorch/main/docs/source/_static/img/pytorch-logo-dark.png"
image_content = {"type": "image_url", "image_url": {"url": IMAGE_URL}}

# 选项B：通过base64传递本地图片（取消注释以使用）
# image_data = base64.b64encode(Path("image.png").read_bytes()).decode()
# image_content = {"type": "image_url",
#                  "image_url": {"url": f"data:image/png;base64,{image_data}"}}

completion = client.chat.completions.create(
    model=MODEL,
    max_tokens=2048,
    messages=[{
        "role": "user",
        "content": [
            image_content,
            {"type": "text", "text": "描述这张图片。"},
        ],
    }],
)

import json

completion = client.chat.completions.create(
    model=MODEL,
    max_tokens=4096,
    messages=[{"role": "user", "content": "Ada Lovelace 36岁。"}],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "person",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {"name": {"type": "string"}, "age": {"type": "integer"}},
                "required": ["name", "age"],
                "additionalProperties": False,
            },
        },
    },
)

person = json.loads(completion.choices[0].message.content)
# -> {'name': 'Ada Lovelace', 'age': 36}

更宽松的 {"type": "json_object"} 模式在 Together 上也能正常工作，当你只需要语法正确的 JSON 时。无论采用哪种模式，请务必保持 max_tokens 设置得足够大：在发出第一个符合模式的 token 之前，整个思考过程都会被消耗，因此过紧的限制会导致 JSON 被截断而不是推理过程被限制。

### 工具和 tool_choice

K3 保留了标准的工具选择约束。标准流程：在 tools 中声明函数；当模型返回 tool_calls 时，将完整的助手消息追加到历史记录中，然后为每个调用追加一条带有匹配 tool_call_id 的工具消息，然后再次调用。在第一轮使用 tool_choice="required" 可强制至少一次工具调用，之后切换回 "auto"。更改 tool_choice 不会使前缀缓存失效。

### 动态工具加载

你可以将完整的工具定义（包括全名、描述和参数）放入一个携带 tools 字段且没有内容的系统消息中。从该消息的位置开始，工具将变得可用。

关键规则：

- 动态声明使用与顶级 tools 字段完全相同的格式。

- 它们按请求应用，不会被服务器保留，因此需要自己在后续请求历史中保留该消息。保留消息可以同时保持工具可用性和缓存前缀；删除消息意味着模型将无法再调用该工具，且修改后的前缀可能无法命中缓存。

- 在消息末尾追加动态声明不会影响缓存前缀；删除或修改早期声明可能在修改点之后影响缓存命中率。

大型工具目录的推荐模式：

- 对话开始时：仅声明一个搜索工具函数（由你的后端实现）和几个核心工具，并在系统提示中宣传可搜索的领域标签。

- 首次调用：设置 tool_choice: "required" 以强制在回答前进行检索。

- 按需注入：根据检索结果，通过系统消息插入匹配工具的完整定义。

- 直接调用：模型在后续生成过程中直接使用已加载的工具。

- 成本权衡：在对话开始前决定 reasoning_effort 的值。

代码示例：

### 1M 上下文与自动缓存

Together 支持完整的 1M 上下文长度，上下文缓存是自动进行的。保持长前缀（系统提示、知识库、仓库转储）在请求之间字节稳定，以便后续调用可以命中缓存。Moonshot 建议将固定的大块上下文（知识文档）放置在消息数组的最开始位置，位于系统消息之前，然后在该位置之后追加问题和回复。

### 采样参数

采样参数是固定的，请求中应省略这些参数。模型是使用这些参数进行训练的，不支持设置其他替代参数：

- temperature = 1.0
- top_p = 0.95
- n = 1
- presence_penalty = 0
- frequency_penalty = 0

### 保留思考过程

K3 是以保留思考历史模式进行训练的，因此跟踪信息是下一个回合依赖的状态。使用以下方式从上一回合保留思考令牌并传递给后续回合：

删除 reasoning_content 行后，相同的调用每次都会返回一个不同的新生成数字。在实际代码中，你永远不会手动编写跟踪信息；而是重放模型生成的内容，即工具循环中的一行：

## Kimi K3 定价

Kimi K3 按 token 计费，包含一个奖励稳定前缀的缓存命中输入层级：

Kimi K3 定价

层级 | 每百万 tokens 价格
--- | ---
输入（缓存命中） | $0.30
输入（缓存未命中） | $3.00
输出 | $15.00

上下文窗口：1,048,576 tokens（1M）。思考 token 按输出计费。

需要理解的两个成本方面：

- 缓存是你手中的杠杆。在编码工作负载中，如果保持前缀稳定，缓存命中率超过 90% 时，有效输入成本将趋于 $0.30 的下限。但若重构早期消息或工具声明，将破坏这一效果。

- 思考过程按输出计费且可调节。思考 token 以 $15/M 的价格计为输出 token，且无法完全禁用思考，但 reasoning_effort 现在有三个级别。max 仍是默认值，因此一个从不设置该字段的流水线会在每次调用（包括简单调用）中支付最大推理费用。

## Kimi K3 基准测试

在评估套件中，Kimi K3展现出前沿水平的性能。它在多个编码和智能体基准测试中（SWE Marathon、BrowseComp、DeepSearchQA、AutomationBench、OmniDocBench）领先行业，与其他基准测试中最强的专有模型保持竞争力，同时明显优于其他测试的开源模型GLM-5.2。在少数基准测试中，其表现略逊于Claude Fable 5和GPT 5.6 Sol，这与Moonshot对模型自身定位的描述一致。

以下所有Kimi K3结果均使用最大推理努力值。

Kimi K3基准测试

推理努力值：最大

基准测试

Kimi K3

max

Claude Fable 5

max，备用方案

GPT 5.6 Sol

Claude Opus 4.8

GLM-5.2

编码

DeepSWE

67.5

70.0

73.0

59.0

46.2

Program Bench

77.8

76.8

77.6

71.9

63.7

Terminal Bench 2.1

88.3

84.6

88.8

82.7

FrontierSWE

81.2

86.6

71.3

66.7

67.3

SWE Marathon

42.0

35.0

39.0

40.0

13.0

PostTrain Bench

36.6

41.4

34.6

34.1

34.3

MLS Bench

48.3

49.9

42.8

40.4

Kimi Code Bench 2.0（内部）

72.9

76.9

64.8

71.7

64.2

智能体

GDPval-AA v2（Elo）

1668

1760

1748

1600

1514

BrowseComp

91.2

88.0

90.4

84.3

N/A

DeepSearchQA（F1）

95.0

94.2

93.1

Toolathlon-Verified

73.2

77.9

74.9

76.2

59.9

MCP Atlas

84.2

84.7

83.6

82.6

Automation Bench

30.8

29.1

29.7

27.2

12.9

Job Bench

52.9

57.4

46.5

48.4

43.4

AA-Briefcase（Elo）

1548

1583

1495

1354

1260

APEX-Agents

41.0

43.3

39.9

39.4

35.6

Office QA Pro

63.3

69.9*

63.2*

63.9*

SpreadsheetBench 2

34.8

34.7*

32.4*

31.6*

28.1

DECK-Bench（内部）

73.5

74.7

66.9

68.6

推理与知识

GPQA-Diamond

93.5

92.6

94.1

91.0

HLE-Full

43.5

53.3

44.5

49.8*

HLE-Full w/ tools

56.0

63.0

58.0

57.9*

视觉

MMMU-Pro

81.6

83.0

78.9

MMMU-Pro w/ python

83.4

86.5

CharXiv（RQ）

84.8

88.9

80.5

CharXiv（RQ）w/ python

91.3

89.1

89.9

MathVision

94.3

94.8

95.8

86.7

MathVision w/ python

97.8

98.6

97.1

BabyVision w/ python

85.7

90.5

ZeroBench_main（pass@5）

23.0

17.0

ZeroBench_main w/ python（pass@5）

46.0

34.0

WorldVQA ForceAnswer

51.0

56.7

41.8

39.1

OmniDocBench

91.1

89.8

85.8

87.9

PerceptionBench

58.5

57.2

59.7

47.2

所有Kimi K3结果均使用最大推理努力值。标注星号（*）的数值是在与基准运行条件不同的情况下报告的——例如，引用自外部来源或不同测试框架。N/A表示未发布分数。阴影单元格标记该行的领先结果。有关每个基准测试的具体方法，请参阅原始报告。来源：Kimi K3。

## Kimi K3 与前沿模型的对比

汇总基准测试表格只能提供有限信息。为了深入了解成本、编码质量和路由行为，我们在DeepSWE上对Kimi K3与领先的专有模型进行了对比：

- Kimi K3 与 GPT 5.6 Sol 在 DeepSWE 上的对比：成本、编码和路由
- Kimi K3 与 Claude Fable 5 在 DeepSWE 上的对比：成本和编码

## 常见问题

Kimi K3 是什么？Kimi K3 是 Moonshot AI 的旗舰 2.8 万亿参数模型，也是首个 3 万亿参数级别的开源模型，专为长周期编码、知识工作和推理而设计。

### Kimi K3 是开源的吗？

是的。它作为开源权重模型发布，Together AI 直接与 Moonshot 团队合作提供服务。

### Kimi K3 的上下文窗口有多大？

100万 tokens（1,048,576），在 Together AI 上完全支持并附带自动上下文缓存。

### 在 Together AI 上使用 Kimi K3 的成本是多少？

每100万次缓存命中输入令牌0.30美元，每100万次缓存未命中输入令牌3.00美元，每100万次输出令牌15.00美元。

### 能否在Kimi K3上关闭思考功能？

在Together AI平台上，可以通过设置reasoning={"enabled": False}来禁用思考功能，或通过将reasoning_effort参数设为low、high或max来调整推理深度。

### Kimi K3是否支持视觉功能？

支持。Kimi K3具备原生视觉能力，单次请求可接受多张图片，只要总请求体不超过100 MB。

## Kimi K3现已上线Together AI。立即运行并部署到生产环境。

将K3纳入你的系统只需一次API调用即可。

- 运行Kimi K3推理：[Kimi K3 API on Together AI](https://example.com)
- 开始使用API开发：[阅读文档](https://example.com/docs)