Проверка подлинности для агентов ИИ (обслуживание моделей)

Это важно

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

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

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

Методы аутентификации

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

Метод	Description	Положение безопасности	Сложность настройки
Сквозная автоматическая аутентификация	Агент запускается с разрешениями пользователя, который развернул его. Databricks автоматически управляет временными учетными данными для объявленных ресурсов	Короткие учетные данные, автоматическая смена	Низкий уровень — объявление зависимостей при записи журнала
Аутентификация от имени пользователя (OBO)	Агент запускается с разрешениями конечного пользователя, выполняющего запрос.	Использует учетные данные конечного пользователя с ограниченными областями	Средний — требует объявления области и инициализации среды выполнения
Проверка подлинности вручную	Явно укажите учетные данные с помощью переменных среды	Для управления ротацией длительных учетных данных требуется организация процесса смены.	Высокий — требуется ручное управление учетными данными

Выбор подходящего метода проверки подлинности для ресурса

Используйте эту блок-схему, чтобы выбрать правильный метод проверки подлинности для каждого ресурса. При необходимости можно объединить методы, а агент может использовать другой метод для каждого ресурса в зависимости от варианта использования.

Требуется ли для каждого пользователя управление доступом или аудит с учетом пользователей?
- Да → Использовать аутентификацию от имени пользователя
- Нет → продолжить шаг 2
Поддерживают ли все ресурсы автоматическую проверку подлинности?
- Да → Использовать сквозную автоматическую проверку подлинности (рекомендуется)
- Нет → использовать проверку подлинности вручную

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

Чтобы пройти проверку подлинности на серверах Databricks MCP, укажите все ресурсы, необходимые агенту во время ведения журнала.

Например, если агент использует указанные ниже 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

Чтобы упростить процесс идентификации всех зависимых ресурсов для управляемых серверов MCP, используйте databricks-mcp пакет databricks_mcp.DatabricksMCPClient().get_databricks_resources(<server_url>) PyPI для получения ресурсов, необходимых управляемому серверу MCP.

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

Автоматическое сквозное прохождение аутентификации

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

Это поведение проверки подлинности аналогично поведению "Запуск от имени владельца" для панелей мониторинга Databricks. К низкоуровневым ресурсам, таким как таблицы каталога Unity, обращаются с помощью учетных данных служебного принципала с минимальными привилегиями, предоставляющими доступ только к тем ресурсам, которые нужны агенту.

Как работает автоматическая сквозная проверка подлинности

Если агент обслуживается за конечной точкой с помощью сквозной автоматической аутентификации, Databricks выполняет следующие действия:

Проверка разрешений: Databricks проверяет, может ли создатель конечной точки получить доступ ко всем зависимостям, указанным во время ведения журнала агента.
Создание и предоставление доступа служебного принципала: служебный принципал создается для версии модели агента и автоматически получает доступ на чтение к ресурсам агента.

Замечание

Системный принципал службы не отображается в списках API или в пользовательских интерфейсах. Если версия модели агента удаляется из конечной точки, субъект-служба также удаляется.
предоставление и ротация учетных данных: кратковременные учетные данные (маркер OAuth M2M) для субъекта-службы интегрируются в конечную точку, что позволяет коду агента получать доступ к ресурсам Databricks. Databricks также обновляет учетные данные, гарантируя, что ваш агент имеет постоянный и безопасный доступ к зависимым ресурсам.

Поддерживаемые ресурсы для автоматической сквозной аутентификации

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

Замечание

Ресурсы каталога Unity также требуют наличие USE SCHEMA в родительской схеме и USE CATALOG в родительском каталоге.

Тип ресурса	Разрешение	Минимальная версия MLflow
Хранилище SQL	`Use Endpoint`	2.16.1 или более поздней версии
Конечная точка обслуживания модели	`Can Query`	2.13.1 или выше
Функция каталога Unity	`EXECUTE`	2.16.1 или более поздней версии
Пространство Genie	`Can Run`	2.17.1 или более поздней версии
Индекс векторного поиска	`Can Use`	2.13.1 или выше
Таблица каталога Unity	`SELECT`	2.18.0 или выше
Подключение каталога Unity	`Use Connection`	2.17.1 или более поздней версии
Lakebase	`databricks_superuser`	3.3.2 или более поздней версии

Реализация автоматической передачи аутентификации

Чтобы включить автоматическую передачу аутентификации, укажите зависимые ресурсы при входе агента. Используйте параметр resources API log_model():

Замечание

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

import mlflow
from mlflow.models.resources import (
  DatabricksVectorSearchIndex,
  DatabricksServingEndpoint,
  DatabricksSQLWarehouse,
  DatabricksFunction,
  DatabricksGenieSpace,
  DatabricksTable,
  DatabricksUCConnection,
  DatabricksApp,
  DatabricksLakebase
)

with mlflow.start_run():
  logged_agent_info = mlflow.pyfunc.log_model(
    python_model="agent.py",
    artifact_path="agent",
    input_example=input_example,
    example_no_conversion=True,
    # Specify resources for automatic authentication passthrough
    resources=[
      DatabricksVectorSearchIndex(index_name="prod.agents.databricks_docs_index"),
      DatabricksServingEndpoint(endpoint_name="databricks-meta-llama-3-3-70b-instruct"),
      DatabricksServingEndpoint(endpoint_name="databricks-bge-large-en"),
      DatabricksSQLWarehouse(warehouse_id="your_warehouse_id"),
      DatabricksFunction(function_name="ml.tools.python_exec"),
      DatabricksGenieSpace(genie_space_id="your_genie_space_id"),
      DatabricksTable(table_name="your_table_name"),
      DatabricksUCConnection(connection_name="your_connection_name"),
      DatabricksApp(app_name="app_name"),
      DatabricksLakebase(database_instance_name="lakebase_instance_name"),
    ]
  )

Аутентификация от имени пользователя

Это важно

Эта функция доступна в общедоступной предварительной версии.

Проверка подлинности от имени пользователя (OBO) позволяет агенту действовать как пользователь Databricks, выполняющий запрос. Это обеспечивает следующее:

Доступ к конфиденциальным данным на пользователя
Тонкозернистый контроль данных, реализуемый Unity Catalog
Маркеры безопасности ограничены (сужены) только теми API, которые объявляет ваш агент, уменьшая риск неправильного использования.

Требования

Для проверки подлинности от имени пользователя требуется MLflow 2.22.1 и выше.
Аутентификация от имени пользователя отключена по умолчанию и должна быть включена администратором рабочей области. Ознакомьтесь с рекомендациями по обеспечению безопасности перед включением этой функции.

Ресурсы с поддержкой OBO

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

Ресурс Databricks	Совместимые клиенты
Индекс векторного поиска	`databricks_langchain.VectorSearchRetrieverTool`, `databricks_openai.VectorSearchRetrieverTool`, `VectorSearchClient`
Конечная точка обслуживания модели	`databricks.sdk.WorkspaceClient`
Хранилище SQL	`databricks.sdk.WorkspaceClient`
Подключения UC	`databricks.sdk.WorkspaceClient`
Таблицы и функции UC	`databricks.sdk.WorkspaceClient` (Для доступа к таблицам UC необходимо использовать sql-запросы с помощью API выполнения инструкций SQL)
Genie Space	`databricks.sdk.WorkspaceClient` (рекомендуется), `databricks_langchain.GenieAgent`или `databricks_ai_bridge.GenieAgent`
Протокол контекста модели (MCP)	`databricks_mcp.DatabricksMCPClient`

Реализация проверки подлинности OBO

Чтобы включить проверку подлинности от имени пользователя, выполните следующие действия:

Обновите вызовы пакета SDK, чтобы указать, что к ресурсам обращаются от имени конечного пользователя.
Обновите код агента для инициализации доступа OBO в функции predict, а не в __init__, поскольку идентификационные данные пользователя известны только во время выполнения.
При настройке агента для развертывания укажите области REST API Databricks, необходимые агенту.

В следующих фрагментах кода показано, как настроить доступ от имени пользователя к различным ресурсам Databricks. При инициализации средств обработайте ошибки разрешений корректно путем упаковки инициализации в try-except блок.

Инструмент для поиска по векторам

from databricks.sdk import WorkspaceClient
from databricks_ai_bridge import ModelServingUserCredentials
from databricks_langchain import VectorSearchRetrieverTool

# Configure a Databricks SDK WorkspaceClient to use on behalf of end
# user authentication
user_client = WorkspaceClient(credentials_strategy = ModelServingUserCredentials())

vector_search_tools = []
# Exclude exception handling if the agent should fail
# when users lack access to all required Databricks resources
try:
  tool = VectorSearchRetrieverTool(
    index_name="<index_name>",
    description="...",
    tool_name="...",
    workspace_client=user_client # Specify the user authorized client
    )
    vector_search_tools.append(tool)
except Exception as e:
    _logger.debug("Skipping adding tool as user does not have permissions")

Клиент поиска векторов

from databricks.vector_search.client import VectorSearchClient
from databricks.vector_search.utils import CredentialStrategy

# Configure a VectorSearch Client to use on behalf of end
# user authentication
user_authenticated_vsc = VectorSearchClient(credential_strategy=CredentialStrategy.MODEL_SERVING_USER_CREDENTIALS)
# Exclude exception handling if the agent should fail when
# users lack access to all required Databricks resources
try:
  vs_index = user_authenticated_vsc.get_index(endpoint_name="endpoint_name", index_name="index_name")
  ...
except Exception as e:
  _logger.debug("Skipping Vector Index because user does not have permissions")

MCP

from databricks.sdk import WorkspaceClient
from databricks_ai_bridge import ModelServingUserCredentials
from databricks_mcp import DatabricksMCPClient

# Configure a Databricks SDK WorkspaceClient to use on behalf of end
# user authentication
user_client = WorkspaceClient(credentials_strategy=ModelServingUserCredentials())

mcp_client = DatabricksMCPClient(
    server_url="<mcp_server_url>",
    workspace_client=user_client, # Specify the user client here
  )

Конечная точка обслуживания модели

from databricks.sdk import WorkspaceClient
from databricks_ai_bridge import ModelServingUserCredentials

# Configure a Databricks SDK WorkspaceClient to use on behalf of end
# user authentication
user_client = WorkspaceClient(credentials_strategy=ModelServingUserCredentials())

# Exclude exception handling if the agent should fail
# when users lack access to all required Databricks resources
try:
  user_client.serving_endpoints.query("endpoint_name", input="")
except Exception as e:
  _logger.debug("Skipping Model Serving Endpoint due to no permissions")

Подключения UC

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.serving import ExternalFunctionRequestHttpMethod
from databricks_ai_bridge import ModelServingUserCredentials

# Configure a Databricks SDK WorkspaceClient to use on behalf of end
# user authentication
user_client = WorkspaceClient(credentials_strategy=ModelServingUserCredentials())

user_client.serving_endpoints.http_request(
  conn="connection_name",
  method=ExternalFunctionRequestHttpMethod.POST,
  path="/api/v1/resource",
  json={"key": "value"},
  headers={"extra_header_key": "extra_header_value"},
)

Genie Spaces (WorkspaceClient)

from databricks_langchain.genie import GenieAgent
from databricks.sdk import WorkspaceClient
from databricks_ai_bridge import ModelServingUserCredentials


# Configure a Databricks SDK WorkspaceClient to use on behalf of end
# user authentication
user_client = WorkspaceClient(credentials_strategy=ModelServingUserCredentials())


genie_agent = GenieAgent(
    genie_space_id="space-id",
    genie_agent_name="Genie",
    description="This Genie space has access to sales data in Europe",
    client=user_client
)

# Use the Genie SDK methods available through WorkspaceClient
try:
    response = agent.invoke("Your query here")
except Exception as e:
    _logger.debug("Skipping Genie due to no permissions")

Genie Spaces (LangChain)

from databricks.sdk import WorkspaceClient
from databricks_ai_bridge import ModelServingUserCredentials
from databricks_langchain.genie import GenieAgent

# Configure a Databricks SDK WorkspaceClient to use on behalf of end
# user authentication
user_client = WorkspaceClient(credentials_strategy=ModelServingUserCredentials())

genie_agent = GenieAgent(
    genie_space_id="<genie_space_id>",
    genie_agent_name="Genie",
    description="Genie_description",
    client=user_client, # Specify the user client here
  )

Инициализируйте агента в функции прогнозирования

Так как удостоверение пользователя известно только во время запроса, необходимо получить доступ к ресурсам OBO внутри predict или predict_stream, а не в методе агента __init__. Это гарантирует, что ресурсы изолированы между вызовами.

from mlflow.pyfunc import ResponsesAgent

class OBOResponsesAgent(ResponsesAgent):
  def initialize_agent():
    user_client = WorkspaceClient(
      credentials_strategy=ModelServingUserCredentials()
    )
    system_authorized_client = WorkspaceClient()
    ### Use the clients above to access resources with either system or user authentication

  def predict(
    self, request
  ) -> ResponsesAgentResponse:
    agent = initialize_agent() # Initialize the Agent in Predict

    agent.predict(request)
    ...

Объявление областей REST API при логировании агента

При регистрации агента OBO для развертывания необходимо перечислить области REST API Databricks, вызываемые агентом от имени пользователя. Это гарантирует, что агент следует принципу наименьших привилегий: токены ограничены только теми API, которые необходимы агенту, что снижает вероятность несанкционированных действий или неправильного употребления токенов.

Ниже приведен список областей, необходимых для доступа к нескольким общим типам ресурсов Databricks:

Тип ресурса	Требуемая область API
Конечные точки обслуживания моделей	`serving.serving-endpoints`
Конечные точки поиска векторов	`vectorsearch.vector-search-endpoints`
Индексы векторного поиска	`vectorsearch.vector-search-indexes`
Хранилища SQL	`sql.warehouses`, `sql.statement-execution`
пространства Джиннов	`dashboards.genie`
Подключения UC	`catalog.connections` и `serving.serving-endpoints`.
Приложения Databricks	`apps.apps`
MCP Genie spaces	`genie`
Функции UC MCP	`unity-catalog`
Поиск векторов MCP	`vector-search`
MCP DBSQL	`sql`
Внешние функции MCP	`unity-catalog`

Чтобы включить аутентификацию от имени пользователя, передайте MLflow AuthPolicy в log_model():

import mlflow
from mlflow.models.auth_policy import AuthPolicy, SystemAuthPolicy, UserAuthPolicy
from mlflow.models.resources import DatabricksServingEndpoint

# System policy: resources accessed with system credentials
system_policy = SystemAuthPolicy(
    resources=[DatabricksServingEndpoint(endpoint_name="my_endpoint")]
)

# User policy: API scopes for OBO access
user_policy = UserAuthPolicy(api_scopes=[
    "serving.serving-endpoints",
    "vectorsearch.vector-search-endpoints",
    "vectorsearch.vector-search-indexes"
])

# Log the agent with both policies
with mlflow.start_run():
    mlflow.pyfunc.log_model(
        name="agent",
        python_model="agent.py",
        auth_policy=AuthPolicy(
            system_auth_policy=system_policy,
            user_auth_policy=user_policy
        )
    )

Проверка подлинности OBO для клиентов OpenAI

Для агентов, использующих клиент OpenAI, используйте пакет SDK Databricks для автоматической проверки подлинности во время развертывания. Пакет SDK Databricks имеет оболочку для создания клиента OpenAI с автоматически настроенной проверкой подлинности, get_open_ai_client():

% pip install databricks-sdk[openai]

from databricks.sdk import WorkspaceClient
def openai_client(self):
  w = WorkspaceClient()
  return w.serving_endpoints.get_open_ai_client()

Затем укажите конечную точку развертывания модели в resources, чтобы автоматически аутентифицироваться во время развертывания.

Примеры записных книжек OBO

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

От имени авторизации пользователя с помощью векторного поиска

Получите ноутбук

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

Замечание

В настоящее время рекомендуется выполнять функции UC с помощью OBO, так как бессерверное выполнение Spark с помощью OBO еще не поддерживается.

От имени пользователя с авторизацией и выполнением SQL-запросов

Получите ноутбук

Проверка подлинности вручную

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

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

Это важно

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

Проверка подлинности OAuth (рекомендуется)

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

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

Настройте учетные данные OAuth в коде агента:

import os

# Configure OAuth authentication for Prompt Registry access
# Replace with actual secret scope and key names
secret_scope_name = "your-secret-scope"
client_id_key = "oauth-client-id"
client_secret_key = "oauth-client-secret"

os.environ["DATABRICKS_HOST"] = "https://<your-workspace-url>"
os.environ["DATABRICKS_CLIENT_ID"] = dbutils.secrets.get(scope=secret_scope_name, key=client_id_key)
os.environ["DATABRICKS_CLIENT_SECRET"] = dbutils.secrets.get(scope=secret_scope_name, key=client_secret_key)

Используйте секреты для подключения к рабочей области:

w = WorkspaceClient(
  host=os.environ["DATABRICKS_HOST"],
  client_id=os.environ["DATABRICKS_CLIENT_ID"],
  client_secret = os.environ["DATABRICKS_CLIENT_SECRET"]
)

При развертывании с использованием agents.deploy() учтите учетные данные OAuth в качестве переменных среды:

agents.deploy(
    UC_MODEL_NAME,
    uc_registered_model_info.version,
    environment_vars={
        "DATABRICKS_HOST": "https://<your-workspace-url>",
        "DATABRICKS_CLIENT_ID": f"{{{{secrets/{secret_scope_name}/{client_id_key}}}}}",
        "DATABRICKS_CLIENT_SECRET": f"{{{{secrets/{secret_scope_name}/{client_secret_key}}}}}"
    },
)

Проверка подлинности PAT

Проверка подлинности личного маркера доступа (PAT) обеспечивает более простую настройку для сред разработки и тестирования, хотя для этого требуется более ручное управление учетными данными:

Получите PAT с помощью учетной записи службы или личной учетной записи.

Учетная запись службы (рекомендуется для безопасности):
1. Создайте служебный принципал.
2. Предоставьте служебному субъекту разрешения на доступ к любым ресурсам Databricks, к которым агент имеет привилегии для доступа к ресурсам Databricks. Чтобы получить доступ к реестру запросов, предоставьте CREATE FUNCTION, EXECUTE и MANAGE разрешения на схему каталога Unity, используемую для хранения запросов.
3. Создайте PAT для субъекта-службы.
Личная учетная запись:
1. Создайте PAT для личной учетной записи.
Безопасно сохраните PAT, создав секрет Databricks для PAT.

Настройте проверку подлинности PAT в коде агента:

import os

# Configure PAT authentication for Prompt Registry access
# Replace with your actual secret scope and key names
secret_scope_name = "your-secret-scope"
secret_key_name = "your-pat-key"

os.environ["DATABRICKS_HOST"] = "https://<your-workspace-url>"
os.environ["DATABRICKS_TOKEN"] = dbutils.secrets.get(scope=secret_scope_name, key=secret_key_name)

# Validate configuration
assert os.environ["DATABRICKS_HOST"], "DATABRICKS_HOST must be set"
assert os.environ["DATABRICKS_TOKEN"], "DATABRICKS_TOKEN must be set"

При развертывании агента с помощью agents.deploy()включите PAT в качестве переменной среды:

agents.deploy(
    UC_MODEL_NAME,
    uc_registered_model_info.version,
    environment_vars={
        "DATABRICKS_HOST": "https://<your-workspace-url>",
        "DATABRICKS_TOKEN": f"{{{{secrets/{secret_scope_name}/{secret_key_name}}}}}"
    },
)

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-02-14

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

Проверка подлинности для агентов ИИ (обслуживание моделей)

Методы аутентификации

Выбор подходящего метода проверки подлинности для ресурса

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

Автоматическое сквозное прохождение аутентификации

Как работает автоматическая сквозная проверка подлинности

Поддерживаемые ресурсы для автоматической сквозной аутентификации

Реализация автоматической передачи аутентификации

Аутентификация от имени пользователя

Требования

Ресурсы с поддержкой OBO

Реализация проверки подлинности OBO

Инструмент для поиска по векторам

Клиент поиска векторов

MCP

Конечная точка обслуживания модели

Подключения UC

Genie Spaces (WorkspaceClient)

Genie Spaces (LangChain)

Инициализируйте агента в функции прогнозирования

Объявление областей REST API при логировании агента

Проверка подлинности OBO для клиентов OpenAI

Рекомендации по безопасности OBO

Примеры записных книжек OBO

От имени авторизации пользователя с помощью векторного поиска

От имени пользователя с авторизацией и выполнением SQL-запросов

Проверка подлинности вручную

Проверка подлинности OAuth (рекомендуется)

Проверка подлинности PAT

Обратная связь

Дополнительные ресурсы