结构化响应

在 Venice API 中使用结构化响应

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

结构化输出的 “response_format” 字段采用 OpenAI API 格式，并在 OpenAI 指南此处进一步描述。OpenAI 还发布了一篇介绍如何在 API 中使用结构化输出的文章此处。由于这是高级功能，本页面底部列出了一些需要注意的”陷阱”。

并非所有模型都原生支持此功能。请参阅模型列表此处，并查找 “supportsResponseSchema” 以确定适用的模型。

    {
      "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”，都是字符串。

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”。

{
  "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"]

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

• 重要：additionalProperties 必须设置为 false，response_format 才能正常工作

• 重要：strict 必须设置为 true，response_format 才能正常工作