用 Databricks CLI 管理 Model…

需要在 Databricks 工作区中创建、更新、查询或运维 Model Serving 端点时使用。

适用场景

解决思路

1. 先使用父级 databricks-core 技能了解 CLI 基础、认证和 profile 选择。
2. 不要猜测命令语法：先运行 `databricks serving-endpoints -h` 列出所有子命令，再运行 `databricks serving-endpoints <subcommand> -h` 查看具体 flags、位置参数和 JSON 字段。
3. 创建端点前不要先 list 端点。用 `databricks serving-endpoints create <ENDPOINT_NAME> --json '{...}' --profile <PROFILE>`，JSON 中包含 served_entities（entity_name、entity_version、min/max_provisioned_throughput、workload_size、scale_to_zero_enabled）和 traffic_config.routes（served_entity_name、traffic_percentage）。
4. 创建是长时操作，CLI 默认等待完成；可用 `--no-wait` 立即返回，然后用 `databricks serving-endpoints get <ENDPOINT_NAME> --profile <PROFILE>` 轮询 `state.ready == "READY"`。
5. 如需 provisioned throughput 或 custom model 端点，运行 `databricks serving-endpoints create -h` 发现该类型所需的 JSON 字段。
6. 用 MLflow Deployments 客户端作为 Python 替代：`mlflow.deployments.get_deploy_client("databricks").create_endpoint(name=..., config={...})`，JSON 形状与 CLI 相同；注意 `tags=` 是顶层 kwarg 而非 config 内字段；`traffic_config.routes[].served_model_name` 格式为 `"<model>-<version>"`（如 `"turbine_failure-3"`），格式错误会导致路由静默不匹配。
7. 零停机版本切换：同时用 `registry.set_registered_model_alias(FULL_NAME, "prod", new_version)` 重指向别名，并调用 `deploy.update_endpoint(endpoint=ENDPOINT_NAME, config={...})` 传入新的 served_entities 和匹配的 traffic_config；只做一半是常见 bug。CLI 等价命令是 `databricks serving-endpoints update-config <NAME> --json '...'`。
8. 判断端点就绪时要同时轮询两个状态字段：`state.ready`（有可用配置即为 READY，版本切换期间仍为 READY）和 `state.config_update`（当前配置更新完成才为 NOT_UPDATING）。用 `databricks serving-endpoints get <ENDPOINT_NAME> --profile <PROFILE> | jq '{ready: .state.ready, config_update: .state.config_update}'`，仅当 ready == "READY" 且 config_update == "NOT_UPDATING" 才算完全就绪。
9. 查询 chat/agent 端点用 messages 数组：`databricks serving-endpoints query <ENDPOINT_NAME> --json '{"messages": [{"role": "user", "content": "Hello"}]}' --profile <PROFILE>`；chat 端点可加 `--stream` 流式响应。
10. 查询 classical-ML 端点用 dataframe_records（每行一条记录）：`databricks serving-endpoints query <ENDPOINT_NAME> --json '{"dataframe_records": [{"vibration": 0.42, "rpm": 18.3, "temp_c": 71.2}]}'`。
11. 查询 embeddings 或其他自定义 schema 前，先用 `databricks serving-endpoints get-open-api <ENDPOINT_NAME> --profile <PROFILE>` 获取 OpenAPI 3.1 schema，了解每个 served model 的请求/响应格式（路径如 `/served-models/<model-name>/invocations`）。
12. 其他运维命令：`list` 列出所有端点；`get <NAME>` 查看状态、配置、served entities；`delete <NAME>` 删除；`update-config <NAME> --json '...'` 更新 served entities 或流量（零停机，旧配置服务到新配置就绪）；`put-ai-gateway <NAME> --json '...'` 设置速率限制与用量追踪；`patch <NAME> --json '...'` 更新标签；`build-logs <NAME> <SERVED_MODEL>` 查看构建日志；`logs <NAME> <SERVED_MODEL>` 查看运行时日志；`export-metrics <NAME>` 导出 Prometheus 格式指标；`get-permissions <ENDPOINT_ID>` 查看权限（注意用端点 ID 十六进制字符串而非名称，ID 从 `get` 输出获取）。
13. SERVED_MODEL 参数从 `get` 输出的 `served_entities[].name` 获取。
14. 集成到 Databricks App：先运行 `databricks apps manifest --profile <PROFILE>` 检查是否有 `serving` 插件；若有则用 `databricks apps init --name <APP_NAME> --features serving --set "serving.serving-endpoint.name=<ENDPOINT_NAME>" --run none --profile <PROFILE>` 脚手架。
15. 若无 `serving` 插件，手动在现有 app 的 `databricks.yml` 中添加资源：`resources.apps.<app>.resources` 下加 `- name: my-model-endpoint` 和 `serving_endpoint: {name: <ENDPOINT_NAME>, permission: CAN_QUERY}`；并在 `app.yaml` 中注入环境变量 `SERVING_ENDPOINT`，`valueFrom: serving-endpoint`；然后通过 `serving()` 插件或 `onPluginsReady` 中的自定义路由接入端点。
16. 发现 Foundation Model API 端点时始终在运行时列出而非硬编码名称：`databricks serving-endpoints list | jq -r '.[] | select(.name | startswith("databricks-")) | select((.config.served_entities[0].entity_name // "") | startswith("system.ai.")) | "\(.task)\t\(.name)"' | sort`，同时按 `databricks-` 前缀和 served entity 属于 `system.ai.*` 过滤。
17. 用户未指定时的默认选择：agent 选编号最高的 Claude Sonnet，代码选编号最高的 `-codex-max`，embeddings 选 `databricks-gte-large-en`，实际名称从上面的实时列表解析。
18. 排查错误：`cannot configure default credentials` 用 `--profile` 或先认证；`PERMISSION_DENIED` 检查工作区权限，app 需声明 `serving_endpoint` 资源并授予 `CAN_QUERY`；端点卡在 `NOT_READY` 时 provisioned throughput 最多等 30 分钟并用 `build-logs <NAME> <ENTITY_NAME>` 查构建日志；`RESOURCE_DOES_NOT_EXIST` 用 `list` 验证端点名；查询返回 404 可能仍在 provisioning，用 `get` 检查 `state.ready`；`RATE_LIMIT_EXCEEDED` (429) 检查 `put-ai-gateway` 配置或退避重试；部署后 Serving UI 看不到端点是因为 UI 默认过滤 "Owned by me"，部署任务以 service principal 运行，切换到 "All" 即可，`databricks serving-endpoints list` 始终可见。

适用边界 · 注意事项

• 不适用于训练、MLflow autologging、UC 注册、自定义 PyFunc/ResponsesAgent 编写（用 databricks-ml-training）。
• 不适用于 Knowledge Assistants/Supervisor Agents（用 databricks-agent-bricks）。
• 不适用于 MLflow 评估（用 databricks-mlflow-evaluation）。