跳转到主要内容
Kimi API 通过 response_format 参数约束聊天补全的输出格式。它支持两种模式：
模式type 值说明适用场景
JSON Modejson_object保证输出为合法 JSON Object，但不约束具体字段简单 JSON 输出、字段灵活的场景
Structured Outputjson_schema通过 JSON Schema 精确定义字段名、类型、嵌套结构需要严格结构、对接下游系统的场景
本文档重点介绍 response_format 的 json_schema 模式（即 Structured Output），包括参数用法、模型差异、常见问题与错误处理。JSON Mode 的基础用法可参考 JSON Mode。

​
response_format 基本结构

response_format={
    "type": "json_schema",           # 或 "json_object"
    "json_schema": {                 # json_schema 模式必填
        "name": "schema_name",
        "strict": True,
        "schema": { ... }            # 你的 JSON Schema
    }
}
  • type 为 json_object 时，不需要 json_schema 字段。
  • type 为 json_schema 时，必须提供 json_schema.name 和 json_schema.schema。

​
Structured Output 的优势

与 JSON Mode 相比，Structured Output 的优势在于：
  • 结构严格受控：模型输出必须完全遵循你定义的 JSON Schema，字段名、类型、嵌套层级都一一对应。
  • 无需在 prompt 中反复描述格式：将格式要求从 schema 中剥离，降低 prompt 工程的复杂度。
  • 下游系统对接更可靠：输出可直接被 json.loads 解析为强类型对象，无需额外的容错处理。
模型差异提示：不同模型对 JSON Schema 的支持程度存在差异。
  • kimi-k2.7-code 对 Structured Output 的支持最稳，包括嵌套对象、数组、anyOf / oneOf / $ref / additionalProperties: true 等都能正常处理。
  • kimi-k2.6 在复杂 schema 下偶有不稳定表现，例如 $ref 可能返回 Markdown 代码块、oneOf 可能被忽略、partial=true 可能输出 schema 外字段。使用 kimi-k2.6 时建议优先使用简单 schema，并在业务层做二次校验。

​
快速开始

​
基本用法

在 response_format 中将 type 设为 "json_schema"，并传入 json_schema 对象： 
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["MOONSHOT_API_KEY"],
    base_url="https://api.moonshot.cn/v1",
)

completion = client.chat.completions.create(
    model="kimi-k2.7-code",
    messages=[
        {
            "role": "system",
            "content": "你是一个新闻摘要助手。"
        },
        {
            "role": "user",
            "content": "请总结以下新闻：今日，人工智能技术领域迎来重大突破..."
        }
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "news_summary",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "title": {"type": "string", "description": "新闻标题"},
                    "author": {"type": "string", "description": "作者或来源"},
                    "publish_time": {"type": "string", "description": "发布时间，ISO 8601 格式"},
                    "summary": {"type": "string", "description": "200 字以内的摘要"},
                    "keywords": {
                        "type": "array",
                        "items": {"type": "string"},
                        "description": "3-5 个关键词"
                    }
                },
                "required": ["title", "author", "summary", "keywords"]
            }
        }
    }
)

import json
result = json.loads(completion.choices[0].message.content)
print(result["title"])
print(result["keywords"])

​
输出示例

{
  "title": "人工智能技术取得重大突破",
  "author": "科技日报",
  "publish_time": "2024-06-19",
  "summary": "研究人员在深度学习模型效率优化方面取得新进展...",
  "keywords": ["人工智能", "深度学习", "模型优化", "技术突破"]
}

​
关于 reasoning_content

kimi-k2.7-code 等思考模型在返回 content 的同时，可能还会返回 reasoning_content。请只解析 choices[0].message.content 作为最终 JSON，不要直接用 json.loads 处理整个响应对象。 
content = completion.choices[0].message.content
result = json.loads(content)

​
参数说明

参数类型说明
type"json_schema" | "json_object"必须设置，二选一
json_schema.namestringSchema 的标识名称，用于日志和调试
json_schema.strictboolean是否严格按 schema 约束输出。建议显式设置为 true
json_schema.schemaobjectJSON Schema 对象，定义输出结构
注意：实测中 strict 为 true、false 或省略时，kimi-k2.7-code 对 schema 的遵守程度都较高；kimi-k2.6 在 strict=false 或省略时更容易输出 schema 外字段。因此建议始终显式设置 strict: true。

​
strict 模式说明

json_schema.strict 建议设置为 true，表示强制模型输出必须完全匹配 schema 定义。此时你的 schema 需要符合 MFJS（Moonshot Flavored JSON Schema） 规范。
MFJS 的模型差异：
  • kimi-k2.7-code 对 anyOf / oneOf / $ref / additionalProperties: true 等特性的支持已比较完善，通常不会触发 MFJS 报错。
  • kimi-k2.6 在复杂 schema 下更可能触碰 MFJS 限制，建议保持 schema 简单。
如果 strict 设为 false，API 仅保证输出为合法 JSON 对象，但不强制约束内部字段结构。这在 schema 较复杂或你希望给予模型更大灵活性时可以使用。

​
如何校验 schema 是否符合 MFJS

可以使用 walle CLI 工具快速自检 schema 的兼容性： 
# 安装 walle 工具
go install github.com/moonshotai/walle/cmd/walle@latest

# 校验你的 schema
walle -schema 'your_schema_json' -level strict
实测中，即使 schema 包含 anyOf / oneOf / $ref，API 也常能正常返回 200，且响应中未出现 warning 字段。因此 walle 更适合作为静态检查入口，实际兼容性请以目标模型的在线调用结果为准。

​
嵌套对象与数组示例

Structured Output 支持任意深度的嵌套对象和数组，这在 kimi-k2.7-code 上表现稳定： 
response_format={
    "type": "json_schema",
    "json_schema": {
        "name": "meeting_minutes",
        "strict": True,
        "schema": {
            "type": "object",
            "properties": {
                "meeting_title": {"type": "string"},
                "date": {"type": "string"},
                "attendees": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {
                            "name": {"type": "string"},
                            "role": {"type": "string"},
                            "present": {"type": "boolean"}
                        },
                        "required": ["name", "role", "present"]
                    }
                },
                "agenda_items": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {
                            "topic": {"type": "string"},
                            "discussion": {"type": "string"},
                            "action_items": {
                                "type": "array",
                                "items": {
                                    "type": "object",
                                    "properties": {
                                        "assignee": {"type": "string"},
                                        "task": {"type": "string"},
                                        "deadline": {"type": "string"}
                                    },
                                    "required": ["assignee", "task"]
                                }
                            }
                        },
                        "required": ["topic", "discussion"]
                    }
                }
            },
            "required": ["meeting_title", "date", "attendees", "agenda_items"]
        }
    }
}

​
JSON Mode 与 Structured Output 的对比

特性json_objectjson_schema
输出合法性保证合法 JSON Object保证合法 JSON Object
结构约束无（需在 prompt 中描述）有（由 schema 严格定义）
字段类型不强制强制匹配
字段缺失可能缺失字段required 字段必现
使用场景简单 JSON 输出需要精确结构的下游系统对接
strict 校验无有（MFJS 规范）

​
注意事项

  1. Schema 需符合 MFJS 规范：strict=true 时，建议使用 walle CLI 工具预先校验 schema。常见的 MFJS 约束在 kimi-k2.7-code 上已大幅放宽，但在 kimi-k2.6 上仍可能触发。
  2. 提示词仍需提供上下文：虽然格式由 schema 约束，但模型仍需理解业务内容。请在 system prompt 或 user prompt 中清晰描述任务目标和数据来源。
  3. additionalProperties：
    • 设置为 false 时，模型不会输出 schema 中未定义的字段。
    • 设置为 true 或不指定时，kimi-k2.7-code 允许输出额外字段；kimi-k2.6 也可能输出额外字段，但稳定性不如 kimi-k2.7-code。
  4. 空值处理：当 required 字段在 prompt 中找不到对应信息时，模型可能返回空字符串（如 "employee_id": ""）。建议在业务层再做一层空值校验。
  5. 错误处理：当 schema 过于复杂或 prompt 与 schema 矛盾时，模型可能输出不完整的 JSON（finish_reason="length"）。建议检查 finish_reason 并适当增大 max_tokens。
  6. 与 Partial Mode 的兼容性：
    • kimi-k2.7-code 在简单 schema 下与 partial=true 混用通常正常，但复杂 schema 仍可能破坏结构约束。
    • kimi-k2.6 在 partial=true 下更容易输出 schema 外字段，因此不建议在该模型上混用。

​
常见错误

​
invalid_request_error

Schema 格式本身不合法（例如 json_schema.schema 不是 object）时，API 会返回 400，错误类型为 invalid_request_error： 
{
  "error": {
    "message": "Invalid request: the `response_format.json_schema.schema` field in the request (expected type dict[string,interface]) is illegal...",
    "type": "invalid_request_error"
  }
}
请检查 schema 是否为合法的 JSON Schema 对象。

​
输出被截断（finish_reason="length"）

模型在输出完整 JSON 之前达到了 max_tokens 限制。建议：
  • 增大 max_tokens（例如 4096 或更高）
  • 简化 schema 的嵌套层级
  • 缩短输入文本长度

​
字段类型不匹配 / 输出 Markdown 代码块

在 kimi-k2.6 等旧模型上，可能出现以下情况：
  • 返回的 content 包含 Markdown 代码块（如 json ... ），导致 json.loads 失败。
  • oneOf / $ref 等复杂 schema 未被严格遵守。
建议：
  • 使用 kimi-k2.7-code 进行 Structured Output 调用。
  • 如果必须使用 kimi-k2.6，在业务层先 stripping Markdown 标记，再对解析结果做 schema 字段校验。