Перейти к основному содержимому

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

Этот документ помогает запустить gateway к GigaChat, совместимый с OpenAI, Anthropic и Gemini, и проверить каждый протокол первым запросом.

Требования​

  • Python 3.10–3.14 для локального запуска.
  • Текущему checkout нужен GigaChat Python SDK >=0.2.4a1,<0.3.0. SDK 0.2.4a1 опубликован в PyPI и устанавливается автоматически вместе со шлюзом.
  • uv для локальной разработки.
  • Docker с плагином Compose для контейнерного запуска.
  • Учётные данные и scope GigaChat для нужного аккаунта.

Настройка учётных данных​

Выполняйте команды из корня текущего checkout. Создайте локальный env-файл:

cp .env.example .env

Минимально заполните:

GPT2GIGA_MODE=DEV
GPT2GIGA_HOST=0.0.0.0
GPT2GIGA_PORT=8090
GPT2GIGA_ENABLE_API_KEY_AUTH=True
GPT2GIGA_API_KEY="<local-proxy-api-key>"
GIGACHAT_CREDENTIALS="<your-gigachat-credentials>"
GIGACHAT_SCOPE=GIGACHAT_API_PERS
GIGACHAT_MODEL=GigaChat-2-Max

Настройки GigaChat SDK используют префикс GIGACHAT_. Настройки прокси используют префикс GPT2GIGA_.

Запуск через Docker Compose​

Соберите и запустите текущий checkout с профилем DEV:

docker compose --env-file .env -f deploy/base.yaml --profile DEV up -d --build --pull never

Профиль PROD:

docker compose --env-file .env -f deploy/base.yaml --profile PROD up -d --build --pull never

Сборка Docker устанавливает GigaChat SDK из PyPI. Без --build --pull never конфигурация Compose скачивает опубликованный образ latest, который может ещё не включать изменения текущего checkout.

В PROD compose-файл по умолчанию привязывает сервис только к 127.0.0.1. Для внешнего доступа поставьте nginx, Traefik, Caddy или другой обратный прокси.

Проверка:

curl http://localhost:8090/health

Установка gateway​

Команда установки из индекса выбирает опубликованный стабильный релиз gateway:

uv tool install gpt2giga
gpt2giga --help

Текущий checkout содержит prerelease-возможности gateway, которых может ещё не быть в этом релизе. Для доступа к ним установите checkout по инструкции ниже. Требуемый GigaChat SDK доступен в PyPI; отдельный локальный wheel SDK больше не нужен.

Запуск из репозитория​

Установите gateway как editable-проект вместе с зависимостями разработки. uv устанавливает GigaChat SDK из PyPI по версии и контрольным суммам в uv.lock:

uv sync --all-extras --dev
uv run gpt2giga

Для обычной установки текущего checkout через pip установите проект gateway. Например, в новом виртуальном окружении Linux или macOS:

python -m venv .venv
.venv/bin/python -m pip install .
.venv/bin/gpt2giga

Для дополнительных зависимостей замените . на ".[postgres]", ".[opensearch]" или ".[phoenix]" в команде pip.

В DEV документация FastAPI доступна на http://localhost:8090/docs. В PROD она отключена.

OpenAI SDK​

from openai import OpenAI

api_version = "v1"
client = OpenAI(
    base_url=f"http://localhost:8090/{api_version}/",
    api_key="<local-proxy-api-key>",
)

completion = client.chat.completions.create(
    model="GigaChat-2-Max",
    messages=[{"role": "user", "content": "Кратко объясни SSE"}],
)
print(completion.choices[0].message.content)

Для явного выбора контракта бэкенда GigaChat используйте api_version = "v1" или api_version = "v2" и подставляйте его в base_url. /v1 всегда выбирает контракт GigaChat v1, /v2 — контракт GigaChat v2. http://localhost:8090 без версии следует GPT2GIGA_GIGACHAT_API_MODE=v1|v2.

Anthropic SDK​

from anthropic import Anthropic

api_version = "v1"
client = Anthropic(
    base_url=f"http://localhost:8090/{api_version}/",
    api_key="<local-proxy-api-key>",
)

message = client.messages.create(
    model="GigaChat-2-Max",
    max_tokens=512,
    messages=[{"role": "user", "content": "Кратко объясни SSE"}],
)
print(message.content[0].text)

Gemini SDK​

Официальный клиент Gemini сам добавляет /v1beta/models/..., поэтому передайте ему корень gateway, а не /v1 или /v2:

from google import genai
from google.genai import types

client = genai.Client(
    api_key="<local-proxy-api-key>",
    http_options=types.HttpOptions(base_url="http://localhost:8090"),
)
response = client.models.generate_content(
    model="GigaChat-2-Max",
    contents="Кратко объясни SSE",
)
print(response.text)

Чтобы выбрать контракт GigaChat для Gemini, добавьте /v1 или /v2 в URL операции либо используйте соответствующую настройку интеграции. В примерах Gemini есть streaming, tools, structured output, подсчёт токенов и embeddings.

Авторизация GigaChat для каждого запроса​

Если клиент должен передавать авторизацию GigaChat через Authorization, включите:

GPT2GIGA_PASS_TOKEN=True

Поддерживаемые значения заголовка:

  • giga-cred-<credentials>:<scope> для учётных данных по ключу авторизации GigaChat;
  • giga-auth-<access_token> для готового access-токена;
  • giga-user-<user>:<password> для авторизации по логину и паролю.

Для типовых сценариев развёртывания предпочтительнее серверные учётные данные GIGACHAT_*. Включайте GPT2GIGA_PASS_TOKEN=True, только если нужны учётные данные вышестоящего сервиса, специфичные для клиента.

Примеры​