8000 GitHub - ai-forever/gpt2giga: FastAPI proxy for OpenAI, Anthropic and Gemini compatible clients backed by the GigaChat API · GitHub
[go: up one dir, main page]

Skip to content
ai-foreverPublic

About

FastAPI proxy for OpenAI, Anthropic and Gemini compatible clients backed by the GigaChat API

Topics

Resources

Contributing

Stars

146 stars

Watchers

5 watching

Forks

Latest commit

 

History

175 Commits

Folders and files

Repository files navigation

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 .

Установка из индекса выбирает 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-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. Публикация кандидата — отдельный шаг.

About

FastAPI proxy for OpenAI, Anthropic and Gemini compatible clients backed by the GigaChat API

Topics

Resources

Contributing

Stars

146 stars

Watchers

5 watching

Forks

Releases

Packages

Used by

Contributors

Languages

0