> ## Documentation Index
> Fetch the complete documentation index at: https://speshu.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Структурный вывод

> Получение структурированных данных (JSON) от AI моделей

Структурный вывод позволяет получать ответы от AI моделей в строгом JSON формате, соответствующем заданной схеме.

<Note>
  Поддержка структурного вывода зависит от модели. Проверяйте возможности в [каталоге моделей](/docs/gaidy/models).
</Note>

## Зачем это нужно?

* **Парсинг данных**: Извлечение структурированной информации из текста
* **API интеграции**: Получение данных в формате, готовом для обработки
* **Валидация**: Гарантия соответствия ответа заданной структуре
* **Автоматизация**: Надёжная интеграция с бизнес-процессами

## Способы получения структурного вывода

### 1. response\_format (рекомендуется)

Самый надёжный способ — использовать параметр `response_format` с JSON Schema:

```typescript theme={null}
import OpenAI from 'openai';

const openai = new OpenAI({
  baseURL: 'https://speshu.ai/api/v1',
  apiKey: '<SPESHU_AI_API_KEY>'
});

const completion = await openai.chat.completions.create({
  model: 'openai/gpt-5.5',
  messages: [
    {
      role: 'user',
      content: 'Извлеки информацию о товаре: iPhone 15 Pro, 256GB, цена 89990 рублей, в наличии'
    }
  ],
  response_format: {
    type: 'json_schema',
    json_schema: {
      name: 'product',
      strict: true,
      schema: {
        type: 'object',
        properties: {
          name: { type: 'string', description: 'Название товара' },
          storage: { type: 'string', description: 'Объём памяти' },
          price: { type: 'number', description: 'Цена в рублях' },
          in_stock: { type: 'boolean', description: 'Наличие на складе' }
        },
        required: ['name', 'storage', 'price', 'in_stock'],
        additionalProperties: false
      }
    }
  }
});

const product = JSON.parse(completion.choices[0].message.content);
```

### 2. json\_object (простой JSON)

Для простых случаев, когда схема не критична:

```typescript theme={null}
const completion = await openai.chat.completions.create({
  model: 'openai/gpt-5.5',
  messages: [
    {
      role: 'system',
      content: 'Всегда отвечай в формате JSON с полями: name, price, currency'
    },
    { role: 'user', content: 'Цена на MacBook Air?' }
  ],
  response_format: { type: 'json_object' }
});
```

## Параметр strict

| Значение | Описание                                             |
| -------- | ---------------------------------------------------- |
| `true`   | Ответ **точно** соответствует схеме. Рекомендуется.  |
| `false`  | Модель может отклоняться от схемы. Не рекомендуется. |

## Советы и лучшие практики

**Всегда используйте strict: true**
Это гарантирует соответствие ответа схеме и предотвращает ошибки парсинга.

**Добавляйте описания полей**
Описания помогают модели лучше понять, что ожидается в каждом поле.

**Используйте enum для ограниченных значений**
Если поле должно содержать одно из нескольких значений, используйте enum.

**Ограничивайте additionalProperties**
Установите `additionalProperties: false` чтобы модель не добавляла лишние поля.

**Оборачивайте массивы в объект**
Вместо `type: "array"` на верхнем уровне, используйте объект с полем-массивом.