Structured Outputs

Получайте надежный JSON, который удобно парсить и валидировать в коде.

Обзор

Structured outputs превращают ответ модели в данные, которые можно валидировать, хранить и использовать в логике приложения. GonkaGate OpenAI-совместим, поэтому формат запросов и SDK такие же.

Два способа получить JSON

• JSON mode: гарантирует валидный JSON, но не навязывает схему.
• JSON Schema: просит модель выдавать данные по вашей схеме. Если модель/провайдер поддерживает строгий режим, выход будет соответствовать схеме.

JSON mode (json_object)

Используйте JSON mode, когда нужен валидный JSON быстро, а форму вы проверяете на своей стороне.

Пример запроса

Установите response_format в json_object.

{
  "model": "qwen/qwen3-235b-a22b-instruct-2507-fp8",
  "messages": [
    { "role": "system", "content": "Return JSON only. Output must be valid JSON." },
    { "role": "user", "content": "Extract: name (string) and age (integer). Text: Alice is 30." }
  ],
  "response_format": { "type": "json_object" },
  "temperature": 0
}

Параметры запроса смотрите в справочнике Chat Completions .

from openai import OpenAI
import json

client = OpenAI(
    base_url="https://api.gonkagate.com/v1",
    api_key="gp-your-api-key"
)

response = client.chat.completions.create(
    model="qwen/qwen3-235b-a22b-instruct-2507-fp8",
    messages=[
        {"role": "system", "content": "Return JSON only. Output must be valid JSON."},
        {"role": "user", "content": "Extract: name (string) and age (integer). Text: Alice is 30."}
    ],
    response_format={"type": "json_object"},
    temperature=0
)

data = json.loads(response.choices[0].message.content)
print(data)

Structured Outputs по JSON Schema (json_schema)

Используйте JSON Schema, когда важна конкретная форма (типы, обязательные поля, enum) и меньше крайних случаев при парсинге.

Пример запроса

Передайте JSON Schema и включите strict=true там, где это поддерживается.

{
  "model": "qwen/qwen3-235b-a22b-instruct-2507-fp8",
  "messages": [
    { "role": "system", "content": "Return JSON only." },
    { "role": "user", "content": "Extract person fields from: Alice is 30." }
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "person",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "name": { "type": "string", "description": "Person name" },
          "age": { "type": "integer", "description": "Age in years" }
        },
        "required": ["name", "age"],
        "additionalProperties": false
      }
    }
  },
  "temperature": 0
}

from openai import OpenAI

client = OpenAI(
    base_url="https://api.gonkagate.com/v1",
    api_key="gp-your-api-key"
)

response = client.chat.completions.create(
    model="qwen/qwen3-235b-a22b-instruct-2507-fp8",
    messages=[
        {"role": "system", "content": "Return JSON only."},
        {"role": "user", "content": "Extract person fields from: Alice is 30."}
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "person",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "name": { "type": "string", "description": "Person name" },
                    "age": { "type": "integer", "description": "Age in years" }
                },
                "required": ["name", "age"],
                "additionalProperties": False
            }
        }
    },
    temperature=0
)

print(response.choices[0].message.content)

Парсинг и валидация

Даже с JSON mode валидируйте результат перед использованием. Считайте вывод модели недоверенным вводом.

Рекомендуемый паттерн

• Парсим JSON (с обработкой ошибок).
• Валидируем по схеме (Pydantic/Zod).
• При ошибке делаем retry с repair-промптом или переключаемся на более строгий режим.

from pydantic import BaseModel

class Person(BaseModel):
    name: str
    age: int

# response.choices[0].message.content should be a JSON string
person = Person.model_validate_json(response.choices[0].message.content)
print(person)

Особенности стриминга

При стриминге JSON часто приходит неполным. Буферизуйте токены и парсите только после финального чанка.

let full = "";

for await (const chunk of stream) {
  const token = chunk.choices[0]?.delta?.content ?? "";
  full += token;
}

// Parse only after stream ends
const data = JSON.parse(full);

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

Сделайте structured outputs надежными в продакшене:

• Держите схемы маленькими и строго под задачу.
• Ставьте additionalProperties=false, чтобы не получить неожиданные поля (schema mode).
• Используйте enum для ограниченных значений (status, category и т.д.).
• Добавляйте description к полям, чтобы снизить неоднозначность.
• Снижайте temperature для детерминированного извлечения.
• Делайте fallback: JSON mode + валидация + retry.

Параметры запроса смотрите в справочнике Chat Completions .

Совместимость моделей

Поддержка JSON mode и JSON Schema зависит от модели/провайдера. Проверьте перед продом.

Проверьте в каталоге Models или через GET /models , чтобы подтвердить актуальные возможности.

Troubleshooting

Частые проблемы и решения:

• Ответ не JSON — уточните system-инструкции и проверьте, что response_format задан.
• JSON.parse падает — сделайте retry с repair-промптом и валидируйте перед использованием.
• Схема не сходится — упростите схему, аккуратнее задайте required или используйте JSON mode.
• JSON обрезается — увеличьте max_tokens или уменьшите объем требуемого вывода.