GigaChat Integration Guide

Integration guide for GigaChat API (Sber Russian LLM) with CodeGraph.

Table of Contents

Overview

GigaChat is a Russian LLM provider from Sberbank. CodeGraph supports GigaChat as an alternative to OpenAI, Yandex AI Studio, or local models.

Tip: For larger context windows (up to 262K tokens), consider using Yandex AI Studio which offers Qwen3-235B and other models.

Quick Setup (3 Steps)

Step 1: Set Authorization Key

# Windows PowerShell
$env:GIGACHAT_AUTH_KEY = "your_authorization_key"

# Permanent (survives restart)
[System.Environment]::SetEnvironmentVariable('GIGACHAT_AUTH_KEY', 'your_key', 'User')

# Linux/Mac
export GIGACHAT_AUTH_KEY="your_authorization_key"

# Add to ~/.bashrc for permanent
echo 'export GIGACHAT_AUTH_KEY="your_key"' >> ~/.bashrc

Step 2: Configure config.yaml

llm:
  provider: gigachat

  gigachat:
    client_id: "019a7e2b-aeb3-78c4-ba3d-ddc1142b4ee6"
    credentials: ${GIGACHAT_AUTH_KEY}
    scope: "GIGACHAT_API_PERS"
    model: "GigaChat-2-Pro"
    temperature: 0.7
    max_tokens: 2000
    timeout: 60

Step 3: Verify

pytest tests/llm/test_gigachat.py -v

Expected output:

tests/llm/test_gigachat.py::test_auth_key_set PASSED
tests/llm/test_gigachat.py::test_config_valid PASSED
tests/llm/test_gigachat.py::test_sdk_available PASSED

Available Models

Model Description Best For
GigaChat-2-Pro Latest generation, most capable Complex analysis (recommended)
GigaChat-Max Maximum quality Critical tasks
GigaChat-Pro Advanced General code analysis
GigaChat-Plus Extended Balanced quality/speed
GigaChat Base model Simple queries

API Scopes

Scope Description
GIGACHAT_API_PERS Personal access (default)
GIGACHAT_API_CORP Corporate access
GIGACHAT_API_B2B B2B access

Set scope in config.yaml → llm.gigachat.scope.

Automated Setup

PowerShell Script

# Run automated setup
.\chroma_db\setup_gigachat.ps1

The script will: 1. Prompt for Authorization Key 2. Create config.yaml from template 3. Install GigaChat SDK 4. Verify configuration

Using Template

# Copy template
cp config/config.gigachat.yaml.example config.yaml

# Edit with your settings
nano config.yaml

Usage in Code

The recommended way to use GigaChat in CodeGraph is through the LLM factory, which reads config.yaml automatically:

from src.llm.factory import get_llm_provider

# Creates provider based on config.yaml (provider: gigachat)
provider = get_llm_provider()

# Generate response
response = provider.generate(
    system_prompt="You are a code analysis expert",
    user_prompt="Explain how MVCC works in PostgreSQL"
)
print(response.content)

With Workflow

from src.workflow import MultiScenarioCopilot

copilot = MultiScenarioCopilot()
result = copilot.run("Find transaction handling methods")
print(result['answer'])

Direct LangChain Usage

import os
from langchain_gigachat import GigaChat

auth_key = os.getenv("GIGACHAT_AUTH_KEY")

llm = GigaChat(
    credentials=auth_key,
    scope="GIGACHAT_API_PERS",
    model="GigaChat-2-Pro",
    verify_ssl_certs=False
)

response = llm.invoke("What is PostgreSQL?")
print(response.content)

Configuration Reference

Full config.yaml Example

llm:
  provider: gigachat

  gigachat:
    # Required
    client_id: "019a7e2b-aeb3-78c4-ba3d-ddc1142b4ee6"
    credentials: ${GIGACHAT_AUTH_KEY}
    scope: "GIGACHAT_API_PERS"
    model: "GigaChat-2-Pro"

    # Optional
    temperature: 0.7          # Creativity (0.0-1.0)
    max_tokens: 2000          # Max response length
    timeout: 60               # Request timeout (seconds)
    verify_ssl_certs: true    # SSL verification (false for dev)
    base_url:                 # Custom API endpoint (optional)
    top_p:                    # Top-p sampling (optional)

Note: Retry logic (3 retries, exponential backoff 0.5–10s) is built into GigaChatProvider and not configurable via config.yaml.

Environment Variables

# Required
GIGACHAT_AUTH_KEY=your_authorization_key

# Optional
GIGACHAT_CLIENT_ID=019a7e2b-aeb3-78c4-ba3d-ddc1142b4ee6

Streaming and Embeddings

Streaming Generation

GigaChatProvider supports streaming for real-time output:

from src.llm.factory import get_llm_provider

provider = get_llm_provider()

for chunk in provider.generate_stream(
    system_prompt="You are a code analyst",
    user_prompt="Describe the executor subsystem"
):
    print(chunk, end="", flush=True)

Embeddings

GigaChat provides embeddings via GigaChatEmbeddings:

from src.llm.factory import get_llm_provider

provider = get_llm_provider()

vectors = provider.get_embeddings([
    "Memory allocation in PostgreSQL",
    "Transaction isolation levels"
])
# vectors: List[List[float]]

Troubleshooting

Authentication Failed (401)

Error: 401 Unauthorized

Solution:

# Check if key is set
echo $GIGACHAT_AUTH_KEY

# Verify key format (should be base64)
python -c "import base64; base64.b64decode('$GIGACHAT_AUTH_KEY')"

Connection Timeout

Error: Connection timed out

Solution:

# Increase timeout in config.yaml
gigachat:
  timeout: 120  # seconds

SSL Certificate Error

Error: SSL: CERTIFICATE_VERIFY_FAILED

Solution:

# Disable SSL verification (not recommended for production)
gigachat:
  verify_ssl_certs: false

Rate Limiting

Error: 429 Too Many Requests

Solution: Built-in retry logic handles rate limits automatically (3 retries with exponential backoff). If errors persist, reduce request frequency or upgrade API scope from GIGACHAT_API_PERS to GIGACHAT_API_CORP.

Best Practices

  1. Never commit auth keys — Use environment variables
  2. Use GigaChat-2-Pro — Best quality for code analysis
  3. Set appropriate timeout — 60s for normal, 120s for complex
  4. Use factory — get_llm_provider() handles config automatically

Security Considerations

  • Store auth keys in environment variables
  • Add .env to .gitignore
  • Use secure connection (HTTPS)
  • Enable SSL verification in production (verify_ssl_certs: true)

Resources

Next Steps