Інтеграція YandexGPT API: налаштування, моделі, RAG під 152-ФЗ

При запуску AI-функцій на російському ринку постає вибір: використовувати закордонні API з ризиком блокувань або локальні моделі. YandexGPT від Яндекса — один із варіантів, але його інтеграція потребує розуміння IAM-аутентифікації, вибору моделі та побудови RAG-пайплайну. Ми вже реалізували такі інтеграції для кількох проєктів, зокрема з держзамовниками. Наші інженери мають 10+ років досвіду в ML та NLP, тому ділимося перевіреними рішеннями.

Ось типова біль: ви розгортаєте MVP на закордонному API, а через місяць вас блокують з санкційних причин. З YandexGPT такої проблеми немає — сервери знаходяться в РФ, дані не покидають країну. Але щоб інтеграція пройшла гладко, доведеться розібратися з IAM-токенами, контекстним вікном та асинхронними викликами. Зв'яжіться з нами для обговорення вашого сценарію — допоможемо з вибором моделі та налаштуванням.

Як налаштувати IAM-аутентифікацію?

YandexGPT API вимагає аутентифікації через IAM-токен або API-ключ сервісного акаунту. Токен живе 12 годин, API-ключ безстроковий. Для production використовуйте автоматичне оновлення токена через SDK. Згідно з Yandex Cloud Documentation, IAM-токен необхідно оновлювати кожні 12 годин. Приклад налаштування:

import requests import json FOLDER_ID = "your-folder-id" IAM_TOKEN = "your-iam-token" # Оновлюється кожні 12 годин # Або API_KEY для сервісного акаунту 

Як працювати з API: синхронні та асинхронні запити?

Синхронний виклик через 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"] 

З 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"] 

Асинхронні виклики через офіційний YandexGPT SDK:

from yandex_cloud_ml_sdk import YCloudML sdk = YCloudML(folder_id=FOLDER_ID, auth=API_KEY) model = sdk.models.completions("yandexgpt") # Синхронно result = model.configure(temperature=0.5).run("Розкажи про Москву") # Async result = await model.configure(temperature=0.5).run_async("Запит") # Streaming for event in model.configure(temperature=0.5).run_stream("Довгий запит"): print(event.alternatives[0].text, end="") 

Налаштування моделі: параметри та доступні варіанти

Детальніше про параметри — в офіційній документації Yandex Cloud.

Що таке ембеддинги Yandex і навіщо вони потрібні?

Ембеддинги Yandex — це векторні представлення тексту, що використовуються для семантичного пошуку та RAG. Два типи: text-search-doc для індексування документів та text-search-query для пошукових запитів. Приклад отримання:

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"] 

З практики: RAG-пайплайн для державного підприємства

Один із клієнтів — державне підприємство з жорсткими вимогами до локалізації даних. Ми розгорнули систему автоматичної відповіді на запити громадян. YandexGPT обрано через:

• дані не покидають РФ (152-ФЗ compliance);
• інтеграція з Yandex SpeechKit для голосового вводу;
• висока якість на російській мові.

Ми налаштували IAM-аутентифікацію, реалізували асинхронні запити та побудували RAG-пайплайн з ембеддингами Yandex і pgvector. Час відповіді знизився на 60%, а витрати на інфраструктуру — на 40% за рахунок оптимізації промптів та кешування. Економія на часі обробки запитів дозволила швидко окупити впровадження. Отримайте консультацію щодо вашого проєкту — оцінимо застосовність YandexGPT та спроектуємо архітектуру.

Процес роботи

1. Аналітика: аудит вашого проєкту, визначення сценаріїв використання YandexGPT.
2. Проектування: архітектура інтеграції, вибір моделі, налаштування безпеки.
3. Реалізація: написання коду, налаштування аутентифікації, інтеграція з існуючими сервісами.
4. Тестування: навантажувальне тестування, перевірка latency p99 та якості відповідей.
5. Деплой: розгортання в production, моніторинг, документація.

Строки орієнтовно

• Базова REST інтеграція: від 1 до 2 днів.
• SDK інтеграція з async/streaming: від 2 до 3 днів.
• Повний RAG-пайплайн з ембеддингами: від 1 до 2 тижнів.

Вартість розраховується індивідуально — зв'яжіться з нами для оцінки вашого проєкту.

Що входить в роботу

• Налаштований API-доступ з IAM-аутентифікацією.
• Готовий код інтеграції (REST/SDK) на Python.
• Документація з використання та підтримки.
• Навчання вашої команди роботі з YandexGPT.
• Технічна підтримка на етапі впровадження.

Які типові помилки допускають при інтеграції YandexGPT?

• Неправильне оновлення IAM-токена: токен живе 12 годин, його потрібно оновлювати автоматично.
• Ігнорування контекстного вікна: при довгих запитах обрізуйте історію.
• Відсутність обробки помилок: API може повертати 429 (rate limit) — реалізуйте retry з експоненційною затримкою.
• Неоптимальні промпти: для російської мови використовуйте чіткі інструкції та приклади (few-shot).

Наші сертифіковані інженери гарантують якість та SLA 99.9%. Зв'яжіться з нами для обговорення вашого проєкту — отримайте консультацію безкоштовно.