通过兼容 OpenAI 的端点获取结构化 JSON：七步接入
把模型回答接进业务系统，关键不是让它“看起来像 JSON”，而是明确字段、类型和失败处理。CodeRelay Hub 提供按量付费的统一 API 入口；接入结构化输出时，仍应分别验证所选模型与路由的能力。下面以工单分类为例，走完从请求到入库的流程。
1. 先定义业务契约
先确定下游需要什么，再编写提示词。工单分类可以只保留两个字段：分类和摘要。分类限定为“故障”“咨询”“其他”，摘要使用字符串。缺少信息时应如何处理，也要预先约定；不要让模型自行补全客户没有提供的事实。
2. 明确需要哪种输出模式
JSON 模式保证输出为合法 JSON，但不保证字段符合业务结构。支持相应能力的模型可以通过 JSON Schema 约束结构。本文使用 Chat Completions 的 response_format；不要把它与其他接口的参数位置混用。([developers.openai.com](https://developers.openai.com/api/docs/guides/structured-outputs?api-mode=chat&trk=article-ssr-frontend-pulse_little-text-block&utm_source=openai))
3. 配置连接并验证路由
将密钥和平台提供的完整基础地址放入环境变量，再交给 OpenAI SDK。建议先发送最小请求，确认鉴权、模型标识和路径配置正确，再加入结构约束。模型标识直接复制控制台中的实际值，不要根据展示名称猜测。
建议把连接配置与业务逻辑分开，分别管理 CODERELAY_API_KEY、CODERELAY_BASE_URL 和 CODERELAY_MODEL。上线前检查最终请求地址，避免重复拼接路径；日志只保留排错所需信息，不记录密钥。
4. 编写最小结构定义
下面是可放入请求的 response_format 对象。按照 OpenAI 严格模式的要求，所有属性都列入 required，并为对象设置 additionalProperties: false。先使用简单结构，再逐步增加字段，更容易定位兼容问题。([developers.openai.com](https://developers.openai.com/api/docs/guides/structured-outputs?api-mode=chat&trk=article-ssr-frontend-pulse_little-text-block&utm_source=openai))
{"type":"json_schema","json_schema":{"name":"ticket","strict":true,"schema":{"type":"object","properties":{"category":{"type":"string","enum":["故障","咨询","其他"]},"summary":{"type":"string"}},"required":["category","summary"],"additionalProperties":false}}}
5. 把结构和任务一起提交
请求中同时传入 model、messages 和上述 response_format。提示词只负责描述任务，例如“根据工单内容分类并概括摘要，不推测缺失信息”；结构定义负责表达字段约束。对支持该能力的接口，json_schema 用于启用结构化输出。([developers.openai.com](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create?utm_source=openai))
建议先关闭流式输出，用“登录后出现错误页面，请协助处理”作为测试输入。验收时检查分类是否正确、摘要是否忠于原文，而不只是检查请求是否返回成功。
6. 先判断响应状态，再解析内容
不要收到响应就立即解析正文。先检查接口错误、拒答和结束原因；拒答或达到输出上限时，响应可能不符合预期结构，必须单独处理。([developers.openai.com](https://developers.openai.com/api/docs/guides/structured-outputs?utm_source=openai))
建议将处理链路拆成三层：JSON 解析、结构校验、业务校验。即使字段类型正确，也要检查摘要是否为空、内容是否包含未经输入支持的判断。只有全部通过，才允许写入正式数据表。
7. 显式降级并留下测试记录
严格模式遇到不支持的结构可能直接返回错误，因此不要把参数错误当成网络故障反复重试。先核对结构，再确认模型和路由是否支持该能力。([developers.openai.com](https://developers.openai.com/api/docs/guides/structured-outputs?utm_source=openai))
建议只有在业务允许时才降级到 JSON 模式，并继续执行本地校验；校验失败就进入人工处理或错误队列，不要静默当成成功。为正常输入、空输入、诱导添加字段和超长输入建立回归样例，记录模型标识、结构版本、结束原因与校验结果。更换路由后重新运行这些样例，让兼容性成为可验证的结果。
欢迎在 CodeRelay Hub 开通免费工作区。