Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

gpt2giga

GitHub Actions Workflow Status PyPI Python GitHub License PyPI Downloads GitHub Repo stars GitHub Open Issues Docs

Gateway coverage

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 .

Установка из индекса выбирает опубликованный стабильный релиз, который может ещё не включать возможности текущего 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-dev

Docusaurus 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

Текущая 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.

Дополнительно подключены 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 -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.

Для 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=80

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

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

Проверка кандидата 0.3.3a1

Кандидат из 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 --help

SDK использует native HTTPX2 по умолчанию. GIGACHAT_ASYNC_BACKEND=aiohttp включает альтернативный backend; GigaChat v1 остаётся default, v2 — opt-in. Alpha-образы получают versioned/preview теги, не обновляя latest или стабильные Python aliases. Публикация кандидата — отдельный шаг.

Metadata

Release files for gpt2giga 0.3.3a1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for gpt2giga 0.3.3a1
File Size Uploaded Provenance Actions
gpt2giga-0.3.3a1.tar.gz 425.1 kB Without provenance Details for gpt2giga-0.3.3a1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for gpt2giga 0.3.3a1
File Interpreter ABI Platform Actions
gpt2giga-0.3.3a1-py3-none-any.whl Python 3 none any Details for gpt2giga-0.3.3a1-py3-none-any.whl

Total release size: 904.4 kB

Release files / gpt2giga-0.3.3a1.tar.gz

Download URL gpt2giga-0.3.3a1.tar.gz
Size 425.1 kB
Tags Source
SHA-256 checksum
How to use checksums
430d40abdebcf2b5493d43fc5992353e9f0eef0f5bd84f9aff867f21076387bb
BLAKE2b-256 checksum
How to use checksums
5b2d827f1848c33259678fdbc0b37e9e3781c561d64ebc9d7a612a5fb16b37fb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / gpt2giga-0.3.3a1-py3-none-any.whl

Download URL gpt2giga-0.3.3a1-py3-none-any.whl
Size 479.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7d6c504341b058bea157773fd0dd90c53a85e12ff0a5bb916b6f2755d8d92518
BLAKE2b-256 checksum
How to use checksums
ab835ca896c999a5aa2cb73cc6dc40c825d66a3c3bf0b7546ae594cd97f52890
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for gpt2giga 0.3.3a1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page