Skip to main content

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-совместимом виде;
  • держит batch/file routes отключёнными, пока их нельзя выполнить end-to-end через GigaChat SDK/backend.

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

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

Релиз 0.3.1 требует GigaChat SDK >=0.2.4,<0.3.0. SDK 0.2.4 опубликован в 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.14. Поддержка Python 3.15 пока экспериментальная (preview): отдельный неблокирующий CI-job проверяет тесты, сборку wheel/sdist и запуск установленного пакета. Для 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-rc -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.

Отключено до появления нужных 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/. Для запуска опубликованного образа 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; files/batches examples are prepared but not mounted
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.

Metadata

Release files for gpt2giga 0.3.2

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.2
File Size Uploaded Provenance Actions
gpt2giga-0.3.2.tar.gz 376.1 kB Without provenance Details for gpt2giga-0.3.2.tar.gz

Built distribution (wheel)

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

Total release size: 802.3 kB

Release files / gpt2giga-0.3.2.tar.gz

Download URL gpt2giga-0.3.2.tar.gz
Size 376.1 kB
Tags Source
SHA-256 checksum
How to use checksums
5ebb24f7ac16ffca55b48da24c5416c17e641a5de19d9b6e546d528f895f1c0d
BLAKE2b-256 checksum
How to use checksums
0016c81ad6b39123e5b0976a5d48eebbd9ea8e29f6dfb4ac3fbaad546678d873
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":"24.04","id":"noble","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.2-py3-none-any.whl

Download URL gpt2giga-0.3.2-py3-none-any.whl
Size 426.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9941e0cece3dd068aa12c8c246d1fb571111873c4156acd2a5366249b5e95efe
BLAKE2b-256 checksum
How to use checksums
cfb3a0da6c6a6571c92709cde79d1bad0d35621f18f72a7aa0e63c5fb85198a3
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":"24.04","id":"noble","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.2

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

0.3.2 This release

2 release files No provenance

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