gpt2giga — FastAPI-прокси, который принимает OpenAI-, Anthropic- и
Gemini-like запросы и отправляет их в GigaChat либо в проверенный
OpenAI-compatible Chat Completions backend. Он нужен, когда клиент, редактор,
агентный фреймворк или SDK говорит на одном API, а реальный backend предоставляет
другой совместимый контракт.
Локальный адрес по умолчанию: 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-совместимом виде;
- поддерживает Files/Batches OpenAI, Anthropic и Gemini в документированном подмножестве.
Подробная матрица поддержки и список реальных ограничений вынесены в API Compatibility.
Кандидат 0.3.3a1 требует gigachat[aiohttp]==0.3.0a1. SDK опубликован в PyPI и устанавливается
автоматически вместе со шлюзом через uv, pip или при сборке Docker.
Из корня репозитория создайте .env из шаблона и заполните GigaChat credentials:
cp .env.example .envСоберите и запустите текущий checkout через Docker Compose:
docker compose --env-file .env -f deploy/base.yaml --profile DEV up -d --build --pull neverИли запустите его локально:
uv sync --all-extras --dev
uv run gpt2gigaДля установки этого checkout через pip в существующее окружение:
python -m pip install .Установка из индекса выбирает 8000 опубликованный стабильный релиз, который может ещё не включать возможности текущего checkout:
uv tool install gpt2giga
gpt2giga --helpДля установки опубликованного релиза в существующее окружение:
python -m pip install gpt2gigaПоддерживается Python 3.10–3.15. Стабильный Python 3.15 входит в обязательные CI-проверки тестов и установленного пакета. Для Postgres, OpenSearch или Phoenix добавьте соответствующую extra-зависимость. Например, для опубликованного релиза:
python -m pip install "gpt2giga[postgres]"При установке из текущего checkout используйте python -m pip install ".[postgres]".
Preview-образы Python 3.15 публикуются для linux/amd64 и linux/arm64:
docker pull gigateam/gpt2giga:0.3.1-preview
docker pull ghcr.io/ai-forever/gpt2giga:0.3.1-previewТег preview отслеживает текущую preview-сборку. Теги latest и 0.3.1
используют Python 3.13. Для локальной сборки preview:
docker build --build-arg PYTHON_VERSION=3.15 -t gpt2giga:preview ..
Минимальный 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-devDocusaurus dev server обслуживает одну локаль за запуск. Для русского dev preview:
make docs-dev-ruЧтобы проверить переключатель языков между en и ru, используйте full preview через make docs или make docs-preview.
| Тема | Документ |
|---|---|
| Быстрый запуск и первые запросы | Quickstart |
Codex, Claude Code и Gemini CLI через /v1/chat/completions |
Chat Completions bridge |
| Что поддерживается, отключено или намеренно игнорируется | API compatibility |
Совместимость SDK extra_* и параметров клиентов |
Client parameter compatibility |
| Встроенные инструменты GigaChat и маппинг OpenAI/Anthropic/Gemini | Built-in tools |
| Переменные окружения, CLI flags, backend modes | Configuration |
| Docker Compose, Traefik, Postgres, OpenSearch, Phoenix, production hardening | Deployment |
| Logs, metrics, traffic logs, admin API, debug translation | Operations |
| Live GigaChat integration tests | Live integration tests |
| Внутренняя архитектура normalized messages | Normalized messages |
| Checklist для добавления provider/protocol | How to add a provider |
| Редакторы, агенты, SDK examples, reverse proxies | Integrations |
| Runnable-примеры | Examples |
| История изменений gateway | RU · EN |
Смонтированные 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.
Дополнительно подключены Files/Batches трёх протоколов, Responses input_tokens,
узкий Images generations и native utilities. Cancel/delete batch не поддерживаются.
Для batch срок 24h означает срок принятия результатов шлюзом: без poll до срока
даже завершённая native job может быть признана expired; upstream job может
продолжиться и тарифицироваться. Полной vendor batch parity нет.
Responses snapshots и Conversations доступны opt-in через
GPT2GIGA_RESPONSES_STORAGE_MODE=gateway; default native сохраняет thread continuation.
См. API compatibility.
Сейчас не является целью проекта:
- полная 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/.
Для запуска опубликованного образа latest:
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 -dProduction 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=TrueCompose profiles, reverse proxies, TLS и hardening описаны в Deployment.
Для GigaChat встроен публичный Russian Trusted Root CA: при
GIGACHAT_VERIFY_SSL_CERTS=True вручную устанавливать его не нужно.
Явный CA bundle или SSL context имеет приоритет; отключить добавление можно через
GIGACHAT_USE_BUNDLED_CA=False. Для клиентов с union-схемами инструментов
(например, Hermes Agent) доступна опция GPT2GIGA_NORMALIZE_TOOL_SCHEMAS=True.
Она применяется только к моделям GigaChat-2 на https://api.giga.chat/v1
и преобразует схемы с потерей части ограничений; по умолчанию выключена.
На других адресах, включая staging.example.com и
gateway.example.com, а также для GigaChat-3 схемы не меняются.
Подробнее — Configuration.
| Path | Назначение |
|---|---|
src/gpt2giga/ |
FastAPI app, routers, protocol transforms, config, middleware |
tests/ |
Unit, router, protocol, sink и integration tests |
examples/ |
Runnable OpenAI, Anthropic, Gemini, embeddings and agents examples; documented Files/Batches subsets use real backend execution |
docs/ |
Markdown-контент пользовательской документации и architecture notes |
docs-site/ |
Docusaurus wrapper, sidebar/theme config и npm tooling для GitHub Pages |
integrations/ |
Editor/agent/reverse-proxy integration guides |
deploy/ |
Docker Compose deployment manifests |
traefik/ |
Traefik config для deploy/traefik.yaml |
.github/ |
CI, release, Docker publish, PR/issue templates |
Установить зависимости:
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=80Live-тесты с реальными вызовами GigaChat запускаются отдельно и требуют локальных секретов: см. Live GigaChat Integration Tests.
Используйте Conventional Commits (feat:, fix:, docs:, refactor:, test:, ci:) и сверяйтесь с PR template.
Кандидат из checkout не объявляется опубликованным релизом. Для проверки wheel:
uv build --no-sources
uv venv /tmp/gpt2giga-candidate
uv pip install --python /tmp/gpt2giga-candidate/bin/python dist/gpt2giga-0.3.3a1-py3-none-any.whl
/tmp/gpt2giga-candidate/bin/gpt2giga --helpSDK использует native HTTPX2 по умолчанию. GIGACHAT_ASYNC_BACKEND=aiohttp
включает альтернативный backend; GigaChat v1 остаётся default, v2 — opt-in.
Alpha-образы получают versioned/preview теги, не обновляя latest или стабильные
Python aliases. Публикация кандидата — отдельный шаг.