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

Настройка доступа к Yandex Foundation Models с помощью API-ключа

Статья создана
Улучшена
Обновлена 21 апреля 2025 г.

Сервис Yandex Foundation Models является частью платформы Yandex Cloud и использует ее систему аутентификации и авторизации. Вы можете отправлять запросы к моделям Foundation Models от имени своего пользовательского аккаунта, используя IAM-токен для авторизации. Это наиболее безопасный способ для быстрых экспериментов, поскольку время жизни IAM-токена не превышает 12 часов. Однако для работы с API мы рекомендуем использовать сервисный аккаунт с API-ключом.

Чтобы настроить авторизацию с API-ключом от имени сервисного аккаунта:

  1. Подготовьте облако к работе.
  2. Создайте сервисный аккаунт.
  3. Назначьте роли сервисному аккаунту.
  4. Создайте API-ключ.

Подготовьте облако к работе

Зарегистрируйтесь в Yandex Cloud и создайте платежный аккаунт:

  1. Перейдите в консоль управления, затем войдите в Yandex Cloud или зарегистрируйтесь.
  2. На странице Yandex Cloud Billing убедитесь, что у вас подключен платежный аккаунт, и он находится в статусе ACTIVE или TRIAL_ACTIVE. Если платежного аккаунта нет, создайте его и привяжите к нему облако.

Если у вас есть активный платежный аккаунт, вы можете создать или выбрать каталог, в котором будет работать ваша инфраструктура, на странице облака.

Подробнее об облаках и каталогах.

Создайте сервисный аккаунт

  1. Войдите в консоль управления.

  2. В левой части экрана нажмите на строку с именем каталога, в котором вы хотите создать сервисный аккаунт.

  3. В списке сервисов выберите Identity and Access Management.

  4. Нажмите кнопку Создать сервисный аккаунт.

  5. Введите имя сервисного аккаунта.

    Требования к формату имени:

    • длина — от 2 до 63 символов;
    • может содержать строчные буквы латинского алфавита, цифры и дефисы;
    • первый символ — буква, последний — не дефис.

    Имя сервисного аккаунта должно быть уникальным в рамках облака.

  6. Нажмите кнопку Создать.

Если у вас еще нет интерфейса командной строки Yandex Cloud (CLI), установите и инициализируйте его.

По умолчанию используется каталог, указанный при создании профиля CLI. Чтобы изменить каталог по умолчанию, используйте команду yc config set folder-id <идентификатор_каталога>. Также для любой команды вы можете указать другой каталог с помощью параметров --folder-name или --folder-id.

Создайте сервисный аккаунт:

yc iam service-account create --name sa-api

Где --name — имя сервисного аккаунта в формате:

  • длина — от 2 до 63 символов;
  • может содержать строчные буквы латинского алфавита, цифры и дефисы;
  • первый символ — буква, последний — не дефис.

Результат:

id: ajehr0to1g8b********
folder_id: b1gv87ssvu49********
created_at: "2023-03-04T09:03:11.665153755Z"
name: sa-api

Создайте сервисный аккаунт с помощью метода REST API create для ресурса ServiceAccount:

curl \
  --request POST \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer <IAM-токен>" \
  --data '{
    "folderId": "<идентификатор_каталога>",
    "name": "<имя_сервисного_аккаунта>",
    "description": "service account for api"
  }' \
  https://iam.api.cloud.yandex.net/iam/v1/serviceAccounts

Где:

  • <IAM-токен> — действующий токен авторизации;

  • <идентификатор_каталога> — идентификатор каталога, в котором размещены сервисы;

  • <имя_сервисного_аккаунта> — имя сервисного аккаунта, например sa-api. Требования к формату имени:

    • длина — от 2 до 63 символов;
    • может содержать строчные буквы латинского алфавита, цифры и дефисы;
    • первый символ — буква, последний — не дефис.

Также сервисный аккаунт можно создать с помощью вызова gRPC ServiceAccountService/Create.

Назначьте роли сервисному аккаунту

  1. В консоли управления выберите нужное облако или каталог.

  2. Перейдите на вкладку Права доступа.

  3. Нажмите кнопку Настроить доступ.

  4. Выберите созданный сервисный аккаунт.

  5. Нажмите кнопку Добавить роль и выберите необходимые роли:

    • Для работы с моделями генерации текста добавьте роль ai.languageModels.user.
    • Для работы с моделями генерации изображений добавьте роль ai.imageGeneration.user.
    • Для создания датасетов и дообучения моделей добавьте роли ai.datasets.editor и ai.models.editor.
    • Для создания ассистента добавьте роль ai.assistants.editor.

    Вы можете назначить несколько ролей одновременно. Подробнее о ролях сервиса Foundation Models.

  6. Нажмите кнопку Сохранить.

Выполните команду:

yc resource-manager folder add-access-binding <идентификатор_каталога> \
   --role <идентификатор_роли> \
   --subject serviceAccount:<идентификатор_сервисного_аккаунта>

Где --role — роль для работы с Foundation Models:
* ai.languageModels.user — для работы с моделями генерации текста.
* ai.imageGeneration.user — для работы с моделями генерации изображений.
* ai.datasets.editor и ai.models.editor — для создания датасетов и дообучения моделей.
* ai.assistants.editor — для создания ассистента.

Подробнее о ролях сервиса Foundation Models.

Назначьте сервисному аккаунту роль с помощью метода REST API setAccessBindings для ресурса ServiceAccount:

curl \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer <IAM-токен>" \
  --data '{
    "accessBindingDeltas": [{
      "action": "ADD",
      "accessBinding": {
        "roleId": "<идентификатор_роли>",
        "subject": {
          "id": "<идентификатор_сервисного_аккаунта>",
          "type": "serviceAccount"
          }
        }
      }
    ]
   }' \
  https://resource-manager.api.cloud.yandex.net/resource-manager/v1/folders/<идентификатор_каталога>:updateAccessBindings

Где:

  • <IAM-токен> — действующий токен авторизации.

  • <идентификатор_роли> — роль для работы с Foundation Models:

    • ai.languageModels.user — для работы с моделями генерации текста.
    • ai.imageGeneration.user — для работы с моделями генерации изображений.
    • ai.datasets.editor и ai.models.editor — для создания датасетов и дообучения моделей.
    • ai.assistants.editor — для создания ассистента.

    Подробнее о ролях сервиса Foundation Models.

  • <идентификатор_сервисного_аккаунта> — идентификатор ранее созданного сервисного аккаунта.

Также назначить сервисному аккаунту роль можно с помощью вызова gRPC ServiceAccountService/SetAccessBindings.

Создайте API-ключ

  1. В консоли управления перейдите в каталог, которому принадлежит сервисный аккаунт.

  2. В списке сервисов выберите Identity and Access Management.

  3. На панели слева выберите Сервисные аккаунты.

  4. Выберите сервисный аккаунт, для которого вы хотите создать API-ключ. При необходимости создайте новый сервисный аккаунт.

  5. На панели сверху нажмите кнопку Создать новый ключ и выберите пункт Создать API-ключ.

  6. Задайте описание ключа, чтобы потом было проще найти его в консоли управления.

  7. Выберите Область действия, чтобы определить, для каких целей будет использоваться API-ключ:

    • yc.ai.languageModels.execute — разрешает использовать API-ключ для работы с моделями генерации текста.
    • yc.ai.imageGeneration.execute — разрешает использовать API-ключ для работы с моделями генерации изображений.
    • yc.ai.foundationModels.execute — разрешает использовать API-ключ для работы со всеми моделями Foundation Models.

  8. (Опционально) Укажите Срок действия.

  9. Нажмите кнопку Создать.

  10. Сохраните идентификатор и секретный ключ.

Внимание

После закрытия диалога значение ключа будет недоступно.

По умолчанию используется каталог, указанный при создании профиля CLI. Чтобы изменить каталог по умолчанию, используйте команду yc config set folder-id <идентификатор_каталога>. Также для любой команды вы можете указать другой каталог с помощью параметров --folder-name или --folder-id.

  1. Посмотрите описание команды создания API-ключа:

    yc iam api-key create --help

  2. Выберите сервисный аккаунт, например sa-api:

    yc iam service-account list

    Результат:

    +----------------------+------------------+-------------------------------+
|          ID          |       NAME       |          DESCRIPTION          |
+----------------------+------------------+-------------------------------+
| aje6o61dvog2******** | sa-api           |                               |
+----------------------+------------------+-------------------------------+

  3. Создайте API-ключ для выбранного сервисного аккаунта и запишите ответ в файл:

    yc iam api-key create --service-account-name sa-api > api-key.yaml

    В ответе в свойстве secret будет содержаться API-ключ:

    api_key:
  id: ajeke74kbp5b********
  service_account_id: ajepg0mjt06********
  created_at: "2019-04-09T08:41:27Z"
secret: AQVN1HHJReSrfo9jU3aopsXrJyfq_UHs********

Создайте API-ключ с помощью метода REST API create для ресурса ApiKey:

curl \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer <IAM-токен>" \
  --data "{ \"serviceAccountId\": \"<идентификатор_сервисного_аккаунта>\" }" \
  https://iam.api.cloud.yandex.net/iam/v1/apiKeys

Где:

  • <IAM-токен> — действующий токен авторизации.
  • <идентификатор_сервисного_аккаунта> — идентификатор сервисного аккаунта sa-api.

Также API-ключ можно создать с помощью вызова gRPC API ApiKeyService/Create.

Теперь вы можете отправлять запросы к моделям Foundation Models от имени сервисного аккаунта.

Предыдущая
Отключить логирование запросов
Следующая
Оценить запрос в токенах