Response Healing

response-healing добавляет server-side исправление для некорректного non-stream structured output. Подключайте его после того, как базовый запрос с json_object или json_schema уже работает, и нужно сократить число JSON-ошибок до того, как ответ попадет в клиент.

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

{
  "model": "qwen/qwen3-235b-a22b-instruct-2507-fp8",
  "messages": [
    { "role": "system", "content": "Return valid JSON only." },
    { "role": "user", "content": "Extract { title, priority } from: \"Fix login bug (high)\"." }
  ],
  "stream": false,
  "response_format": { "type": "json_object" },
  "plugins": [
    { "id": "response-healing" }
  ]
}

Ожидаемый результат: GonkaGate попытается исправить некорректный structured output до возврата финального сообщения. choices[*].message.content вы всё равно читаете и парсите на клиенте.

Когда использовать

• stream равен false.
• response_format.type равен json_object или json_schema.
• Базовый structured-output запрос уже работает, но нужен дополнительный server-side hardening перед client-side parsing или schema validation.

Когда не использовать

• Ответ стримится.
• Задача про free-form text, а не про structured output.
• Задача зависит от tool calls или другого non-string content. response-healing не чинит такие ответы.

Как включать и выключать

Request-level opt-in срабатывает, когда одновременно выполнены все условия:

• stream равен false.
• response_format.type равен json_object или json_schema.
• plugins включает { "id": "response-healing" }.
• Запись плагина не выключена через enabled: false.

Чтобы выключить плагин для конкретного запроса, уберите запись из plugins или оставьте её и передайте enabled: false.

Для OpenRouter-совместимых клиентов на поведение в GonkaGate сейчас влияют только id и опциональный enabled. Compatibility extras вроде mode или schema_validation допускаются, но для активации healing игнорируются.

Saved plugin settings и overrides

Аутентифицированные запросы также могут унаследовать saved plugin settings, если включена plugin settings policy.

• plugins: [{ "id": "response-healing" }] это явный request-level контракт, но не единственный путь активации.
• Saved defaults подмешиваются только когда request-level запись плагина отсутствует.
• enabled: false выключает healing для этого запроса только если saved setting не locked.
• Если locked saved setting конфликтует с запросом, GonkaGate возвращает 400 invalid_request_error с code=plugin_override_blocked.

Примеры SDK

TypeScript

Официальные TypeScript-типы openai не описывают GonkaGate-specific plugins. Используйте documented workaround для undocumented request params.

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",
  stream: false,
  messages: [
    { role: "system", content: "Return JSON only." },
    { role: "user", content: "Extract title and priority." }
  ],
  response_format: { type: "json_object" },
  // @ts-expect-error undocumented request field for an OpenAI-compatible backend
  plugins: [{ id: "response-healing" }]
});

const content = response.choices[0]?.message?.content ?? "{}";
const data = JSON.parse(content);
console.log(data);

Python

Передавайте plugins через extra_body.

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",
    stream=False,
    messages=[
        {"role": "system", "content": "Return JSON only."},
        {"role": "user", "content": "Extract title and priority."}
    ],
    response_format={"type": "json_object"},
    extra_body={"plugins": [{"id": "response-healing"}]}
)

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

Что учесть перед rollout

• JSON всё равно нужно парсить на клиенте.
• Логируйте x-request-id для support и debugging.
• Если делаете retry для non-stream запросов, используйте x-idempotency-key на активном healing path.

Какие ошибки обрабатывать

Для невалидных типов payload вроде enabled: "yes" ожидайте обычную schema-validation ошибку 400 invalid_request_error с code=invalid_request.

См. также

• Structured Outputs для выбора между json_object и json_schema.
• Plugins Overview для выбора между плагинами chat completions.
• Chat Completions API reference для точной схемы запроса.