Структурированные ответы

Структурированные ответы

Обеспечьте валидацию JSON Schema для ответов моделей ИИ. Получайте согласованные, типобезопасные ответы и избегайте ошибок парсинга с помощью функции структурированных ответов AITUNNEL.

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

Обзор

Структурированные ответы позволяют:

• Обеспечить валидацию JSON Schema для ответов моделей
• Получать согласованные, типобезопасные ответы
• Избегать ошибок парсинга и выдуманных полей
• Упростить обработку ответов в вашем приложении

Использование структурированных ответов

Для использования структурированных ответов включите параметр response_format в ваш запрос, установив type в значение json_schema и добавив объект json_schema с вашей схемой:

{
  "messages": [
    { "role": "user", "content": "Какая погода в Лондоне?" }
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "weather",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "Название города или местоположения"
          },
          "temperature": {
            "type": "number",
            "description": "Температура в градусах Цельсия"
          },
          "conditions": {
            "type": "string",
            "description": "Описание погодных условий"
          }
        },
        "required": ["location", "temperature", "conditions"],
        "additionalProperties": false
      }
    }
  }
}

Модель ответит JSON-объектом, который строго соответствует вашей схеме:

{
  "location": "Лондон",
  "temperature": 18,
  "conditions": "Переменная облачность с легкой моросью"
}

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

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

• Модели OpenAI (GPT-4 и более поздние версии) Документация
• Некоторые модели от других провайдеров.

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

1. Добавляйте описания: Добавляйте четкие описания к свойствам вашей схемы, чтобы направлять модель

2. Используйте строгий режим: Всегда устанавливайте strict: true, чтобы гарантировать точное соответствие вашей схеме

Пример реализации

Вот полный пример с использованием Fetch API:

JavaScript

const response = await fetch("https://api.aitunnel.ru/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk-aitunnel-xxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "gpt-4o",
    messages: [{ role: "user", content: "Какая погода в Лондоне?" }],
    response_format: {
      type: "json_schema",
      json_schema: {
        name: "weather",
        strict: true,
        schema: {
          type: "object",
          properties: {
            location: {
              type: "string",
              description: "Название города или местоположения",
            },
            temperature: {
              type: "number",
              description: "Температура в градусах Цельсия",
            },
            conditions: {
              type: "string",
              description: "Описание погодных условий",
            },
          },
          required: ["location", "temperature", "conditions"],
          additionalProperties: false,
        },
      },
    },
  }),
});

const data = await response.json();
const weatherInfo = data.choices[0].message.content;

Python

import requests
import json

response = requests.post(
  "https://api.aitunnel.ru/v1/chat/completions",
  headers={
    "Authorization": "Bearer sk-aitunnel-xxx",
    "Content-Type": "application/json",
  },
  json={
    "model": "gpt-4o",
    "messages": [
      {"role": "user", "content": "Какая погода в Лондоне?"},
    ],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "weather",
        "strict": True,
        "schema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "Название города или местоположения",
            },
            "temperature": {
              "type": "number",
              "description": "Температура в градусах Цельсия",
            },
            "conditions": {
              "type": "string",
              "description": "Описание погодных условий",
            },
          },
          "required": ["location", "temperature", "conditions"],
          "additionalProperties": False,
        },
      },
    },
  },
)

data = response.json()
weather_info = data["choices"][0]["message"]["content"]

Стриминг с структурированными ответами

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

Чтобы включить стриминг с структурированными ответами, просто добавьте stream: true в ваш запрос:

{
  "stream": true,
  "response_format": {
    "type": "json_schema",
    // ... остальная часть вашей схемы
  }
}

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

При использовании структурированных ответов вы можете столкнуться со следующими сценариями:

1. Модель не поддерживает структурированные ответы: Запрос завершится с ошибкой, указывающей на отсутствие поддержки
2. Недействительная схема: Модель вернет ошибку, если ваша JSON Schema недействительна