调试已部署的 AI 代理

2025-05-14

本页介绍如何使用马赛克 AI 代理框架的 agents.deploy() API 部署 AI 代理时调试常见问题。

代理框架部署到模型服务终结点，因此除了本页上的代理调试步骤外，还应查看模型服务的调试指南。

使用最佳做法创作代理

在创作代理时，请使用以下最佳做法：

通过使用推荐的代理创作接口和 MLflow 跟踪来改进调试：遵循代码中 AI 代理编写的最佳实践，例如启用 MLflow 跟踪自动记录，以使您的代理更易于调试。
明确文档工具：清晰的工具和参数说明可确保代理人了解工具并适当使用这些工具。请参阅使用清晰文档改进调用工具。
向 LLM 调用添加超时和令牌限制：向代码中的 LLM 调用添加超时和令牌限制，以避免长时间运行的步骤导致的延迟。
- 如果代理使用 OpenAI 客户端查询 Databricks LLM 服务终结点，请根据需要在服务终结点调用上设置自定义超时。

针对已部署代理的请求速度缓慢或失败进行调试

如果在创作代理时启用了 MLflow 跟踪自动记录，则跟踪会自动记录在推理表中。这些跟踪可以帮助识别速度缓慢或失败的代理组件。

识别有问题的请求

按照以下步骤查找有问题的请求：

在工作区中，转到“ 服务 ”选项卡并选择部署名称。
在 “推理表 ”部分中，找到推理表的完全限定名称。例如，my-catalog.my-schema.my-table。

在 Databricks 笔记本中运行以下命令：

%sql
SELECT * FROM my-catalog.my-schema.my-table

检查 “响应 ”列以获取详细的跟踪信息。
在request_time、databricks_request_id或status_code上筛选以缩小结果范围。
```
%sql
SELECT * FROM my-catalog.my-schema.my-table
WHERE status_code != 200
```

分析根本原因问题

识别失败或速度缓慢的请求后，请使用 mlflow.models.validate_serving_input API 针对失败的输入请求调用代理。然后，查看生成的跟踪，并针对失败的响应执行根本原因分析。

为了更快的开发循环，可以直接更新智能体代码，并通过针对失败的输入示例调用智能体进行迭代。

调试身份验证错误

如果部署的代理在访问矢量搜索索引或 LLM 终结点等资源时遇到身份验证错误，请检查它是否已记录自动身份验证直通所需的资源。请参阅自动身份验证直通。

若要检查记录的资源，请在笔记本中运行以下命令：

%pip install -U mlflow[databricks]
%restart_python

import mlflow
mlflow.set_registry_uri("databricks-uc")

# Replace with the model name and version of your deployed agent
agent_registered_model_name = ...
agent_model_version = ...

model_uri = f"models:/{agent_registered_model_name}/{agent_model_version}"
agent_info = mlflow.models.Model.load(model_uri)
print(f"Resources logged for agent model {model_uri}:", agent_info.resources)

若要重新添加缺失或不正确的资源，必须记录代理并重新部署它。

如果对资源使用手动身份验证，请验证是否已正确设置环境变量。手动设置会替代任何自动身份验证配置。请参阅手动身份验证。

通过