Документация / Модели и роутинг

Алиасы и лестница отказов

В поле model стоит алиас, а не имя модели вендора. За алиасом — несколько маршрутов: тот же вес модели у разных провайдеров, в разных аккаунтах и регионах. Выбор делает шлюз.

Порядок маршрутов шлюз считает сам — по цене, задержке и здоровью провайдера. Первый маршрут пробуется, и если он отказал до первого байта ответа, запрос уходит на следующий: это и есть лестница отказов. Платите вы за ответ, а не за попытки.

Параметра маршрутизации в теле запроса нет и не будет: чем управлять — решает алиас на стороне шлюза, а не клиент. Оператор задаёт алиасу список маршрутов, наценку, потолок ответа и то, разрешено ли ему деградировать.

Что значит allow_degrade

Лестница по умолчанию держится одного класса модели: если у алиаса allow_degrade выключен, запрос скорее получит отказ, чем ответ от модели попроще. Когда оператор включает деградацию, шлюз вправе уйти на запасную ступень — и говорит об этом заголовком X-Degraded: true, чтобы «дешёвый ответ» не выдавался за дорогой.

Липкость диалога

Заголовок X-Conversation-Id закрепляет разговор за маршрутом, который ответил в прошлый раз: продолжение не должно перепрыгивать между моделями посреди диалога. Липкость действует, пока маршрут здоров, живёт ограниченное время и не пересекает границы проекта. Само значение шлюз не хранит — только его хэш.

Python JavaScript curl

import os

from openai import OpenAI

client = OpenAI(
    base_url="https://ai.globall.dev/v1",
    api_key=os.environ["TOK_API_KEY"],
)

r = client.chat.completions.create(
    model="anthropic/claude-haiku-5.5",
    messages=[{"role": "user", "content": "Продолжим"}],
    max_tokens=64,
    extra_headers={"X-Conversation-Id": "order-42"},
)
print(r.model)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://ai.globall.dev/v1",
  apiKey: process.env.TOK_API_KEY,
});

const r = await client.chat.completions.create(
  {
    model: "anthropic/claude-haiku-5.5",
    messages: [{ role: "user", content: "Продолжим" }],
    max_tokens: 64,
  },
  { headers: { "X-Conversation-Id": "order-42" } },
);
console.log(r.model);

curl https://ai.globall.dev/v1/chat/completions \
  -H "Authorization: Bearer $TOK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Conversation-Id: order-42" \
  -d '{
    "model": "anthropic/claude-haiku-5.5",
    "messages": [{"role": "user", "content": "Продолжим"}],
    "max_tokens": 64
  }'

В ответе — ваш алиас

Поле model в ответе повторяет алиас, который вы попросили, а не имя модели у вендора. Какая ступень ответила, видно по заголовкам X-Route, X-Attempts и X-Degraded. Идентификатор маршрута — наш внутренний и меняется без предупреждения: назовите его в поддержке, но не стройте на нём логику.

Когда лестница кончилась

Если ни один маршрут алиаса не здоров, приходит 503 no_healthy_route с Retry-After. Если маршрут в принципе не может выполнить запрос — например, вы прислали картинку модели без зрения, — это 400 no_route, и повтор не поможет.

model: string; Алиас. Некоторые алиасы отвечают ещё и на имя модели вендора — синонимы видны в GET /v1/models.
X-Conversation-Id: header; Идентификатор разговора. Любая строка, которую вы придумали сами.
X-Degraded: header; Ответ пришёл с запасной ступени лестницы.
X-Route, X-Attempts: header; Маршрут, который ответил, и номер попытки. Приходят вместе и только после того, как шлюз выбрал маршрут.