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

项目
03/16/2025

本文介绍如何使用 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 或更高版本。

安装 databricks-agents SDK。

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

使用 `deploy()` 部署代理

deploy （）函数执行以下操作：

为代理创建可集成到面向用户的应用程序中的 CPU 模型服务终结点。
- 若要降低空闲终结点的成本（代价是增加处理初始查询的时间），可以通过将 scale_to_zero_enabled=True 传递给 deploy() 来为服务终结点启用缩放至零。请参阅终结点缩放预期。
- 在模型服务终结点上为推理表启用 AI 网关。请参阅使用启用了 AI 网关的推理表来监视服务的模型。
注意

对于流式响应日志，只有与 ChatCompletion 兼容的字段和跟踪会被汇总。
- Databricks 自动为在终结点中运行的代理程序代码提供短期有效的服务主体凭据。凭据具有访问在模型日志记录期间定义的 Databricks 托管资源的最低权限。在生成这些凭据之前，Databricks 可确保终结点所有者具有适当的权限，以防止特权升级和未经授权的访问。请参阅从属资源的身份验证。
  - 例如，如果资源依赖项不是 Databricks 管理的，则可以使用 Pinecone 将具有机密的环境变量传递给 deploy() API。请参阅配置从模型服务终结点对资源的访问权限。
为代理启用评审应用。 “审阅应用”允许利益干系人与代理聊天，并使用“审阅应用 UI”提供反馈。
将对评审应用或 REST API 发出的每个请求记录到推理表中。记录的数据包括查询请求、响应以及来自 MLflow 跟踪的中间跟踪数据。
创建与你尝试部署的代理具有相同目录和架构的反馈模型。此反馈模型是一种机制，可用于接受来自评审应用的反馈并将其记录到推理表。此模型在与您已部署代理相同的 CPU 型号服务端点中进行服务。由于此服务终结点已启用推理表，因此可以将来自“评审应用”的反馈记录到推理表。

注意

部署可能需要长达 15 分钟才能完成。原始 JSON 有效负载需要 10 到 30 分钟才能到达，大约每隔一小时从原始有效负载处理带格式的日志。


from databricks.agents import deploy
from mlflow.utils import databricks_utils as du

deployment = deploy(model_fqn, uc_model_info.version)

# query_endpoint is the URL that can be used to make queries to the app
deployment.query_endpoint

# Copy deployment.rag_app_url to browser and start interacting with your RAG application.
deployment.rag_app_url

从属资源的身份验证

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

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

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

自动身份验证直通

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

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

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

权限验证： Databricks 验证终结点创建者是否可以访问代理日志记录期间指定的所有依赖项。
服务主体创建和授予：为代理模型版本创建服务主体，并自动授予对代理资源的读取访问权限。

注意

系统生成的服务主体不会显示在 API 或 UI 列表中。如果从终结点中删除代理模型版本，也会删除服务主体。
凭据预配和轮换：服务主体的短期凭据（例如 M2M OAuth 令牌）被注入到端点，以便代理代码可以访问 Databricks 资源。 Databricks 还会轮换凭据，确保代理保持安全访问依赖资源的能力。

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

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

注意

Unity Catalog 资源还需要在父架构上具有 USE SCHEMA，并在父目录上具有 USE CATALOG。

资源类型	权限
SQL 仓库	使用终结点
模型服务终结点	可以查询
Unity 目录函数	执行
精灵空间	可以运行
矢量搜索索引	可以使用
Unity Catalog 表	SELECT

手动身份验证

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

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

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

监视已部署的代理

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

请参阅使用推理表监视已部署的代理。

获取已部署的应用程序

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

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 为 573d4a61-4adb-41bd-96db-0ec8cebc3744 的请求的响应正确无误，且位于检索器工具提取的上下文中。

通过