This release is a pre-release and may not be stable for production use.
gpt2giga
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.
Быстрый Старт
Текущий checkout содержит prerelease gateway и требует GigaChat SDK
>=0.2.4a1,<0.3.0. SDK 0.2.4a1 опубликован в 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. Для Postgres, OpenSearch или Phoenix добавьте соответствующую extra-зависимость. Например, для опубликованного релиза:
python -m pip install "gpt2giga[postgres]"
При установке из текущего checkout используйте python -m pip install ".[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.
| Тема | Документ |
|---|---|
| Быстрый запуск и первые запросы | 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.
Структура Репозитория
| 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.1a1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| gpt2giga-0.3.1a1.tar.gz | 361.9 kB | Without provenance | Details for gpt2giga-0.3.1a1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| gpt2giga-0.3.1a1-py3-none-any.whl | Python 3 | none | any | Details for gpt2giga-0.3.1a1-py3-none-any.whl |
Total release size: 776.1 kB
Release files / gpt2giga-0.3.1a1.tar.gz
| Download URL | gpt2giga-0.3.1a1.tar.gz |
|---|---|
| Size | 361.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d4527f019d617f5e421f85d4ba92b935173909dbe4310dceee6753f0ff05ee6b
|
|
BLAKE2b-256 checksum How to use checksums |
bc6b364866e8e4f0d35f18e67966cd248920674117b9945ff6fb134a15adee83
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.24 {"installer":{"name":"uv","version":"0.12.24","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.1a1-py3-none-any.whl
| Download URL | gpt2giga-0.3.1a1-py3-none-any.whl |
|---|---|
| Size | 414.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2b9713f8d3b10f04c94b21ea8b5c0cca1ef90e7c488fd766277b6cc079b63e90
|
|
BLAKE2b-256 checksum How to use checksums |
546c0100d94600bdf56e9ec6c021c61d4353d77844eb5475153791c38de1afc4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.24 {"installer":{"name":"uv","version":"0.12.24","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.1a1
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.