gpt2giga

gpt2giga — FastAPI-прокси, который принимает OpenAI-, Anthropic- и Gemini-like запросы и отправляет их в GigaChat. Он нужен, когда клиент, редактор, агентный фреймворк или SDK умеет работать с OpenAI/Anthropic/Gemini API, а реальный backend должен быть GigaChat.

Локальный адрес по умолчанию: http://localhost:8090.

Зачем Нужен

GigaChat не является drop-in заменой OpenAI или Anthropic API. Прямое подключение существующих SDK часто ломается на формате запросов, streaming-событиях, tool schemas, model discovery, авторизации и optional-параметрах клиентов.

gpt2giga закрывает практические несовместимости:

• переводит OpenAI Chat Completions, OpenAI Responses, OpenAI Embeddings, Anthropic Messages и Gemini GenerateContent в вызовы GigaChat;
• маппит tools/function calling, structured output, изображения, reasoning flags и SSE streaming там, где GigaChat поддерживает базовую возможность;
• принимает и безопасно игнорирует optional-поля OpenAI/Anthropic, которые SDK присылают, но GigaChat не понимает;
• фильтрует транспортные SDK headers, клиентские API keys, cookies и другие небезопасные метаданные перед upstream;
• отделяет клиентскую API-key авторизацию прокси от GigaChat credentials;
• отдаёт список моделей в OpenAI-, Anthropic-, Gemini- и LiteLLM-совместимом виде;
• держит batch/file routes отключёнными, пока их нельзя выполнить end-to-end через GigaChat SDK/backend.

Подробная матрица поддержки и список реальных ограничений вынесены в API Compatibility.

Быстрый Старт

Создайте .env из шаблона и заполните GigaChat credentials:

cp .env.example .env

Запуск через Docker Compose:

docker compose --env-file .env -f deploy/base.yaml --profile DEV up -d

Или локальная установка gateway:

uv tool install gpt2giga
gpt2giga --help

Для установки в существующее окружение:

python -m pip install gpt2giga

Поддерживается Python 3.10–3.14. Для Postgres, OpenSearch или Phoenix добавьте соответствующую extra-зависимость, например:

python -m pip install "gpt2giga[postgres]"

Минимальный OpenAI SDK вызов:

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8090/v1", api_key="<GPT2GIGA_API_KEY>")

response = client.chat.completions.create(
    model="GigaChat-2-Max",
    messages=[{"role": "user", "content": "Привет"}],
)
print(response.choices[0].message.content)

Минимальный Anthropic SDK вызов:

from anthropic import Anthropic

client = Anthropic(base_url="http://localhost:8090", api_key="<GPT2GIGA_API_KEY>")

response = client.messages.create(
    model="GigaChat-2-Max",
    max_tokens=256,
    messages=[{"role": "user", "content": "Привет"}],
)
print(response.content[0].text)

Больше вариантов запуска — в Quickstart.

Документация

Полная документация публикуется на GitHub Pages.

Локально проверить docs можно через Docusaurus wrapper в docs-site/:

make docs-install
make docs

После make docs сайт доступен на http://127.0.0.1:3000/ и включает локали en/ru. Для быстрой разработки с hot reload:

make docs-dev

Docusaurus dev server обслуживает одну локаль за запуск. Для русского dev preview:

make docs-dev-ru

Чтобы проверить переключатель языков между en и ru, используйте full preview через make docs или make docs-preview.

Текущая API-Поверхность

Смонтированные routes доступны в корне и под versioned prefixes. Root routes используют GPT2GIGA_GIGACHAT_API_MODE, /v1 принудительно выбирает GigaChat v1 contract, /v2 принудительно выбирает GigaChat v2 contract. Например: /chat/completions, /v1/chat/completions и /v2/chat/completions.

Поддерживается:

• OpenAI-compatible GET /models, GET /models/{model}, POST /chat/completions, POST /responses, POST /embeddings;
• Anthropic-compatible POST /messages, POST /messages/count_tokens, а также Anthropic-shaped model responses для model-вызовов Anthropic SDK;
• Gemini-compatible /v1beta/models/{model}:generateContent, :streamGenerateContent, :countTokens, :embedContent, :batchEmbedContents, а также /v1beta/models;
• LiteLLM-compatible GET /model/info;
• системные endpoints GET /health и GET|POST /ping.

Отключено до появления нужных batch methods в GigaChat SDK/backend:

• OpenAI-compatible Files API и Batches API;
• Anthropic Message Batches API.
• Gemini-compatible Files API и Batch GenerateContent API.

Сейчас не является целью проекта:

• полная OpenAI parity для audio, image generation/editing, fine-tuning, assistants, threads, runs, vector stores, uploads, moderations, realtime;
• полная Anthropic parity для Files beta, Skills beta, Agents beta, Sessions, Environments или Admin API;
• полная Gemini parity для Files, batchGenerateContent, cached content, Vertex/RAG tools и non-text embeddings content.

Деплой

Docker Compose manifests лежат в deploy/:

docker compose --env-file .env -f deploy/base.yaml --profile PROD up -d
docker compose --env-file .env -f deploy/base.yaml --profile DEV up -d

Production mode требует API key и отключает /docs, /redoc, /openapi.json и /logs*:

GPT2GIGA_MODE=PROD
GPT2GIGA_ENABLE_API_KEY_AUTH=True
GPT2GIGA_API_KEY="<strong-random-secret>"
GIGACHAT_VERIFY_SSL_CERTS=True

Compose profiles, reverse proxies, TLS и hardening описаны в Deployment.

Структура Репозитория

Разработка

Установить зависимости:

uv sync --all-extras --dev

Запустить сервис:

uv run gpt2giga

Сборка дистрибутива выполняется явно:

uv build

Проверки перед PR:

uv run ruff check .
uv run ruff format --check .
uv run pytest tests/ --cov=. --cov-report=term --cov-fail-under=80

Live-тесты с реальными вызовами GigaChat запускаются отдельно и требуют локальных секретов: см. Live GigaChat Integration Tests.

Используйте Conventional Commits (feat:, fix:, docs:, refactor:, test:, ci:) и сверяйтесь с PR template.