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

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

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

• 模型服务管理自动缩放、日志记录、版本控制和访问控制，使你能够专注于开发质量代理。
• 主题专家可以使用评审应用与部署的代理交互，并提供反馈，你可以将其纳入监视和评估。
• 可以通过评估实时流量来监视代理。 尽管用户流量不包括基本情况，但 LLM 评委（和你创建的自定义指标）执行无监督评估。

Requirements

• 使用来自deploy()的databricks.agents API 部署代理时，需使用 MLflow 2.13.1 或更高版本。

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

有关所有身份验证方法以及何时使用它们的综合信息，请参阅 AI 代理的身份验证。

监视已部署的代理

将代理部署到 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

请参阅 Databricks 代理 Python API。

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

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

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

其他资源

• 查询已部署的 Mosaic AI 代理
• Mosaic AI 代理评估 (MLflow 2)
• 使用评审应用对生成式 AI 应用进行人工评审（MLflow 2）
• 调试已部署的 AI 代理