> ## Documentation Index
> Fetch the complete documentation index at: https://apione.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 结构化输出

> 让模型返回可验证的 JSON，并处理不完整或不合格结果。

结构化输出适合分类、信息抽取和工作流参数生成。是否支持 `response_format`、JSON Schema 或其他格式约束取决于模型参数。

## 基本策略

1. 查询模型是否支持结构化输出。
2. 使用尽量小、明确的结构。
3. 在服务端做 JSON 解析和 Schema 校验。
4. 校验失败时有限重试，或降级为普通文本解析。

## JSON 对象示例

```json theme={null}
{
  "model": "YOUR_APIONE_MODEL_ID",
  "messages": [
    {"role": "system", "content": "只返回 JSON，不要添加 Markdown。"},
    {"role": "user", "content": "从文本中提取产品名和数量：订购 3 个蓝色键盘。"}
  ],
  "response_format": {"type": "json_object"}
}
```

不要只依赖提示词保证格式。即使 HTTP 200，也要捕获空内容、截断 JSON、类型错误和缺失字段。

## 服务端校验

```javascript theme={null}
function parseOrder(text) {
  const value = JSON.parse(text);
  if (typeof value.product !== "string") throw new Error("product is required");
  if (!Number.isInteger(value.quantity) || value.quantity < 1) {
    throw new Error("quantity must be a positive integer");
  }
  return value;
}
```

## 截断与结束原因

当 `finish_reason` 表示长度限制，JSON 可能缺少结尾括号。不要尝试静默拼接不可信 JSON；提高合理的输出上限、缩小 Schema 或重新请求。工具调用场景应读取工具参数，而不是把正文当成 JSON。

## Schema 设计建议

* 字段名简短、含义明确；
* 枚举控制在必要范围；
* 避免深层嵌套和无限数组；
* 对金额、时间和标识使用字符串并单独验证格式；
* 明确哪些字段允许 `null`；
* 不让模型决定权限、最终价格或安全策略。

下一步：[工具调用](https://apione.ai/docs/api/tool-calls.md)、[Chat Completions](https://apione.ai/docs/models/chat.md)、[模型参数](https://apione.ai/docs/models/parameters.md)、[请求跟踪、超时与重试](https://apione.ai/docs/api/request-reliability.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.