透過結構化輸出進行更深入的研究

幫助增強您對結構化輸出和法學碩士的理解和最佳使用

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

````蟒蛇