# 部署到 Databricks 应用程序 ## 配置文件配置 **重要提示：** 在运行任何“databricks” CLI 命令之前，请读取“.env”文件以获取“DATABRICKS_CONFIG_PROFILE”值。所有命令必须包含配置文件： databricks <命令> --profile <配置文件> 例如，如果“.env”具有“DATABRICKS_CONFIG_PROFILE=dev”，则运行“databricks bundle deploy --profile dev”。如果没有这个，CLI 可能会定位到错误的工作空间。 ## 应用程序命名约定除非用户指定不同的名称，否则应用程序应使用前缀“agent-*”： * `代理数据分析师` * `代理客户支持` * `代理代码助手` 更新“databricks.yml”中的应用程序名称：资源：应用程序： {{BUNDLE_NAME}}： name: "agent-your-app-name" # 使用agent-* 前缀 ## 部署命令 **重要：** 始终运行两个命令来部署和启动您的应用程序： # 1. 验证捆绑包配置（在部署之前捕获错误） databricks 捆绑验证 # 2. 部署包（创建/更新资源，上传文件） databricks 捆绑部署 # 3. 运行应用程序（使用上传的源代码启动/重新启动）- 必需！ databricks 捆绑包运行 {{BUNDLE_NAME}} > **注意：** `bundle deploy` 只上传文件和配置资源。 “bundle run”是使用新代码实际启动/重新启动应用程序所必需的。如果您只运行“deploy”，应用程序将继续运行旧代码！资源键“{{BUNDLE_NAME}}”与“resources.apps”下的“databricks.yml”中的应用程序名称匹配。 ## 处理“应用程序已存在”错误如果“databricks 包部署”失败并显示：错误：创建应用程序失败无法创建应用程序 <应用程序名称>。已存在同名应用程序。 **询问用户：**“您想要将现有应用程序绑定到此捆绑包，还是删除它并创建一个新应用程序？” ### 选项1：绑定现有应用程序（推荐） **第1步：** 获取现有应用程序的完整配置： # 获取应用配置，包括budget_policy_id和其他服务器端设置 databricks apps get --output json | databricks apps get --output json | jq '{名称，预算政策 ID，描述}' **步骤 2：** 更新 `databricks.yml` 以完全匹配现有应用程序的配置：资源：应用程序： {{BUNDLE_NAME}}： name: "existing-app-name" # 必须完全匹配 Budget_policy_id: "xxx-xxx-xxx" # 从步骤 1 复制（如果存在） > **为什么这很重要：** 现有应用程序可能具有不在您的捆绑包中的服务器端配置（例如“budget_policy_id”）。如果这些不匹配，Terraform 将失败并显示“Provider 在应用后产生不一致的结果”。在绑定之前始终将应用程序的当前配置同步到“databricks.yml”。 **步骤 3：** 如果部署到 `mode: production` 目标，请设置 `workspace.root_path`：目标：产品：方式: 生产工作区： root_path：/Workspace/Users/${workspace.current_user.userName}/.bundle/${bundle.name}/${bundle.target} > **为什么这很重要：** 生产模式需要显式根路径以确保仅部署捆绑包的一个副本。如果没有这个，部署将失败，并建议设置“workspace.root_path”。 **步骤4：** 检查是否已经绑定，如果需要则进行绑定： # 检查资源是否已由该包管理 databricks 捆绑摘要 --output json | jq '.resources.apps' # 如果应用程序出现在摘要中，则跳过绑定并转到步骤 5 # 如果摘要中没有，则绑定资源： databricks 捆绑包部署绑定 {{BUNDLE_NAME}} --auto-approve > **注意：** 如果绑定失败并显示“资源已由 Terraform 管理”，则应用程序已绑定到此捆绑包。跳到步骤5，直接部署。 **步骤 5：** 部署： databricks 捆绑部署 databricks 捆绑包运行 {{BUNDLE_NAME}} ### 选项 2：删除并重新创建 databricks 应用程序删除 <应用程序名称> databricks 捆绑部署 **警告：** 这将永久删除应用程序的 URL、OAuth 凭据和服务主体。 ## 解绑App 要删除捆绑包和已部署应用程序之间的链接： databricks 捆绑包部署取消绑定 {{BUNDLE_NAME}} 使用时： * 切换到不同的应用程序 * 让bundle创建一个新的应用程序 * 在部署的实例之间切换注意：解除绑定不会删除已部署的应用程序。 ## 查询已部署的应用程序 > **重要：** Databricks 应用程序**只能**通过 OAuth 令牌进行查询。您**不能**使用个人访问令牌 (PAT) 来查询您的代理。尝试使用 PAT 将导致 302 重定向错误。 **获取 OAuth 令牌：** databricks 身份验证令牌 | jq -r '.access_token' **发送请求：** curl -X POST <应用程序 URL>/调用 \ -H“授权：持有者”\ -H“内容类型：application/json”\ -d '{“输入”：[{“角色”：“用户”，“内容”：“嗨”}]，“流”：true }' **如果使用内存** \- 包含 `user_id` 来确定每个用户的内存范围： curl -X POST <应用程序 URL>/调用 \ -H“授权：持有者”\ -H“内容类型：application/json”\ -d'{ "input": [{"role": "user", "content": "你还记得我什么？"}], “custom_inputs”：{“user_id”：“user@example.com”} }' ## 代表 (OBO) 用户身份验证要以请求用户而不是应用服务主体身份进行身份验证：从agent_server.utils导入get_user_workspace_client # 在你的代理代码中 user_client = get_user_workspace_client() # 使用 user_client 执行应以用户身份运行的操作当您希望代理使用用户的权限而不是应用程序的服务主体权限访问资源时，这非常有用。请参阅：[OBO 身份验证文档]() ## 调试已部署的应用程序 # 查看日志（follow模式） databricks 应用程序日志 <应用程序名称> --follow # 检查应用程序状态 databricks apps get --output json | databricks apps get --output json | databricks apps get --output json | jq '{app_status，compute_status}' # 获取应用程序 URL databricks apps get --output json | databricks apps get --output json | databricks apps get --output json | jq -r '.url' ## 重要提示 * **应用程序命名约定** ：应用程序名称必须以 `agent-` 为前缀（例如，`agent-my-assistant`、`agent-data-analyst`） * **名称是不可变的**：更改`databricks.yml`中的`name`字段强制应用程序替换（销毁+创建） * **远程 Terraform 状态** ：Databricks 远程存储状态；跨目录检测到相同的应用程序 * **审查计划** ：在确认之前在 Terraform 输出中查找“#forces replacement” ## 常见问题解答 **问：我在日志中看到 200 OK，但在实际流中出现错误。发生了什么事？ ** 这是预期的行为。最初的 200 OK 确认流设置成功。流式传输期间发生的错误不会影响初始 HTTP 状态代码。检查流内容以获取实际的错误消息。 **问：查询我的代理时，我收到 302 重定向错误。怎么了？** 您可能正在使用个人访问令牌 (PAT)。 Databricks 应用程序仅支持 OAuth 令牌。生成一个： databricks 身份验证令牌 **问：如何向我的代理添加依赖项？** 使用“uv add”： uv 添加 # 示例：uv add "mlflow-skinny[databricks]" ## 故障排除问题 |解决方案 ---|--- 验证错误 |部署前运行“databricks bundle validate”以查看详细错误运行时权限错误 |在`databricks.yml`中授予资源（参见**add-tools**技能） Lakebase 访问错误 |请参阅 **lakebase-setup** 技能了解权限（如果使用内存）应用程序未启动 |检查“databricks 应用程序日志 <应用程序名称>” 身份验证令牌已过期 |再次运行“databricks auth token” 302 重定向错误 |使用 OAuth 令牌，而不是 PAT “提供商产生了不一致的结果”|将应用程序配置同步到“databricks.yml” “应该设置workspace.root_path” |将 `root_path` 添加到生产目标部署后运行旧代码的应用程序 |部署后运行“databricks bundle run {{BUNDLE_NAME}}” 部署的应用程序中的环境变量为 None |检查 databricks.yml `config.env` 中的 `value_from` 是否与资源 `name` 匹配

部署

包含技能