Поделиться через

Проверка подлинности для агентов ИИ

Агенты ИИ часто должны проходить проверку подлинности в других ресурсах для выполнения задач. Например, развернутому агенту может понадобиться получить доступ к индексу векторного поиска для поиска неструктурированных данных, к эндпоинту для вызова фундаментальной модели или к функциям каталога Unity для выполнения пользовательской логики.

На этой странице рассматриваются методы проверки подлинности для агентов, развернутых в приложениях Databricks. Сведения об агентах, развернутых в конечных точках обслуживания моделей, см. в разделе "Проверка подлинности для агентов ИИ" (обслуживание моделей).

Databricks Apps предоставляет два метода проверки подлинности для агентов. Каждый метод обслуживает различные варианты использования:

Метод Description Когда следует использовать
Авторизация приложения Агент авторизуется с помощью автоматически созданного служебного принципала с согласованными разрешениями. Ранее называлась проверка подлинности основного объекта службы. Наиболее распространенный вариант использования. Используйте, когда у всех пользователей должен быть одинаковый доступ к ресурсам.
Авторизация пользователей Агент проверяет подлинность с помощью удостоверения пользователя, выполняющего запрос. Ранее именовалась On-Behalf-Of (OBO) аутентификация. Используйте, если вам нужны разрешения для конкретных пользователей, следы аудита или точное управление доступом с помощью каталога Unity.

Оба метода можно объединить в одном агенте. Например, используйте авторизацию приложения для доступа к общему индексу поиска векторов при использовании авторизации пользователя для запроса таблиц, определенных пользователем.

Авторизация приложения

По умолчанию Databricks Apps проходит проверку подлинности с помощью авторизации приложения. Azure Databricks автоматически создает учетную запись службы при создании приложения и используется как идентификатор приложения.

Все пользователи, взаимодействующие с приложением, имеют одинаковые разрешения, определенные для субъекта-службы. Эта модель хорошо работает, если все пользователи будут видеть одни и те же данные или когда приложение выполняет общие операции, не связанные с элементами управления доступом для конкретных пользователей.

Подробные сведения об авторизации приложения см. в разделе "Авторизация приложений".

Предоставление разрешений эксперименту MLflow

Агенту требуется доступ к эксперименту MLflow для регистрации трассировок и результатов оценки.

Предоставьте служебному принципалу Can Edit разрешение на эксперимент MLflow.

  1. Щелкните "Изменить" на домашней странице приложения.
  2. Перейдите к шагу настройки .
  3. В разделе "Ресурсы приложения" добавьте ресурс эксперимента MLflow.

См. статью "Добавление ресурса эксперимента MLflow" в приложение Databricks.

Предоставление разрешений другим ресурсам Databricks

Если ваш агент использует другие ресурсы Databricks, такие как пространства Genie, индексы векторного поиска или склады данных SQL, предоставьте разрешения сервисному аккаунту через интерфейс приложений Databricks. Полный список поддерживаемых ресурсов и инструкции по настройке см. в разделе Добавление ресурсов в приложение Databricks.

Чтобы получить доступ к реестру запросов, предоставить CREATE FUNCTION, EXECUTE, и MANAGE разрешения на схему каталога Unity для хранения запросов.

В следующей таблице перечислены минимальные разрешения, необходимые для доступа к общим ресурсам Databricks:

Тип ресурса Разрешение
Хранилище SQL Can Use
Конечная точка обслуживания модели Can Query
Функция каталога Unity CAN Execute
Пространство Genie Can Run
Индекс векторного поиска Can Select
Таблица каталога Unity SELECT
Подключение каталога Unity Use Connection
Том каталога Unity Can Read или Can Read and Write
Lakebase Can Connect and Create

При предоставлении доступа к ресурсам каталога Unity необходимо также предоставить разрешения всем подчиненным ресурсам. Например, если вы предоставляете доступ к пространству Genie, необходимо также предоставить доступ к своим базовым таблицам, хранилищам SQL и функциям каталога Unity.

Пользователь, добавляя ресурс, должен иметь Can Manage разрешение как на ресурс, так и на приложение. Полный список поддерживаемых ресурсов и всех доступных разрешений см. в поддерживаемых типах ресурсов.

Рекомендации по безопасному управлению авторизацией приложений, включая управление учетными данными и принципы наименьших привилегий, см. в разделе "Авторизация приложений".

Авторизация пользователей

Это важно

Авторизация пользователя доступна в общедоступной предварительной версии. Администратор рабочей области должен включить его, прежде чем использовать авторизацию пользователя.

Авторизация пользователя позволяет агенту действовать с удостоверением пользователя, выполняющего запрос. Это обеспечивает следующее:

  • Доступ к конфиденциальным данным на пользователя
  • Тонкозернистый контроль данных, реализуемый Unity Catalog
  • Следы аудита для конкретного пользователя
  • Автоматическое применение фильтров на уровне строк и маски столбцов

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

Как работает авторизация пользователей

При настройке авторизации пользователя для агента:

  1. Добавьте области API в приложение: определите, какие API Databricks приложение может получить доступ от имени пользователей. См. статью "Добавление областей в приложение".
  2. Учетные данные пользователя ограничены: Azure Databricks принимает учетные данные пользователя и ограничивает их только определенными областями API.
  3. Перенаправление токенов: суженный токен становится доступным вашему приложению через x-forwarded-access-token заголовок HTTP.
  4. MLflow AgentServer сохраняет маркер: сервер агента автоматически сохраняет этот маркер на запрос для удобного доступа в коде агента.

Настройте авторизацию пользователя, добавив области в пользовательский интерфейс Databricks Apps при создании или редактировании приложения или программно с помощью API. Подробные инструкции см. в статье "Добавление областей в приложение".

Агенты с авторизацией пользователя могут получить доступ к следующим ресурсам Databricks:

  • Хранилище SQL
  • Genie Space
  • Файлы и каталоги
  • Конечная точка обслуживания модели
  • Индекс векторного поиска
  • Подключения каталога Unity
  • Таблицы каталога Unity

Реализация авторизации пользователей

Чтобы реализовать авторизацию пользователя, необходимо добавить области авторизации в приложение. Области действия ограничивают возможности приложения от имени пользователя.

  1. В пользовательском интерфейсе Databricks перейдите к параметрам авторизации приложений Databricks.
  2. Нажмите кнопку +Добавить область и выберите области, к которым требуется получить доступ от имени пользователя.
  3. Сохраните изменения.

Чтобы настроить авторизацию пользователя в коде агента, получите заголовок этого запроса из AgentServer и создайте клиент рабочей области с этими учетными данными.

  1. Импортируйте утилиту аутентификации в ваш код агента.

    При использовании одного из предоставленных шаблонов из databricks/app-templates импортируйте предоставленную программу:

    from databricks_app.utils import get_user_workspace_client

    В противном случае импортируйте из утилит сервера-агента:

    from agent_server.utils import get_user_workspace_client

    Функция get_user_workspace_client() использует сервер агента для записи x-forwarded-access-token заголовка и создания клиента рабочей области с этими учетными данными пользователя, обработки проверки подлинности между пользователем, приложением и сервером агента.

  2. Инициализировать клиент рабочей области во время запроса, а не во время запуска приложения:

    Это важно

    Вызов get_user_workspace_client() внутри invoke и stream обработчиков, а не в __init__ или при запуске приложения. Учетные данные пользователя доступны только во время запроса, когда пользователь выполняет запрос. Инициализация во время запуска приложения приведет к ошибке, так как контекст пользователя еще не существует.

    # In your agent code (inside invoke or stream handler)
user_client = get_user_workspace_client()


# Use user_client to access Databricks resources with user permissions
response = user_client.serving_endpoints.query(name="my-endpoint", inputs=inputs)

Полное руководство по добавлению областей и пониманию безопасности на основе областей см. в разделе "Безопасность на основе областей " и "Повышение привилегий".

Аутентификация на серверах Databricks MCP

Чтобы выполнить проверку подлинности на серверах Databricks MCP, укажите все ресурсы, необходимые агенту в databricks.yaml файле. Предоставьте субъекту-службе приложения (или пользователям, если используется авторизация пользователя) доступ ко всем подчиненным ресурсам.

Например, если агент использует ниже перечисленные URL-адреса сервера MCP, необходимо предоставить доступ ко всем векторным индексам поиска в prod.customer_support и prod.billing схемах, и всем функциям каталога Unity в prod.billing.

  • https://<your-workspace-hostname>/api/2.0/mcp/vector-search/prod/customer_support
  • https://<your-workspace-hostname>/api/2.0/mcp/vector-search/prod/billing
  • https://<your-workspace-hostname>/api/2.0/mcp/functions/prod/billing

Настройка проверки подлинности с помощью пакетов ресурсов Databricks

Все параметры проверки подлинности можно настроить программным способом с помощью пакетов ресурсов Databricks вместо пользовательского интерфейса Databricks Apps. На этой странице показана конфигурация на основе пользовательского интерфейса для иллюстрации необходимых ресурсов и разрешений, но та же конфигурация может быть определена в файлах YAML пакета. См. статью "Приложения в пакетах" для полной ссылки на конфигурацию пакета.

Дальнейшие шаги

  • Last updated on