为生成式 AI 应用程序部署代理

本文介绍如何使用 Agent Framework Python API中的 deploy() 函数将 AI 代理 部署到马赛克 AI 模型服务。

在马赛克 AI 模型服务上部署代理具有以下优势：

• 模型服务管理自动缩放、日志记录、版本控制和访问控制，使你能够专注于开发质量代理。
• 领域专家可以使用评审应用与已部署的代理交互，并提供可集成到监视和评估中的反馈。
• 可以通过评估实时流量来监视代理。 尽管用户流量不包括真实数据，但 LLM 评委（以及你创建的自定义指标）进行无监督评估。

要求

• MLflow 2.13.1 或更高版本，用于通过 deploy() 中的 databricks.agents API 部署代理。

• 将 AI 代理注册到 Unity Catalog。 请参阅将代理注册到 Unity Catalog。

• 从 Databricks 笔记本外部部署代理需要 databricks-agents SDK 版本 0.12.0 或更高版本。

• 终结点创建者（部署代理的用户）必须在选中的 Unity Catalog 架构上拥有权限，以便在部署时存储推理表。 这可确保可以在架构中创建相关的评估和日志记录表。 请参阅 “启用和禁用推理表”。

• 安装 databricks-agents SDK。

  %pip install databricks-agents
  dbutils.library.restartPython()
  

使用 deploy() 部署代理

使用 deploy（） 将代理部署到模型服务终结点。

from databricks import agents

deployment = agents.deploy(uc_model_name, uc_model_info.version)

# Retrieve the query endpoint URL for making API requests
deployment.query_endpoint

默认情况下，deploy() 函数执行以下作：

自定义部署

若要自定义部署，可以将其他参数传递给 deploy()。 例如，可以通过传递 scale_to_zero_enabled=True，为空闲终结点启用缩放到零功能。 这降低了成本，但增加了为初始查询提供服务的时间。

有关更多参数，请参阅 Databricks Agents Python API。

检索和删除代理部署

检索或管理现有代理部署：

from databricks.agents import list_deployments, get_deployments, delete_deployment

# Print all current deployments
deployments = list_deployments()
print(deployments)

# Get the deployment for a specific agent model name and version
agent_model_name = ""  # Set to your Unity Catalog model name
agent_model_version = 1  # Set to your agent model version
deployment = get_deployments(model_name=agent_model_name, model_version=agent_model_version)

# Delete an agent deployment
delete_deployment(model_name=agent_model_name, model_version=agent_model_version)

从属资源的身份验证

AI 代理通常需要向其他资源进行身份验证才能完成任务。 例如，代理可能需要访问矢量搜索索引来查询非结构化数据。

如果在模型服务终结点后提供代理，可以使用以下方法之一对依赖资源进行身份验证：

1. 自动身份验证直通：在日志记录期间为代理声明 Databricks 资源依赖项。 部署代理以安全访问资源时，Databricks 可以自动预配、轮换和管理生存期较短的凭据。 Databricks 建议尽可能使用自动身份验证直通。
2. 代表用户身份验证：允许使用代理最终用户凭据访问 Databricks REST API 和资源
3. 手动身份验证：在代理部署期间手动指定长期凭据。 对于不支持自动身份验证传递的 Databricks 资源或外部 API 访问，请使用手动身份验证。

自动身份验证直通

模型服务支持对于代理使用的最常见 Databricks 资源类型使用自动身份验证直通。

若要启用自动身份验证直通，必须在代理日志记录期间指定依赖项。

然后，在终结点后提供代理时，Databricks 将执行以下步骤：

1. 权限验证： Databricks 验证终结点创建者是否可以访问代理日志记录期间指定的所有依赖项。

2. 服务主体创建和授予：为代理模型版本创建服务主体，并自动授予对代理资源的读取访问权限。

   注意

   系统生成的服务主体不会显示在 API 或 UI 列表中。 如果从终结点中删除代理模型版本，也会删除服务主体。

3. 凭据预配和轮换：服务主体的短期凭据（例如 M2M OAuth 令牌）被注入到端点，以便代理代码可以访问 Databricks 资源。 Databricks 还会轮换凭据，确保代理保持安全访问依赖资源的能力。

这种身份验证行为类似于 Databricks 仪表板的“以所有者身份运行”行为——下游资源（如 Unity Catalog 表）是通过具有对依赖资源最小特权访问的服务主体的凭据来访问的。

下表列出了支持自动身份验证传递的 Databricks 资源，以及部署代理时终结点创建者必须拥有的权限。

代表用户身份验证

代表用户身份验证允许代理开发人员使用代理的最终用户凭据访问 Databricks 敏感资源。 若要启用代用户访问资源，需要执行两个步骤：

1. 在代理代码中，请确保使用启用了代表用户身份验证的客户端来访问 Databricks 资源。 有关详细信息，请参阅代表用户身份验证。
2. 在记录代理日志时，指定代理所需的终端用户 REST API 范围（例如 vectorsearch.vector-search-endpoints）。 代理随后部署后，它可以代表最终用户访问 Databricks 资源，但只能使用指定的范围。 有关 API 范围的详细信息，请参阅 用户代理身份验证。

手动身份验证

还可以使用 基于机密的环境变量手动提供凭据。 在以下方案中，手动身份验证非常有用：

• 依赖资源不支持自动身份验证直通。
• 代理正在访问外部资源或 API。
• 代理需要使用不同于代理部署程序的凭据。

例如，若要在代理中使用 Databricks SDK 访问其他依赖资源，可以设置 databricks 客户端统一身份验证中所述的环境变量。

监视已部署的代理

将代理部署到 Databricks 模型服务后，可以使用 AI 网关推理表监视已部署的代理。 推理表包含来自评审应用的请求、响应、代理跟踪和代理反馈的详细日志。 利用此信息，可以调试问题、监视性能，并创建黄金数据集进行脱机评估。

请参阅 “查看 MLflow 跟踪”。

获取已部署的应用程序

下面介绍如何获取已部署的代理。

from databricks.agents import list_deployments, get_deployments

# Get the deployment for specific model_fqn and version
deployment = get_deployments(model_name=model_fqn, model_version=model_version.version)

deployments = list_deployments()
# Print all the current deployments
deployments

提供有关已部署代理人的反馈（实验性）

当你使用agents.deploy()部署代理时，agents.deploy()框架还会在同一终结点中创建并部署一个“反馈”模型版本，你可以查询该版本以提供有关代理应用程序的反馈。 反馈条目显示为与代理服务终结点关联的推理表中的请求行。

请注意，此行为是 实验性的：Databricks 可能会提供一流的 API，以便将来提供有关已部署代理的反馈，将来的功能可能需要迁移到此 API。

此 API 的限制包括：

• 反馈 API 缺少输入验证 - 即使传递了无效的输入，它始终会成功响应。
• 反馈 API 需要传入 Databricks 生成的要提供反馈的代理终结点请求的 request_id。 若要获取 databricks_request_id，请在对代理服务终结点的原始请求中包含 {"databricks_options": {"return_trace": True}}。 然后，代理终结点响应将包含与请求关联的 databricks_request_id，以便在提供有关代理响应的反馈时将请求 ID 传递回反馈 API。
• 使用推理表收集反馈。 请参阅 推理表限制。

以下示例请求对名为“your-agent-endpoint-name”的代理终结点提供反馈，假设 DATABRICKS_TOKEN 环境变量已被设置为 Databricks REST API 令牌。

curl \
  -u token:$DATABRICKS_TOKEN \
  -X POST \
  -H "Content-Type: application/json" \
  -d '
      {
          "dataframe_records": [
              {
                  "source": {
                      "id": "user@company.com",
                      "type": "human"
                  },
                  "request_id": "573d4a61-4adb-41bd-96db-0ec8cebc3744",
                  "text_assessments": [
                      {
                          "ratings": {
                              "answer_correct": {
                                  "value": "positive"
                              },
                              "accurate": {
                                  "value": "positive"
                              }
                          },
                          "free_text_comment": "The answer used the provided context to talk about DLT"
                      }
                  ],
                  "retrieval_assessments": [
                      {
                          "ratings": {
                              "groundedness": {
                                  "value": "positive"
                              }
                          }
                      }
                  ]
              }
          ]
      }' \
https://<workspace-host>.databricks.com/serving-endpoints/<your-agent-endpoint-name>/served-models/feedback/invocations

可以在text_assessments.ratings和retrieval_assessments.ratings字段中传递附加或不同的键值对，以提供不同类型的反馈。 在此示例中，反馈有效负载指示代理对 ID 为 ID 573d4a61-4adb-41bd-96db-0ec8cebc3744 的请求的响应正确、准确且位于检索器工具提取的上下文中。

其他资源

• 查询已部署的 Mosaic AI 代理
• 什么是 Mosaic AI 代理评估？
• 使用评审应用对第一代 AI 应用进行人工评审
• 调试已部署的 AI 代理