YandexGPT за 30 минут: пошаговое руководство от первого запроса до интеграции

Нейросетевые языковые модели перестали быть экзотикой и стали рабочим инструментом для разработчиков, аналитиков и контент-менеджеров. YandexGPT — мощная LLM от Яндекса, доступная через Yandex Cloud, предлагает российским разработчикам и компаниям альтернативу с низкой задержкой и удобной интеграцией в экосистему. Если у вас есть полчаса, вы можете пройти путь от нуля до работающего прототипа. Это руководство покажет вам, как это сделать.

Шаг 0: Предварительные условия (2 минуты). Вам понадобится аккаунт в Yandex Cloud. Если его нет, зарегистрируйтесь на cloud.yandex.ru. После регистрации необходимо создать платежный аккаунт (для начала работы предоставляется начальный грант). Также вам потребуется установленная на компьютер среда для выполнения HTTP-запросов: Postman, Insomnia, или просто готовность использовать терминал с curl.

Шаг 1: Создание сервисного аккаунта и получение IAM-токена (5 минут). Безопасное взаимодействие с API Yandex Cloud происходит через сервисные аккаунты. В консоли управления перейдите в раздел «Сервисные аккаунты» и создайте новый, например, с именем `gpt-integration-sa`. Запомните его ID. Теперь этому аккаунту нужно назначить роль `ai.languageModels.user` на каталог, в котором вы работаете. Это можно сделать через вкладку «Права доступа» каталога.

Далее вам нужен IAM-токен для аутентификации. Самый простой способ для тестирования — получить его через CLI Yandex Cloud. Установите его, если не установлен, и выполните команду `yc iam create-token`. Токен будет выведен в консоль. Скопируйте его — это ваш ключ к API. Для продакшена следует использовать авторизованные ключи сервисного аккаунта.

Шаг 2: Знакомство с API и первый запрос (8 минут). YandexGPT предоставляет два основных endpoint’а: для асинхронных задач и для синхронных запросов. Для начала используем синхронный: `https://llm.api.cloud.yandex.net/foundationModels/v1/completion`. Откройте ваш HTTP-клиент (например, Postman). Создайте новый POST-запрос на этот URL. Во вкладке «Headers» добавьте два заголовка: `Authorization: Bearer ` и `Content-Type: application/json`.

Теперь тело запроса (body). Минимальный рабочий JSON выглядит так:
{
 "modelUri": "gpt:///yandexgpt-lite",
 "completionOptions": {
 "stream": false,
 "temperature": 0.6,
 "maxTokens": "2000"
 },
 "messages": [
 {
 "role": "user",
 "text": "Привет! Напиши короткое приветствие для нового пользователя нашего приложения."
 }
 ]
}

Где взять `modelUri`? `yandexgpt-lite` — базовая модель. Идентификатор каталога можно найти в URL консоли управления или в свойствах каталога. Он выглядит как `b1gxxxxxxxxxxxxxx`. Таким образом, полный URI будет `gpt://b1gxxxxxxxxxxxxxx/yandexgpt-lite`.

Отправьте запрос. В ответе вы должны получить JSON с полем `result.alternatives[0].message.text`, содержащим сгенерированный текст. Поздравляем, вы только что пообщались с YandexGPT!

Шаг 3: Настройка параметров генерации (5 минут). Поэкспериментируйте с параметрами, чтобы управлять творчеством модели. `temperature` (от 0.0 до 1.0) контролирует случайность: чем выше, тем более креативным и неожиданным будет ответ. Для задач с однозначным ответом (классификация, извлечение фактов) используйте низкие значения (~0.1). Для творческих задач — высокие (~0.8). `maxTokens` ограничивает длину ответа. Один токен — это примерно 3/4 слова. Будьте экономны, чтобы контролировать стоимость. `stream: true` позволит получать ответ потоком, по частям, что полезно для создания интерактивных чат-интерфейсов.

Шаг 4: Построение диалога (контекста) (5 минут). Модель поддерживает историю сообщений в массиве `messages`. Это ключ к созданию осмысленного чата. Каждое сообщение имеет `role` (`"user"`, `"assistant"`, `"system"`) и `text`. `system` используется для задания поведения модели. Пример продвинутого контекста:
"messages": [
 { "role": "system", "text": "Ты полезный ассистент-эксперт по программированию. Отвечай кратко и по делу." },
 { "role": "user", "text": "Как объявить функцию на Python?" },
 { "role": "assistant", "text": "Функция объявляется с помощью ключевого слова def. Например: def my_function(arg):" },
 { "role": "user", "text": "А как добавить аргумент по умолчанию?" }
]
Модель будет помнить всю историю и ответит, учитывая предыдущие реплики.

Шаг 5: Простая интеграция в код на Python (5 минут). Давайте автоматизируем вызов. Установите библиотеку requests: `pip install requests`. Создайте файл `yandex_gpt_client.py`.

import requests
import json

IAM_TOKEN = "ваш_токен_здесь"
FOLDER_ID = "ваш_идентификатор_каталога_здесь"

def ask_yandex_gpt(prompt):
 url = "https://llm.api.cloud.yandex.net/foundationModels/v1/completion"
 headers = {
 "Authorization": f"Bearer {IAM_TOKEN}",
 "Content-Type": "application/json"
 }
 data = {
 "modelUri": f"gpt://{FOLDER_ID}/yandexgpt-lite",
 "completionOptions": {
 "stream": False,
 "temperature": 0.7
 },
 "messages": [{"role": "user", "text": prompt}]
 }
 response = requests.post(url, headers=headers, json=data)
 if response.status_code == 200:
 result = response.json()
 return result['result']['alternatives'][0]['message']['text']
 else:
 return f"Ошибка: {response.status_code}, {response.text}"

if __name__ == "__main__":
 answer = ask_yandex_gpt("Объясни, что такое API, одним предложением.")
 print(answer)

Запустите скрипт. Вы получите ответ модели. Не забудьте никогда не коммитить IAM-токен в публичный репозиторий! Используйте переменные окружения.

Что дальше? За оставшиеся минуты вы можете изучить возможности асинхронного API для длинных задач, ознакомиться с лимитами и тарификацией в Yandex Cloud, а также подумать о кэшировании частых запросов для экономии средств. YandexGPT — это мощный инструмент, и теперь вы знаете базовый способ его использования. От прототипа до продакшена путь недолог: замените получение токена на более безопасный метод (через метаданные ВМ или с помощью API-ключей), добавьте обработку ошибок и логирование, и ваше приложение станет «умнее» уже сегодня.