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

项目
02/10/2025

重要

此功能目前以公共预览版提供。

本文介绍如何使用 Agent Framework Python APIdeploy()函数部署 AI 代理。

要求

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=Truedeploy()服务终结点，为服务终结点启用缩放到零。请参阅终结点缩放预期。
- 在模型服务终结点上使用 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

代理增强的推理表

deploy() 为每个部署创建三个推理表，以记录发往/来自代理服务终结点的请求和响应。用户可以预期数据在与部署交互后一小时内出现在有效负载表中。

有效负载请求日志和评估日志可能需要更长时间才能填充，但最终派生自原始有效负载表。可以自行从有效负载表提取请求和评估日志。有效负载表的删除和更新不会反映在有效负载请求日志或有效负载评估日志中。

注意

如果启用了 Azure 存储防火墙，请联系 Databricks 客户团队为终结点启用推理表。

表	示例 Unity Catalog 表名	每个表中的内容
有效负载	`{catalog_name}.{schema_name}.{model_name}_payload`	原始 JSON 请求和响应有效负载
有效负载请求日志	`{catalog_name}.{schema_name}.{model_name}_payload_request_logs`	带格式的请求和响应，MLflow 跟踪
有效负载评估日志	`{catalog_name}.{schema_name}.{model_name}_payload_assessment_logs`	针对每个请求的带格式反馈（在评审应用中提供）

以下显示了请求日志表的架构。

列名称	类型	说明
`client_request_id`	字符串	客户端请求 ID，通常为 `null`。
`databricks_request_id`	字符串	Databricks 请求 ID。
`date`	日期	请求日期。
`timestamp_ms`	Long	时间戳（以毫秒为单位）。
`timestamp`	时间戳	请求的时间戳。
`status_code`	Integer	终结点的状态代码。
`execution_time_ms`	Long	总执行毫秒数。
`conversation_id`	字符串	从请求日志中提取的对话 ID。
`request`	字符串	用户对话中的最后一个用户查询。这是从 RAG 请求中提取的。
`response`	字符串	用户的上一个响应。这是从 RAG 请求中提取的。
`request_raw`	字符串	请求的字符串表示形式。
`response_raw`	字符串	响应的字符串表示形式。
`trace`	字符串	从 `databricks_options` 响应结构中提取的跟踪的字符串表示形式。
`sampling_fraction`	双精度	抽样分数。
`request_metadata`	Map[String, String]	与请求关联的模型服务终结点相关的元数据映射。此映射包含终结点使用的终结点名称、模型名称和模型版本。
`schema_version`	字符串	架构版本的整数。

以下是评估日志表的架构。

列名称	类型	说明
`request_id`	字符串	Databricks 请求 ID。
`step_id`	字符串	派生自检索评估。
`source`	结构	一个结构字段，其中包含有关评估创建者的信息。
`timestamp`	时间戳	请求的时间戳。
`text_assessment`	结构	一个结构字段，其中包含来自审阅应用的代理响应的任何反馈数据。
`retrieval_assessment`	结构	一个结构字段，其中包含针对响应检索到的文档的任何反馈数据。

从属资源的身份验证

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 目录函数	EXECUTE
Genie 空间	可以运行
矢量搜索索引	可以使用
Unity 目录表	SELECT

手动身份验证

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

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

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

获取已部署的应用程序

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

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

请注意，此行为是实验性的：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 Delta Live Tables"
                      }
                  ],
                  "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 的请求的响应正确、准确且位于检索器工具提取的上下文中。

通过