类型安全 AI：构建结构化 JSON 输出

为什么需要结构化输出？

原始的 AI 响应是不可预测的。不同的供应商返回不同的格式，即使是同一个模型在不同请求之间也可能存在差异。结构化输出（Structured outputs）通过在每个响应上强制执行 JSON 模式来解决这个问题，为您的应用程序提供可依赖的契约。

工作原理

定义模式（schema）：在 ModelRiver 控制台下的 Structured Outputs 中创建一个 JSON 模式。
附加到工作流：将模式链接到一个或多个工作流。
自动验证：ModelRiver 根据您的模式验证每个 AI 响应，并合并结果，以便所需字段始终存在。
供应商故障转移：如果供应商停机或超时，ModelRiver 会依次尝试您配置的备用模型。如果所有尝试都失败，请求将返回错误。ModelRiver 绝不会编造响应。

创建结构化输出

从您的项目侧边栏导航至 Structured Outputs
点击 Create Structured Output
定义您的 JSON schema，包含所需的字段、类型和描述
添加符合该模式的示例数据（用于测试模式）
保存并附加到工作流

模式示例

JSON

1{
2  "type": "object",
3  "required": ["summary", "sentiment", "category"],
4  "properties": {
5    "summary": {
6      "type": "string",
7      "description": "A concise summary of the input"
8    },
9    "sentiment": {
10      "type": "string",
11      "enum": ["positive", "negative", "neutral"],
12      "description": "Overall sentiment classification"
13    },
14    "category": {
15      "type": "string",
16      "description": "Topic category of the content"
17    },
18    "confidence": {
19      "type": "number",
20      "minimum": 0,
21      "maximum": 1,
22      "description": "Model confidence score"
23    }
24  }
25}

最佳实践

在模式中 包含示例 以指导供应商。ModelRiver 将其作为上下文传递以提高遵循度。
从简单开始：从最少的模式开始，随着应用程序的成熟添加字段。
对分类字段 使用枚举（enums） 以约束值并减少解析错误。
监控验证情况：在可观测性（Observability）中检查验证失败率并相应调整模式。
配置备用模型：添加来自其他供应商的备用模型，这样单个供应商故障不会导致请求失败。

所有供应商均失败时

如果主模型和所有备用模型都失败，ModelRiver 会返回错误，并在 meta.attempts 中列出每次尝试的供应商、模型和失败原因。它不会填充占位数据或示例数据，因此任何成功的响应都包含由模型生成的输出。

在您的应用程序中处理该错误，例如稍后重试或显示“请重试”提示
如果需要在不调用供应商的情况下获取示例数据，请使用测试模式

后续步骤

Type-safe AI Solution：在生产中为何以及如何使用结构化数据。
Test mode：使用示例数据验证集成。
Build a workflow：将结构化输出附加到工作流。
导入与导出：随工作流配置一起迁移结构化输出。
API response formats：了解响应结构。