Databricks
Databricks Model Serving 在 Databricks 工作区的端点后托管基础模型。AISIX 为这些端点提供面向应用的统一 OpenAI 兼容 API,并管理工作区 Token、调用方访问权限、限流和用量核算。
准备工作
开始前,请准备以下内容:
- 一套 AISIX 环境:
- 对于 AISIX Enterprise 或 AISIX Cloud,需要一个已关联网关的环境和具有写入作用域的 Admin Token。对于 AISIX Enterprise,请按照 AISIX Enterprise 快速入门操作。如需申请 AISIX Cloud 访问权限,请联系 API7。
- 对于开源 AISIX 网关,请准备本地 AISIX 安装,或使用开源 AISIX 网关快速入门中的 Docker 配置。配置网关以加载声明式资源文件。
- 已启用 Model Serving 且至少包含一个可查询 Serving Endpoint 的 Databricks 工作区。
- 该工作区的工作区实例名称,即登录时逐工作区 URL 的主机部分。在 AWS 上类似
dbc-a1b2c3d4-e5f6.cloud.databricks.com,在 Azure 上类似adb-<workspace-id>.<number>.azuredatabricks.net,在 Google Cloud 上类似<workspace-id>.<number>.gcp.databricks.com。 - Databricks API Token,其身份对 AISIX 将访问的每个 Serving Endpoint 都具有
CAN QUERY权限。示例使用工作区 Personal Access Token。Databricks 建议生产环境使用 OAuth 机器到机器认证,但 AISIX 会把 Bearer Token 作为静态服务提供 方密钥凭证存储,不会刷新。使用短期 OAuth Access Token 时,请在过期前刷新服务提供方密钥凭证。 curl和jq。
使用 AISIX Enterprise 或 AISIX Cloud 配置
导出控制面连接信息:
# AISIX_CP 是 Admin API 基础 URL;应包含 /api,且不含尾部斜杠
# 本地 AISIX Enterprise 快速入门使用 http://localhost:8080/api
export AISIX_CP="YOUR_AISIX_CONTROL_PLANE_API_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"
为 Databricks 支持的 Chat Completions 路由创建服务提供方密钥、模型别名和调用方 API Key。
Databricks 是提供 OpenAI 兼容 API 的社区目录服务提供方。AISIX 通过 openai 适配器连接,并使用工作区特定的 Serving 根路径作为 api_base。AISIX 不会提供精选基础 URL 或服务提供方特定的请求和响应重写。下文还会说明 Databricks 的 Token 限制参数名称。
Databricks 提供两套兼容 OpenAI 的工作区接口。每个基础 URL 必须与自己的模型命名方案配对:
| Databricks 接口 | api_base | 上游 model_name |
|---|---|---|
| 本指南使用的 Model Serving Endpoint | https://<workspace-instance>/serving-endpoints | Serving Endpoint 名称,例如 databricks-claude-sonnet-4-5 或自定义名称。 |
| Unity AI Gateway Model Service(Beta) | https://<workspace-instance>/ai-gateway/mlflow/v1 | 完全限定的 Model Service 名称,例如 system.ai.claude-sonnet-4-5。 |
Databricks 建议新访问其托管基础模型时使用 Beta Model Service。Model Serving 接口仍受支持,并覆盖预置吞吐量、外部模型和兼容 OpenAI 的自定义端点。两种请求结构请参阅查询 Chat 模型。不要把 system.ai.* Model Service 名称与下方 /serving-endpoints 基础地址混用。
创建服务提供方密钥
创建用于存储 Databricks Token 和工作区 Serving 根路径的服务提供方密钥:
# 请替换为实际值
export DATABRICKS_HOST="dbc-a1b2c3d4-e5f6.cloud.databricks.com"
export DATABRICKS_TOKEN="YOUR_PROVIDER_API_KEY"
PROVIDER_KEY_ID=$(curl -sS -X POST "$AISIX_CP/provider_keys" \
-H "Authorization: Bearer $AISIX_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"display_name": "databricks-prod",
"provider": "databricks",
"api_key": "'"${DATABRICKS_TOKEN}"'",
"api_base": "https://'"${DATABRICKS_HOST}"'/serving-endpoints",
"allowed_environments": ["'"${ENV_ID}"'"]
}' | jq -r '.provider_key.id')
echo "$PROVIDER_KEY_ID"
❶ provider 为 databricks。AISIX Cloud Admin API 接受该值,因为 databricks 是 models.dev 目录 ID,并根据社区目录规则派生使用 Bearer 身份认证的 openai 适配器。adapter 字段仅接受 BYO 服务提供方密钥,因此不要在此发送。
❷ api_key 存储 Databricks 个人访问 Token。Databricks 使用 HTTP Bearer 身份认证其 OpenAI 兼容界面,这正是 openai 适配器已经发送的形式。该值遵循服务提供方密钥中的凭证处理行为。
❸ api_base 为 https://<workspace-instance>/serving-endpoints。Databricks 在 Model Serving 中的外部模型中把该根路径记录为 OpenAI 客户端的 base_url,完整聊天端点因此为 https://<workspace-instance>/serving-endpoints/chat/completions。AISIX 会向 api_base 追加 /chat/completions 等端点路径,因此配置值必须止于 /serving-endpoints。如果改为粘贴完整端点 URL,AISIX 会移除末尾的 /chat/completions 和任何末尾斜杠,但应配置上述根路径。
Databricks 必须设置 api_base。Databricks 没有共享公共 API 主机:每个请求都发往你自己的工作区实例,因此 AISIX 无法代为提供该值。
对于社区目录服务提供方,省略 api_base 时,AISIX Cloud Admin API 会回退到 models.dev 目录条目发布的基础 URL。Databricks 条目发布的是 https://${DATABRICKS_HOST}/ai-gateway/mlflow/v1。这是 Unity AI Gateway Model Service 根路径,但其中的工作区主机仍是未解析模板。AISIX 不会填充模板,因此未提供 api_base 的创建请求会被拒绝,返回 400,消息为 models.dev does not publish a default api_base for this provider — set api_base explicitly。显式设置 api_base 还能确保其 API 界面与所选模型命名方案匹配。
本指南不涵盖路由优化 Serving Endpoint。它们使用专用 Endpoint URL 和 Endpoint 范围 OAuth 凭证,而不是此处显示的工作区 URL 与 Personal Access Token。
该命令会把返回的服务提供方密钥 ID 保存到 PROVIDER_KEY_ID。
创建模型
在 Databricks 上,AISIX 在 model 中发送给上游的值是工作区中的 Serving Endpoint 名称,而不是厂商模型 ID。两个工作区可以使用不同端点名称提供相同权重,因此应从自己的工作区读取名称,而不是从厂商目录中获取。
端点名称分为两类:
| 端点类型 | 命名方式 | 示例 |
|---|---|---|
| Databricks 托管、按 Token 计费的基础模型 | Databricks 会预置该端点。名称带有 databricks- 前缀,并使用连字符而不是点号表示模型版本。 | databricks-claude-sonnet-4-5 |
| 兼容 OpenAI 的自定义、预置吞吐量或外部模型端点 | 创建端点时自行选择名称,不使用前缀,也没有命名规则。 | openai-chat-endpoint |
当前按 Token 计费的端点名称包括 databricks-claude-sonnet-4-5、databricks-gpt-oss-120b 和 databricks-gemini-2-5-pro。Databricks 新增和退役托管模型时,该集合会轮换,因此创建别名前,请对照 Databricks 托管基础模型列表或工作区中的 Serving 页面确认名称。
创建调用方将在请求中发送的模型别名:
MODEL_ID=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
-H "Authorization: Bearer $AISIX_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"display_name": "databricks-sonnet-prod",
"model_name": "databricks-claude-sonnet-4-5",
"provider_key_id": "'"${PROVIDER_KEY_ID}"'"
}' | jq -r '.model.id')
echo "$MODEL_ID"
❶ display_name 是调用方在 model 中发送的别名。
❷ model_name 是 Databricks Serving Endpoint 名称。不要从介绍厂商自有 API 的页面沿用 claude-sonnet-4-5 等底层厂商模型 ID。工作区中不存在的端点名称会在上游失败,而不是在创建别名时失败。
❸ provider_key_id 将别名关联到 Databricks 服务提供方密钥。凭证只能访问其身份获准查询的 Serving Endpoint。一个服务提供方密钥可以服务所有获准 Endpoint 的别名,也可以使用独立身份和密钥,在不同 Endpoint 组之间保持最小权限边界。
创建调用方 API Key
创建能够访问该模型别名的调用方 API Key。明文密钥由服务器生成,并只在创建响应中返回一次,因此请立即保存:
AISIX_API_KEY=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/api_keys" \
-H "Authorization: Bearer $AISIX_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"display_name": "databricks-caller",
"allowed_models": ["'"${MODEL_ID}"'"]
}' | jq -r '.plaintext')
echo "$AISIX_API_KEY"
allowed_models 值必须引用上一步保存的模型 ID。写入后,配置会自动投射到已关联的网关。
使用开源 AISIX 网关配置
导出上游凭证,并选择应用将发送给网关的调用方 API Key:
export DATABRICKS_TOKEN="YOUR_PROVIDER_API_KEY"
export DATABRICKS_HOST="YOUR_DATABRICKS_WORKSPACE_HOST"
export CALLER_API_KEY="YOUR_CALLER_API_KEY"
对于新网关,请使用以下完整的声明式资源文件。对于现有网关,请把这些条目合并到当前文件,并保留其他资源:
_format_version: "1"
provider_keys:
- display_name: "databricks-prod"
provider: "databricks"
adapter: "openai"
api_key: ${DATABRICKS_TOKEN}
api_base: "https://${DATABRICKS_HOST}/serving-endpoints"
models:
- display_name: "databricks-sonnet-prod"
provider: "databricks"
model_name: "databricks-claude-sonnet-4-5"
provider_key: "databricks-prod"
api_keys:
- display_name: "databricks-caller"
key_env: CALLER_API_KEY
allowed_models:
- "databricks-sonnet-prod"
如果 AISIX 安装在本地,请在加载前验证文件:
aisix validate --resources resources.yaml
验证后,在网关进程环境中提供文件引用的环境变量,再启动网关。仅当这些变量已经可供进程使用时,才重新加载现有网关;否则,请使用更新后的环境重启网关。
如果使用 Docker,请调整开源 AISIX 网关快速入门中的验证和启动命令。挂载此 resources.yaml 文件,并在两条命令中使用 -e 传入它引用的每个环境变量。资源加载后,准备下文共用的验证请求:
export AISIX_API_KEY="$CALLER_API_KEY"
验证服务提供方连接
导出 AISIX 网关 Origin:
# AISIX_PROXY 不含尾部斜杠或端点路径
# 本地快速入门使用 http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_URL"
通过 AISIX 代理发送 Chat Completions 请求:
curl -sS -X POST "$AISIX_PROXY/v1/chat/completions" \
-H "Authorization: Bearer ${AISIX_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"model": "databricks-sonnet-prod",
"messages": [
{
"role": "user",
"content": "Say hello from Databricks."
}
],
"max_tokens": 64
}'
网关返回 OpenAI 兼容响应,其中回显面向调用方的别名 databricks-sonnet-prod。工作区主机、Token 和端点名称是三个独立值,因此每种失败模式都有不同的表现:
| 现象 | 可能原因 |
|---|---|
| 上游身份认证错误 | Databricks API Token 已过期,或它所属的工作区与 api_base 中的主机不同。 |
上游返回 403 权限错误 | Token 身份不具备该 Serving Endpoint 的 CAN QUERY 权限。 |
端点路径返回上游 404 | api_base 未止于 /serving-endpoints,导致 AISIX 构造了 Databricks 不提供的路径。 |
| 指明端点名称的上游错误 | model_name 与工作区中的 Serving Endpoint 不匹配。 |