databricks-model-serving

模型服务端点

首先：使用上级 databricks-core 技能了解 CLI 基础知识、身份验证和配置文件选择。

**网关边界：**此技能负责配置附加到模型服务端点的旧版 AI Gateway，例如 serving-endpoints put-ai-gateway。明确请求 Unity Gateway / Unity AI Gateway，或请求任何 databricks ai-gateway 模型服务、MCP 服务或模型提供商服务时，应使用 databricks-unity-gateway。

Model Serving 提供托管端点，可将大模型、自定义 ML 模型和外部模型作为可扩展的 REST API 提供服务。端点由名称标识（在每个工作区内唯一）。

端点类型

类型	适用场景	关键细节
按 Token 付费	Foundation Model API（Llama、GPT-5、Claude、Gemini 等）	使用 system.ai.* 目录模型，这些模型已预先配置在每个工作区中。请在运行时发现模型，参见下文的 Foundation Model API 端点。
预配吞吐量	专用 GPU 容量	吞吐量有保障，成本更高
自定义模型	自有 MLflow 模型或容器	可通过 MLflow 签名部署任意模型

端点结构

Serving Endpoint (top-level, identified by NAME)
  ├── Config
  │     ├── Served Entities (model references + scaling config)
  │     └── Traffic Config (routing percentages across entities)
  ├── AI Gateway (rate limits, usage tracking)
  └── State (READY / NOT_READY, config_update status)

• 服务实体：每个实体都引用一个模型（来自 Unity Catalog 或 MLflow），并带有扩缩参数。从 get 输出中的 served_entities[].name 获取实体名称，以用于 build-logs 和 logs 命令。
• 流量配置：按百分比将请求路由到各个服务实体（用于 A/B 测试和金丝雀部署）。
• 状态：创建端点或更新配置后，端点会从 NOT_READY 转为 READY。通过 get 轮询并检查 state.ready。

CLI 探索——务必先执行

**不要猜测命令语法。**动态探索可用命令及其用法：

# List all serving-endpoints subcommands
databricks serving-endpoints -h

# Get detailed usage for any subcommand (flags, args, JSON fields)
databricks serving-endpoints <subcommand> -h

构造任何命令前，先运行 databricks serving-endpoints -h。运行 databricks serving-endpoints <subcommand> -h，探索该子命令的准确标志、位置参数和 JSON 规格字段。

创建端点

创建前不要列出端点。

databricks serving-endpoints create <ENDPOINT_NAME> \
  --json '{
    "served_entities": [{
      "entity_name": "<MODEL_CATALOG_PATH>",
      "entity_version": "<VERSION>",
      "min_provisioned_throughput": 0,
      "max_provisioned_throughput": 0,
      "workload_size": "Small",
      "scale_to_zero_enabled": true
    }],
    "traffic_config": {
      "routes": [{
        "served_entity_name": "<ENTITY_NAME>",
        "traffic_percentage": 100
      }]
    }
  }' --profile <PROFILE>

• 探索可用的 Foundation Model：参见下文的 Foundation Model API 端点，了解运行时列表代码片段和默认模型选择规则。你也可以在 Unity Catalog 中查看 system.ai 目录，或运行 databricks serving-endpoints list --profile <PROFILE>，查看工作区中已部署的端点。使用 databricks serving-endpoints get-open-api <ENDPOINT_NAME> --profile <PROFILE> 检查特定端点的 API 架构。
• 这是长时间运行的操作；CLI 默认会等待其完成。使用 --no-wait 立即返回，然后轮询：

  databricks serving-endpoints get <ENDPOINT_NAME> --profile <PROFILE>
  # Check: state.ready == "READY"
  

• 对于预配吞吐量或自定义模型端点，运行 databricks serving-endpoints create -h，探索适用于相应端点类型的必填 JSON 字段。

MLflow 部署客户端（Python 替代方案）

mlflow.deployments.get_deploy_client("databricks").create_endpoint(name=..., config={...}) 接受与 CLI 相同的 JSON 结构。注意以下两点：

• tags= 是顶层关键字参数，不是 config 内的字段。其形状与 serving-endpoints patch --add-tags 相同，即 [{key, value}]。
• traffic_config.routes[].served_model_name = "<model>-<version>"（例如 "turbine_failure-3"）。API 会根据实体自动推导此值，但你需要在 traffic_config 中引用完全相同的字符串——格式错误会导致路由静默失效。

零停机版本切换

要将端点切换到新模型版本：重新指定别名，并且使用新的 served_entities 和匹配的 traffic_config 调用 update_endpoint。遗漏其中任一环节都是常见错误——仅更新别名不会更新端点；仅调用 update_endpoint 则会让别名仍指向旧版本。

from mlflow.tracking import MlflowClient
from mlflow.deployments import get_deploy_client

registry = MlflowClient(registry_uri="databricks-uc")
deploy   = get_deploy_client("databricks")

registry.set_registered_model_alias(FULL_NAME, "prod", new_version)
deploy.update_endpoint(endpoint=ENDPOINT_NAME, config={
    "served_entities": [{"entity_name": FULL_NAME, "entity_version": new_version,
                         "workload_size": "Small", "scale_to_zero_enabled": True}],
    "traffic_config": {"routes": [
        {"served_model_name": f"{NAME}-{new_version}", "traffic_percentage": 100}
    ]},
})

对应的 CLI 命令是 databricks serving-endpoints update-config <NAME> --json '...'。无论使用哪种方式，之后都要轮询 state.ready 和 state.config_update——请参阅下文的“端点就绪状态”。

端点就绪状态

调用 create 或 update-config 后，端点会配置计算资源并加载模型。端点就绪之前，请勿查询端点。 两个状态字段很重要，且含义不同：

• state.ready——端点具有任意可用配置后变为 READY。版本切换期间会保持 READY。
• state.config_update——当前配置更新完成后变为 NOT_UPDATING；版本切换期间为 IN_PROGRESS。

仅监控 state.ready 的循环会在版本切换过程中误报“就绪”，此时旧版本仍在提供服务。请同时轮询两者：

databricks serving-endpoints get <ENDPOINT_NAME> --profile <PROFILE> \
  | jq '{ready: .state.ready, config_update: .state.config_update}'
# Fully ready when ready == "READY" AND config_update == "NOT_UPDATING"

配置资源可能需要几分钟。预配吞吐量端点耗时最长（需要分配 GPU）。查询尚未处于 READY 状态的端点会返回 404 或 503。

查询端点

聊天 / Agent 端点使用 messages 数组：

databricks serving-endpoints query <ENDPOINT_NAME> \
  --json '{"messages": [{"role": "user", "content": "Hello"}]}' --profile <PROFILE>

传统 ML 端点使用 dataframe_records（每行一条记录）：

databricks serving-endpoints query <ENDPOINT_NAME> \
  --json '{"dataframe_records": [{"vibration": 0.42, "rpm": 18.3, "temp_c": 71.2}]}'

• 聊天端点的流式响应请使用 --stream。
• 对于嵌入或其他自定义架构：请先使用 get-open-api <ENDPOINT_NAME> 来发现请求 / 响应格式。

获取端点架构（OpenAPI）

返回描述每个已服务模型接受和返回内容的 OpenAPI 3.1 JSON 架构。查询端点之前，可用它了解端点的输入 / 输出格式。

databricks serving-endpoints get-open-api <ENDPOINT_NAME> --profile <PROFILE>

架构会显示每个已服务模型对应的路径（例如 /served-models/<model-name>/invocations），并包含完整的请求 / 响应定义，包括参数类型、枚举和可空字段。

其他命令

运行 databricks serving-endpoints <subcommand> -h 查看用法详情。

任务	命令	备注
列出所有端点	list
获取端点详情	get <NAME>	显示状态、配置和已服务实体
删除端点	delete <NAME>
更新已服务实体或流量	update-config <NAME> --json '...'	零停机：新配置就绪前，旧配置会继续提供服务
速率限制和使用情况跟踪	put-ai-gateway <NAME> --json '...'
更新标签	patch <NAME> --json '...'
构建日志	build-logs <NAME> <SERVED_MODEL>	从 get 输出中获取 SERVED_MODEL：served_entities[].name
运行时日志	logs <NAME> <SERVED_MODEL>
指标（Prometheus 格式）	export-metrics <NAME>
权限	get-permissions <ENDPOINT_ID>	⚠️ 使用端点 ID（十六进制字符串），而非名称。通过 get 查找 ID。

后续步骤

与 Databricks App 集成

创建服务端点后，将其接入 Databricks App。

步骤 1 — 检查 AppKit 模板中是否提供 serving 插件：

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>

步骤 2 — 如果没有 serving 插件，则手动将端点资源添加到现有应用的 databricks.yml 中：

resources:
  apps:
    my_app:
      resources:
        - name: my-model-endpoint
          serving_endpoint:
            name: <ENDPOINT_NAME>
            permission: CAN_QUERY

并在 app.yaml 中将端点名称注入为环境变量：

env:
  - name: SERVING_ENDPOINT
    valueFrom: serving-endpoint

然后通过 serving() 插件或 onPluginsReady 中的自定义路由，将端点接入应用。有关完整的应用集成模式，请使用 databricks-apps skill 并阅读 Model Serving Guide。

开发和部署新模型

此 skill 侧重运维（管理现有端点）。有关开发侧流程——训练、MLflow 跟踪、UC 注册、自定义 PyFunc 编写以及手动编写 ResponsesAgent 代码——请参阅 databricks-ml-training（实验性）。

基础模型 API 端点

按 Token 付费，已在每个工作区中预先配置。新模型会定期上线，静态的技能列表很快就会过时——始终在运行时列出模型，而不是硬编码名称。按 databricks- 名称前缀筛选，并确保所服务的实体位于 system.ai.* 中（其他端点，例如 databricks-app-template-serving，也共享此前缀，但并非基础模型 API 端点）。使用 Databricks Unity Gateway（databricks-unity-gateway）管理对基础模型端点的访问。不要使用旧版 AI Gateway databricks-model-serving。

# FM API endpoints in this workspace, grouped by task (chat / embeddings / etc.)
databricks serving-endpoints list \
  | jq -r '.[]
      | select(.name | startswith("databricks-"))
      | select((.config.served_entities[0].entity_name // "") | startswith("system.ai."))
      | "\(.task)\t\(.name)"' \
  | sort

用户未指定时的默认选择：为 Agent 选择编号最高的 Claude Sonnet，为代码选择编号最高的 -codex-max，为嵌入选择 databricks-gte-large-en——从上方的实时列表中解析实际名称。

平台外流式传输

对于部署在 Databricks Apps 之外（Vercel、AWS、独立 Node.js）的应用，如果使用 Vercel AI SDK v6 调用 Databricks 旧版 AI Gateway，请参阅 references/off-platform-streaming.md。平台外应用应更新为调用 Databricks Unity Gateway（databricks-unity-gateway）。对于基于 AppKit 的应用，请改用 databricks-apps 技能内置的服务插件。

故障排除

错误	解决方案
cannot configure default credentials	使用 --profile 标志，或先进行身份验证
PERMISSION_DENIED	检查工作区权限；对于应用，确保声明了带有 CAN_QUERY 的 serving_endpoint 资源
端点卡在 NOT_READY 状态	为预配吞吐量最多等待 30 分钟。检查构建日志：build-logs <NAME> <ENTITY_NAME>（从 get 输出的 served_entities[].name 获取实体名称）
RESOURCE_DOES_NOT_EXIST	使用 list 验证端点名称
查询返回 404	端点可能仍在预配中；通过 get 检查 state.ready
RATE_LIMIT_EXCEEDED (429)	AI Gateway 速率限制；检查 put-ai-gateway 配置，或等待一段时间后重试
部署后在 Serving UI 中找不到端点	UI 筛选器默认设为“由我拥有”。部署作业以服务主体身份运行，因此端点会被隐藏，直到你切换为“全部”。databricks serving-endpoints list 始终会显示该端点。