为生成式 AI 应用程序部署代理
重要
此功能目前以公共预览版提供。
本文介绍如何使用 deploy() Agent Framework Python API 中的函数部署 AI 代理。
要求
MLflow 2.13.1 或更高版本，用于通过
databricks.agents中的deploy()API 部署代理。将 AI 代理注册到 Unity Catalog。 请参阅将链注册到 Unity Catalog。
安装
databricks-agentsSDK。%pip install databricks-agents dbutils.library.restartPython()
使用 deploy() 部署代理
deploy （） 函数执行以下操作：
- 为代理创建可集成到面向用户的应用程序中的 CPU 模型服务终结点。
- 若要降低空闲终结点的成本（代价是为初始查询提供服务的时间增加），可以通过传递给
scale_to_zero_enabled=Truedeploy()服务终结点，为服务终结点启用缩放到零。 请参阅 终结点缩放预期。 - 在这些模型服务终结点上启用了推理表。 请参阅用于监视和调试模型的推理表。
- 身份验证凭据会自动传递给代理在记录模型时指定的所有由 Databricks 管理的所需资源。 Databricks 创建有权访问这些资源的服务主体，并自动将其传递到终结点。 请参阅从属资源的身份验证。
- 如果你有非 Databricks 托管的资源依赖项（例如使用 Pinecone），则可以将包含机密的环境变量传递给
deploy()API。 请参阅配置从模型服务终结点对资源的访问权限。
- 如果你有非 Databricks 托管的资源依赖项（例如使用 Pinecone），则可以将包含机密的环境变量传递给
- 若要降低空闲终结点的成本（代价是为初始查询提供服务的时间增加），可以通过传递给
- 为代理启用评审应用。 评审应用允许利益干系人与代理聊天，并使用评审应用 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 |
结构 | 一个结构字段，其中包含针对响应检索到的文档的任何反馈数据。 |
依赖资源的权限要求
使用依赖资源部署模型时，终结点的创建者必须具有以下权限，具体取决于资源类型：
| 资源类型 | 权限 |
|---|---|
| Sql Warehouse | 使用终结点 |
| 模型服务终结点 | 可以查询 |
| Unity 目录函数 | 执行 |
| Genie 空间 | 执行 |
| 矢量搜索索引 | ReadVectorIndex |
| Unity 目录表 | 可读取 |
从属资源的身份验证
在为代理部署创建模型服务终结点时，Databricks 会验证终结点的创建者是否具有必要的权限，能够访问代理依赖的所有资源。
对于 LangChain 风格的代理，会在代理创建和日志记录期间自动推断从属资源。 这些资源将记录在所记录的模型项目中的 resources.yaml 文件中。 在部署期间，databricks.agents.deploy 会自动创建访问这些推断的资源依赖项并与之通信所需的 M2M OAuth 令牌。
对于 PyFunc 风格的代理，必须在 resources 参数中记录已部署的代理期间手动指定任何资源依赖项。 请参阅 指定 PyFunc 或 LangChain 代理的资源。
在部署期间，databricks.agents.deploy 会创建一个 M2M OAuth 令牌（该令牌有权访问 resources 参数中指定的资源），并将其部署到已部署的代理。
自动身份验证直通
下表列出了支持自动身份验证直通的功能。 自动身份验证直通使用部署创建者的凭据，自动对受支持的功能进行身份验证。
| 功能 | 最低 mlflow 版本 |
|---|---|
| 矢量搜索索引 | 需要 mlflow 2.13.1 或更高版本 |
| 模型服务终结点 | 需要 mlflow 2.13.1 或更高版本 |
| SQL 仓库 | 需要 mlflow 2.16.1 或更高版本 |
| Unity 目录函数 | 需要 mlflow 2.16.1 或更高版本 |
手动身份验证
如果依赖资源不支持自动身份验证直通，或者你要使用部署创建者之外的凭据，则可以使用基于机密的环境变量手动提供凭据。 例如，如果在代理中使用 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
可以在和retrieval_assessments.ratings字段中传递其他键值对或不同的键值对text_assessments.ratings，以提供不同类型的反馈。 在此示例中，反馈有效负载指示代理对 ID 为 ID 573d4a61-4adb-41bd-96db-0ec8cebc3744 的请求的响应正确、准确且位于检索器工具提取的上下文中。