gpt2giga 0.1.8a2

Утилита для проксирования OpenAI и Anthropic запросов в GigaChat

Утилита для проксирования OpenAI/Anthropic-запросов в GigaChat

Содержание

1. Описание
2. Возможности gpt2giga
3. Начало работы
   1. Запуск в Docker
   2. Запуск в Docker с Traefik
   3. Локальный запуск
4. Примеры
5. Параметры
   1. Аргументы командной строки
   2. Переменные окружения
6. Авторизация с помощью заголовка
7. Использование HTTPS
8. Использование API ключа
9. Системные эндпоинты
10. Совместимые приложения
11. Вклад и PR-шаблоны

Описание

Утилита gpt2giga — это прокси-сервер, который перенаправляет запросы, отправленные в OpenAI API или Anthropic Messages API, в GigaChat API.

При старте утилиты запускается HTTP-сервер, адрес которого нужно использовать вместо адреса OpenAI API (например, https://api.openai.com/v1/) или Anthropic API (например, https://api.anthropic.com/v1/), заданного в вашем приложении. Утилита обработает запрос и перенаправит его заданной модели GigaChat. После получения ответа модели, она передаст его в приложение в формате исходного API (OpenAI или Anthropic).

Утилита работает как с запросами на генерацию, так и с запросами на создание эмбеддингов (эндпоинты /embeddings или /v1/embeddings).

Общая схема работы gpt2giga:

sequenceDiagram
    participant YourApp as Приложение
    participant gpt2giga
    participant GigaChat as GigaChat API

    YourApp->>gpt2giga: OpenAI / Anthropic запрос
    gpt2giga->>GigaChat: Запрос формата GigaChat API
    GigaChat->>gpt2giga: Ответ формата GigaChat API
    gpt2giga->>YourApp: OpenAI / Anthropic ответ

Возможности gpt2giga

С помощью gpt2giga вы можете:

• использовать OpenAI-совместимые и Anthropic-совместимые клиенты поверх GigaChat без переписывания основного клиентского кода;
• работать через OpenAI Chat Completions API и OpenAI Responses API;
• использовать Anthropic Messages API, включая стриминг, tool use и extended thinking;
• вызывать функции и инструменты через API, включая передачу аргументов в OpenAI- и Anthropic-совместимом формате;
• использовать structured outputs для получения JSON-ответов;
• обрабатывать ответы модели в потоковом режиме с помощью stream=true;
• создавать эмбеддинги через /embeddings и /v1/embeddings;
• использовать подготовленные OpenAI-совместимые Files API и Batches API после появления полного batch API в GigaChat SDK/backend;
• использовать подготовленный Anthropic Message Batches API после появления batch methods в GigaChat SDK;
• получать список моделей и информацию о конкретной модели через OpenAI- и Anthropic-совместимый Models API;
• использовать LiteLLM-совместимый эндпоинт /model/info для клиентов и автодополнения моделей;
• работать с несколькими клиентами и множеством запросов в асинхронном режиме;
• настраивать прокси через .env, переменные окружения и аргументы командной строки;
• включать логирование, HTTPS и API-key авторизацию для локальной разработки и production-сценариев.

Поддерживаемые API routes

Ниже перечислены основные route-группы официальных OpenAI и Anthropic API и отмечено, что из этого поддерживается в gpt2giga. Все смонтированные маршруты в gpt2giga доступны как без префикса, так и с префиксом /v1, например /chat/completions и /v1/chat/completions.

OpenAI API

Route / группа	Официальный OpenAI API	В gpt2giga	Что поддерживается
POST /chat/completions	Да	Да	Основной чатовый эндпоинт, включая stream=true, tools/function calling, structured outputs, работу с вложениями
GET /models	Да	Да	Список доступных моделей GigaChat в OpenAI-совместимом виде
GET /models/{model}	Да	Да	Информация по конкретной модели
POST /embeddings	Да	Да	Создание эмбеддингов через модель из запроса или настроек прокси
POST /responses	Да	Да	OpenAI Responses API для новых клиентов
POST /files	Да	Временно отключено	Router-модуль подготовлен, но не смонтирован: files отключены вместе с batches, пока в gigachat==0.2.1 нет полного batch API
GET /files	Да	Временно отключено	Router-модуль подготовлен, но не смонтирован: files отключены вместе с batches, пока в gigachat==0.2.1 нет полного batch API
GET /files/{file_id}	Да	Временно отключено	Router-модуль подготовлен, но не смонтирован: files отключены вместе с batches, пока в gigachat==0.2.1 нет полного batch API
DELETE /files/{file_id}	Да	Временно отключено	Router-модуль подготовлен, но не смонтирован: files отключены вместе с batches, пока в gigachat==0.2.1 нет полного batch API
GET /files/{file_id}/content	Да	Временно отключено	Router-модуль подготовлен, но не смонтирован: files отключены вместе с batches, пока в gigachat==0.2.1 нет полного batch API
POST /batches	Да	Временно отключено	Router-модуль подготовлен, но не смонтирован: в gigachat==0.2.1 нет полного набора batch methods
GET /batches	Да	Временно отключено	Router-модуль подготовлен, но не смонтирован: в gigachat==0.2.1 нет полного набора batch methods
GET /batches/{batch_id}	Да	Временно отключено	Router-модуль подготовлен, но не смонтирован: в gigachat==0.2.1 нет полного набора batch methods
POST /batches/{batch_id}/cancel	Да	Временно отключено	Не смонтирован: в текущем gigachat==0.2.1 нет полного набора batch methods, включая cancel
GET/POST /chat/completions stored-completions routes	Да	Нет	Маршруты для хранения, выборки и обновления сохранённых chat completions не реализованы
POST /completions	Да	Нет	Legacy Completions API не реализован
POST /images*	Да	Нет	Генерация и редактирование изображений не реализованы
POST /audio*	Да	Нет	Speech / transcription / translation не реализованы
POST /moderations	Да	Нет	Moderations API не реализован
POST /uploads*	Да	Нет	Uploads API не реализован
POST /fine_tuning*	Да	Нет	Fine-tuning API не реализован
POST /assistants*, POST /threads*, POST /runs*	Да	Нет	Assistants/Threads/Runs API не реализованы
POST /vector_stores*	Да	Нет	Vector Stores API не реализован
Realtime API	Да	Нет	Realtime/WebSocket API не реализован

Anthropic API

Route / группа	Официальный Anthropic API	В gpt2giga	Что поддерживается
GET /models	Да	Да	Список моделей в Anthropic-совместимом виде для запросов с Anthropic SDK headers
GET /models/{model_id}	Да	Да	Информация о модели в Anthropic-совместимом виде для запросов с Anthropic SDK headers
POST /messages	Да	Да	Основной Messages API, включая стриминг
POST /messages/count_tokens	Да	Да	Подсчёт токенов для Messages API
POST /messages/batches	Да	Временно отключено	Router-модуль подготовлен, но публичный маршрут не смонтирован: в текущем gigachat==0.2.1 нет batch methods
GET /messages/batches	Да	Временно отключено	Router-модуль подготовлен, но публичный маршрут не смонтирован: в текущем gigachat==0.2.1 нет batch methods
GET /messages/batches/{message_batch_id}	Да	Временно отключено	Router-модуль подготовлен, но публичный маршрут не смонтирован: в текущем gigachat==0.2.1 нет batch methods
GET /messages/batches/{message_batch_id}/results	Да	Временно отключено	Router-модуль подготовлен, но публичный маршрут не смонтирован: в текущем gigachat==0.2.1 нет batch methods
POST /messages/batches/{message_batch_id}/cancel	Да	Временно отключено	Router-модуль подготовлен, но публичный маршрут не смонтирован: в текущем gigachat==0.2.1 нет batch methods
DELETE /messages/batches/{message_batch_id}	Да	Временно отключено	Router-модуль подготовлен, но публичный маршрут не смонтирован: в текущем gigachat==0.2.1 нет batch methods
Files API beta	Да	Нет	Anthropic file upload/download/delete routes не реализованы
Skills API beta	Да	Нет	Anthropic Skills API не реализован
Agents API beta	Да	Нет	Anthropic Agents API не реализован
Sessions / Environments / Admin API beta	Да	Нет	Управляемые beta/API группы Anthropic не реализованы

Коротко по покрытию

• OpenAI: поддерживается основной рабочий набор для прокси-сценариев: models, chat/completions, responses, embeddings; router-модули files и batches подготовлены, но временно не смонтированы, потому что в gigachat==0.2.1 отсутствует полный batch API.
• Anthropic: поддерживается Models API, Messages API и count_tokens; router-модуль Message Batches API подготовлен, но временно не смонтирован.
• Не цель проекта: полная реализация всех route официальных OpenAI/Anthropic API, включая fine-tuning, images, audio, vector stores, assistants и realtime.

Совместимость SDK и политика extra_*

Подробная таблица совместимости параметров вынесена в docs/client-parameter-compatibility.md.

Клиентские настройки SDK вроде base_url, api_key, timeout, retry-настроек, http_client и proxy/transport остаются на стороне клиента. Сервер не трактует их как body-параметры и не прокидывает пользовательские Authorization, x-api-key, cookies, transport headers, x-stainless-*, openai-* или anthropic-* во внешний GigaChat upstream.

При ответе 429 OpenAI SDK по умолчанию повторяет запросы: max_retries=2, то есть один клиентский вызов может отправить до трёх HTTP-запросов в gpt2giga. Чтобы отключить эти клиентские повторы, передайте max_retries=0 при создании OpenAI/AsyncOpenAI клиента.

extra_headers и HTTP headers переносятся в request-scoped contextvars SDK GigaChat для безопасных служебных заголовков: x-request-id, x-session-id, x-service-id, x-operation-id, x-client-id, x-trace-id, x-agent-id. Прочие безопасные пользовательские заголовки идут через custom_headers_cvar; Authorization, x-api-key, cookies, transport headers, x-stainless-*, openai-* и anthropic-* заблокированы. extra_query по умолчанию не прокидывает произвольные query-параметры upstream. Неподдержанные optional body-параметры принимаются и игнорируются, чтобы не ломать SDK-клиенты.

extra_body для Chat Completions, Responses и Anthropic Messages переносится в GigaChat additional_fields целиком, включая SDK-style поля, которые клиент разворачивает в top-level JSON:

• OpenAI Embeddings принимает и игнорирует extra_body, неизвестные top-level поля и dimensions; исполняемыми остаются input, model, encoding_format=base64, extra_headers, extra_query.
• Для OpenAI Chat/Responses unsupported параметры вроде logprobs, top_logprobs, audio, prediction, web_search_options, n > 1, parallel_tool_calls=true принимаются и игнорируются. Built-in tools поддерживаются на GigaChat v2 surface (web_search*, code_interpreter, image_generation / image_generate, url_content_extraction, model_3d_generate); для /responses v2 также строятся нормализованные Responses output items и stream progress events для web_search* и image_generation / image_generate. /chat/completions v1 остаётся поддержанным compatibility route, но новые tool/built-in-tool возможности развиваются для GigaChat v2 mode.
• Для Anthropic Messages unsupported параметры и блоки вроде container, context_management, mcp_servers, server tools, document, file, container_upload, search_result, thinking/redacted_thinking во входном контенте принимаются и игнорируются.

OpenAI SDK:

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8090/v1", api_key="local-key")

client.chat.completions.create(
    model="GigaChat-2-Max",
    messages=[{"role": "user", "content": "Привет"}],
    extra_body={"profanity_check": False},
)

Anthropic SDK:

from anthropic import Anthropic

client = Anthropic(base_url="http://localhost:8090", api_key="local-key")

client.messages.create(
    model="GigaChat-2-Max",
    max_tokens=256,
    messages=[{"role": "user", "content": "Привет"}],
)

Пример игнорируемого compatibility-поля:

client.messages.create(
    model="GigaChat-2-Max",
    max_tokens=256,
    messages=[{"role": "user", "content": "Привет"}],
    extra_body={"mcp_servers": []},  # accepted, ignored
)

Начало работы

Утилиту можно запустить как в контейнере, с помощью Docker, так и локально.

Запуск в Docker

1. Переименуйте файл .env.example в .env.

   cp .env.example .env
   

2. В файле .env укажите данные для авторизации в GigaChat API.

   GigaChat API поддерживает различные способы авторизации, которые отличаются в зависимости от типа вашей учетной записи. Пример с Authorization key.

   GPT2GIGA_MODE=PROD
   GPT2GIGA_HOST=0.0.0.0
   GPT2GIGA_PORT=8090
   GPT2GIGA_ENABLE_API_KEY_AUTH=True
   GPT2GIGA_API_KEY="<your_strong_api_key>"
   GIGACHAT_CREDENTIALS="<your_gigachat_credentials>"
   GIGACHAT_SCOPE=<your_api_scope>
   GIGACHAT_MODEL=GigaChat-2-Max
   GIGACHAT_VERIFY_SSL_CERTS=True
   

3. (Опционально) Используйте образ/сборку с нужной версией Python (3.10–3.14).

   Все Docker Compose-стеки лежат в папке compose/. В compose/base.yaml по умолчанию задан image: ghcr.io/ai-forever/gpt2giga:latest и build.args.PYTHON_VERSION. При необходимости:

   • обновите build.args.PYTHON_VERSION (если собираете образ локально);
   • или замените image: на нужный тег из реестра.

   PYTHON_VERSION=3.10
   docker pull gigateam/gpt2giga:python${PYTHON_VERSION}
   docker pull ghcr.io/ai-forever/gpt2giga:py${PYTHON_VERSION}
   

   Доступные теги смотрите в реестрах: Docker Hub и GHCR.

4. Запустите контейнер с помощью Docker Compose:

   • PROD:

     docker compose --env-file .env -f compose/base.yaml --profile PROD up -d
     

   • DEV:

     docker compose --env-file .env -f compose/base.yaml --profile DEV up -d
     

   В профиле PROD порт по умолчанию пробрасывается только на 127.0.0.1 (см. compose/base.yaml). Для доступа извне используйте reverse proxy (nginx/Traefik/Caddy) или измените bind-адрес в ports:.

Запуск в Docker с Traefik

В репозитории есть готовый стек Traefik + несколько инстансов gpt2giga в файле compose/traefik.yaml:

• gpt2giga (модель по умолчанию GigaChat) → http://localhost:8090
• gpt2giga-pro (модель по умолчанию GigaChat-Pro) → http://localhost:8091
• gpt2giga-max (модель по умолчанию GigaChat-Max) → http://localhost:8092
• Traefik Dashboard → http://localhost:8080/dashboard/

1. Запустите стек:

   docker compose --env-file .env -f compose/traefik.yaml up -d
   

Важно: роутинг в Traefik в этой конфигурации завязан на HTTP Host (см. traefik/rules.yml). Если вы обращаетесь по IP (например, 127.0.0.1), задайте HOST=127.0.0.1 или отправляйте корректный заголовок Host:.

Локальный запуск

Для управления зависимостями и запуска проекта рекомендуется использовать uv.

1. Установите gpt2giga:

   С помощью uv:

   uv tool install gpt2giga
   # или uv add gpt2giga
   

   Или используя pip:

   pip install gpt2giga
   

   Вы также можете использовать исходники:

   pip install git+https://github.com/ai-forever/gpt2giga.git
   

   После установки пакета вы сможете использовать команду gpt2giga, которая позволяет запускать и настраивать прокси-сервер.

2. Переименуйте файл .env.example в .env и сохраните его в корне своего проекта:

   cp .env.example .env
   

3. В файле .env укажите данные для авторизации в GigaChat API.

   GigaChat API поддерживает различные способы авторизации, которые отличаются в зависимости от типа вашей учетной записи.

   Кроме переменных gpt2giga в .env можно указать переменные окружения, которые поддерживает python-библиотека GigaChat.

4. В терминале выполните команду gpt2giga.

Запустится прокси-сервер, по умолчанию доступный по адресу localhost:8090 (если не задан GPT2GIGA_PORT или --proxy.port). Адрес и порт сервера, а также другие параметры, можно настроить с помощью аргументов командной строки или переменных окружения. Документация FastAPI доступна по адресу http://localhost:<PORT>/docs.

Примеры

Подробные runnable-примеры вынесены в папку examples/.

• OpenAI Python SDK:
  • Chat Completions API: examples/openai/chat_completions/README.md
  • Responses API: examples/openai/responses/README.md
  • Files / Batches / embeddings / models: examples/README.md
• Anthropic Python SDK (Messages API): examples/anthropic/README.md
• Индекс всех примеров: examples/README.md

Изменение параметров gpt2giga

Вы можете изменять параметры работы утилиты с помощью аргументов командной строки или переменных окружения.

Аргументы командной строки

Полный список параметров смотрите в gpt2giga --help.

⚠️ Безопасность: Не передавайте секреты (--proxy.api-key, --gigachat.credentials, --gigachat.password, --gigachat.access-token, --gigachat.key-file-password) через аргументы командной строки — они видны всем пользователям через ps aux. Используйте переменные окружения или .env файл (см. раздел ниже). Утилита поддерживает аргументы 2 типов (настройки прокси и настройки GigaChat):

• --env-path <PATH> — путь до файла с переменными окружения .env. По умолчанию ищется .env в текущей директории.

• --proxy [JSON] — set proxy from JSON string (по умолчанию {});

• --proxy.host <HOST> — хост, на котором запускается прокси-сервер. По умолчанию localhost;

• --proxy.port <PORT> — порт, на котором запускается прокси-сервер. По умолчанию 8090;

• --proxy.use-https <true/false> — использовать ли HTTPS. По умолчанию False;

• --proxy.https-key-file <PATH> — Путь до key файла для https. По умолчанию None;

• --proxy.https-cert-file <PATH> — Путь до cert файла https. По умолчанию None;

• --proxy.pass-model <true/false> — передавать в GigaChat API модель, которую указал клиент в поле model (для чата и эмбеддингов);

• --proxy.pass-token <true/false> — передавать токен, полученный в заголовке Authorization, в GigaChat API. С помощью него можно настраивать передачу ключей в GigaChat через OPENAI_API_KEY;

• --proxy.embeddings <EMBED_MODEL> — модель для создания эмбеддингов по умолчанию. Игнорируется при --proxy.pass-model true, если клиент указал model в запросе. По умолчанию EmbeddingsGigaR;

• --proxy.enable-images <true/false> — включить/выключить передачу изображений в формате OpenAI в GigaChat API (по умолчанию True);

• --proxy.enable-reasoning <true/false> — включить reasoning по умолчанию (добавляет reasoning_effort="high" в payload к GigaChat, если клиент не указал reasoning_effort явно);

• --proxy.disable-reasoning <true/false> — полностью отключить передачу reasoning в GigaChat: удаляет reasoning/reasoning_effort из payload, включая явные параметры клиента и extra_body passthrough;

• --proxy.structured-output-mode <function_call/native> — режим structured output: совместимый fallback через function calling или нативное response_format GigaChat SDK 0.2.1+;

• --proxy.model-max-connections <JSON> — per-model лимиты одновременных upstream model-call внутри gpt2giga, например '{"GigaChat-2-Max":5}';

• --proxy.model-max-connections-default <INT> — fallback per-model лимит для моделей, которых нет в --proxy.model-max-connections;

• --proxy.model-max-connections-acquire-timeout <FLOAT> — сколько секунд ждать свободный model slot; 0 означает fail-fast, отсутствие значения — ждать без локального timeout;

• --proxy.log-level — уровень логов {CRITICAL,ERROR,WARNING,INFO,DEBUG}. По умолчанию INFO;

• --proxy.log-filename — имя лог файла. По умолчанию gpt2giga.log;

• --proxy.log-max-size — максимальный размер файла в байтах. По умолчанию 10 * 1024 * 1024 (10 MB);

• --proxy.enable-api-key-auth — нужно ли закрыть доступ к эндпоинтам (требовать API-ключ). По умолчанию False;

• --proxy.api-key — API ключ для защиты эндпоинтов (если enable_api_key_auth=True).

⚠️ Безопасность: Не передавайте секреты (--proxy.api-key, --gigachat.credentials, --gigachat.password, --gigachat.access-token, --gigachat.key-file-password) через аргументы командной строки — они видны всем пользователям через ps aux. Используйте переменные окружения или .env файл (см. раздел ниже).

Далее идут стандартные настройки из библиотеки GigaChat:

• --gigachat [JSON] — set gigachat from JSON string (по умолчанию {});
• --gigachat.base-url <BASE_URL> — базовый URL для GigaChat API. По умолчанию берется значение переменной GIGACHAT_BASE_URL или поля BASE_URL внутри пакета;
• --gigachat.auth-url <AUTH_URL> — базовый URL для Auth GigaChat API. По умолчанию берется значение переменной GIGACHAT_AUTH_URL или поля AUTH_URL внутри пакета;
• --gigachat.credentials <CREDENTIALS> — credentials (ключ/данные авторизации) для GigaChat;
• --gigachat.scope <GIGACHAT_SCOPE> — Скоуп гигачат (API_CORP, API_PERS...);
• --gigachat.user <GIGACHAT_USER> — Вариант авторизации через user/password;
• --gigachat.password <GIGACHAT_PASSWORD> — Вариант авторизации через user/password;
• --gigachat.access-token <ACCESS_TOKEN> — JWE токен;
• --gigachat.model <MODEL> — модель для запросов в GigaChat. По умолчанию GIGACHAT_MODEL;
• --gigachat.profanity-check <True/False> — Параметр цензуры. По умолчанию None;
• --gigachat.timeout <TIMEOUT> — таймаут для запросов к GigaChat API. По умолчанию 30 секунд;
• --gigachat.verify-ssl-certs <True/False> — проверять сертификаты SSL (по умолчанию True);
• --gigachat.ssl-context — Пользовательский SSL контекст;
• --gigachat.ca-bundle-file <PATH> — Путь к CA bundle файлу для проверки TLS сертификатов;
• --gigachat.cert-file <PATH> — Путь к файлу клиентского сертификата;
• --gigachat.key-file <PATH> — Путь к файлу приватного ключа клиента;
• --gigachat.key-file-password <PASSWORD> — Пароль для зашифрованного файла приватного ключа;
• --gigachat.flags <FLAGS> — Дополнительные флаги для управления поведением клиента;
• --gigachat.max-connections <INT> — Максимальное количество одновременных подключений к GigaChat API;
• --gigachat.max-retries <INT> — Максимальное количество попыток повтора для временных ошибок. По умолчанию 0 (отключено);
• --gigachat.retry-backoff-factor <FLOAT> — Множитель задержки для повторных попыток. По умолчанию 0.5;
• --gigachat.retry-on-status-codes <INT,INT...> — HTTP коды статуса, вызывающие повторную попытку. По умолчанию (429, 500, 502, 503, 504);
• --gigachat.token-expiry-buffer-ms <INT> — Буфер времени (мс) до истечения токена для запуска обновления. По умолчанию 60000 (60 секунд).

Пример запуска утилиты с заданными параметрами

Для запуска прокси-сервера с заданным адресом и портом выполните команду:

gpt2giga \
    --proxy.host 127.0.0.1 \
    --proxy.port 8080 \
    --proxy.pass-model true \
    --proxy.pass-token true \
    --gigachat.base-url https://gigachat.devices.sberbank.ru/api/v1 \
    --gigachat.model GigaChat-2-Max \
    --gigachat.timeout 300 \
    --proxy.embeddings EmbeddingsGigaR

Переменные окружения

Для настройки параметров утилиты также можно использовать переменные окружения, заданные в файле .env.

У настроек прокси префикс GPT2GIGA_, у настроек GigaChat: GIGACHAT_

Список доступных переменных:

• GPT2GIGA_HOST="localhost" — хост, на котором запускается прокси-сервер. По умолчанию localhost;
• GPT2GIGA_MODE="DEV" — режим запуска (DEV или PROD). В PROD отключаются /docs, /redoc, /openapi.json; в PROD также обязательно требуется GPT2GIGA_API_KEY, отключаются /logs, /logs/stream, /logs/html; и автоматически ужесточается CORS (нет wildcard *, allow_credentials=False);
• GPT2GIGA_PORT="8090" — порт, на котором запускается прокси-сервер. По умолчанию 8090;
• GPT2GIGA_USE_HTTPS="False" — Использовать ли https. По умолчанию False;
• GPT2GIGA_HTTPS_KEY_FILE=<PATH> — Путь до key файла для https. По умолчанию None;
• GPT2GIGA_HTTPS_CERT_FILE=<PATH> — Путь до cert файла https. По умолчанию None;
• GPT2GIGA_PASS_MODEL="True" — передавать ли модель, указанную в запросе, непосредственно в GigaChat (для чата и эмбеддингов);
• GPT2GIGA_PASS_TOKEN="False" — передавать токен, полученный в заголовке Authorization, в GigaChat API;
• GPT2GIGA_EMBEDDINGS="EmbeddingsGigaR" — модель для создания эмбеддингов по умолчанию. При GPT2GIGA_PASS_MODEL=True используется модель из запроса клиента (с fallback на это значение).
• GPT2GIGA_ENABLE_IMAGES="True" — флаг, который включает передачу изображений в формате OpenAI в GigaChat API;
• GPT2GIGA_ENABLE_REASONING="False" — включить reasoning по умолчанию (добавляет reasoning_effort="high" в payload к GigaChat, если клиент не указал reasoning_effort явно);
• GPT2GIGA_DISABLE_REASONING="False" — полностью отключить передачу reasoning в GigaChat: удаляет reasoning/reasoning_effort из payload, включая явные параметры клиента и extra_body passthrough;
• GPT2GIGA_DEFAULT_MAX_TOKENS — опциональный default max_tokens. По умолчанию не задан, и gpt2giga не добавляет max_tokens к GigaChat-запросу, если клиент сам не передал лимит;
• GPT2GIGA_STRUCTURED_OUTPUT_MODE="function_call" — режим structured output: function_call сохраняет совместимый fallback через function calling, native передает JSON Schema в нативное поле response_format GigaChat SDK 0.2.1+ (требует поддержки модели/API);
• GPT2GIGA_GIGACHAT_API_MODE="v1" — backend contract для chat-like запросов к GigaChat: v1 использует root compatibility methods achat/astream, v2 использует primary v2/chat/completions surface achat.create/achat.stream;
• GPT2GIGA_RESPONSES_API_MODE="inherit" — backend contract для OpenAI /responses: inherit использует GPT2GIGA_GIGACHAT_API_MODE, v1 или v2 переопределяют только /responses;
• GPT2GIGA_MODEL_MAX_CONNECTIONS='{}' — JSON-словарь per-model лимитов одновременных upstream model-call внутри gpt2giga;
• GPT2GIGA_MODEL_MAX_CONNECTIONS_DEFAULT — fallback per-model лимит для моделей, которых нет в GPT2GIGA_MODEL_MAX_CONNECTIONS. По умолчанию не задан;
• GPT2GIGA_MODEL_MAX_CONNECTIONS_ACQUIRE_TIMEOUT — сколько секунд ждать свободный model slot. По умолчанию не задано, 0 означает fail-fast;
• GPT2GIGA_LOG_LEVEL="INFO" — Уровень логов {CRITICAL,ERROR,WARNING,INFO,DEBUG}. По умолчанию INFO
• GPT2GIGA_LOG_FILENAME="gpt2giga.log" — Имя лог файла. По умолчанию gpt2giga.log
• GPT2GIGA_LOG_MAX_SIZE="10*1024*1024" Максимальный размер файла в байтах. По умолчанию 10 * 1024 * 1024 (10 MB)
• GPT2GIGA_ENABLE_API_KEY_AUTH="False" — Нужно ли закрыть доступ к эндпоинтам (требовать API-ключ). По умолчанию False
• GPT2GIGA_API_KEY="" — API ключ для защиты эндпоинтов (если enable_api_key_auth=True).
• GPT2GIGA_CORS_ALLOW_ORIGINS='["*"]' — список разрешенных Origin (JSON массив);
• GPT2GIGA_CORS_ALLOW_METHODS='["*"]' — список разрешенных HTTP-методов (JSON массив);
• GPT2GIGA_CORS_ALLOW_HEADERS='["*"]' — список разрешенных заголовков (JSON массив).

Режим backend API GigaChat

По умолчанию gpt2giga сохраняет прежний контракт GigaChat SDK через root compatibility methods achat/astream:

GPT2GIGA_GIGACHAT_API_MODE=v1
GPT2GIGA_RESPONSES_API_MODE=inherit

Чтобы переключить chat-like запросы на primary v2/chat/completions surface из gigachat==0.2.2a1, задайте:

GPT2GIGA_GIGACHAT_API_MODE=v2

GPT2GIGA_RESPONSES_API_MODE управляет только OpenAI /responses:

GPT2GIGA_GIGACHAT_API_MODE	GPT2GIGA_RESPONSES_API_MODE	/chat/completions	/responses
v1	inherit	v1	v1
v2	inherit	v2	v2
v1	v2	v1	v2
v2	v1	v2	v1

Режим v2 меняет только backend-вызовы к GigaChat (achat.create / achat.stream); внешние OpenAI-compatible маршруты и URL /v1/... остаются прежними. /chat/completions v1 поддерживается для совместимости, но новые tool/built-in-tool возможности ориентированы на GigaChat v2/chat/completions.

Для maintainers: эта реализация целится в gigachat==0.2.2a1 и не является переносом pre-release/1.0.0 архитектуры из PR #123.

Breaking change в 0.1.6: GPT2GIGA_PASS_MODEL по умолчанию True. Если клиент отправляет OpenAI/Anthropic-имя модели, оно будет передано в GigaChat. Чтобы всегда использовать модель из GIGACHAT_MODEL / настроек прокси, задайте GPT2GIGA_PASS_MODEL=False.

Per-model max connections

GIGACHAT_MAX_CONNECTIONS остаётся глобальным лимитом HTTP/SDK подключений к GigaChat. Дополнительно можно включить локальный in-process limiter в gpt2giga, который ограничивает число одновременных upstream model-call отдельно для каждой effective GigaChat модели.

Пример:

GIGACHAT_MAX_CONNECTIONS=7
GPT2GIGA_MODEL_MAX_CONNECTIONS='{"GigaChat-2-Max":5}'
GPT2GIGA_MODEL_MAX_CONNECTIONS_ACQUIRE_TIMEOUT=30

В этом примере общий SDK/HTTP cap равен 7, но GigaChat-2-Max получает максимум пять одновременных upstream model-call.

То же через CLI:

gpt2giga \
    --gigachat.max-connections 7 \
    --proxy.model-max-connections '{"GigaChat-2-Max":5}' \
    --proxy.model-max-connections-acquire-timeout 30

Семантика:

• если GPT2GIGA_MODEL_MAX_CONNECTIONS пустой и GPT2GIGA_MODEL_MAX_CONNECTIONS_DEFAULT не задан, limiter выключен и поведение не меняется;
• если модель есть в GPT2GIGA_MODEL_MAX_CONNECTIONS, используется её explicit limit;
• если модели нет в словаре, но задан GPT2GIGA_MODEL_MAX_CONNECTIONS_DEFAULT, этот limit применяется отдельно к каждой такой модели;
• GPT2GIGA_MODEL_MAX_CONNECTIONS_ACQUIRE_TIMEOUT=0 возвращает локальный 429 сразу, положительное значение ждёт указанное число секунд, отсутствие значения ждёт без локального timeout;
• streaming slot удерживается до завершения upstream stream или закрытия генератора клиентом;
• backend GigaChat всё равно может вернуть собственный 429 по другим причинам.

Ограничения:

• limiter локальный для одного процесса gpt2giga. Несколько workers, контейнеров или pods умножают effective limit: effective_limit = per_process_model_limit * workers * pods. Например, {"GigaChat-2-Max":5} при двух workers в каждом из трёх pods даёт до 5 * 2 * 3 = 30 одновременных upstream-вызовов этой модели;
• при GPT2GIGA_PASS_TOKEN=True разные credentials делят один per-model pool внутри процесса;
• limiter применяется только к model-call endpoint-ам: Chat Completions, Responses, Embeddings, Anthropic Messages и messages/count_tokens. Model list/info endpoints не лимитируются.

При локальном timeout-е limiter возвращает 429 с кодом model_concurrency_limit и пишет warning log event model_concurrency_timeout с provider, model и limit.

Также можно использовать переменные, которые поддерживает библиотека GigaChat:

• GIGACHAT_BASE_URL="https://gigachat.devices.sberbank.ru/api/v1" — базовый URL GigaChat;
• GIGACHAT_MODEL="GigaChat-2-Max" — модель GigaChat API, которая будет обрабатывать запросы по умолчанию;
• GIGACHAT_USER и GIGACHAT_PASSWORD — для авторизации с помощью с помощью логина и пароля;
• GIGACHAT_CREDENTIALS и GIGACHAT_SCOPE — для авторизации с помощью ключа авторизации;
• GIGACHAT_ACCESS_TOKEN — для авторизации с помощью токена доступа, полученного в обмен на ключ;
• GIGACHAT_CA_BUNDLE_FILE - путь к файлу сертификата корневого центра сертификации;
• GIGACHAT_CERT_FILE - путь к клиентскому сертификату;
• GIGACHAT_KEY_FILE - путь к закрытому ключу;
• GIGACHAT_KEY_FILE_PASSWORD - пароль от закрытого ключа;
• GIGACHAT_VERIFY_SSL_CERTS — для того, чтобы проверять SSL сертификаты, по умолчанию True;
• GIGACHAT_MAX_CONNECTIONS - Максимальное количество одновременных подключений к GigaChat API;
• GIGACHAT_MAX_RETRIES - Максимальное количество попыток повтора для временных ошибок. По умолчанию 0 (отключено);
• GIGACHAT_RETRY_BACKOFF_FACTOR - Множитель задержки для повторных попыток. По умолчанию 0.5;
• GIGACHAT_TOKEN_EXPIRY_BUFFER_MS - Буфер времени (мс) до истечения токена для запуска обновления. По умолчанию 60000 (60 секунд).

После запуска сервер будет перенаправлять все запросы, адресованные OpenAI API, в GigaChat API.

Авторизация с помощью заголовка

Утилита может авторизовать запросы в GigaChat API с помощью данных, полученных в заголовке Authorization.

Для этого запустите gpt2giga с аргументом --proxy.pass-token true или задайте переменную окружения GPT2GIGA_PASS_TOKEN=True. Поддерживается авторизация с помощью ключа, токена доступа и логина и пароля.

Возможные варианты содержимого заголовка Authorization:

• giga-cred-<credentials>:<scope> — авторизация с помощью ключа. Вместо <scope> нужно указать версию API, к которой будут выполняться запросы. Подробнее о ключе авторизации и версии API.
• giga-auth-<access_token> — при авторизации с помощью токена доступа. Токен доступа получается в обмен на ключ авторизации и действителен в течение 30 минут.
• giga-user-<user>:<password> — при авторизации с помощью логина и пароля.

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8090", api_key="giga-cred-<credentials>:<scope>")

completion = client.chat.completions.create(
    model="gpt-5",
    messages=[
        {"role": "user", "content": "Кто ты?"},
    ],
)

Использование HTTPS

Утилита может использоваться с протоколом HTTPS, пример генерации сертификатов:

openssl req -x509 -nodes -days 365   -newkey rsa:4096   -keyout key.pem   -out cert.pem   -subj "/CN=localhost"   -addext "subjectAltName=DNS:localhost,IP:127.0.0.1"

GPT2GIGA_USE_HTTPS=True
GPT2GIGA_HTTPS_KEY_FILE="Path to key.pem"
GPT2GIGA_HTTPS_CERT_FILE="Path to cert.pem"

После этого укажите пути к сертификатам в переменных окружения или CLI-аргументах и включите HTTPS.

Альтернатива: разместите gpt2giga за reverse proxy с TLS-терминацией:

• пример стека с Traefik: compose/traefik.yaml и правила в traefik/ (при необходимости добавьте ACME/сертификаты под свой домен).

Использование API ключа

GPT2GIGA_ENABLE_API_KEY_AUTH=True
GPT2GIGA_API_KEY=123

После этого, в сервисе будет добавлена авторизация по токену. Возможны разные варианты выполнения запросов, например: Авторизация по запросу:

curl -L http://localhost:8090/models?x-api-key=123

Авторизация по заголовкам:

curl -H "x-api-key:123" -L http://localhost:8090/models

Авторизация через Bearer:

 curl -H "Authorization: Bearer 123" -L http://localhost:8090/models

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8090", api_key="123")

completion = client.chat.completions.create(
    model="gpt-5",
    messages=[
        {"role": "user", "content": "Кто ты?"},
    ],
)

Системные эндпоинты

• GET /health
• GET | POST /ping
• GET /logs/{last_n_lines} - получение последних N строчек из логов;
• GET /logs/stream - SSE стриминг логов;
• GET /logs/html - HTML страница для удобства просмотра стрима логов

При использовании можно зайти на страницу: http://localhost:8090/logs/html и:

1. Если используется API ключ Использование API ключа, то введите ваш GPT2GIGA_API_KEY
2. Иначе, введите любой символ

После этого, воспользуйтесь утилитой и будут выведены логи.

⚠️ Безопасность: Эндпоинты /logs* предназначены только для разработки. В PROD режиме (GPT2GIGA_MODE=PROD) они автоматически отключены. Не открывайте log-эндпоинты наружу без аутентификации.

Production hardening checklist

Перед развертыванием gpt2giga в production-среде убедитесь, что выполнены следующие шаги:

Обязательные

• Режим PROD: установите GPT2GIGA_MODE=PROD. В этом режиме автоматически отключаются /docs, /redoc, /openapi.json и все /logs*-эндпоинты; CORS ужесточается (нет wildcard *, allow_credentials=False).
• API key аутентификация: установите GPT2GIGA_ENABLE_API_KEY_AUTH=True и задайте надёжный GPT2GIGA_API_KEY (минимум 32 символа, случайная строка).
• TLS-сертификаты GigaChat: установите GIGACHAT_VERIFY_SSL_CERTS=True. Не отключайте проверку SSL в production.
• HTTPS: включите GPT2GIGA_USE_HTTPS=True и укажите пути к TLS-сертификатам (GPT2GIGA_HTTPS_KEY_FILE, GPT2GIGA_HTTPS_CERT_FILE), либо разместите прокси за reverse proxy (nginx, Caddy, Traefik) с TLS-терминацией.
• CORS origins: ограничьте GPT2GIGA_CORS_ALLOW_ORIGINS конкретными доменами вместо ["*"].
• Секреты: храните GIGACHAT_CREDENTIALS, GPT2GIGA_API_KEY и другие секреты в переменных окружения или secrets manager.
• Не передавайте секреты через CLI: используйте .env или переменные окружения вместо --proxy.api-key и --gigachat.credentials (аргументы видны в ps aux).

Рекомендуемые

• Reverse proxy: разместите gpt2giga за reverse proxy (nginx, Caddy и др.) для rate limiting, TLS-терминации и дополнительной фильтрации.
• Уровень логов: установите GPT2GIGA_LOG_LEVEL=WARNING или INFO (не DEBUG) для production — уровень DEBUG может содержать чувствительные данные в логах.
• Network isolation: запускайте gpt2giga в изолированной сети, чтобы исключить доступ к внутренним сервисам через SSRF.
• Мониторинг: настройте мониторинг /health и /ping эндпоинтов.
• Ротация секретов: регулярно обновляйте GPT2GIGA_API_KEY и GIGACHAT_CREDENTIALS.

Совместимые приложения

Таблица содержит приложения, проверенные на совместную работу с gpt2giga.

Название агента/фреймворка	URL	Описание
OpenCode	https://opencode.ai/	AI-агент с открытым исходным кодом
KiloCode	https://kilo.ai/	AI-агент для написания кода, доступен в JetBrains/VSCode
OpenHands	https://openhands.dev/	AI-ассистент для разработки. Подробнее о запуске и настройке OpenHands для работы с gpt2giga — в README
Zed	https://zed.dev/	AI-ассистент
Cline	https://cline.bot/	AI-ассистент разработчика
OpenAI Codex	https://github.com/openai/codex	CLI-агент от OpenAI. Подробнее о запуске и настройке Codex для работы с gpt2giga — в README
Aider	https://aider.chat/	AI-ассистент для написания приложений. Подробнее о запуске и настройке Aider для работы с gpt2giga — в README
Langflow	https://github.com/langflow-ai/langflow	Low/No-code платформа для создания агентов
DeepAgentsCLI	https://github.com/langchain-ai/deepagents	Deep Agents — это платформа для работы с агентами, построенная на основе langchain и langgraph
CrewAI	https://github.com/crewAIInc/crewAI	Фреймворк для оркестрации агентов
Qwen Agent	https://github.com/QwenLM/Qwen-Agent	Фреймворк
PydanticAI	https://github.com/pydantic/pydantic-ai	GenAI Agent Framework, the Pydantic way
Camel	https://github.com/camel-ai/camel	Мультиагентный фреймворк
smolagents	https://github.com/huggingface/smolagents	Фреймворк от hf
Openclaw	https://openclaw.ai/	Personal AI assistant
Claude Code	https://code.claude.com/docs/en/overview	CLI-агент от Anthropic. Подробнее о запуске и настройке Claude Code для работы с gpt2giga — в README
OpenAI Agents SDK	https://github.com/openai/openai-agents-python	SDK для создания агентов с function calling и handoffs. Пример использования — в examples/openai_agents.py
Anthropic SDK	https://github.com/anthropics/anthropic-sdk-python	Официальный Python SDK для Anthropic API. Примеры использования — в examples/anthropic/
Cursor	https://cursor.com/	Редактор с ИИ и агентом для программирования. Подробнее о запуске и настройке Cursor для работы с gpt2giga — в README
Qwen Code	https://github.com/QwenLM/qwen-code	CLI-агент для написания кода. Подробнее о запуске и настройке Qwen Code для работы с gpt2giga — в README
Xcode	https://developer.apple.com/xcode/	Coding Intelligence и внешние агентные инструменты Apple. Подробнее о подключении Xcode к gpt2giga — в README

Вклад и PR-шаблоны

Основной PR-шаблон по умолчанию находится в .github/PULL_REQUEST_TEMPLATE.md. Русскоязычный вариант расположен в .github/PULL_REQUEST_TEMPLATE/ru.md.

Чтобы открыть pull request с русским шаблоном, используйте параметр GitHub template=ru.md в URL сравнения веток:

https://github.com/ai-forever/gpt2giga/compare/main...your-branch?quick_pull=1&template=ru.md

Замените your-branch на имя вашей ветки. Если базовая ветка отличается от main, замените и ее в URL.

История изменений

Подробная информация об изменениях в каждой версии доступна в файле CHANGELOG.md или CHANGELOG_en.md.

Лицензия

Проект распространяется под лицензией MIT. Подробная информация — в файле LICENSE.