Совместимость API

gpt2giga — прокси совместимости, а не полный клон OpenAI, Anthropic или Gemini. Он закрывает подмножество API, которое обычно нужно SDK, редакторам и агентным инструментам, когда бэкендом выступает GigaChat или проверенный OpenAI-compatible Chat Completions server.

Что не работает напрямую с GigaChat

Ниже перечислены практические несовместимости, которые закрывает прокси.

Ожидание клиента	Почему ломается без прокси	Что делает gpt2giga
OpenAI Chat Completions JSON	У GigaChat другие форматы сообщений, инструментов, вложений и ответов.	Конвертирует запросы и ответы, включая потоковые фрагменты (chunks).
OpenAI Responses API	У GigaChat нет такого же маршрута /responses и схемы для элементов вывода.	Принимает /responses, сопоставляет input/instructions/tools и нормализует элементы вывода там, где это возможно.
Anthropic Messages API	Блоки контента Anthropic, вызовы инструментов, system, max_tokens и события потока не совпадают с GigaChat.	Конвертирует полезную нагрузку Anthropic в чат-запросы, совместимые с GigaChat, и сопоставляет ответы обратно.
Gemini GenerateContent API	contents/parts, кандидаты, объявления функций, подсчёт токенов и потоковые фрагменты SSE в Gemini отличаются от OpenAI/Anthropic и GigaChat.	Принимает Gemini-подобные запросы в корне, под /v1, /v2 и /v1beta, переводит их в нормализованные запросы chat/embeddings и сопоставляет ответы обратно в форму Gemini.
SDK extra_headers, extra_query, extra_body	SDK могут прислать транспортные поля или необязательные поля модели, которые GigaChat не принимает.	Фильтрует опасные заголовки, передаёт только разрешённые метаданные, пробрасывает специфичный для GigaChat extra_body и игнорирует известные неподдерживаемые необязательные поля.
Потоковая передача SSE	SDK OpenAI, Anthropic и Gemini ждут свои имена событий и формы дельт.	Генерирует SSE, совместимый с OpenAI, Anthropic и Gemini, из потоковых ответов GigaChat.
Инструменты и структурированный вывод	Схемы функций/инструментов и управление через JSON-схему отличаются между провайдерами и режимами бэкенда.	Сопоставляет локальные инструменты/функции и передаёт схемы структурированного вывода через нативный GigaChat response_format.
Авторизация	Клиенты OpenAI/Anthropic работают с API-ключами, а GigaChat требует другого механизма учётных данных и scope.	Разделяет аутентификацию по API-ключу прокси и авторизацию в вышестоящем GigaChat, при необходимости поддерживает сквозную передачу для каждого запроса.
Получение списка моделей	Ответы GigaChat о моделях не совпадают с формой OpenAI/Anthropic/Gemini/LiteLLM.	Переупаковывает список и описание моделей под нужный клиент.
Пакетные маршруты OpenAI/Anthropic/Gemini	У установленного SDK/бэкенда GigaChat нет полного цикла create/list/retrieve/cancel для пакетных API.	Держит роутеры Files/Batches отключёнными, пока они не смогут работать сквозным образом.

Подключённые маршруты

Публичные API-маршруты доступны в корне и под версионированными префиксами. Для встроенных моделей GigaChat префикс /v1 выбирает контракт GigaChat v1, /v2 — v2, а корневые маршруты используют GPT2GIGA_GIGACHAT_API_MODE=v1|v2. Модель, разрешённая в явный алиас профиля провайдера, использует этот профиль; версия публичного пути не перенаправляет её в GigaChat.

Примеры:

• /chat/completions, /v1/chat/completions и /v2/chat/completions
• /responses, /v1/responses и /v2/responses
• /messages, /v1/messages и /v2/messages
• /models/{model}:generateContent, /v1/models/{model}:generateContent, /v2/models/{model}:generateContent и /v1beta/models/{model}:generateContent

Маршруты, совместимые с OpenAI

Маршрут / группа	Статус	Комментарий
GET /models	Поддерживается	Динамический каталог GigaChat или статические алиасы профилей в форме OpenAI. Запрос Codex с client_version получает пустой нативный каталог Codex, чтобы явно настроенная пользовательская модель сохранила принадлежащие клиенту инструкции и метаданные инструментов.
GET /models/{model}	Поддерживается	Одна динамическая модель или точный статический алиас в форме OpenAI.
POST /chat/completions	Поддерживается	Чат без потоковой передачи и потоковый, инструменты/вызов функций, структурированный вывод, вложения там, где поддерживаются.
POST /responses	Stable native / normalized preview	Native GigaChat execution сохраняет compatibility surface, включая hosted tools и attachment handoff. Route-selected normalized execution остаётся technical preview и отклоняет semantics, которые выбранные route/model/API mode не сохраняют.
POST /embeddings	Поддерживается	Использует модель из запроса или модель прокси по умолчанию для эмбеддингов, в зависимости от конфигурации.
GET /model/info	Поддерживается	Эндпоинт информации о модели, совместимый с LiteLLM.
POST /files, GET /files*	Отключено	Код роутера есть, но он не подключён: files без batches дают неполный пакетный цикл OpenAI.
POST /batches, GET /batches*	Отключено	Отключено до появления create/list/retrieve/cancel для пакетов в SDK/бэкенде GigaChat.
Маршруты сохранённых chat-completion	Не реализовано	Сохранённые completions сейчас вне области поддержки.
Устаревший POST /completions	Не реализовано	Устаревшие текстовые completions сейчас вне области поддержки.
Изображения, аудио, модерация, загрузки	Не реализовано	Эти семейства маршрутов OpenAI прокси не реализует.
Fine-tuning, assistants, threads, runs, vector stores	Не реализовано	Сейчас вне области поддержки.
Realtime/WebSocket API	Не реализовано	Сейчас вне области поддержки.

Маршруты, совместимые с Anthropic

Маршрут / группа	Статус	Комментарий
GET /models	Поддерживается	Возвращается в форме Anthropic, когда запрос содержит заголовки Anthropic SDK.
GET /models/{model_id}	Поддерживается	Возвращается в форме Anthropic, когда запрос содержит заголовки Anthropic SDK.
POST /messages	Поддерживается	Messages API, потоковая передача, локальные инструменты, сопоставление с GigaChat v2 для совместимых провайдерских инструментов Anthropic и нативный структурированный вывод. При GPT2GIGA_NORMALIZATION_MODE=on принятое подмножество v1 использует нормализованное ядро запросов, ответов и SSE.
POST /messages/count_tokens	Зависит от провайдера	GigaChat умеет считать текст сообщений, system, tools и structured output. Внешний алиас только с Chat Completions отклоняет операцию: точного token-count API у него нет.
POST /messages/batches, GET /messages/batches*	Отключено	Код роутера есть, но он не подключён до появления пакетных методов в SDK/бэкенде GigaChat.
Files API beta	Не реализовано	Сейчас вне области поддержки.
Skills API beta	Не реализовано	Сейчас вне области поддержки.
Agents, Sessions, Environments, Admin beta APIs	Не реализовано	Сейчас вне области поддержки.

Маршруты, совместимые с Gemini

Операционные маршруты Gemini подключаются в корне, под /v1, /v2 и /v1beta, как остальные публичные API. Для клиентов, которые добавляют версию Gemini API к уже версионированному base URL, также доступны /v1/v1beta и /v2/v1beta. /v1 и /v1/v1beta принудительно выбирают контракт бэкенда GigaChat v1, /v2 и /v2/v1beta — контракт бэкенда GigaChat v2. Корневые пути Gemini /... и /v1beta/... без внешнего /v1 или /v2 используют GPT2GIGA_GIGACHAT_API_MODE=v1|v2.

Эти правила версий Gemini относятся к встроенным моделям GigaChat. Точный внешний алиас профиля остаётся на выбранном провайдере при любом совместимом публичном пути.

Получение списка моделей Gemini в чистой форме Gemini всегда доступно под /v1beta, /v1/v1beta и /v2/v1beta. На общих /models, /v1/models и /v2/models прокси по умолчанию сохраняет форму OpenAI, но возвращает форму Gemini для клиентов Google/Gemini, например при заголовках X-Goog-Api-Client или X-Goog-Api-Key, либо при query-параметре ?key=....

Объекты моделей в форме OpenAI содержат расширение gpt2giga metadata.type="chat"|"embedder". Gateway сохраняет тип от бэкенда, когда он доступен, а иначе определяет embedding-модели по их идентификатору. Потребители могут использовать эти метаданные, чтобы не показывать embedding-only модели в селекторе чат-моделей, не изменяя стандартные поля модели OpenAI.

Если включена аутентификация по API-ключу прокси, клиенты, совместимые с Gemini, могут передавать ключ через x-goog-api-key или ?key=..., помимо общих Authorization: Bearer ..., x-api-key и ?x-api-key=.... Для новых настроек предпочтительнее аутентификация через заголовок: ключи в query-параметрах чаще попадают в журналы доступа.

supportedGenerationMethods строится консервативно: известные чат-подобные модели GigaChat объявляют generateContent, streamGenerateContent и countTokens; модели типа эмбеддингов объявляют только embedContent и batchEmbedContents; неизвестные/пользовательские идентификаторы моделей объявляют только countTokens, если метаданные бэкенда не дают более точной информации. Статический алиас Chat Completions объявляет генерацию и streaming, но не countTokens.

Маршрут / группа	Статус	Комментарий
GET /v1beta/models, /v1/v1beta/models, /v2/v1beta/models	Поддерживается	Список моделей GigaChat в форме Gemini models/*.
GET /v1beta/models/{model}, /v1/v1beta/models/{model}, /v2/v1beta/models/{model}	Поддерживается	Одна модель в форме Gemini Model.
POST /models/{model}:generateContent, /v1/..., /v2/..., /v1beta/..., /v1/v1beta/..., /v2/v1beta/...	Поддерживается	Принятые contents/parts, systemInstruction, generationConfig, объявления/результаты функций, типизированные inline-изображения и JSON Schema output сопоставляются с допустимым для bridge нормализованным чат-запросом. Несмоделированные safety, cache, file и tool-семантики остаются явными и отклоняются admission для OpenAI-compatible bridge до I/O.
POST /models/{model}:streamGenerateContent, /v1/..., /v2/..., /v1beta/..., /v1/v1beta/..., /v2/v1beta/...	Поддерживается	Возвращает text/event-stream с фрагментами Gemini GenerateContentResponse.
POST /models/{model}:countTokens, /v1/..., /v2/..., /v1beta/..., /v1/v1beta/..., /v2/v1beta/...	Зависит от провайдера	GigaChat считает systemInstruction, contents и объявления функций. Внешний алиас только с Chat Completions отклоняет операцию.
POST /models/{model}:embedContent, /v1/..., /v2/..., /v1beta/..., /v1/v1beta/..., /v2/v1beta/...	Поддерживается	Возвращает Gemini embedding.values, используя бэкенд эмбеддингов GigaChat.
POST /models/{model}:batchEmbedContents, /v1/..., /v2/..., /v1beta/..., /v1/v1beta/..., /v2/v1beta/...	Поддерживается	Возвращает Gemini embeddings[], используя бэкенд эмбеддингов GigaChat.
POST /v1beta/files, GET /v1beta/files*	Отключено	Код роутера подготовлен, но по умолчанию не подключён.
POST /v1beta/models/{model}:batchGenerateContent, GET /v1beta/batches*	Отключено	Код роутера подготовлен, но не подключён до сквозного выполнения пакетов.

Вызов функций в Gemini

toolConfig.functionCallingConfig сопоставляется с ближайшей поддерживаемой семантикой нормализованного/OpenAI-подобного слоя:

• mode=AUTO оставляет вызов функций необязательным. Если задан allowedFunctionNames, вышестоящий сервис получает только эти объявленные функции.
• mode=NONE отключает вызов функций.
• mode=ANY поддерживается только когда после учёта allowedFunctionNames остаётся ровно одна функция; она сопоставляется с принудительным вызовом функции.
• mode=ANY без allowedFunctionNames также поддерживается, если объявлена ровно одна функция.
• mode=ANY с несколькими возможными функциями возвращает 400, потому что путь бэкенда GigaChat сейчас не умеет честно выразить «обязательно вызвать одну из нескольких функций».
• allowedFunctionNames проверяется по объявленным functionDeclarations; ссылки на необъявленные функции возвращают 400.

Эмбеддинги в Gemini

embedContent и batchEmbedContents поддерживают только текстовые content.parts[].text. Пустые requests, некорректные элементы пакета и нетекстовые части возвращают 400 до вызова бэкенда эмбеддингов GigaChat.

outputDimensionality принимается как метаданные совместимости для нормализованного запроса и наблюдаемости, но не передаётся в вышестоящий сервис как исполняемая настройка: текущий путь бэкенда эмбеддингов GigaChat не предоставляет управляемое уменьшение размерности через этот параметр.

Область поддержки и проверка Gemini

Это API, совместимый с Gemini, а не полный паритет с Gemini API. Перед релизом проверяйте именно заявленную область поддержки:

• поддерживаемые маршруты: generateContent, streamGenerateContent, countTokens, embedContent, batchEmbedContents, получение списка моделей;
• поддерживаемые префиксы: корень, /v1, /v2, /v1beta, /v1/v1beta, /v2/v1beta;
• отключённые маршруты: роутеры Gemini Files API и batchGenerateContent есть в коде, но не подключены публично до сквозного выполнения в вышестоящем сервисе;
• частично поддерживаемые поля: safetySettings и cachedContent принимаются для совместимости и диагностики, но не применяются; candidateCount, topK и responseModalities принимаются и фиксируются, но игнорируются при выполнении в GigaChat;
• структурированный вывод: generationConfig.responseMimeType=text/plain считается текстовым режимом по умолчанию, application/json сопоставляется с форматом ответа JSON, а другие MIME-типы и responseSchema без application/json возвращают 400;
• неподдерживаемые возможности: инструменты Gemini вне встроенного сопоставления GigaChat SDK (fileSearch, googleMaps, computerUse, MCP, инструменты RAG/retrieval/Vertex), полностью мультимодальные/файловые сценарии Gemini, нетекстовое содержимое эмбеддингов;
• приближения: countTokens считает извлечённый текст через подсчёт токенов GigaChat, игнорирует части non-text/file/cachedContent и не является точным токенизатором Gemini.

Чек-лист для копирования в описание PR:

uv run ruff check .
uv run ruff format --check .
uv run pytest tests/test_protocol/test_gemini_adapter.py tests/test_router/test_gemini_router.py tests/integration/gemini/test_gemini_app_wiring.py

# Optional, requires live GigaChat credentials.
GPT2GIGA_RUN_LIVE_TESTS=1 uv run pytest tests/live/test_real_gigachat_integration.py -k gemini

# Optional release smoke for google-genai + Gemini CLI, auth on/off, and base URL matrix.
GPT2GIGA_RUN_GEMINI_SMOKE=1 GPT2GIGA_LIVE_ENV_FILE=.env.live uv run pytest tests/live/test_gemini_client_smoke.py

Политика совместимости

gpt2giga намеренно принимает многие необязательные поля SDK, которые GigaChat не может исполнить. Это не даёт клиентам падать до того, как полезная часть запроса попадёт в модель.

Типичные поля, которые принимаются и игнорируются:

• Метаданные OpenAI и параметры тонкой настройки: user, metadata, service_tier, seed, prompt_cache_key, logprobs, top_logprobs, logit_bias, prediction, web_search_options, n > 1;
• Необязательные поля Anthropic: metadata, service_tier, top_k, container, context_management, mcp_servers, неподдерживаемые провайдерские инструменты, цитаты (citations), неподдерживаемые блоки контента document/file. Совместимые провайдерские инструменты (web_search*, web_fetch*, code_execution*) сопоставляются со встроенными инструментами GigaChat v2.
• Необязательные поля Gemini: safetySettings, cachedContent, serviceTier, игнорируемые настройки generationConfig, например candidateCount/topK/responseModalities, и неподдерживаемые инструменты, не являющиеся функциями, принимаются и сохраняются для диагностики, но не применяются GigaChat. Совместимые провайдерские инструменты Gemini сопоставляются со встроенными инструментами GigaChat v2: googleSearch / googleSearchRetrieval -> web_search, urlContext -> url_content_extraction, codeExecution -> code_interpreter; полное сопоставление описано во Встроенных инструментах. Неподдерживаемые значения responseMimeType и responseSchema без application/json отклоняются.

Буферизованные параллельные вызовы локальных функций поддерживаются для GigaChat-2-Max на маршрутах v2 OpenAI Chat Completions, Anthropic Messages и Gemini generateContent. Поведение GigaChat v1 не изменилось.

Если поле намеренно игнорируется, оно не отправляется в вышестоящий сервис как исполняемая возможность GigaChat. Буквальный объект extra_body может быть передан в GigaChat additional_fields; в таком случае поддержку определяет API GigaChat.

В наблюдаемости проигнорированные расширения запроса публикуются в маскированном атрибуте llm.request.extensions, а проигнорированные настройки генерации Gemini остаются в llm.invocation_parameters.

Справочник по каждому параметру: Совместимость параметров клиентов.

Статусы маршрутов 0.3, правила проверки отдельных возможностей и стабильные коды ошибок описаны в разделе «Совместимость провайдеров».

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

В нормализованный путь входят:

• версионированная матрица потерь для OpenAI-совместимых, Anthropic- и Gemini-маршрутов; неподдерживаемые запросы отклоняются до обращения к сети;
• адаптер Chat Completions для OpenAI-совместимых API и vLLM с точной привязкой профиля и модели, сетевым разрешением на каждый запрос, SecretRef, строгим каталогом моделей и ограниченным потоком SSE;
• преобразование запросов, ответов, SSE, инструментов, сведений о токенах и ошибок Anthropic;
• поддерживаемая часть Gemini API, включая функции, ошибки безопасности, список моделей и подсчёт токенов; встроенные изображения переводятся в типизированные ссылки;
• единая проверка обычных и потоковых ответов OpenAI, Anthropic и Gemini, функций, отмены, тайм-аутов и некорректных ответов провайдера.

Публичного переключателя на произвольный внешний адрес нет. Маршруты задаются профилями, секреты остаются в окружении, а сетевые и TLS-политики выбирает владелец приложения. Подробнее — в разделе «Настройка провайдеров и моделей».

Режимы бэкенда

По умолчанию используются корневые методы совместимости GigaChat:

GPT2GIGA_GIGACHAT_API_MODE=v1

Задайте GPT2GIGA_GIGACHAT_API_MODE=v2, чтобы корневые маршруты без /v1 или /v2 использовали более новый интерфейс GigaChat v2/chat/completions для чат-подобных запросов. Для явного выбора на уровне клиента используйте base_url с /v1 или /v2: /v1 всегда идёт в контракт GigaChat v1, /v2 — в контракт GigaChat v2.

/chat/completions остаётся маршрутом совместимости и следует переменной окружения. Новые возможности встроенных инструментов развиваются преимущественно вокруг режима GigaChat v2, поэтому клиенты, которым они нужны, могут указывать http://localhost:8090/v2.

Согласование контрактов SDK в 0.3.1a1

Включённый wheel gigachat==0.2.4a1 собран из коммита SDK 6e9bb50. Его SHA-256 записан в lock-файле. Совместимость шлюза и SDK проверяется синтетическими HTTP-ответами; эти проверки не подтверждают качество живой модели, права доступа к возможностям, экономию кэша или детерминированность генерации.

Контракт	Поведение шлюза
Параметры генерации v2	Лимиты и параметры сэмплирования сериализуются в model_options; бюджет reasoning сохраняется. Преобразованные публичные параметры имеют приоритет над дополнительными; остальные вложенные настройки сохраняются.
Обязательный вызов функции	OpenAI tool_choice="required" и Anthropic tool_choice.type="any" преобразуются в v2 tool_config.mode="any". v1 отклоняет требование вместо молчаливого auto. Выбор по имени использует mode="forced".
Параллельные результаты функций	Каждый результат сохраняет id своего вызова, в том числе при одинаковых именах функций. tools_state_id остаётся отдельным полем состояния диалога.
Дополнительные параметры	extra_body / SDK additional_fields сохраняют поддерживаемые провайдером настройки без отдельных классов шлюза для внутренних сервисов.
Кэшированные токены	OpenAI prompt/input включает кэш; число токенов кэша также доступно в деталях usage. Anthropic возвращает незакэшированный input_tokens и отдельный cache_read_input_tokens.
Настройки Responses	Если temperature и top_p не заданы, ответ содержит null, в том числе в потоке; отсутствие store отображается как false. parallel_tool_calls отражает эффективный запрос GigaChat с учётом вложенных переопределений; значение GigaChat по умолчанию — false.
История Responses	Native v2 отображает previous_response_id в storage.thread_id, убирает model при продолжении и отправляет новый input. v1 отклоняет previous_response_id и store=true; передавайте полную историю или используйте /v2/responses.
Выбор assistant/thread	Native assistant_id и stateful storage выбирают upstream без подстановки модели по умолчанию, в том числе в v1.
Заголовок сессии	GIGACHAT_SESSION_ID задаёт значение SDK по умолчанию; X-Session-ID запроса переопределяет его и не влияет на следующие запросы.
Env-файл CLI	Относительный --env-path разрешается от рабочего каталога. Отсутствующий явно указанный файл останавливает запуск.

Получение сохранённого ответа (GET /responses/{id}) остаётся нереализованным: продолжение v2 использует треды GigaChat, а не полное хранилище OpenAI Responses. Клиент должен сохранить идентификатор ответа. JSON Schema передаётся без изменений; шлюз не исправляет сгенерированные моделью аргументы или поведение v1 с anyOf.

Часть отличий намеренная: строковый результат инструмента оборачивается в {"result": "..."} для GigaChat; Messages принимает отсутствие max_tokens (Anthropic SDK требует этот параметр). Для переносимости передавайте лимит явно. Wildcard CORS в DEV остаётся настройкой разработки; управление авторизацией и CORS описано в Конфигурации. Ограничение зависимости остаётся openai>=2.50,<3.

Повторная отправка вызовов инструментов

Состояние диалога GigaChat возвращается в расширении tools_state_id каждого элемента OpenAI Chat Completions tool_calls[], Responses function_call и Anthropic tool_use. Сохраняйте это поле при повторной отправке assistant-сообщения или элементов output, например через model_dump() Python SDK. Шлюз переносит состояние в ход assistant и сопоставляет результаты по исходному ID вызова, в том числе при одинаковых именах функций.

ID вызова и ID состояния — отдельные непрозрачные строки. Не удаляйте их префиксы и не подменяйте id / call_id / tool_use_id состоянием. При сборке потока SDK получает каждый идентификатор однократно; блоки инструментов могут задерживаться до прихода завершающего события с состоянием. Клиенты, которые заново собирают сообщения по строгому списку полей, должны явно сохранять tools_state_id. Поле ответа metadata.gigachat_tool_state_id остаётся доступным для ручной сборки истории.

Примеры обновлённых контрактов

Запуск из корня репозитория после старта локального прокси:

uv run python examples/openai/chat_completions/basic/session_cache_usage.py
uv run python examples/openai/responses/tools/required_parallel_stream.py
uv run python examples/anthropic/messages/tools/required_tool.py
uv run python examples/openai/chat_completions/reasoning/chat_reasoning.py
uv run python examples/openai/responses/basic/stateful.py

Индекс примеров объясняет ожидаемые поля и условия запуска. Пример Responses сохраняет каждый call_id и переносит metadata.gigachat_tool_state_id в отдельный tools_state_id элемента истории. Включение параллельных вызовов не гарантирует их количество. Инструменты в примерах используют локальные данные-заглушки.

Дополнительные параметры можно передать через OpenAI SDK:

response = client.chat.completions.create(
    model="GigaChat-2-Max",
    messages=[{"role": "user", "content": "Реши задачу кратко."}],
    max_completion_tokens=1024,
    reasoning_effort="low",
    extra_body={
        "reasoning": {"max_tokens": 256},
        "model_options": {"repetition_penalty": 1.05},
    },
)

Здесь client использует /v2. Для выбора настроенного assistant вместо модели можно передать extra_body={"assistant_id": "<ваш assistant ID>"}: шлюз уберёт model из запроса upstream. Это не создаёт assistant и требует доступного в вашем аккаунте идентификатора.