开发者文档 结构化输出
结构化输出
让模型返回 JSON，并在应用侧校验需要的字段。
使用前确认
需要：上游支持 json_object 模式的 Chat Completions 模型。网关不检查 response_format，原样交给上游；挑选模型时可参考控制台的「结构化输出」标记，或 /v1/models 返回的 capabilities.structured_outputs.supported。先完成快速开始中的环境变量配置，并把 YOUR_MODEL_ID 换成这把密钥可用的模型 ID。
完整示例
可从页头“下载代码”保存为 .py 文件，在配置好环境的服务端运行。
import os, json, urllib.request, urllib.error
BASE = os.environ["MOSSHUB_API_BASE"].rstrip("/")
KEY = os.environ["MOSSHUB_API_KEY"]
MODEL = "YOUR_MODEL_ID"
def chat(messages, **options):
body = {"model": MODEL, "messages": messages, "stream": False, **options}
request = urllib.request.Request(
BASE + "/v1/chat/completions",
data=json.dumps(body, ensure_ascii=False).encode("utf-8"),
headers={"Authorization": "Bearer " + KEY,
"Content-Type": "application/json"}, method="POST")
try:
with urllib.request.urlopen(request, timeout=60) as response:
result = json.load(response)
except urllib.error.HTTPError as error:
raise RuntimeError(f"HTTP {error.code}: {error.read().decode('utf-8')}") from error
choices = result.get("choices", [])
if not choices or not isinstance(choices[0].get("message"), dict):
raise RuntimeError("未返回有效消息，请检查错误信息与模型能力")
if choices[0].get("finish_reason") == "length":
raise RuntimeError("回答因输出上限而截断，请调整预算后重试")
return choices[0]["message"]
message = chat([
{"role": "system", "content": "只返回 JSON 对象，包含 title 字符串和 tags 字符串数组，不要 Markdown。"},
{"role": "user", "content": "为一家主打手冲咖啡的小店提取标题和三个标签。"},
], response_format={"type": "json_object"})
text = message.get("content")
if not isinstance(text, str):
raise RuntimeError("没有可解析的文本内容，检查是否拒绝或返回其他消息类型")
try:
data = json.loads(text)
except json.JSONDecodeError as error:
raise RuntimeError("模型没有返回合法 JSON，不要直接交给业务使用") from error
if (not isinstance(data, dict) or not isinstance(data.get("title"), str)
or not isinstance(data.get("tags"), list)
or not all(isinstance(tag, str) for tag in data["tags"])):
raise RuntimeError("JSON 字段类型与约定不一致")
print(json.dumps(data, ensure_ascii=False, indent=2))JSON 模式不等于字段校验
JSON 可解析，并不保证 title、tags 等业务字段齐全，本例主动校验字段与类型。更严格的 json_schema 模式同样原样交给上游，需确认所选模型支持。
常见问题
- 上游拒绝
response_format：网关原样返回上游的状态码和错误正文。换用支持的模型，或去掉该字段、在应用中处理普通文本。 - 输出截断（
finish_reason为length）：调高请求的输出上限后重试，不超过模型的最大输出。 - 模型拒绝或返回非文本消息：进入错误分支，不当成空 JSON 保存。
继续阅读
实际可调用的模型、授权与价格以控制台为准。
页面字体：MiSans（小米，依《MiSans 字体知识产权许可协议》使用）；Google Sans Flex（SIL Open Font License 1.1）。
页面字体：MiSans（小米，依《MiSans 字体知识产权许可协议》使用）；Google Sans Flex（SIL Open Font License 1.1）。