YandexGPT API на Python в 2026 году: без музейных примеров

Поиск по запросу «YandexGPT Python example» до сих пор приводит к коду с устаревшими именами пакетов, ручной сборкой model URI и API, которые уже получили замену. Такой пример может запускаться — и всё равно быть плохой точкой старта.

Актуальный официальный SDK называется yandex-ai-studio-sdk, а основной класс — AIStudio. Он объединяет Completions, OpenAI-compatible Chat, Streaming, Tool Calling, Embeddings, Text Classifiers, YandexART, Vision OCR, SpeechKit и Yandex Search API.

Что подготовить

· каталог Yandex Cloud и его folder_id;

· сервисный аккаунт с минимально необходимыми ролями;

· API Key или другой поддерживаемый SDK способ аутентификации;

· Python 3 и переменные окружения — секрет не должен лежать в репозитории.

export YC_FOLDER_ID="..."
export YC_API_KEY="..."
pip install yandex-ai-studio-sdk

API Key не делает приложение безопасным. Ограничьте роли сервисного аккаунта, разделяйте ключи dev/prod, задайте бюджеты и никогда не отправляйте ключ в браузер.

Минимальный YandexGPT API example

import os
from yandex_ai_studio_sdk import AIStudio

sdk = AIStudio(
    folder_id=os.environ["YC_FOLDER_ID"],
    auth=os.environ["YC_API_KEY"],
)

model = sdk.models.completions("yandexgpt").configure(
    temperature=0.2,
)

result = model.run(
    "Объясни клиенту разницу между оплатой по факту и предоплатой. "
    "Не придумывай условия договора. Ответ — до 500 знаков."
)

for alternative in result:
    print(alternative)

Это код из текущей логики официального SDK, а не обёртка над случайным REST-примером. Для production добавьте Timeout, обработку исключений, Request ID и журнал Usage.

Streaming: когда скорость ответа важнее полного текста

model = sdk.models.completions("yandexgpt").configure(temperature=0.2)

for event in model.run_stream("Составь краткий план миграции API"):
    print(event, flush=True)

Streaming уменьшает воспринимаемую задержку, но не общую стоимость. Не сохраняйте каждый частичный фрагмент как отдельный ответ: финальное событие и Usage должны быть связаны одним Request ID.

YandexGPT Lite или Pro в коде приложения

Не разбрасывайте Model ID по бизнес-коду. Создайте профили:

MODEL_PROFILES = {
    "fast": {"model": "yandexgpt-lite", "temperature": 0.1},
    "deep": {"model": "yandexgpt", "temperature": 0.2},
}

def get_model(profile: str):
    cfg = MODEL_PROFILES[profile]
    return sdk.models.completions(cfg["model"]).configure(
        temperature=cfg["temperature"]
    )

Конкретные идентификаторы и доступные версии проверяйте в разделе Yandex Cloud AI Studio models: они меняются быстрее, чем архитектура приложения.

Tool Calling: модель предлагает, код решает

Function Calling не означает, что YandexGPT сама вызывает вашу CRM. Модель возвращает имя функции и аргументы; приложение валидирует их, проверяет права и только затем исполняет Tool.

def get_order_status(order_id: str) -> dict:
    # Здесь проверка доступа и вызов реальной системы.
    return {"order_id": order_id, "status": "ready"}

# Регистрируем Function Tool по схеме SDK.
# После ответа проверяем result.tool_calls,
# исполняем только разрешённую функцию
# и возвращаем результат в историю модели.

Мы намеренно не скрываем цикл за магической функцией: Tool Calling состоит минимум из двух модельных вызовов и одного контролируемого действия приложения.

OpenAI-compatible Chat: зачем он нужен

Официальный SDK предоставляет sdk.chat для OpenAI-compatible Chat, включая Streaming, Tool Calls и Text Embeddings. Это полезно, если приложение уже построено вокруг ролей system, user, assistant и стандартного Chat-контракта.

Совместимость не означает полную идентичность провайдеров. Перед миграцией проверьте параметры, Structured Output, Tool Calling, Usage и ошибки Rate Limit.

Responses API и старые Assistants

В текущем официальном SDK домены Assistants, Threads, Runs и Messages удалены; документация направляет пользователей на миграцию к Responses API. Это важный маркер свежести статьи: новый проект не стоит строить на старой Assistants-архитектуре только потому, что найденный Tutorial всё ещё индексируется.

REST или SDK

Как добавить внешний Fallback

Технический Fallback запускается на Timeout, Rate Limit или временной недоступности, а не потому, что текст «не понравился». Внешняя модель должна соответствовать тому же Policy Class: данным, контексту, Tool Calls и минимальному Eval.

Через OdiRouter.ai можно подключить внешние модели по OpenAI-compatible API и оставить YandexGPT основным маршрутом. В коде бизнес-логика обращается к профилю, а не к бренду:

try:
    return yandex_route(messages)
except TransientProviderError:
    return compatible_fallback(messages, policy="ru_business_text")

Production-checklist

1. API Key хранится в Secret Manager, а не в Git.

2. Service Account имеет минимальные роли.

3. Есть Timeout, retry с backoff и лимит повторов.

4. Логируются Request ID, модель, версия, Token и задержка.

5. Prompt и ответы не попадают в журнал без политики данных.

6. Streaming корректно завершается при отключении клиента.

7. Tool Call валидируется и авторизуется вне модели.

8. Новая версия модели проходит Eval до переключения.

YandexGPT интеграция на Python сегодня начинается не с копирования старого cURL. Она начинается с текущего Yandex AI Studio SDK, правильной аутентификации и ясного контракта между моделью и приложением.

Пять строк вызывают модель. Production начинается со всего, что происходит вокруг них: секреты, Timeout, Tool Policy, Streaming, Eval и контролируемый Fallback.