YandexGPT API Integration: IAM, Models, RAG for 152-FZ

When launching AI features in the Russian market, you face a choice: use foreign APIs with a risk of blocking or local models. YandexGPT from Yandex is one option, but its integration requires understanding IAM authentication, model selection, and building a RAG pipeline. We have implemented such integrations for several projects, including with government customers. Our engineers have 10+ years of experience in ML and NLP, so we share proven solutions.

Here's a typical pain point: you deploy an MVP on a foreign API, and a month later you are blocked due to sanctions. With YandexGPT, this problem does not exist — servers are located in Russia, data does not leave the country. But to ensure a smooth integration, you will need to handle IAM tokens, context windows, and asynchronous calls. Contact us to discuss your scenario — we will help with model selection and configuration.

How to set up IAM authentication?

YandexGPT API requires authentication via an IAM token or a service account API key. The token lives 12 hours, the API key is perpetual. For production, use automatic token refresh via the SDK. According to Yandex Cloud Documentation, the IAM token must be refreshed every 12 hours. Example setup:

import requests
import json

FOLDER_ID = "your-folder-id"
IAM_TOKEN = "your-iam-token"  # Refreshed every 12 hours
# Or API_KEY for service account

How to work with the API: synchronous and asynchronous requests?

Synchronous call via REST API:

def yandexgpt_chat(
    prompt: str,
    model: str = "yandexgpt",
    temperature: float = 0.1,
    max_tokens: int = 2000,
) -> str:
    url = "https://llm.api.cloud.yandex.net/foundationModels/v1/completion"

    headers = {
        "Authorization": f"Api-Key {API_KEY}",
        "x-folder-id": FOLDER_ID,
    }

    body = {
        "modelUri": f"gpt://{FOLDER_ID}/{model}",
        "completionOptions": {
            "stream": False,
            "temperature": temperature,
            "maxTokens": max_tokens,
        },
        "messages": [
            {"role": "user", "text": prompt}
        ]
    }

    response = requests.post(url, headers=headers, json=body)
    response.raise_for_status()

    return response.json()["result"]["alternatives"][0]["message"]["text"]

With system prompt:

def yandexgpt_with_system(system: str, user_prompt: str) -> str:
    url = "https://llm.api.cloud.yandex.net/foundationModels/v1/completion"

    body = {
        "modelUri": f"gpt://{FOLDER_ID}/yandexgpt",
        "completionOptions": {"stream": False, "temperature": 0.1, "maxTokens": 2000},
        "messages": [
            {"role": "system", "text": system},
            {"role": "user", "text": user_prompt}
        ]
    }

    response = requests.post(
        url,
        headers={"Authorization": f"Api-Key {API_KEY}", "x-folder-id": FOLDER_ID},
        json=body,
    )
    return response.json()["result"]["alternatives"][0]["message"]["text"]

Asynchronous calls via the official YandexGPT SDK:

from yandex_cloud_ml_sdk import YCloudML

sdk = YCloudML(folder_id=FOLDER_ID, auth=API_KEY)
model = sdk.models.completions("yandexgpt")

# Synchronous
result = model.configure(temperature=0.5).run("Tell me about Moscow")

# Async
result = await model.configure(temperature=0.5).run_async("Request")

# Streaming
for event in model.configure(temperature=0.5).run_stream("Long request"):
    print(event.alternatives[0].text, end="")

Model configuration: parameters and available options

For more details on parameters, see the official Yandex Cloud documentation.

What are Yandex embeddings and why are they needed?

Yandex embeddings are vector representations of text, used for semantic search and RAG. Two types: text-search-doc for document indexing and text-search-query for search queries. Example retrieval:

def get_yandex_embedding(text: str, embedding_type: str = "text-search-doc") -> list[float]:
    response = requests.post(
        "https://llm.api.cloud.yandex.net/foundationModels/v1/textEmbedding",
        headers={"Authorization": f"Api-Key {API_KEY}", "x-folder-id": FOLDER_ID},
        json={
            "modelUri": f"emb://{FOLDER_ID}/{embedding_type}",
            "text": text,
        }
    )
    return response.json()["embedding"]

From practice: RAG pipeline for a state enterprise

One client — a state enterprise with strict data localization requirements. We deployed an automatic response system for citizens' inquiries. YandexGPT was chosen because:

• data does not leave the Russian Federation (152-FZ compliance);
• integration with Yandex SpeechKit for voice input;
• high quality in Russian.

We configured IAM authentication, implemented asynchronous requests, and built a RAG pipeline with Yandex embeddings and pgvector. Response time decreased by 60%, and infrastructure costs — by 40% due to prompt optimization and caching. Savings in query processing time allowed fast ROI. Get a consultation for your project — we will evaluate YandexGPT applicability and design the architecture.

Process

1. Analytics: audit your project, identify YandexGPT usage scenarios.
2. Design: integration architecture, model selection, security setup.
3. Implementation: coding, authentication configuration, integration with existing services.
4. Testing: load testing, p99 latency checks, response quality.
5. Deployment: production rollout, monitoring, documentation.

Estimated timelines

• Basic REST integration: 1 to 2 days.
• SDK integration with async/streaming: 2 to 3 days.
• Full RAG pipeline with embeddings: 1 to 2 weeks.

Cost is calculated individually — contact us for a project evaluation.

What is included

• Configured API access with IAM authentication.
• Ready integration code (REST/SDK) in Python.
• Documentation for use and maintenance.
• Training your team on YandexGPT.
• Technical support during implementation.

Typical mistakes when integrating YandexGPT

• Incorrect IAM token refresh: the token lives 12 hours, it must be updated automatically.
• Ignoring the context window: trim history for long requests.
• Lack of error handling: API may return 429 (rate limit) — implement retry with exponential backoff.
• Suboptimal prompts: for Russian, use clear instructions and examples (few-shot).

Our certified engineers guarantee quality and SLA 99.9%. Contact us to discuss your project — get a free consultation.