Урок 2: YandexGPT API — Работа с Yandex Cloud

Чему вы научитесь

• Регистрироваться в Yandex Cloud и создавать платёжный аккаунт
• Получать бесплатный грант для экспериментов
• Работать с IAM-токенами и их автообновлением
• Отправлять REST API запросы к YandexGPT
• Использовать удобный Python SDK (yandexgpt-python)
• Выбирать между REST и gRPC для вашего приложения
• Работать с embeddings для RAG-систем
• Сравнивать модели YandexGPT 5 Lite, YandexGPT 5 Pro и YandexGPT 5.1 Pro

Содержание

Шаг 1: Регистрация в Yandex Cloud

YandexGPT — LLM от Яндекса, популярна в России благодаря интеграции с экосистемой Яндекса и хорошей поддержке на русском.

Чтобы начать:

1. Перейдите на console.yandex.cloud
2. Нажмите «Зарегистрироваться» (используйте Яндекс аккаунт или почту)
3. Создайте новую организацию или выберите существующую
4. Перейдите в раздел «Платёжные аккаунты» → «Создать аккаунт»
5. Выберите реквизиты (для ИП или организации)
6. Привяжите способ оплаты (карта или счёт)

Раздел будет дополнен после получения материалов от партнёров (детали по грантам и промокодам).

Шаг 2: Создание сервисного аккаунта и получение IAM-токена

Для работы с API нужен IAM-токен. Его можно получить несколькими способами:

Способ 1: Через облачную консоль

1. Перейдите «Управление доступом» → «Сервисные аккаунты»
2. Нажмите «Создать сервисный аккаунт»
3. Задайте имя, например yandexgpt-bot
4. Нажмите «Создать и продолжить»
5. Выдайте роль ai.models.user (чтобы вызывать API)
6. Нажмите «Продолжить» → «Готово»

Способ 2: Создание API-ключа (более простой для разработки)

1. В списке сервисных аккаунтов найдите только что созданный
2. Нажмите на его имя
3. Перейдите на вкладку «API ключи»
4. Нажмите «Создать новый ключ»
5. Скопируйте содержимое и сохраните в файл key.json

Шаг 3: Получение IAM-токена

import requests
import json
import os
from datetime import datetime, timedelta

class YandexGPTAuth:
    def __init__(self, api_key_path):
        """
        api_key_path: путь к файлу key.json из Yandex Cloud
        """
        with open(api_key_path, 'r') as f:
            self.api_key = json.load(f)

        self.access_token = None
        self.token_expires = None
        self.service_account_id = self.api_key.get('service_account_id')

    def get_iam_token(self):
        """Получить новый IAM-токен"""
        url = "https://iam.api.cloud.yandex.net/iam/v1/tokens"

        data = {
            "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
            "requested_token_use": "access",
            "subject_token": self._create_jwt(),
            "subject_token_type": "urn:ietf:params:oauth:token-type:jwt"
        }

        response = requests.post(url, data=data)

        if response.status_code == 200:
            result = response.json()
            self.access_token = result["access_token"]
            self.token_expires = datetime.now() + timedelta(
                seconds=result["expires_in"] - 60  # Обновляем за минуту до истечения
            )
            return self.access_token
        else:
            raise Exception(f"Ошибка получения токена: {response.text}")

    def _create_jwt(self):
        """JWT создание — раздел будет дополнен после получения материалов"""
        # В production используйте библиотеку yandex-cloud
        pass

    @property
    def token(self):
        """Получить актуальный токен (с автообновлением)"""
        if not self.access_token or datetime.now() >= self.token_expires:
            self.get_iam_token()
        return self.access_token

Упрощённый способ: используйте готовую библиотеку (см. Шаг 5).

flowchart LR
  A["Сервисный аккаунт"] --> B["JWT подпись"]
  B --> C["Yandex Auth"]
  C --> D["IAM токен (12ч)"]
  D --> E["YandexGPT API"]

Шаг 4: REST API запрос к YandexGPT

import requests

ACCESS_TOKEN = "ваш_iam_токен"
FOLDER_ID = "ваш_folder_id"  # Из Yandex Cloud консоли

headers = {
    "Authorization": f"Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json"
}

# Параметры для REST API
url = "https://llm.api.cloud.yandex.net/foundationModels/v1/completion"

payload = {
    "modelUri": f"gpt://{FOLDER_ID}/yandexgpt-pro-5.1",  # или yandexgpt-pro-5, yandexgpt-lite-5; совместимость с OpenAI API тоже поддерживается
    "completionOptions": {
        "stream": False,
        "temperature": 0.7,
        "maxTokens": "256"
    },
    "messages": [
        {
            "role": "user",
            "text": "Объясни, что такое машинное обучение, очень просто"
        }
    ]
}

response = requests.post(url, headers=headers, json=payload)

if response.status_code == 200:
    result = response.json()
    message = result["result"]["alternatives"][0]["message"]["text"]
    print(f"[AI] YandexGPT: {message}")
else:
    print(f"[-] Ошибка: {response.status_code}")
    print(response.text)

Шаг 5: Python SDK — удобный способ

YandexGPT теперь поддерживает OpenAI-совместимый API. Это самый простой способ работы:

pip install openai  # стандартный openai SDK

from openai import OpenAI

client = OpenAI(
    api_key="<IAM-токен или API-ключ>",
    base_url="https://llm.api.cloud.yandex.net/v1"
)

def chat_with_yandexgpt(folder_id, prompt, model="yandexgpt-pro-5.1"):
    """Простой чат с YandexGPT через OpenAI-совместимый API"""
    response = client.chat.completions.create(
        model=f"gpt://{folder_id}/{model}",
        messages=[{"role": "user", "content": prompt}],
        temperature=0.7,
        max_tokens=256
    )
    return response.choices[0].message.content

# Использование
result = chat_with_yandexgpt(
    folder_id="your_folder_id",
    prompt="Напиши короткий стишок про Python"
)
print(result)

Также доступна интеграция через LangChain и LlamaIndex (см. ниже).

Рекомендация: Для разработки используйте OpenAI-совместимый REST (проще и переносимее), для production с высокой нагрузкой — gRPC (быстрее).

Шаг 6: Сравнение моделей YandexGPT

Актуальная линейка на 2025–2026 годы — YandexGPT 5 (с августа 2025 доступна YandexGPT 5.1 Pro). Модель YandexGPT RC упразднена.

YandexGPT 5.1 Pro — лучшая модель Яндекса для работы с текстом и точных ответов по базам знаний. Стоимость снижена в 3 раза относительно предыдущего флагмана.

Шаг 7: Embeddings для RAG-систем

YandexGPT также предоставляет модель для векторизации текста (embeddings). Это нужно для RAG (Retrieval Augmented Generation):

import requests

def get_embeddings(text, folder_id, access_token):
    """Получить вектор для текста"""

    url = "https://llm.api.cloud.yandex.net/foundationModels/v1/textEmbedding"

    headers = {
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json"
    }

    payload = {
        "modelUri": f"emb://{folder_id}/text-search-query/latest",  # Для запросов
        "text": text
    }

    response = requests.post(url, headers=headers, json=payload)

    if response.status_code == 200:
        embedding = response.json()["embedding"]
        return embedding  # Список из 256 чисел (text-search-query) или 256 (text-search-doc)
    else:
        raise Exception(f"Ошибка embeddings: {response.text}")

# Пример: закодировать документ
doc_text = "Python — это язык программирования высокого уровня"
embedding = get_embeddings(doc_text, folder_id, access_token)
print(f"[+] Вектор размером {len(embedding)} измерений")
print(f"Первые 5 значений: {embedding[:5]}")

Как это используется в RAG:

1. Закодируйте все документы в базе → сохраните векторы в векторной БД (Pinecone, Milvus, Weaviate)
2. На запрос пользователя → закодируйте его запрос в вектор
3. Найдите K похожих документов (по близости векторов)
4. Передайте их контекст в prompt для GigaChat или YandexGPT

Шаг 8: REST vs gRPC — когда что использовать

graph TD
    A[Нужен API для YandexGPT]
    A -->|Экспериментирую,<br/>прототипирую| B[REST API]
    A -->|Production,<br/>высокая нагрузка| C[gRPC]
    B --> D["[+] Проще отладить<br/>[+] HTTP, curl<br/>[+] Медленнее<br/>[-] Больше overhead"]
    C --> E["[+] Быстро<br/>[+] Бинарный протокол<br/>[-] Сложнее отладить<br/>[-] Требует компиляции proto"]

Попробуйте сами

Установите зависимости:

pip install requests yandex-cloud

Создайте файл config.py:

import os
from dotenv import load_dotenv

load_dotenv()

YANDEX_API_KEY_PATH = os.getenv("YANDEX_API_KEY_PATH")
FOLDER_ID = os.getenv("FOLDER_ID")

Напишите полный пример:

import requests
import json
import os
from config import FOLDER_ID

class YandexGPTClient:
    def __init__(self, folder_id, api_key_path):
        self.folder_id = folder_id
        self.api_key_path = api_key_path
        self.access_token = None
        self._get_token()

    def _get_token(self):
        """Получение токена через JWT — см. документацию Yandex Cloud"""
        # Временно используем токен из переменной окружения
        self.access_token = os.getenv("YANDEX_ACCESS_TOKEN")

    def complete(self, prompt, model="yandexgpt-pro-5.1"):
        """Получить ответ от модели"""

        url = "https://llm.api.cloud.yandex.net/foundationModels/v1/completion"

        headers = {
            "Authorization": f"Bearer {self.access_token}",
            "Content-Type": "application/json"
        }

        payload = {
            "modelUri": f"gpt://{self.folder_id}/{model}",
            "completionOptions": {
                "stream": False,
                "temperature": 0.7,
                "maxTokens": "256"
            },
            "messages": [
                {
                    "role": "user",
                    "text": prompt
                }
            ]
        }

        response = requests.post(url, headers=headers, json=payload)

        if response.status_code == 200:
            return response.json()["result"]["alternatives"][0]["message"]["text"]
        else:
            raise Exception(f"API Error: {response.status_code} - {response.text}")

    def embed(self, text):
        """Получить embedding для текста"""

        url = "https://llm.api.cloud.yandex.net/foundationModels/v1/textEmbedding"

        headers = {
            "Authorization": f"Bearer {self.access_token}",
            "Content-Type": "application/json"
        }

        payload = {
            "modelUri": f"emb://{self.folder_id}/text-search-query/latest",
            "text": text
        }

        response = requests.post(url, headers=headers, json=payload)

        if response.status_code == 200:
            return response.json()["embedding"]
        else:
            raise Exception(f"Embedding Error: {response.status_code}")

# Использование
client = YandexGPTClient(FOLDER_ID, "path/to/key.json")

# Простой чат
response = client.complete("Объясни рекурсию простыми словами")
print(f"Ответ: {response}")

# Embeddings
embedding = client.embed("Рекурсия — это когда функция вызывает сама себя")
print(f"Embedding размер: {len(embedding)}")

Задачи для упражнения:

1. Создайте клиент и отправьте запрос на русском
2. Сравните скорость ответов между yandexgpt-pro-5.1 и yandexgpt-lite-5
3. Закодируйте 3 разных текста и сравните их embeddings (какие ближе друг к другу?)
4. Попробуйте реализовать простой RAG: закодируйте 5 фактов, потом найдите 2 самых похожих на запрос

Ключевые выводы

[+] Запомните:

1. Yandex Cloud — надёжная инфраструктура, много интеграций с экосистемой Яндекса
2. IAM-токены автоматически обновляются; не забывайте проверять срок действия (12 часов)
3. OpenAI-совместимый API позволяет использовать стандартные библиотеки (openai, LangChain, LlamaIndex)
4. Embeddings — ключевой инструмент для RAG; модели text-search-doc/latest и text-search-query/latest (префикс emb://)
5. YandexGPT 5.1 Pro — флагман с августа 2025, лучший выбор для аналитики и работы с базами знаний
6. Function calling поддерживается у YandexGPT 5 Pro и Lite
7. Цены прозрачные в рублях: ~0,4 ₽ за 1K токенов (5.1 Pro, уточняйте в калькуляторе Yandex Cloud), снижены в 3 раза по сравнению с предыдущей версией

Дополнительные материалы:

• Официальная документация Yandex Cloud AI Studio
• Совместимость с OpenAI API
• Примеры на GitHub
• Калькулятор стоимости

Следующий урок

В Уроке 3: Интеграция с агентами мы объединим GigaChat и YandexGPT в один универсальный скрипт с fallback-логикой: если одна модель недоступна, автоматически переключимся на другую.

Также посмотрим, как интегрировать российские LLM в популярные платформы вроде n8n и Dify.