> ## Documentation Index
> Fetch the complete documentation index at: https://veniceai-mintlify-d2fddb8a.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 结构化响应

> 使用 response_format 和 JSON Schema 强制 Venice 聊天模型返回符合您的模式的 JSON，以获得可靠、可解析的输出。

Venice 现已在 API 中加入了通过 "response\_format" 字段实现的结构化输出。该字段使您能够生成遵循特定预定义格式的响应。通过这种新方法，与之前通过操纵系统 prompt 或函数调用相比，模型在响应中出现错误的键或值的可能性更低。

结构化输出的 "response\_format" 字段采用 OpenAI API 格式，并在 OpenAI 指南[此处](https://platform.openai.com/docs/guides/structured-outputs)进一步描述。OpenAI 还发布了一篇介绍如何在 API 中使用结构化输出的文章[此处](https://openai.com/index/introducing-structured-outputs-in-the-api/)。由于这是高级功能，本页面底部列出了一些需要注意的"陷阱"。

并非所有模型都原生支持此功能。请参阅模型列表[此处](https://docs.venice.ai/api-reference/endpoint/models/list?playground=open)，并查找 "supportsResponseSchema" 以确定适用的模型。

```json theme={null}
    {
      "id": "venice-uncensored",
      "type": "text",
      "object": "model",
      "created": 1726869022,
      "owned_by": "venice.ai",
      "model_spec": {
        "availableContextTokens": 32768,
        "capabilities": {
          "supportsFunctionCalling": true,
          "supportsResponseSchema": true,
          "supportsWebSearch": true
        },
```

### 如何使用结构化响应

要正确使用 "response\_format"，您可以使用各种 "properties" 定义 schema，这些属性代表输出类别，每个属性都有单独配置的数据类型。这些对象可以嵌套以创建更高级的输出结构。

下面是一个使用 response\_format 解释逐步求解数学方程过程的 API 调用示例。

可以看到，properties 被配置为要求响应中同时包含 "steps" 和 "final\_answer"。在嵌套中，steps 类别包含 "explanation" 和 "output"，都是字符串。

```json theme={null}
curl --request POST \
  --url https://api.venice.ai/api/v1/chat/completions \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "venice-uncensored",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful math tutor."
    },
    {
      "role": "user",
      "content": "solve 8x + 31 = 2"
    }
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "math_response",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "steps": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "explanation": {
                  "type": "string"
                },
                "output": {
                  "type": "string"
                }
              },
              "required": ["explanation", "output"],
              "additionalProperties": false
            }
          },
          "final_answer": {
            "type": "string"
          }
        },
        "required": ["steps", "final_answer"],
        "additionalProperties": false
      }
    }
  }
}

```

下面是从模型收到的响应。可以看到结构遵循了要求：首先提供 "steps"，每一步带有 "explanation" 和 "output"，然后是 "final answer"。

```json theme={null}
{
  "steps": [
    {
      "explanation": "Subtract 31 from both sides to isolate the term with x.",
      "output": "8x + 31 - 31 = 2 - 31"
    },
    {
      "explanation": "This simplifies to 8x = -29.",
      "output": "8x = -29"
    },
    {
      "explanation": "Divide both sides by 8 to solve for x.",
      "output": "x = -29 / 8"
    }
  ],
  "final_answer": "x = -29 / 8"
}

```

虽然这是一个简单的示例，但可以将其延伸至更高级的用例，例如：数据提取、思维链练习、UI 生成、数据分类等。

### 陷阱

通过 response\_format 使用结构化输出时，需要注意一些关键要求：

* 使用 response\_format 的初始请求生成响应可能需要更长时间。后续请求不会出现与初始请求相同的延迟。

* 对于较大的查询，如果达到 `max_tokens` 或模型超时，或违反任何速率限制，模型可能无法完成

* 不正确的 schema 格式将导致完成时出错，通常是由于超时

* 虽然 response\_format 确保模型以特定方式输出，但它不能保证模型在其中提供了正确的信息。内容由 prompt 和模型性能驱动。

* 通过 response\_format 实现的结构化输出与并行函数调用不兼容

* 重要：所有字段或参数都必须包含 `required` 标签。要使字段可选，您需要在字段的 `type` 中添加 `null` 选项，例如 `"type": ["string", "null"]`&#x20;

* 可以通过在 required 字段中给出 `null` 选项来允许空响应，从而使字段可选。

* 重要：`additionalProperties` 必须设置为 false，response\_format 才能正常工作

* 重要：`strict` 必须设置为 true，response\_format 才能正常工作