Связаться с намиПодключиться

Yandex Cloud ML SDK

Статья создана
Обновлена 20 ноября 2025 г.

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

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

Полный перечень поддерживаемых функций, исходный код библиотеки и примеры использования доступны на 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 — в форме строки можно передать:

      SDK автоматически определит тип аутентификационных данных.

    • Объект одного из следующих классов:

      • APIKeyAuth — позволяет явно задать аутентификацию по передаваемому API-ключу.
        Например: auth = APIKeyAuth('<api_ключ>').

      • EnvIAMTokenAuth — позволяет явно задать аутентификацию по IAM-токену, заданному в переменной окружения YC_TOKEN или любой другой.
        Например: auth = EnvIAMTokenAuth() или auth = EnvIAMTokenAuth("env_var").

        SDK при каждом запросе заново получает IAM-токен из этой переменной окружения, поэтому вы можете вне SDK самостоятельно периодически обновлять IAM-токен в переменной окружения. Этот вариант аутентификации является оптимальным для использования с сервисным агентом в Yandex DataSphere, если для этого сервиса включен доступ к другим ресурсам в облаке пользователя.

      • IAMTokenAuth — позволяет явно задать аутентификацию по передаваемому IAM-токену.
        Например: auth = IAMTokenAuth('<iam_токен>').

      • MetadataAuth — позволяет явно задать аутентификацию от имени сервисного аккаунта, заданного в метаданных виртуальной машины Yandex Compute Cloud.
        Например: auth = MetadataAuth().

      • NoAuth — позволяет указать, что аутентификационные данные не будут передаваться.
        Например: auth = NoAuth().

      • OAuthTokenAuth — позволяет явно задать аутентификацию по передаваемому OAuth-токену.
        Например: auth = OAuthTokenAuth('<oauth_токен>').

      • YandexCloudCLIAuth — позволяет явно задать аутентификацию от имени пользователя или сервисного аккаунта, заданного в профиле Yandex Cloud CLI на компьютере пользователя.
        Например: auth = YandexCloudCLIAuth().

      Эти классы вы можете получить, импортировав из библиотеки 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=}')

Где:

Результат:

  1. Переменная 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')

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

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

  3. Поле result.alternatives[0].role содержит одно из значений роли отправителя сообщения:

    • user — предназначена для отправки пользовательских сообщений к модели.
    • system — позволяет задать контекст запроса и определить поведение модели.
    • assistant — используется для ответов, которые генерирует модель.
    assistant

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

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

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

  5. Поле result.alternatives[0].status содержит статус сообщения. Возможные значения статуса:

    • UNSPECIFIED — статус не определен.
    • PARTIAL — часть сгенерированного текста, который может измениться в ходе дальнейшей генерации.
    • TRUNCATED_FINAL — итоговый сгенерированный текст, но результат превышает установленные ограничения.
    • FINAL — итоговый сгенерированный текст в пределах установленных ограничений.
    • CONTENT_FILTER — генерация остановлена из-за наличия конфиденциальных данных или этически ненадлежащих тем в промпте или сгенерированном тексте.
    AlternativeStatus.FINAL: 3

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

Предыдущая
Совместимость с OpenAI
Следующая
Overview