Использование по API

Модели вызываются через REST API сервиса foundationModels. Запрос - это HTTP POST с JSON-телом: какую модель взять, какие сообщения отправить и какие параметры генерации использовать. Авторизация - через заголовок с API-ключом или IAM-токеном.

Как указывается модель

Модель задаётся строкой-URI, в которую входит идентификатор вашего каталога. Для YandexGPT это выглядит так: gpt://<folder-id>/yandexgpt-lite (или другая версия модели вместо yandexgpt-lite). Подставьте свой folder-id из консоли.

Авторизация

В заголовке Authorization передаётся либо API-ключ как Api-Key <ключ>, либо IAM-токен как Bearer <токен>. Идентификатор каталога в ряде запросов также передают отдельным заголовком.

Запрос к YandexGPT: curl

curl -s \
  -H "Authorization: Api-Key ${YANDEX_API_KEY}" \
  -H "x-folder-id: ${YANDEX_FOLDER_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "modelUri": "gpt://'"${YANDEX_FOLDER_ID}"'/yandexgpt-lite",
    "completionOptions": { "temperature": 0.3, "maxTokens": 500 },
    "messages": [
      { "role": "system", "text": "Ты помощник. Отвечай кратко и по-русски." },
      { "role": "user", "text": "Объясни, что такое эмбеддинги, в трёх предложениях." }
    ]
  }' \
  https://llm.api.cloud.yandex.net/foundationModels/v1/completion

Здесь modelUri указывает на модель в вашем каталоге, messages - это диалог с ролями (system задаёт поведение, user - запрос), completionOptions управляет генерацией. Ответ приходит в JSON, текст лежит внутри поля с альтернативами.

Запрос к YandexGPT: Python

import os
import requests

API_KEY = os.environ["YANDEX_API_KEY"]
FOLDER_ID = os.environ["YANDEX_FOLDER_ID"]

url = "https://llm.api.cloud.yandex.net/foundationModels/v1/completion"
headers = {
    "Authorization": f"Api-Key {API_KEY}",
    "x-folder-id": FOLDER_ID,
    "Content-Type": "application/json",
}
payload = {
    "modelUri": f"gpt://{FOLDER_ID}/yandexgpt-lite",
    "completionOptions": {"temperature": 0.3, "maxTokens": 500},
    "messages": [
        {"role": "system", "text": "Ты помощник. Отвечай кратко и по-русски."},
        {"role": "user", "text": "Назови три применения LLM в поддержке клиентов."},
    ],
}

resp = requests.post(url, headers=headers, json=payload, timeout=60)
resp.raise_for_status()
data = resp.json()
print(data["result"]["alternatives"][0]["message"]["text"])

Ключ и идентификатор каталога берутся из переменных окружения YANDEX_API_KEY и YANDEX_FOLDER_ID - так секрет не попадает в код.

Эмбеддинги (кратко)

Для эмбеддингов используется отдельная модель (URI вида emb://<folder-id>/...) и свой endpoint textEmbedding. Запрос принимает текст и возвращает вектор чисел. Эти векторы складывают в векторную базу и потом ищут похожие фрагменты для RAG и семантического поиска.

YandexART (кратко)

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