Yandex Cloud ML SDK

Статья создана

Обновлена 27 мая 2025 г.

Установка
Аутентификация в Yandex Cloud ML SDK
Использование

Yandex Cloud AI Studio предоставляет библиотеку инструментов и примеров готового кода для разработки продуктов на языке Python — Yandex Cloud ML SDK. ML SDK обеспечивает стандартизированный способ взаимодействия с фундаментальными моделями и упрощает интеграцию с другими сервисами Yandex Cloud.

Библиотека ML SDK реализует синхронный и асинхронный интерфейсы Python на основе gRPC-вызовов API сервисов AI Studio. В ML SDK доступны следующие возможности:

генерация текста с помощью всех поддерживаемых моделей;
работа с эмбеддингами;
работа с классификаторами на базе YandexGPT;
создание AI-ассистентов;
генерация изображений от YandexART;
дообучение моделей генерации текста и классификаторов;
интеграция с LangСhain.

Полный перечень поддерживаемых функций, исходный код библиотеки и примеры использования доступны на GitHub.

Установка

Установить библиотеку ML SDK можно с помощью менеджера пакетов pip:

pip install yandex-cloud-ml-sdk

Аутентификация в Yandex Cloud ML SDK

Аутентификация в Yandex Cloud ML SDK выполняется путем передачи в модель объекта YCloudML, который содержит поля:

folder_id — идентификатор каталога, в котором вы будете работать с моделями.
auth — ключ, токен или другие данные для аутентификации, позволяющие идентифицировать субъекта. Значение поля auth может быть задано явно или получено автоматически из окружения:
Значение задано явно

Значение получено из окружения
Заданное явно значение поля auth может принимать одно из значений:
- string — в форме строки можно передать:
  - IAM-токен пользовательского или сервисного аккаунта;
  - секретную часть API-ключа сервисного аккаунта;
  - OAuth-токен пользовательского аккаунта.
  SDK автоматически определит тип аутентификационных данных.
- Объект одного из следующих классов:
  - APIKeyAuth — позволяет явно задать аутентификацию по передаваемому API-ключу. Например: auth = APIKeyAuth('<API_ключ>').
  - IAMTokenAuth — позволяет явно задать аутентификацию по передаваемому IAM-токену. Например: auth = IAMTokenAuth('<IAM-токен>').
  - OAuthTokenAuth — позволяет явно задать аутентификацию по передаваемому OAuth-токену. Например: auth = OAuthTokenAuth('<OAuth-токен>').
  - MetadataAuth — позволяет явно задать аутентификацию от имени сервисного аккаунта, заданного в метаданных виртуальной машины Yandex Compute Cloud. Например: auth = MetadataAuth().
  - EnvIAMTokenAuth — позволяет явно задать аутентификацию по IAM-токену, заданному в переменной окружения YC_TOKEN или любой другой. Например: auth = EnvIAMTokenAuth() или auth = EnvIAMTokenAuth("ENV_VAR").
    
    SDK при каждом запросе заново получает IAM-токен из этой переменной окружения, поэтому вы можете вне SDK самостоятельно периодически обновлять IAM-токен в переменной окружения. Этот вариант аутентификации является оптимальным для использования с сервисным агентом в Yandex DataSphere, если для этого сервиса включен доступ к другим ресурсам в облаке пользователя.
  - YandexCloudCLIAuth — позволяет явно задать аутентификацию от имени пользователя или сервисного аккаунта, заданного в профиле Yandex Cloud CLI на компьютере пользователя. Например: auth = YandexCloudCLIAuth().
  - NoAuth — позволяет указать, что аутентификационные данные не будут передаваться. Например: auth = NoAuth().
  Эти классы вы можете получить, импортировав из библиотеки ML SDK. Например:
  from yandex_cloud_ml_sdk.auth import APIKeyAuth
Если поле auth явно не задано, то SDK автоматически попытается выбрать один из вариантов аутентификации в следующем порядке:
1. Если задана переменная окружения YC_API_KEY, для аутентификации будет использован указанный в ней API-ключ.
2. Если задана переменная окружения YC_IAM_TOKEN, для аутентификации будет использован указанный в ней IAM-токен.
3. Если задана переменная окружения YC_OAUTH_TOKEN, для аутентификации будет использован переданный в ней OAuth-токен.
4. Если такие переменные окружения не заданы, SDK попытается выполнить аутентификацию по IAM-токену сервисного аккаунта, заданного в метаданных виртуальной машины.
5. Если задана переменная окружения YC_TOKEN, для аутентификации будет использован указанный в ней IAM-токен.
  
  SDK при каждом запросе заново получает IAM-токен из этой переменной окружения, поэтому вы можете вне SDK самостоятельно периодически обновлять IAM-токен в переменной окружения YC_TOKEN.
6. Если предыдущие варианты не сработали, SDK попытается выполнить аутентификацию по IAM-токену пользователя или сервисного аккаунта, заданного в профиле Yandex Cloud CLI на компьютере пользователя.
Примечание

Время жизни IAM-токена — не более 12 часов. Учитывайте это, выполняя запросы с аутентификацией по IAM-токену, заданному в строке, объекте класса IAMTokenAuth или переменной окружения YC_IAM_TOKEN.

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

В качестве входных данных для запроса ML SDK может принимать:

Строку. Например: Что такое небо?.
Словарь — структуру данных, аналогичную JSON. Например: {"role": "role", "text": "text"}.
Объект класса TextMessage ML SDK. Например: result[0].

Объект result класса TextMessage представляет собой массив альтернатив, содержащихся в ответах модели. С помощью такого объекта можно передать предыдущий ответ модели в последующем запросе.
Массив, содержащий любое сочетание указанных выше типов данных. Например: ["text", {"role": "role", "text": "text"}].

Пример ниже отправит в модель YandexGPT Pro запрос c промтом в форме строки «Что такое небо?».

from yandex_cloud_ml_sdk import YCloudML

sdk = YCloudML(
    folder_id="<идентификатор_каталога>",
    auth="<аутентификационные_данные>",
)

model = sdk.models.completions("yandexgpt")
model = model.configure(temperature=0.5)
result = model.run("Что такое небо?")

print(f'{result=}')

print(f'{result[0]=}')

print(f'{result.alternatives[0].role=}')

print(f'{result.alternatives[0].text=}')

print(f'{result.alternatives[0].status=}')

Где:

folder_id — идентификатор каталога, в котором создан сервисный аккаунт.
auth — ключ, токен или другие данные для аутентификации, позволяющие идентифицировать субъекта.

Результат:

Переменная result содержит массив альтернатив, содержащихся в ответах модели:

GPTModelResult(alternatives=(Alternative(role='assistant', text='Небо — это пространство над поверхностью Земли или другой планеты, которое мы видим, когда смотрим вверх. Оно может быть ясным и безоблачным, облачным или пасмурным, а ночью на нём появляются звёзды, луна и другие небесные тела.\n\nТакже слово «небо» может использоваться в переносном смысле, обозначая не только физическое пространство, но и нечто возвышенное, идеальное или божественное.', status=<AlternativeStatus.FINAL: 3>),), usage=Usage(input_text_tokens=14, completion_tokens=83, total_tokens=97), model_version='23.10.2024')

Элемент массива result[0] содержит объект result.alternatives[0] класса TextMessage ML SDK, который в свою очередь содержит поля role, text и status:

Alternative(role='assistant', text='Небо — это пространство над поверхностью Земли или другой планеты, которое мы видим, когда смотрим вверх. Оно может быть ясным и безоблачным, облачным или пасмурным, а ночью на нём появляются звёзды, луна и другие небесные тела.\n\nТакже слово «небо» может использоваться в переносном смысле, обозначая не только физическое пространство, но и нечто возвышенное, идеальное или божественное.', status=<AlternativeStatus.FINAL: 3>)

Поле result.alternatives[0].role содержит одно из значений роли отправителя сообщения:
- user — предназначена для отправки пользовательских сообщений к модели.
- system — позволяет задать контекст запроса и определить поведение модели.
- assistant — используется для ответов, которые генерирует модель.
```
assistant
```

Поле result.alternatives[0].text содержит текст сообщения:

Небо — это пространство над поверхностью Земли или другой планеты, которое мы видим, когда смотрим вверх. Оно может быть ясным и безоблачным, облачным или пасмурным, а ночью на нём появляются звёзды, луна и другие небесные тела.

Также слово «небо» может использоваться в переносном смысле, обозначая не только физическое пространство, но и нечто возвышенное, идеальное или божественное.

Поле result.alternatives[0].status содержит статус сообщения. Возможные значения статуса:
- UNSPECIFIED — статус не определен.
- PARTIAL — часть сгенерированного текста, который может измениться в ходе дальнейшей генерации.
- TRUNCATED_FINAL — итоговый сгенерированный текст, но результат превышает установленные ограничения.
- FINAL — итоговый сгенерированный текст в пределах установленных ограничений.
- CONTENT_FILTER — генерация остановлена из-за наличия конфиденциальных данных или этически ненадлежащих тем в промте или сгенерированном тексте.
```
AlternativeStatus.FINAL: 3
```

Дополнительные примеры использования ML SDK см. в пошаговых инструкциях для Yandex Foundation Models.

Yandex Cloud ML SDK

УстановкаУстановка

Аутентификация в Yandex Cloud ML SDKАутентификация в Yandex Cloud ML SDK

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

Была ли статья полезна?

Установка

Аутентификация в Yandex Cloud ML SDK

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