Structured Outputs

Структурированные выводы преобразуют ответы модели из свободного текста в строго форматированный JSON. RouteAPI поддерживает два режима структурированного вывода: JSON mode (требует валидный JSON) и JSON Schema (гарантирует соответствие конкретной схеме).

1. Обзор структурированных выводов

Что такое структурированные выводы

Структурированные выводы — это механизм контроля формата ответа модели. В отличие от обычных диалогов, где модели свободно генерируют текст, структурированные выводы заставляют модель генерировать данные JSON в соответствии с определенным вами форматом. Это критически важно для сценариев, требующих программной обработки выходных данных модели (извлечение данных, генерация форм, парсинг ответов API).

JSON mode vs JSON Schema

RouteAPI предоставляет два режима структурированного вывода:

Сравнение	JSON mode	JSON Schema
Гарантия	Вывод является валидным JSON	Вывод соответствует указанной схеме
Параметр	`response_format: { type: "json_object" }`	`response_format: { type: "json_schema", json_schema: {...} }`
Определение схемы	Не требуется, но формат должен быть описан в промпте	Требуется полная JSON Schema
Строгость	Только гарантирует парсируемость, не структуру	Гарантирует точное соответствие полей, типов и обязательных элементов
Сценарии использования	Простые форматы, модель понимает структуру из промпта	Сложные вложенные структуры, необходима строгая валидация типов

Простое объяснение: JSON mode только гарантирует «может быть успешно распарсен JSON.parse», но не заботится о полях; JSON Schema гарантирует не только валидность, но и что структура, имена полей, типы и обязательные элементы соответствуют вашему определению.

Сценарии использования

Сценарий	Описание	Рекомендуемый режим
Извлечение данных	Извлечение структурированной информации из неструктурированного текста (имя, адрес, дата)	JSON Schema
Генерация форм	Модель генерирует начальные значения формы или объекты конфигурации	JSON Schema
Парсинг ответов API	Вывод модели должен интегрироваться с API нижележащих систем	JSON Schema
Простые пары ключ-значение	Нужно лишь несколько полей, структура проста и ясна	JSON mode
Задачи классификации	Вывод фиксированных enum значений (например, sentiment: positive/negative/neutral)	JSON Schema + enum

2. JSON Mode

JSON mode — это самый простой метод структурированного вывода: вы устанавливаете response_format.type в "json_object" в запросе, и модель будет выводить валидный JSON вместо простого текста.

Формат запроса

{
  "model": "gpt-5.5",
  "messages": [
    {
      "role": "system",
      "content": "You are a data extraction assistant. Extract name, age, and city fields from user input and return in JSON format."
    },
    {
      "role": "user",
      "content": "My name is Li Ming, I'm 28 years old, and I live in Shanghai."
    }
  ],
  "response_format": { "type": "json_object" }
}

Ключевые моменты

Необходимо описать формат JSON в промпте: Модель не знает, какие поля вам нужны; вы должны явно указать через системное сообщение или сообщение пользователя, какие поля выводить и их типы. В приведенном выше примере "Extract name, age, and city fields from user input and return in JSON format" — это описание формата.
Не гарантирует соответствие схеме: Модель может вывести {"name": "Li Ming", "age": 28, "city": "Shanghai"}, или {"姓名": "Li Ming", "年龄": 28}, или даже {"person": {"name": "Li Ming"}}. Пока это валидный JSON, это приемлемо.
Как использовать: Подходит для сценариев с простыми форматами, небольшим количеством полей и где модель может понять структуру из естественного языка. Если необходима строгая валидация имен полей или типов, используйте JSON Schema.

Полный пример

Запрос (curl):

curl https://api.routeapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      {
        "role": "system",
        "content": "You are a data extraction assistant. Extract name, age, and city fields from user input and return in JSON format."
      },
      {
        "role": "user",
        "content": "My name is Li Ming, I am 28 years old, and I live in Shanghai."
      }
    ],
    "response_format": { "type": "json_object" }
  }'

Ответ:

{
  "id": "chatcmpl_xxx",
  "object": "chat.completion",
  "created": 1730000000,
  "model": "gpt-5.5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "{\"name\": \"Li Ming\", \"age\": 28, \"city\": \"Shanghai\"}"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 58,
    "completion_tokens": 18,
    "total_tokens": 76
  }
}

Обратите внимание, что message.content — это JSON строка, вам нужно самостоятельно выполнить JSON.parse / json.loads.

3. JSON Schema (Structured Outputs)

Режим JSON Schema позволяет точно определить структуру вывода, и модель гарантирует, что сгенерированный JSON полностью соответствует вашему определению схемы.

Формат запроса

{
  "model": "gpt-5.5",
  "messages": [
    {
      "role": "user",
      "content": "My name is Li Ming, I'm 28 years old, and I live in Shanghai."
    }
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "person_extraction",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "name": { "type": "string", "description": "Name" },
          "age": { "type": "integer", "description": "Age" },
          "city": { "type": "string", "description": "City" }
        },
        "required": ["name", "age", "city"],
        "additionalProperties": false
      }
    }
  }
}

Структура response_format

Поле	Тип	Обязательно	Описание
`type`	string	Да	Фиксировано как `"json_schema"`
`json_schema.name`	string	Да	Имя схемы для идентификации, буквы, цифры, подчеркивания, дефисы
`json_schema.strict`	boolean	Нет	Включить ли строгий режим, по умолчанию `false`
`json_schema.schema`	object	Да	Стандартное определение JSON Schema

Строгий режим vs Нестрогий режим

Режим	`strict`	Поведение
Строгий режим	`true`	Модель должна генерировать точно в соответствии со схемой, имена полей, типы, обязательные элементы, `additionalProperties` строго соблюдаются
Нестрогий режим	`false`	Модель пытается соответствовать схеме, но не гарантирует полную согласованность, может пропустить поля или добавить дополнительные

Рекомендация: Используйте strict: true в продакшене; это основная ценность режима JSON Schema. Поведение нестрогого режима аналогично JSON mode + описание в промпте, смысл ограничен.

Спецификация определения схемы

Поле schema следует стандартной спецификации JSON Schema (Draft 2020-12), общие поля:

Поле	Описание
`type`	Тип данных: `"object"`, `"array"`, `"string"`, `"number"`, `"integer"`, `"boolean"`, `"null"`
`properties`	Определения полей для объектов (используется когда type = `"object"`)
`required`	Массив имен обязательных полей
`additionalProperties`	Разрешать ли неопределенные дополнительные поля (рекомендуется `false` в строгом режиме)
`items`	Схема элементов массива (используется когда type = `"array"`)
`enum`	Список enum значений, ограничивает диапазон значений
`description`	Описание поля, помогает модели понять семантику

4. Руководство по определению схемы

Базовые типы

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "integer" },
    "score": { "type": "number" },
    "is_active": { "type": "boolean" },
    "notes": { "type": ["string", "null"] }
  }
}

Описания типов:

"string": Строка
"integer": Целое число
"number": Число (включая целые и десятичные)
"boolean": Булево значение
"null": Null значение
["string", "null"]: Разрешает строку или null (необязательное поле)

Объекты и массивы

{
  "type": "object",
  "properties": {
    "user": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "email": { "type": "string" }
      },
      "required": ["name"]
    },
    "tags": {
      "type": "array",
      "items": { "type": "string" }
    },
    "scores": {
      "type": "array",
      "items": { "type": "number" }
    }
  }
}

Обязательные поля

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "integer" },
    "city": { "type": "string" }
  },
  "required": ["name", "age"]
}

Массив required перечисляет поля, которые должны существовать. В приведенном выше примере name и age обязательны, city необязателен.

Enum значения

{
  "type": "object",
  "properties": {
    "sentiment": {
      "type": "string",
      "enum": ["positive", "negative", "neutral"],
      "description": "Sentiment classification result"
    },
    "priority": {
      "type": "integer",
      "enum": [1, 2, 3],
      "description": "Priority: 1-low, 2-medium, 3-high"
    }
  },
  "required": ["sentiment"]
}

enum ограничивает поле только значениями из списка; модель не будет генерировать другие значения.

Вложенные структуры

{
  "type": "object",
  "properties": {
    "user": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "address": {
          "type": "object",
          "properties": {
            "city": { "type": "string" },
            "street": { "type": "string" }
          },
          "required": ["city"]
        }
      },
      "required": ["name", "address"]
    }
  },
  "required": ["user"]
}

Объекты могут быть вложены бесконечно, но чрезмерная вложенность может повлиять на качество генерации модели и производительность.

Поля описания

{
  "type": "object",
  "properties": {
    "date": {
      "type": "string",
      "description": "Date, format YYYY-MM-DD"
    },
    "amount": {
      "type": "number",
      "description": "Amount in CNY"
    }
  }
}

description не обязательно, но настоятельно рекомендуется. Это помогает модели понять семантику поля, диапазон значений и соглашения о формате, значительно улучшая точность генерации.

5. Примеры схем

Извлечение информации о пользователе

Извлечение информации о пользователе из неструктурированного текста:

{
  "name": "user_info_extraction",
  "strict": true,
  "schema": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string",
        "description": "User name"
      },
      "age": {
        "type": "integer",
        "description": "Age"
      },
      "email": {
        "type": ["string", "null"],
        "description": "Email address, null if not in text"
      },
      "phone": {
        "type": ["string", "null"],
        "description": "Phone number, null if not in text"
      },
      "city": {
        "type": "string",
        "description": "City"
      }
    },
    "required": ["name", "age", "city"],
    "additionalProperties": false
  }
}

Генерация списка продуктов

Модель генерирует массив продуктов:

{
  "name": "product_list",
  "strict": true,
  "schema": {
    "type": "object",
    "properties": {
      "products": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "description": "Product name"
            },
            "price": {
              "type": "number",
              "description": "Price in CNY"
            },
            "category": {
              "type": "string",
              "enum": ["electronics", "clothing", "food", "other"],
              "description": "Product category"
            },
            "in_stock": {
              "type": "boolean",
              "description": "Whether in stock"
            }
          },
          "required": ["name", "price", "category", "in_stock"],
          "additionalProperties": false
        }
      },
      "total_count": {
        "type": "integer",
        "description": "Total product count"
      }
    },
    "required": ["products", "total_count"],
    "additionalProperties": false
  }
}

Сложный вложенный объект

Извлечение информации о заказе с многоуровневой вложенностью:

{
  "name": "order_extraction",
  "strict": true,
  "schema": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "description": "Order ID"
      },
      "customer": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "phone": { "type": "string" },
          "address": {
            "type": "object",
            "properties": {
              "province": { "type": "string" },
              "city": { "type": "string" },
              "street": { "type": "string" }
            },
            "required": ["province", "city", "street"],
            "additionalProperties": false
          }
        },
        "required": ["name", "phone", "address"],
        "additionalProperties": false
      },
      "items": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "product_name": { "type": "string" },
            "quantity": { "type": "integer" },
            "unit_price": { "type": "number" }
          },
          "required": ["product_name", "quantity", "unit_price"],
          "additionalProperties": false
        }
      },
      "total_amount": {
        "type": "number",
        "description": "Order total amount"
      }
    },
    "required": ["order_id", "customer", "items", "total_amount"],
    "additionalProperties": false
  }
}

6. Поддержка моделей

Модели, поддерживающие JSON mode

Большинство основных моделей, агрегированных RouteAPI, поддерживают JSON mode (response_format: { type: "json_object" }), включая:

Серия OpenAI GPT (gpt-4o, gpt-4-turbo, gpt-3.5-turbo, и т.д.)
Серия Claude (claude-3.5-sonnet, claude-3-opus, claude-3-haiku, и т.д.)
Серия Gemini (gemini-2.0-flash, gemini-1.5-pro, и т.д.)
Другие модели, поддерживающие формат OpenAI

Модели, поддерживающие JSON Schema

JSON Schema (response_format: { type: "json_schema" }) требует более высоких возможностей модели; в настоящее время поддерживаемые модели:

OpenAI: серия gpt-4o, серия gpt-4-turbo (версия 2024-08-06 и позже)
Claude: серия claude-3.5-sonnet, серия claude-3-opus
Gemini: gemini-2.0-flash-exp, серия gemini-1.5-pro
Другие: некоторые модели нового поколения

Как подтвердить: Запросите возможности модели через Models API перед вызовом, проверьте поле supports_response_format.

Сравнение возможностей моделей

Возможность	JSON mode	JSON Schema	Примечания
Диапазон поддержки моделей	Широкий (почти все основные модели)	Ограниченный (модели нового поколения)	JSON mode имеет более высокую поддержку
Сложность схемы	N/A	Рекомендуется не более 3 уровней вложенности	Чрезмерная глубина влияет на качество генерации
Максимальное количество полей	N/A	Рекомендуется не более 50 полей верхнего уровня	Слишком много полей влияет на производительность
Строгая гарантия	Только гарантирует валидный JSON	Гарантирует соответствие схеме	100% соответствие в строгом режиме
Производительность	Быстрая	Относительно медленнее	Валидация схемы имеет дополнительные издержки
Потребление токенов	Низкое	Немного выше	Определение схемы занимает токены промпта

Ограничения и примечания

Ограничение размера схемы: Рекомендуется, чтобы одно определение схемы не превышало 10KB; слишком большие схемы могут быть обрезаны или отклонены.
Ограничение глубины вложенности: Рекомендуется, чтобы уровни вложенности не превышали 3-4 слоя; чрезмерная вложенность снижает качество генерации модели и скорость.
Влияние на производительность: Время ответа режима JSON Schema обычно на 10%-30% медленнее, чем обычные запросы, потому что модель должна валидировать структуру в реальном времени во время генерации.
Неподдерживаемые возможности схемы: Некоторые расширенные возможности JSON Schema (такие как $ref, allOf, anyOf, oneOf, regex) могут не поддерживаться всеми моделями.
Потоковый вывод: Режим JSON Schema поддерживает потоковый вывод (stream: true), но content возвращается фрагментами; полный JSON необходимо конкатенировать перед парсингом.

7. Полные примеры приложений

Пример 1: Извлечение структурированной информации из неструктурированного текста

Сценарий: Извлечение информации о клиенте и классификации проблемы из диалога службы поддержки.

curl:

curl https://api.routeapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {
        "role": "user",
        "content": "Customer Li Ming (phone 13800138000) reported that order ORD-2024-001 in Chaoyang District, Beijing has not been shipped and is quite urgent."
      }
    ],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "customer_inquiry",
        "strict": true,
        "schema": {
          "type": "object",
          "properties": {
            "customer_name": { "type": "string", "description": "Customer name" },
            "phone": { "type": ["string", "null"], "description": "Customer phone" },
            "location": { "type": ["string", "null"], "description": "Customer location" },
            "order_id": { "type": ["string", "null"], "description": "Order ID" },
            "issue_category": {
              "type": "string",
              "enum": ["delivery", "quality", "refund", "other"],
              "description": "Issue category: delivery-logistics, quality-quality, refund-refund, other-other"
            },
            "urgency": {
              "type": "string",
              "enum": ["low", "medium", "high"],
              "description": "Urgency level"
            }
          },
          "required": ["customer_name", "issue_category", "urgency"],
          "additionalProperties": false
        }
      }
    }
  }'

Ответ:

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "{\"customer_name\":\"Li Ming\",\"phone\":\"13800138000\",\"location\":\"Chaoyang District, Beijing\",\"order_id\":\"ORD-2024-001\",\"issue_category\":\"delivery\",\"urgency\":\"high\"}"
      },
      "finish_reason": "stop"
    }
  ]
}

Python:

import os
import json
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ROUTEAPI_KEY"],
    base_url="https://api.routeapi.ai/v1",
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {
            "role": "user",
            "content": "Customer Li Ming (phone 13800138000) reported that order ORD-2024-001 in Chaoyang District, Beijing has not been shipped and is quite urgent.",
        }
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "customer_inquiry",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "customer_name": {"type": "string", "description": "Customer name"},
                    "phone": {"type": ["string", "null"], "description": "Customer phone"},
                    "location": {"type": ["string", "null"], "description": "Customer location"},
                    "order_id": {"type": ["string", "null"], "description": "Order ID"},
                    "issue_category": {
                        "type": "string",
                        "enum": ["delivery", "quality", "refund", "other"],
                        "description": "Issue category",
                    },
                    "urgency": {
                        "type": "string",
                        "enum": ["low", "medium", "high"],
                        "description": "Urgency level",
                    },
                },
                "required": ["customer_name", "issue_category", "urgency"],
                "additionalProperties": False,
            },
        },
    },
)

data = json.loads(response.choices[0].message.content)
print(f"Customer: {data['customer_name']}")
print(f"Issue type: {data['issue_category']}")
print(f"Urgency: {data['urgency']}")

Node.js:

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.ROUTEAPI_KEY,
  baseURL: 'https://api.routeapi.ai/v1',
});

const response = await client.chat.completions.create({
  model: 'gpt-4o',
  messages: [
    {
      role: 'user',
      content: 'Customer Li Ming (phone 13800138000) reported that order ORD-2024-001 in Chaoyang District, Beijing has not been shipped and is quite urgent.',
    },
  ],
  response_format: {
    type: 'json_schema',
    json_schema: {
      name: 'customer_inquiry',
      strict: true,
      schema: {
        type: 'object',
        properties: {
          customer_name: { type: 'string', description: 'Customer name' },
          phone: { type: ['string', 'null'], description: 'Customer phone' },
          location: { type: ['string', 'null'], description: 'Customer location' },
          order_id: { type: ['string', 'null'], description: 'Order ID' },
          issue_category: {
            type: 'string',
            enum: ['delivery', 'quality', 'refund', 'other'],
            description: 'Issue category',
          },
          urgency: {
            type: 'string',
            enum: ['low', 'medium', 'high'],
            description: 'Urgency level',
          },
        },
        required: ['customer_name', 'issue_category', 'urgency'],
        additionalProperties: false,
      },
    },
  },
});

const data = JSON.parse(response.choices[0].message.content);
console.log(`Customer: ${data.customer_name}`);
console.log(`Issue type: ${data.issue_category}`);
console.log(`Urgency: ${data.urgency}`);

Пример 2: Генерация данных формы

Сценарий: Модель генерирует начальные значения формы на основе описания на естественном языке.

Python:

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {
            "role": "system",
            "content": "You are a form filling assistant. Generate form data based on user description.",
        },
        {
            "role": "user",
            "content": "Create a new employee onboarding form: Zhang Wei, male, born in 1995, bachelor's degree, software engineer position, monthly salary 15000.",
        },
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "employee_form",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "gender": {"type": "string", "enum": ["male", "female"]},
                    "birth_year": {"type": "integer"},
                    "education": {
                        "type": "string",
                        "enum": ["high_school", "bachelor", "master", "phd"],
                    },
                    "position": {"type": "string"},
                    "salary": {"type": "number", "description": "Monthly salary in CNY"},
                },
                "required": ["name", "gender", "birth_year", "education", "position", "salary"],
                "additionalProperties": False,
            },
        },
    },
)

form_data = json.loads(response.choices[0].message.content)
print(json.dumps(form_data, ensure_ascii=False, indent=2))

Вывод:

{
  "name": "Zhang Wei",
  "gender": "male",
  "birth_year": 1995,
  "education": "bachelor",
  "position": "Software Engineer",
  "salary": 15000
}

Пример 3: Парсинг ответа API

Сценарий: Модель извлекает ключевую информацию из неструктурированного ответа стороннего API.

Node.js:

const apiResponse = `
Order status: Shipped
Logistics company: SF Express
Tracking number: SF1234567890
Estimated delivery: January 20, 2024
Current location: Beijing Distribution Center
`;

const response = await client.chat.completions.create({
  model: 'gpt-4o',
  messages: [
    {
      role: 'user',
      content: `Extract structured data from the following logistics information:\n${apiResponse}`,
    },
  ],
  response_format: {
    type: 'json_schema',
    json_schema: {
      name: 'logistics_info',
      strict: true,
      schema: {
        type: 'object',
        properties: {
          status: {
            type: 'string',
            enum: ['pending', 'shipped', 'in_transit', 'delivered'],
          },
          carrier: { type: 'string', description: 'Logistics company' },
          tracking_number: { type: 'string', description: 'Tracking number' },
          estimated_delivery: {
            type: ['string', 'null'],
            description: 'Estimated delivery date, format YYYY-MM-DD',
          },
          current_location: { type: ['string', 'null'], description: 'Current location' },
        },
        required: ['status', 'carrier', 'tracking_number'],
        additionalProperties: false,
      },
    },
  },
});

const data = JSON.parse(response.choices[0].message.content);
console.log(data);
// Output: { status: 'shipped', carrier: 'SF Express', tracking_number: 'SF1234567890', estimated_delivery: '2024-01-20', current_location: 'Beijing Distribution Center' }

8. Обработка ошибок

Ошибка валидации схемы

Если ваше определение схемы имеет проблемы (синтаксические ошибки, неподдерживаемые возможности), запрос напрямую вернет ошибку 400:

{
  "error": {
    "message": "Invalid JSON schema: ...",
    "type": "invalid_request_error",
    "param": "response_format.json_schema.schema",
    "code": "invalid_json_schema"
  }
}

Решение:

Проверьте, соответствует ли синтаксис схемы спецификации JSON Schema
Удалите неподдерживаемые расширенные возможности (такие как $ref, allOf)
Упростите чрезмерно вложенные структуры

Модель не может сгенерировать вывод, соответствующий схеме

В редких случаях модель может быть не в состоянии сгенерировать контент, соответствующий схеме (например, ввод пользователя полностью конфликтует с требованиями схемы); в этом случае будет возвращена ошибка или произойдет откат к выводу простого текста. Пример ошибки:

{
  "error": {
    "message": "Failed to generate valid output matching the provided schema after maximum retries.",
    "type": "model_error",
    "code": "schema_generation_failed"
  }
}

Решение:

Проверьте, согласован ли промпт с требованиями схемы
Упростите схему, удалите слишком строгие ограничения
Явно укажите требования к выводу в промпте
Для необязательных полей используйте тип ["string", "null"] вместо просто "string"

Стратегия повторных попыток

Для эпизодических сбоев генерации вы можете реализовать автоматические повторные попытки:

import time

def call_with_retry(client, **kwargs):
    max_retries = 3
    for attempt in range(max_retries):
        try:
            response = client.chat.completions.create(**kwargs)
            content = response.choices[0].message.content
            data = json.loads(content)  # Verify it can be parsed
            return data
        except (json.JSONDecodeError, Exception) as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)  # Exponential backoff

9. Лучшие практики

Принципы проектирования схемы

Начинайте просто: Сначала проверьте осуществимость с JSON mode, затем обновите до JSON Schema после подтверждения необходимости строгой валидации.
Определите обязательные и необязательные: Поместите обязательные поля в массив required, используйте ["type", "null"] для необязательных полей или просто не помещайте их в required.
Используйте enum для ограничения перечислений: Для полей с ограниченными значениями (статус, классификация, приоритет) явно перечислите их с enum; это может значительно снизить частоту ошибок.
Добавьте description: Добавьте description к каждому полю, объясняя значение, формат, диапазон значений; модель генерирует более точно на основе этого.
Установите additionalProperties: false: В строгом режиме добавление этого предотвращает вывод модели неопределенных дополнительных полей.

Избегайте слишком сложных схем

Проблема	Описание	Рекомендация
Слишком глубокая вложенность	Более 4 уровней вложенности снижает качество генерации	Разделите на несколько плоских объектов или извлекайте поэтапно с многоходовыми диалогами
Слишком много полей	Один объект превышает 50 полей	Группируйте по бизнес-логике, разделите на несколько подобъектов
Чрезмерные ограничения	Все поля обязательны, нет гибкости	Помечайте как обязательные только ключевые поля, разрешайте null для других полей
Нет описания	Модель не понимает семантику поля	Добавьте description к каждому полю, объясните ясно

Оптимизация производительности

Уменьшите размер схемы: Определение схемы занимает токены промпта; чрезмерно большие схемы увеличивают задержку и стоимость.
Кэшируйте определения схем: Когда одна и та же схема используется повторно, определите ее как константу в коде, чтобы избежать реконструкции для каждого запроса.
Выберите подходящую модель: Не все задачи нуждаются в самой сильной модели; простое структурированное извлечение может использовать gpt-3.5-turbo + JSON mode.
Пакетная обработка: Если есть несколько похожих задач, спроектируйте схему массива, чтобы модель обрабатывала несколько элементов данных одновременно.

Соображения о стоимости

Фактор	Влияние	Рекомендация по оптимизации
Размер схемы	Определение схемы занимает токены промпта	Упростите описание, удалите избыточные поля
Выбор модели	JSON Schema обычно требует более сильных моделей	Используйте JSON mode + более слабую модель для простых задач
Длина ответа	Вывод JSON обычно длиннее текста (имена ключей, кавычки, скобки)	Сократите имена полей, используйте enum вместо длинных строк
Количество повторных попыток	Повторные попытки при сбое генерации удваивают выставление счетов	Оптимизируйте схему и промпт для снижения частоты сбоев

Практический совет: Для сценариев с высокочастотными вызовами сначала протестируйте с JSON mode; после подтверждения, что модель может стабильно выводить правильный формат, обновите до JSON Schema. JSON mode обычно имеет на 10%-20% более низкое потребление токенов и стоимость, чем JSON Schema.

Примечания по совместимости

Поддержка JSON mode и JSON Schema зависит от выбранной модели; пожалуйста, запросите поле supports_response_format через Models API для подтверждения.
response_format взаимоисключающий с tools (вызов инструментов): один и тот же запрос не может использовать одновременно структурированные выводы и вызов инструментов.
В потоковом выводе (stream: true) content возвращается фрагментами и должен быть полностью конкатенирован перед JSON.parse.
Явно переданные 0 или false необязательные параметры рассматриваются как явно установленные пользователем и не будут рассматриваться как пропуски по умолчанию.
Регистрируйте request ID, model ID, код статуса и использование токенов каждого запроса для устранения неполадок. Подробности структуры ошибок см. в Errors and Debugging.