JSON Mode и Structured Output — это режимы работы AI моделей, которые гарантируют ответ в строгом JSON-формате. Это критически важно для интеграции AI в бизнес-логику, где ответ модели должен быть машиночитаемым, а не просто текстом. В этой статье покажем все способы получения структурированных данных через ModelSwitch.
Проблема свободного текста
По умолчанию языковая модель возвращает свободный текст. Если вы попросите «извлечь данные из текста», модель может ответить по-разному:
Имя: Иван Петров
Возраст: 35
Город: МоскваИли в другом формате, или с пояснениями. Парсить такой текст регулярными выражениями ненадёжно. JSON Mode решает эту проблему.
JSON Mode: базовый режим
JSON Mode гарантирует, что ответ будет валидным JSON. Включается параметром response_format:
from openai import OpenAI
import json
client = OpenAI(
base_url="https://api.modelswitch.ru/v1",
api_key="msk_ваш_ключ"
)
response = client.chat.completions.create(
model="gpt-4o",
response_format={"type": "json_object"},
messages=[
{"role": "system", "content": "Извлеки данные из текста. Верни JSON с полями: name, age, city, occupation."},
{"role": "user", "content": "Меня зовут Анна Сидорова, мне 28 лет, живу в Санкт-Петербурге, работаю дизайнером."}
]
)
data = json.loads(response.choices[0].message.content)
print(data)
# {"name": "Анна Сидорова", "age": 28, "city": "Санкт-Петербург", "occupation": "дизайнер"}Structured Output: строгая JSON Schema
Structured Output идёт дальше JSON Mode: он гарантирует соответствие ответа определённой JSON Schema. Модель не сможет пропустить обязательное поле или вернуть неправильный тип данных.
response = client.chat.completions.create(
model="gpt-4o",
response_format={
"type": "json_schema",
"json_schema": {
"name": "product_review",
"strict": True,
"schema": {
"type": "object",
"properties": {
"product_name": {"type": "string"},
"rating": {"type": "integer", "minimum": 1, "maximum": 5},
"pros": {"type": "array", "items": {"type": "string"}},
"cons": {"type": "array", "items": {"type": "string"}},
"summary": {"type": "string"},
"recommend": {"type": "boolean"}
},
"required": ["product_name", "rating", "pros", "cons", "summary", "recommend"],
"additionalProperties": False
}
}
},
messages=[
{"role": "user", "content": "Проанализируй отзыв: 'Отличный ноутбук! Быстрый, лёгкий, батарея держит весь день. Но экран мог бы быть поярче, и цена высоковата.'"}
]
)
review = json.loads(response.choices[0].message.content)
print(f"Оценка: {review['rating']}/5")
print(f"Рекомендует: {review['recommend']}")
print(f"Плюсы: {', '.join(review['pros'])}")Интеграция с Pydantic (Python)
Для удобства валидации используйте Pydantic-модели:
from pydantic import BaseModel
class ExtractedEvent(BaseModel):
title: str
date: str
location: str
participants: list[str]
is_online: bool
response = client.chat.completions.create(
model="gpt-4o",
response_format={"type": "json_object"},
messages=[
{"role": "system", "content": f"Извлеки информацию о мероприятии. Верни JSON по схеме: {ExtractedEvent.model_json_schema()}"},
{"role": "user", "content": "Конференция AI Summit 2025, 15 марта, Москва, Крокус Экспо. Спикеры: Иванов, Петрова. Формат — очный."}
]
)
event = ExtractedEvent.model_validate_json(response.choices[0].message.content)
print(f"Событие: {event.title}, {event.date}")
print(f"Онлайн: {event.is_online}")import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.modelswitch.ru/v1",
apiKey: "msk_ваш_ключ",
});
interface TaskExtraction {
tasks: Array<{
title: string;
priority: "high" | "medium" | "low";
deadline: string | null;
assignee: string | null;
}>;
}
const response = await client.chat.completions.create({
model: "gpt-4o",
response_format: { type: "json_object" },
messages: [
{
role: "system",
content: "Извлеки задачи из текста. Верни JSON: {tasks: [{title, priority, deadline, assignee}]}",
},
{
role: "user",
content: "Нужно срочно исправить баг в оплате (Саша, до пятницы). Также обновить документацию (низкий приоритет).",
},
],
});
const result: TaskExtraction = JSON.parse(response.choices[0].message.content!);
result.tasks.forEach((t) => console.log(`[${t.priority}] ${t.title}`));Советы по работе со структурированным выводом
- Всегда указывайте схему в system prompt — даже в JSON Mode модели нужно знать, какие поля ожидаются.
- Используйте strict: true — в Structured Output это гарантирует 100% соответствие схеме.
- Обрабатывайте ошибки парсинга — оберните
json.loads()в try/except, несмотря на гарантии. - Ограничивайте enum-значения — вместо свободных строк используйте enum для категориальных полей.
JSON Mode и Structured Output поддерживаются через ModelSwitch для GPT-4o, GPT-4o-mini, Claude и Gemini. Единый формат запроса для всех моделей.