Как добавить YandexGPT в продукт

YandexGPT — модели от Яндекса, которые хорошо работают с русским языком и предоставляют удобный API с OpenAI-совместимым интерфейсом. Если у вас уже есть интеграция с OpenAI, переключиться на YandexGPT можно за несколько строк; если интеграции нет — это хороший повод сделать её сразу правильно. Ниже — практическое руководство: инфраструктура, способы интеграции, типичные задачи, ценообразование и пример реального пайплайна с агентом для ведения сделки.

Инфраструктура в Yandex Cloud

Прежде чем делать первый запрос к API, нужно подготовить облачное окружение. Это занимает 10–15 минут, но сделать один раз правильно — значит не возвращаться к этому при каждом новом сервисе.

Создание Folder и подключение Foundation Models

В Yandex Cloud ресурсы организованы по Folder (папкам) внутри облака. Folder — это единица изоляции: у неё собственные права доступа, квоты и история биллинга. Для каждого продукта или окружения рекомендуется создавать отдельный Folder.

1. Откройте консоль Yandex Cloud и создайте новый Folder (или выберите существующий).
2. В разделе AI Studio или Model Gallery включите сервис Foundation Models для нужного Folder — без этого шага API возвращает 403.
3. Зафиксируйте Folder ID — он нужен в каждом запросе к API для маршрутизации биллинга и прав.

Аутентификация

Для серверных интеграций доступны два способа аутентификации:

Для старта удобнее API Key: создаёте сервисный аккаунт, выдаёте ему роль ai.languageModels.user на Folder, генерируете ключ — и кладёте его в переменную окружения YANDEX_CLOUD_API_KEY. Folder ID — в YANDEX_CLOUD_FOLDER.

Выбор способа интеграции

YandexGPT предлагает два способа вызова модели. Выбор зависит от того, есть ли у вас уже обвязка под OpenAI SDK, и насколько вы хотите контролировать детали запроса.

A. OpenAI-совместимый API

Если в вашем проекте уже есть клиент под OpenAI — это самый быстрый путь. Меняете base_url и модель, добавляете параметр project с Folder ID — и всё остальное работает как прежде.

import openai
import os

YANDEX_CLOUD_API_KEY = os.environ["YANDEX_CLOUD_API_KEY"]
YANDEX_CLOUD_FOLDER  = os.environ["YANDEX_CLOUD_FOLDER"]

client = openai.OpenAI(
    api_key=YANDEX_CLOUD_API_KEY,
    base_url="https://ai.api.cloud.yandex.net/v1",
    project=YANDEX_CLOUD_FOLDER,
)

resp = client.responses.create(
    model="yandexgpt-lite",
    input=[
        {
            "role": "system",
            "content": "Ты помощник: отвечай кратко, структурно.",
        },
        {
            "role": "user",
            "content": (
                "Суммаризируй заявку клиента и выдели поля: "
                "компания, контакт, запрос."
            ),
        },
    ],
)

print(resp.output_text)

B. Нативный REST Foundation Models API

Прямой вызов эндпойнта генерации даёт полный контроль над параметрами запроса: температура, maxTokens, поддержка tool-calls согласно спецификации. Используйте этот вариант, если нужны возможности, которые OpenAI-совместимый интерфейс ещё не проксирует.

POST https://llm.api.cloud.yandex.net/foundationModels/v1/completion

Authorization: Api-Key <YANDEX_CLOUD_API_KEY>
Content-Type: application/json
x-folder-id: <YANDEX_CLOUD_FOLDER>

{
  "modelUri": "gpt://<FOLDER_ID>/yandexgpt-lite/latest",
  "completionOptions": {
    "stream": false,
    "temperature": 0.2,
    "maxTokens": 1000
  },
  "messages": [
    {
      "role": "system",
      "text": "Ты помощник: отвечай кратко, структурно."
    },
    {
      "role": "user",
      "text": "Суммаризируй заявку клиента и выдели поля: компания, контакт, запрос."
    }
  ]
}

Ответ приходит в поле result.alternatives[0].message.text. Для асинхронного режима — отдельный эндпойнт /foundationModels/v1/completionAsync, который возвращает operation_id, а результат получаете поллингом.

Какие задачи решает YandexGPT

YandexGPT — это языковая модель, а не бизнес-система. Она хорошо решает задачи с текстом как входом и выходом. Важно понимать эту границу: модель генерирует текст на основе контекста, она не имеет доступа к вашей БД и не «знает» про вашу предметную область — пока вы не дадите ей контекст в промпте.

Генерация текста

Ответы клиенту, письма, инструкции, сценарии разговоров, краткие резюме — всё, где нужен качественный русскоязычный текст по заданным параметрам. YandexGPT заметно лучше справляется с нюансами русского языка: склонения, падежи, стиль деловой переписки.

Структурирование входящих данных

Превращение «потока текста» в структурированный формат — одна из самых ценных задач. Клиент пишет заявку в свободной форме; модель извлекает из неё поля: компания, контакт, услуга, дедлайн, бюджет — и возвращает JSON. Это заменяет регулярные выражения и ручной разбор там, где структура варьируется.

Классификация

Prompt-based классификация: маршрутизация обращений по типу, проставление тегов, определение приоритета и тона. Не требует файн-тюнинга — достаточно хорошего промпта с примерами (few-shot). Работает точнее жёстких правил на нестандартных формулировках.

Работа с длинным контекстом

YandexGPT Pro заявляет контекст до 32 000 токенов. Это позволяет передавать в промпт длинные переписки, договоры, технические задания целиком — без фрагментации и потери связности. Для сложных кейсов это принципиально: модель видит полную картину, а не кусок.

Стоимость: токены, агенты, оценка

Ценообразование в AI Studio — по токенам (вход и выход считаются отдельно). Инструменты агентов тарифицируются отдельно. Ниже — актуальные цены без НДС.

Текстовая генерация

Инструменты агентов

Грубая оценка стоимости одного шага диалога

Допустим, один шаг агента — это ~800 input-токенов (системный промпт + история + входящее сообщение) и ~300 output-токенов (ответ модели). На YandexGPT Lite в синхронном режиме:

Input:  0.8 × $0.001639 ≈ $0.00131
Output: 0.3 × $0.001639 ≈ $0.00049
—————————————————————
Итого за шаг:          ≈ $0.0018

1 000 шагов диалога — около $1.80. Для продукта с сотнями пользователей в день это вполне управляемая статья расходов. При переходе на Pro — умножайте примерно на 4.

Пример: агент для ведения сделки

Чтобы всё выше не осталось абстракцией — разберём конкретный пайплайн: текстовый агент, который ведёт лид/сделку от первого сообщения до пакета «готово к исполнителю». Такой агент собирает данные, проверяет комплектность, формирует артефакты и фиксирует следующий шаг.

Роль агента в процессе

Агент не заменяет менеджера по продажам. Он берёт на себя рутину: разбор входящего сообщения, ведение карточки сделки, запрос недостающих данных, подготовку черновиков. Менеджер видит готовую карточку и пакет документов — не сырой поток сообщений.

Что делает YandexGPT на каждом шаге

1. Разбор входящего сообщения (Telegram, почта, форма)

Первый промпт классифицирует сообщение и извлекает сущности. Системный промпт задаёт структуру вывода; пользовательское сообщение — это сырой текст заявки:

Системный промпт (упрощённо):

Ты — ассистент по обработке входящих заявок.

Задача: проанализируй сообщение и верни JSON:
{
  "type": "lead" | "question" | "change_request" | "problem",
  "entities": {
    "client_name": str | null,
    "company": str | null,
    "service": str | null,
    "deadline": str | null,
    "budget": str | null,
    "contact_channel": str | null,
    "documents_mentioned": list[str]
  },
  "confidence": float  // 0.0–1.0
}

Отвечай только валидным JSON, без пояснений.

Пользовательское сообщение (входящая заявка):

Добрый день! Мы ООО "Ромашка", ищем подрядчика для разработки CRM.
Бюджет — до 800 тысяч, нужно к 1 июня. Контакт — Иванов Сергей,
можно писать в Telegram @ivanov_s. Готовы предоставить ТЗ.

Модель возвращает структуру, которая сразу ложится в карточку сделки — не нужен ручной разбор.

2. Нормализация в карточку сделки

Второй промпт обновляет состояние карточки: какие поля заполнены, чего не хватает, что нужно запросить у клиента:

Системный промпт:

Ты ведёшь карточку сделки. Текущее состояние:
<state>{{ deal_state_json }}</state>

На основе нового сообщения обнови карточку и верни JSON:
{
  "stage": "new" | "data_collection" | "docs_requested" | "ready",
  "missing_fields": [...],
  "missing_docs": [...],
  "next_action": "Краткое описание следующего шага",
  "updated_fields": { ... }
}

3. Управление диалогом

Агент генерирует точечный запрос одного недостающего поля — не список из десяти вопросов сразу. Один шаг — один вопрос. После ответа клиента — обновление карточки и следующий запрос (если ещё что-то нужно) или подведение итогов:

Системный промпт:

На основе карточки сделки и списка missing_fields задай клиенту
один конкретный вопрос. Тон — деловой, вежливый, без лишних слов.
Не перечисляй все пропущенные поля — только один, наиболее важный.

4. Подготовка артефактов для исполнителя

Когда карточка заполнена, агент генерирует:

• Черновик письма-предложения или краткое ТЗ в форматированном тексте
• Протокол согласования: список решений, допущений, открытых вопросов
• Чек-лист комплектности: что запрошено, что получено, что ещё нужно

Минимальный стек: агентный цикл

# Псевдокод агентного цикла
def process_message(deal_id, new_message):
    deal    = db.get_deal(deal_id)       # Текущая карточка сделки
    history = db.get_history(deal_id)    # Последние N сообщений

    # Шаг 1: классификация + извлечение сущностей (дешёвая модель)
    parsed = yandex_gpt(
        system=CLASSIFY_PROMPT,
        user=new_message,
        model="yandexgpt-lite",
    )

    # Шаг 2: обновление карточки (Pro — нужен больший контекст)
    updated_deal = yandex_gpt(
        system=UPDATE_DEAL_PROMPT.format(state=deal.to_json()),
        user=parsed.to_json(),
        model="yandexgpt-pro",
    )

    db.update_deal(deal_id, updated_deal)

    # Шаг 3: запрос недостающих данных
    if updated_deal["stage"] != "ready":
        reply = yandex_gpt(
            system=NEXT_QUESTION_PROMPT,
            user=updated_deal.to_json(),
            model="yandexgpt-lite",
        )
        return reply

    # Шаг 4: артефакты для исполнителя
    artifacts = yandex_gpt(
        system=ARTIFACTS_PROMPT,
        user=updated_deal.to_json(),
        model="yandexgpt-pro",
    )
    db.save_artifacts(deal_id, artifacts)
    return "Сделка готова к передаче исполнителю."

Почему здесь YandexGPT "в тему"

Задача — чистая работа с текстом, контекстом, структурированием и контролем полноты. Никаких специфических вычислений или внешних данных. YandexGPT Pro с контекстом 32k токенов держит весь тред сделки целиком — не теряет контекст при длинных переговорах. Качество русскоязычного текста в деловом стиле — на уровне, который заметен клиентам.

Резюме

YandexGPT — рабочий выбор для продуктов, работающих с русскоязычным текстом. Интеграция через OpenAI-совместимый API занимает часы, не недели. Ниже — ключевые моменты, которые стоит учесть на старте.

• Инфраструктура: отдельный Folder на окружение, сервисный аккаунт с минимальными правами, API Key в переменных окружения.
• Способ интеграции: OpenAI-совместимый API — быстрый старт; нативный REST — когда нужен полный контроль над параметрами и поддержка tool-calls.
• Модель: Lite для простых задач (суммаризация, классификация, извлечение сущностей), Pro для длинного контекста и сложных генераций.
• Стоимость: Lite в синхронном режиме — около $0.0018 за один типичный шаг диалога. Считайте токены заранее, оптимизируйте промпты.
• Задачи: лучше всего работает там, где есть текст на входе и нужен структурированный или сформулированный текст на выходе.
• Пайплайн: разбивайте агента на маленькие специализированные шаги (классификация → обновление карточки → запрос → артефакты). Один промпт — одна задача.
• Fallback: обрабатывайте ошибки API явно; не давайте им утонуть в тихом сбое.