通过结构化输出进行更深入的研究

帮助增强您对结构化输出和法学硕士的理解和最佳使用

In the previous article, we were introduced to structured outputs using OpenAI. Since the general availability release in ChatCompletions API (v1.40.0), structured outputs have been applied across dozens of use cases, and spawned numerous threads on OpenAI forums.

在上一篇文章中，我们介绍了使用 OpenAI 的结构化输出。自 ChatCompletions API (v1.40.0) 正式发布以来，结构化输出已应用于数十个用例，并在 OpenAI 论坛上产生了大量线程。

In this article, our aim is to provide you with an even deeper understanding, dispel some misconceptions, and give you some tips on how to apply them in the most optimal manner possible, across different scenarios.

在本文中，我们的目的是为您提供更深入的理解，消除一些误解，并为您提供一些关于如何在不同场景中以最佳方式应用它们的提示。

## Structured outputs overview

## 结构化输出概述

Structured outputs are a way of enforcing the output of an LLM to follow a pre-defined schema — usually a JSON schema. This works by transforming the schema into a context free grammar (CFG), which during the token sampling step, is used together with the previously generated tokens, to inform which subsequent tokens are valid. It’s helpful to think of it as creating a regex for token generation.

结构化输出是一种强制 LLM 输出遵循预定义模式（通常是 JSON 模式）的方法。这是通过将模式转换为上下文无关语法 (CFG) 来实现的，该语法在令牌采样步骤中与先前生成的令牌一起使用，以告知哪些后续令牌是有效的。将其视为创建用于令牌生成的正则表达式会很有帮助。

OpenAI API implementation actually tracks a limited subset of JSON schema features. With more general structured output solutions, such as Outlines, it is possible to use a somewhat larger subset of the JSON schema, and even define completely custom non-JSON schemas — as long as one has access to an open weight model. For the purpose of this article, we will assume the OpenAI API implementation.

OpenAI API 实现实际上跟踪 JSON 模式功能的有限子集。借助更通用的结构化输出解决方案（例如 Outlines），可以使用 JSON 模式的更大子集，甚至可以定义完全自定义的非 JSON 模式 — 只要可以访问开放权重模型。出于本文的目的，我们将假设 OpenAI API 实现。

### JSON Schema and Pydantic

### JSON 模式和 Pydantic

According to JSON Schema Core Specification, “JSON Schema asserts what a JSON document must look like, ways to extract information from it, and how to interact with it”. JSON schema defines six primitive types — null, boolean, object, array, number and string. It also defines certain keywords, annotations, and specific behaviours. For example, we can specify in our schema that we expect an array and add an annotation that minItems shall be 5 .

根据 JSON Schema 核心规范，“JSON Schema 断言 JSON 文档必须是什么样子、从中提取信息的方法以及如何与其交互”。 JSON 模式定义了六种基本类型——null、boolean、object、array、number 和 string。它还定义了某些关键字、注释和特定行为。例如，我们可以在模式中指定我们需要一个数组，并添加一个注释，指出 minItems 应为 5 。

Pydantic is a Python library that implements the JSON schema specification. We use Pydantic to build robust and maintainable software in Python. Since Python is a dynamically typed language, data scientists do not necessarily think in terms of variable types — these are often implied in their code. For example, a fruit would be specified as:

Pydantic 是一个实现 JSON 模式规范的 Python 库。我们使用 Pydantic 在 Python 中构建健壮且可维护的软件。由于 Python 是一种动态类型语言，数据科学家不一定会考虑变量类型——这些类型通常隐含在他们的代码中。例如，水果将被指定为：

```python

````蟒蛇

fruit = "apple"

水果=“苹果”

```

````

…while a function declaration that returns “fruit” from some piece of data would often be specified as:

…而从某些数据返回“fruit”的函数声明通常会指定为：

```python

````蟒蛇

def get_fruit(data):

def get_fruit(数据):

return data

返回数据

```

````

Pydantic on the other hand allows us to generate a JSON-schema compliant class, with properly annotated variables and type hints, making our code more readable/maintainable and in general more robust, i.e.

另一方面，Pydantic 允许我们生成一个符合 JSON 模式的类，具有正确注释的变量和类型提示，使我们的代码更具可读性/可维护性，并且通常更健壮，即

```python

````蟒蛇

class Fruit(BaseModel):

水果类（基础模型）：

fruit: str

水果：str

```

````

OpenAI actually strongly recommends the use of Pydantic for specifying schemas, as opposed to specifying the “raw” JSON schema directly. There are several reasons for this. Firstly, Pydantic is guaranteed to adhere to the JSON schema specification, so it saves you extra pre-validation steps. Secondly, for larger schemas, it is less verbose, allowing you to write cleaner code, faster. Finally, the openai Python package actually does some housekeeping, like setting additionalProperties to False for you, whereas when defining your schema “by-hand” using JSON, you would need to set these manually, for every object in your schema (failing to do so results in a rather annoying API error).

OpenAI 实际上强烈建议使用 Pydantic 来指定模式，而不是直接指定“原始”JSON 模式。这有几个原因。首先，Pydantic 保证遵守 JSON 模式规范，因此它可以为您节省额外的预验证步骤。其次，对于较大的模式，它不那么冗长，允许您更快地编写更清晰的代码。最后，openai Python 包实际上做了一些内务处理，例如为您将 extraProperties 设置为 False，而当使用 JSON“手动”定义模式时，您需要为模式中的每个对象手动设置这些（无法执行因此会导致一个相当烦人的 API 错误）。

## Limitations

## 限制

As we alluded to previously, the ChatCompletions API provides a limited subset of the full JSON schema specification. There are numerous keywords that are not yet supported, such as minimum and maximum for numbers, and minItems and maxItems for arrays — annotations that would be otherwise very useful in reducing hallucinations, or constraining the output size.

正如我们之前提到的，ChatCompletions API 提供了完整 JSON 模式规范的有限子集。有许多关键字尚不支持，例如数字的最小值和最大值，以及数组的 minItems 和 maxItems - 这些注释对于减少幻觉或限制输出大小非常有用。

Certain formatting features are also unavailable. For example, the following Pydantic schema would result in API error when passed to response_format in ChatCompletions:

某些格式化功能也不可用。例如，以下 Pydantic 模式在传递给 ChatCompletions 中的 response_format 时会导致 API 错误：

```python

````蟒蛇

class Post(BaseModel):

类帖子（基础模型）：

date_published: datetime

date_published: 日期时间

```

````

It would fail because openai package has no format handling for datetime , so instead you would need to set date_published as a str and perform format validation (e.g. ISO 8601 compliance) post-hoc.

它会失败，因为 openai 包没有对 datetime 的格式处理，因此您需要将 date_published 设置为 str 并事后执行格式验证（例如 ISO 8601 合规性）。

Other key limitations include the following:

其他主要限制包括：

- Schemas must be able to be represented using Pydantic models.

- 模式必须能够使用 Pydantic 模型来表示。

- Schemas must be able to be serialized to JSON.

- 模式必须能够序列化为 JSON。

- Schemas must be able to be validated using Pydantic models.

- 模式必须能够使用 Pydantic 模型进行验证。

- Schemas must be able to be deserialized from JSON.

- 模式必须能够从 JSON 反序列化。

## Tips and tricks

## 提示和技巧

With all this in mind, we can now go through a couple of use cases with tips and tricks on how to enhance the performance when using structured outputs.

考虑到这一切，我们现在可以通过几个用例来了解如何在使用结构化输出时提高性能的提示和技巧。

### Creating flexibility using optional parameters

### 使用可选参数创建灵活性

Let’s say we are building a web scraping application where our goal is to collect specific components from the web pages. For each web page, we supply the raw HTML in the user prompt, give specific scraping instructions in the system prompt, and define the following Pydantic model:

假设我们正在构建一个网络抓取应用程序，我们的目标是从网页收集特定组件。对于每个网页，我们在用户提示中提供原始 HTML，在系统提示中给出特定的抓取指令，并定义以下 Pydantic 模型：

```python

````蟒蛇