databricks-langgraph-rag-agent

# LangGraph RAG 智能体在 Databricks 上 可重复使用的演示：一个 **LangGraph 智能体**，具有 **检索（AI 搜索）+ 网络搜索 + 工具**，作为 MLflow 的 **`ResponsesAgent`** 编写，通过 **聊天应用程序**提供服务，并由 **Unity AI Gateway** 管理 — 所有这些都在 Databricks 上。基于官方的 [`databricks/app-templates/agent-langgraph`](https://github.com/databricks/app-templates/tree/main/agent-langgraph) 模板 — 该存储库仅保留与演示相关的文件和自定义；请参阅上游模板以获取完整的基础结构。 **此演示展示的内容（及其使用的最新功能）：** - **通过 AI 搜索（向量搜索）进行 RAG** — 智能体通过 **向量搜索 MCP** 服务器从 Unity 目录索引中检索。`setup_kb_table` 作业（`notebooks/setup_kb_table.py`）从中创建源 Delta 表和索引。 - **网络搜索** — 可选的 You.com（或其他）**外部 MCP** 工具；设置 `WEB_SEARCH_CONNECTION` 以启用。（仅限 Claude，按令牌付费。） - **工具** — 本地函数工具 + 内置的 `system.ai` 代码解释器 / UC 函数 MCP。 - **LLM** — `ChatDatabricks`，通过 **Unity AI Gateway** 端点（`USE_AI_GATEWAY=true`）路由，可以在不更改智能体代码的情况下跨 **Gemini、GPT 和 Claude** 分流流量并回退。 - **`ResponsesAgent` + 聊天 UI + 应用程序** — 通过 DAB 部署到 Databricks 应用程序；包含 MLflow 跟踪 + `evaluate_agent.py`。 **设置顺序：**（1）配置 `databricks.yml` 中的环境变量（`LLM_ENDPOINT`、`RAG_CATALOG`/`RAG_SCHEMA`、`WEB_SEARCH_CONNECTION`、`USE_AI_GATEWAY`），并在 `targets` 下设置工作区的 `host`；（2）`uv run quickstart`；（3）`databricks bundle deploy`（也运行创建表和索引的 `setup_kb_table` 作业）；然后 `databricks bundle run langgraph_rag_agent`。 智能体线路位于 `agent_server/agent.py`（MCP 服务器 + 模型 + 系统提示）。 --- ## 模板参考（来自 `agent-langgraph`） 该模板定义了一个对话式智能体应用程序。该应用程序带有内置的聊天 UI，但也公开了一个 API 端点来调用智能体，以便您可以将 UI 部署在其他地方（例如，在您的网站或移动应用程序中）。 该模板中的智能体实现了 [OpenAI Responses API](https://platform.openai.com/docs/api-reference/responses) 接口。它附带了一个示例 `get_current_time` 工具。智能体代码包括注释掉的示例，展示了如何连接到 [Databricks MCP 服务器](https://docs.databricks.com/aws/en/generative-ai/agent-framework/agent-tool)（包括内置的代码解释器、向量搜索、Genie 和 UC 函数）。您可以自定义智能体代码并通过 API 或 UI 测试它。 智能体输入和输出格式由 MLflow 的 ResponsesAgent 接口定义，该接口与 [OpenAI Responses API](https://platform.openai.com/docs/api-reference/responses) 接口密切相关。请参阅 [MLflow 文档](https://mlflow.org/docs/latest/genai/flavors/responses-agent-intro/) 以获取输入和输出格式、跟踪要求和其他智能体创作详细信息。 ## 使用 AI 助手构建 我们建议使用 AI 编码助手（Claude Code、Cursor、GitHub Copilot）来自定义和部署此模板。`.claude/skills/` 中的智能体技能提供了常见任务的分步指南，例如设置、添加工具和部署。这些技能被 Claude、Cursor 和 GitHub Copilot 自动检测。 ## 快速开始 运行 `uv run quickstart` 脚本以快速设置本地环境并启动智能体服务器。在任何步骤中，如果出现问题，请参考下面的手动本地开发循环设置。 该脚本将： 1. 验证 uv、nvm 和 Databricks CLI 安装 2. 配置 Databricks 身份验证 3. 配置智能体跟踪，方法是创建并链接 MLflow 实验到您的应用程序 4. 启动智能体服务器和聊天应用程序 ```bash uv run quickstart ``` 设置完成后，您可以通过以下方式在本地启动智能体服务器和聊天应用程序： ```bash uv run start-app ``` 这将启动智能体服务器和聊天应用程序，地址为 http://localhost:8000。 **下一步**：请参阅 [修改您的智能体](#修改您的智能体) 以自定义和迭代智能体代码。 ## 手动本地开发循环设置 1. **设置本地环境** 安装 `uv`（Python 包管理器）、`nvm`（节点版本管理器）和 Databricks CLI： - [`uv` 安装文档](https://docs.astral.sh/uv/getting-started/installation/) - [`nvm` 安装](https://github.com/nvm-sh/nvm?tab=readme-ov-file#installing-and-updating) - 运行以下命令以使用 Node 20 LTS： ```bash nvm use 20 ``` - [`databricks CLI` 安装](https://docs.databricks.com/aws/en/dev-tools/cli/install) 2. **设置本地身份验证到 Databricks** 为了在本地开发智能体时访问 Databricks 资源，您需要使用 Databricks 进行身份验证。请选择以下选项之一： **选项 1：通过 Databricks CLI 进行 OAuth（推荐）** 使用 CLI 与 Databricks 进行身份验证。请参阅 [CLI OAuth 文档](https://docs.databricks.com/aws/en/dev-tools/cli/authentication#oauth-user-to-machine-u2m-authentication)。 ```bash databricks auth login ``` 在您的 `.env` 文件中设置 `DATABRICKS_CONFIG_PROFILE` 环境变量为用于身份验证的配置文件： ```bash DATABRICKS_CONFIG_PROFILE="DEFAULT" # 更改为配置文件名称 ``` **选项 2：个人访问令牌（PAT）** 请参阅 [PAT 文档](https://docs.databricks.com/aws/en/dev-tools/auth/pat#databricks-personal-access-tokens-for-workspace-users)。 ```bash # 将以下内容添加到您的 .env 文件中 DATABRICKS_HOST="https://host.databricks.com" DATABRICKS_TOKEN="dapi_token" ``` 请参阅 [Databricks SDK 身份验证文档](https://docs.databricks.com/aws/en/dev-tools/sdk-python#authenticate-the-databricks-sdk-for-python-with-your-databricks-account-or-workspace)。 3. **创建并链接 MLflow 实验到您的应用程序** 创建 MLflow 实验以启用跟踪和版本跟踪。这由 `uv run quickstart` 脚本自动完成。 通过 CLI 创建 MLflow 实验： ```bash DATABRICKS_USERNAME=$(databricks current-user me | jq -r .userName) databricks experiments create-experiment /Users/$DATABRICKS_USERNAME/agents-on-apps ``` 将 `.env.example` 复制到 `.env` 并更新 `.env` 文件中的 `MLFLOW_EXPERIMENT_ID` 为您创建的实验 ID。`.env` 文件将在启动服务器时自动加载。 ```bash cp .env.example .env # 编辑 .env 并填写实验 ID ``` 请参阅 [MLflow 实验文档](https://docs.databricks.com/aws/en/mlflow/experiments#create-experiment-from-the-workspace)。 4. **在本地测试您的智能体** 在本地启动智能体服务器和聊天 UI： ```bash uv run start-app ``` 通过 UI（http://localhost:8000）或 REST API 查询您的智能体： **高级服务器选项： ```bash uv run start-server --reload # 代码更改时热重载服务器 uv run start-server --port 8001 # 更改服务器监听的端口 uv run start-server --workers 4 # 使用多个工作线程运行服务器 ``` - 示例流式请求： ```bash curl -X POST http://localhost:8000/invocations \ -H "Content-Type: application/json" \ -d '{ "input": [{ "role": "user", "content": "hi" }], "stream": true }' ``` - 示例非流式请求： ```bash curl -X POST http://localhost:8000/invocations \ -H "Content-Type: application/json" \ -d '{ "input": [{ "role": "user", "content": "hi" }] }' ``` ## 修改您的智能体 请参阅 [LangGraph 文档](https://docs.langchain.com/oss/python/langgraph/quickstart) 以获取有关如何编辑您自己的智能体的更多信息。 托管 MLflow `AgentServer` 需要的文件： - `agent.py`：包含您的智能体逻辑。修改此文件以创建自定义智能体。例如，您可以 [添加智能体工具](https://docs.databricks.com/aws/en/generative-ai/agent-framework/agent-tool) 以赋予您的智能体额外功能。 - `start_server.py`：使用 `agent_type="ResponsesAgent"` 初始化并运行 MLflow `AgentServer`。您不需要修改此文件以适应大多数常见用例，但可以在此处添加其他服务器路由（例如 `/metrics` 端点）。 **常见自定义问题：** **问：我可以向我的智能体添加其他文件或文件夹吗？** 是的。根据需要添加其他文件或文件夹。确保 `pyproject.toml` 中的脚本运行正确的脚本以启动服务器并设置 MLflow 跟踪。 **问：如何向我的智能体添加依赖项？** 运行 `uv add <package_name>`（例如，`uv add "mlflow-skinny[databricks]"`）。请参阅 [Python pyproject.toml 指南](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#dependencies-and-requirements)。 **问：我可以在内置跟踪之外添加自定义跟踪吗？** 是的。该模板使用 MLflow 的智能体服务器，它带有对使用 `@invoke()` 和 `@stream()` 装饰的智能体逻辑的自动跟踪。它还使用 [MLflow 自动日志 API](https://mlflow.org/docs/latest/genai/tracing/#one-line-auto-tracing-integrations) 来捕获 LLM 调用跟踪。但是，您可以添加额外的检测以在智能体运行时捕获更细粒度的跟踪信息。请参阅 [MLflow 跟踪文档](https://docs.databricks.com/aws/en/mlflow3/genai/tracing/app-instrumentation/). **问：如何使用额外的工具和功能扩展此示例？** 此模板可以通过集成额外的 MCP 服务器、向量搜索索引、UC 函数和 Databricks 工具来扩展。请参阅 [“智能体框架工具文档”](https://docs.databricks.com/aws/en/generative-ai/agent-framework/agent-tool)。 ## 评估您的智能体 通过调用您为智能体定义的 invoke 函数来评估您的智能体。 - 更新您的 `evaluate_agent.py` 文件以使用首选的评估数据集和评估指标。 使用评估脚本运行评估： ```bash uv run agent-evaluate ``` 完成后，打开您的实验的 MLflow UI 链接以检查结果。 ## 部署到 Databricks 应用程序 此模板使用 [Databricks 资产包（DAB）](https://docs.databricks.com/aws/en/dev-tools/bundles/) 进行部署。`databricks.yml` 文件定义了应用程序配置和资源权限。 > **`app.yaml` 与 `databricks.yml` **：`app.yaml` 用于通过 `databricks apps deploy`（手动路径）部署。当通过 DAB（`databricks bundle deploy`）部署时，`databricks.yml` 中的 `config:` 部分优先。如果您更改环境变量或启动命令，请更新 `databricks.yml` — 这是 DAB 读取的内容。 确保您已安装并配置了 [Databricks CLI](https://docs.databricks.com/aws/en/dev-tools/cli/tutorial)。 1. **运行预飞行检查** 在本地启动智能体，发送测试请求，并验证响应以尽早发现配置和代码错误： ```bash uv run preflight ``` 2. **验证包配置** 在部署前捕获任何配置错误： ```bash databricks bundle validate ``` 3. **部署包** 这会上传您的代码并配置 `databricks.yml` 中定义的资源（MLflow 实验、服务终结点等）： ```bash databricks bundle deploy ``` 4. **启动或重启应用程序** ```bash databricks bundle run agent_langgraph ``` > **注意：** `bundle deploy` 仅上传文件并配置资源。`bundle run` 是 **必需的** 以实际启动/重启具有新代码的应用程序。 要授予对其他资源（服务终结点、Genie 空间、UC 函数、向量搜索）的访问权限，请在 `databricks.yml` 中添加它们并重新部署。请参阅 [Databricks 应用程序资源文档](https://docs.databricks.com/aws/en/dev-tools/databricks-apps/resources)。 **代表用户（OBO）身份验证**：使用 `agent_server.utils` 中的 `get_user_workspace_client()` 以代表请求用户而不是应用程序服务主体进行身份验证。请参阅 [OBO 身份验证文档](https://docs.databricks.com/aws/en/dev-tools/databricks-apps/auth?language=Streamlit#retrieve-user-authorization-credentials)。 5. **在 Databricks 应用程序上查询您的智能体** 您必须使用 Databricks OAuth 令牌来查询 Databricks 应用程序上的智能体。请参阅 [查询智能体](https://docs.databricks.com/aws/en/generative-ai/agent-framework/query-agent) 以获取完整详细信息。 **使用 Python 的 Databricks OpenAI 客户端：** ```bash uv pip install databricks-openai ``` ```python from databricks.sdk import WorkspaceClient from databricks_openai import DatabricksOpenAI w = WorkspaceClient() client = DatabricksOpenAI(workspace_client=w) # 非流式 response = client.responses.create( model="apps/<app-name>", input=[{"role": "user", "content": "hi"}], ) print(response) # 流式 streaming_response = client.responses.create( model="apps/<app-name>", input=[{"role": "user", "content": "hi"}], stream=True, ) for chunk in streaming_response: print(chunk) ``` **使用 curl：** ```bash # 生成 OAuth 令牌 databricks auth login --host <https://host.databricks.com> databricks auth token ``` ```bash # 流式请求 curl --request POST \ --url <app-url>.databricksapps.com/responses \ --header "Authorization: Bearer <oauth-token>" \ --header "Content-Type: application/json" \ --data '{ "input": [{ "role": "user", "content": "hi" }], "stream": true }' ``` ```bash # 非流式请求 curl --request POST \ --url <app-url>.databricksapps.com/responses \ --header "Authorization: Bearer <oauth-token>" \ --header "Content-Type: application/json" \ --data '{ "input": [{ "role": "user", "content": "hi" }] }' ``` 对于未来更新，请运行 `databricks bundle deploy` 和 `databricks bundle run agent_langgraph` 以重新部署。 ### 常见问题 - **`databricks bundle deploy` 失败，提示“具有相同名称的应用程序已经存在”** 这发生在以前在 DAB 之外创建了具有相同名称的应用程序。要修复，请将现有应用程序绑定到您的包： ```bash # 1. 获取现有应用程序的配置（注意 budget_policy_id 如果存在） databricks apps get <app-name> --output json | jq '{name, budget_policy_id, description}' # 2. 更新 databricks.yml 以包含 budget_policy_id 如果它在上面返回 # 3. 将现有应用程序绑定到您的包 databricks bundle deployment bind agent_langgraph <app-name> --auto-approve # 4. 部署 databricks bundle deploy ``` 否则，请删除现有应用程序并重新部署：`databricks apps delete <app-name>`（这永久删除应用程序的 URL 和服务主体）。 - **`databricks bundle deploy` 失败，提示“提供者产生不一致的结果后应用”** 现有应用程序有服务器端配置（如 `budget_policy_id`）与您的 `databricks.yml` 不匹配。运行 `databricks apps get <app-name> --output json` 并同步任何缺失的字段到您的 `databricks.yml`。 - **应用程序在 `databricks bundle deploy` 后运行旧代码** `bundle deploy` 仅上传文件并配置资源。您必须运行 `databricks bundle run agent_langgraph` 以实际启动/重启具有新代码的应用程序。 ### FAQ - 对于流式响应，我在日志中看到 200 OK，但在实际流中出现错误。怎么回事？ - 这是预期行为。初始的 200 OK 确认流设置；流错误不会影响此状态。 - 查询我的智能体时，我收到 302 错误。怎么回事？ - 使用 OAuth 令牌。PAT 不支持查询智能体。