Пресеты для Chat Completions

Используйте пресеты, когда одни и те же значения по умолчанию должны применяться во многих /v1/chat/completions запросах. Самый безопасный старт: явная пара model + preset. Так запрос остаётся читаемым и OpenAI-совместимым, а пресет подставляет только недостающие поддерживаемые значения.

Минимальный рабочий запрос

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.gonkagate.com/v1",
  apiKey: "gp-your-api-key",
});

const response = await client.chat.completions.create({
  model: "qwen/qwen3-235b-a22b-instruct-2507-fp8",
  preset: "support-agent",
  messages: [{ role: "user", content: "Draft a concise reply to this support ticket." }],
  temperature: 0.3,
});

console.log(response.choices[0]?.message?.content);

Ожидаемое поведение: поля на уровне запроса всё равно выигрывают. В этом примере temperature: 0.3 переопределяет значение из пресета, а другие отсутствующие поддерживаемые поля всё ещё могут прийти из него.

Как привязать пресет

• model: "<model>" плюс preset: "<slug>": начинайте с него, если тело запроса должно оставаться явным и удобным для отладки. GonkaGate использует модель из запроса и заполняет из пресета только недостающие поддерживаемые значения по умолчанию.
• model: "@preset/<slug>": используйте этот вариант, когда пресет должен задавать и порядок моделей тоже. GonkaGate использует список models, системный промпт, params и reasoning из пресета.
• model: "<model>@preset/<slug>": используйте этот вариант, когда нужна одна явная модель, но остальные значения по умолчанию должны прийти из пресета. GonkaGate использует модель из запроса и всё равно применяет системный промпт и поддерживаемые значения из пресета.

Что может хранить пресет

Используйте пресеты для стабильных общих значений по умолчанию. Всё, что меняется от вызова к вызову, оставляйте на уровне запроса.

• systemPrompt
• params
• reasoning
• models

{
  "name": "Support Agent",
  "slug": "support-agent",
  "description": "Preset for support replies",
  "systemPrompt": "You are a concise support assistant.",
  "models": ["qwen/qwen3-235b-a22b-instruct-2507-fp8"],
  "params": {
    "temperature": 0.2,
    "top_p": 0.9
  },
  "reasoning": {
    "enabled": true,
    "effort": "high"
  }
}

Ограничения валидации, которые влияют на интеграцию:

• models поддерживает максимум 10 элементов.
• params принимает только temperature, top_p, top_k, frequency_penalty, presence_penalty, repetition_penalty, max_tokens и seed.
• reasoning.enabled обязателен, если передан блок reasoning.
• reasoning.effort и reasoning.max_tokens нельзя задавать одновременно.

Как работают merge и приоритет

1. GonkaGate берёт поля из запроса.
2. Поддерживаемые отсутствующие поля заполняются из preset params и reasoning.
3. Поле preset удаляется перед отправкой upstream.
4. Значение systemPrompt применяется как system message:
   • если все существующие system messages используют строковый контент, GonkaGate объединяет systemPrompt и существующий system text в одно system message, где текст пресета идёт первым, а части разделяются пустыми строками
   • если хотя бы одно существующее system message использует нестроковый контент, GonkaGate добавляет systemPrompt как отдельное system message перед остальными

Итоговый приоритет: request > preset > default. Пресеты меняют вход перед отправкой upstream, но не меняют OpenAI-совместимую форму ответа.

Модели и fallback

• model: "@preset/<slug>" требует хотя бы одну сохранённую модель в списке models.
• Если в пресете есть models, GonkaGate строит упорядоченный список кандидатов из этого массива.
• Retry-based fallback применяется только к retry-eligible ошибкам, например transient provider или model-availability проблемам.
• Если запрос использует <model>@preset/<slug> или явную model плюс preset, fallback остаётся на этой модели и не использует список моделей из пресета.
• Для streaming-запросов fallback возможен только до отправки первого чанка.

Частые ошибки и ограничения

• Отключённые пресеты нельзя использовать в /v1/chat/completions; такие запросы завершаются ошибкой preset_disabled.
• preset_not_found: slug не указывает на доступный пресет.
• preset_missing_model: в пресете нет usable model list и запрос не переопределил модель.
• preset_ambiguous: model и preset ссылаются на разные preset slug.
• preset_invalid: ссылка @preset/ сформирована некорректно, например {"model":"@preset/"}.
• preset_invalid_slug: значение slug не проходит формат или зарезервировано, например {"model":"@preset/Ad"}.

Создание и управление в Dashboard

Пресеты относятся к пользователю и управляются через Dashboard. Там их создают, редактируют, включают, отключают, версионируют и откатывают. Runtime-использование всё равно происходит через обычные /v1/chat/completions запросы.

Правила для slug:

• от 3 до 64 символов
• только строчные a-z, цифры и -
• без пробелов, заглавных букв, ведущего или замыкающего дефиса и повторяющихся групп дефисов
• если slug не передан, он генерируется из name

Rollback создаёт новую текущую версию из исторического snapshot. Это не просто перевод указателя на старую запись.

См. также

• Chat Completions API reference для точной схемы запроса.
• Параметры chat completions для поведения отдельных полей.
• Structured Outputs, когда ответ должен следовать JSON-контракту.
• Tool Calling, когда модель должна вызывать инструменты вашего приложения.
• Выбор плагина для runtime-расширений на уровне запроса.