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 автоматически попытается выбрать один из вариантов аутентификации в следующем порядке:-
Если задана переменная окружения
YC_API_KEY
, для аутентификации будет использован указанный в ней API-ключ. -
Если задана переменная окружения
YC_IAM_TOKEN
, для аутентификации будет использован указанный в ней IAM-токен. -
Если задана переменная окружения
YC_OAUTH_TOKEN
, для аутентификации будет использован переданный в ней OAuth-токен. -
Если такие переменные окружения не заданы, SDK попытается выполнить аутентификацию по IAM-токену сервисного аккаунта, заданного в метаданных виртуальной машины.
-
Если задана переменная окружения
YC_TOKEN
, для аутентификации будет использован указанный в ней IAM-токен.SDK при каждом запросе заново получает IAM-токен из этой переменной окружения, поэтому вы можете вне SDK самостоятельно периодически обновлять IAM-токен в переменной окружения
YC_TOKEN
. -
Если предыдущие варианты не сработали, 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=}')
Результат:
-
Переменная
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.