Skip to main content

Quickstart

This document helps you launch an OpenAI-, Anthropic-, and Gemini-compatible gateway to GigaChat and verify each protocol with a first request.

Requirements​

  • Python 3.10–3.14 for a local run.
  • This checkout requires GigaChat Python SDK >=0.2.4a1,<0.3.0. SDK 0.2.4a1 is available on PyPI and is installed automatically with the gateway.
  • uv for local development.
  • Docker with the Compose plugin for a container run.
  • GigaChat credentials and scope for the target account.

Setting up credentials​

Run repository commands from the root of this checkout. Create a local env file:

cp .env.example .env

At a minimum, fill in:

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

The GigaChat SDK settings use the GIGACHAT_ prefix. The proxy settings use the GPT2GIGA_ prefix.

Running via Docker Compose​

Build and run the current checkout with the DEV profile:

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

PROD profile:

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

The Docker build installs the GigaChat SDK from PyPI. Without --build --pull never, the Compose configuration pulls the published latest image, which may not include the changes in this checkout.

In PROD, the Compose file binds the service to 127.0.0.1 only by default. For external access, put nginx, Traefik, Caddy, or another reverse proxy in front.

Check:

curl http://localhost:8090/health

Install the gateway​

The package-index command installs the published stable gateway release:

uv tool install gpt2giga
gpt2giga --help

This checkout contains prerelease gateway features that may not be in that release. Install the checkout as described below to use them. Its GigaChat SDK dependency is available on PyPI; a separate local SDK wheel is no longer needed.

Run from the repository​

Install the editable gateway project and development dependencies. uv installs the GigaChat SDK from PyPI using the version and hashes in uv.lock:

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

For a regular pip installation of the current checkout, install the gateway project. For example, in a new virtual environment on Linux or macOS:

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

For optional dependencies, replace . with ".[postgres]", ".[opensearch]", or ".[phoenix]" in the pip command.

In DEV, the FastAPI docs are available at http://localhost:8090/docs. In PROD they are disabled.

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": "Briefly explain SSE"}],
)
print(completion.choices[0].message.content)

To explicitly select the GigaChat backend contract, use api_version = "v1" or api_version = "v2" and pass it into base_url. /v1 always selects the GigaChat v1 contract, /v2 selects the GigaChat v2 contract. http://localhost:8090 without a version follows 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": "Briefly explain SSE"}],
)
print(message.content[0].text)

Gemini SDK​

The official Gemini client appends /v1beta/models/... itself, so pass the gateway root rather than /v1 or /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="Briefly explain SSE",
)
print(response.text)

To select a GigaChat backend contract for Gemini, include /v1 or /v2 in the operation URL or use the corresponding integration configuration. See the Gemini examples for streaming, tools, structured output, token counting, and embeddings.

Per-request GigaChat authorization​

If a client must pass GigaChat authorization via Authorization, enable:

GPT2GIGA_PASS_TOKEN=True

Supported header values:

  • giga-cred-<credentials>:<scope> for GigaChat authorization key credentials;
  • giga-auth-<access_token> for a ready access token;
  • giga-user-<user>:<password> for username/password authorization.

For typical deployment scenarios, server-side GIGACHAT_* credentials are preferable. Enable GPT2GIGA_PASS_TOKEN=True only if you need client-specific upstream credentials.

Examples​