Databricks

Databricks Model Serving 在 Databricks 工作区的端点后托管基础模型。AISIX 为这些端点提供面向应用的统一 OpenAI 兼容 API，并管理工作区 Token、调用方访问权限、限流和用量核算。

准备工作

开始前，请准备以下内容：

一套 AISIX 环境：
- 对于 AISIX Cloud，需要一个已关联网关的环境和具有写入作用域的 Admin Token。对于 On-Premises，请按照 AISIX Cloud 快速入门操作。如需申请 Hybrid 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 Cloud 配置

导出 AISIX Cloud 连接信息：

# AISIX_CP 是 Admin API 基础 URL；应包含 /api，且末尾不带斜杠
# 本地 On-Premises 快速入门使用 http://localhost:8080/api
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_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 API 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。由于每个工作区都有自己的主机，该值是模板而不是已解析的 URL。AISIX 不会替换占位符，并会原样存储回退值，因此创建请求仍会成功，但服务提供方密钥会携带字面量 ${DATABRICKS_HOST}，而不是工作区主机，第一次聊天请求将在上游失败。该模板还指向 Databricks AI Gateway 根路径，而不是本页配置的 /serving-endpoints 根路径。显式设置 api_base 可以完全避免该回退行为。

本指南不涵盖路由优化 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"

为该服务提供方创建完整的声明式资源文件：

resources.yaml
_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：

# 本地快速入门使用 http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_ORIGIN"

通过 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 不匹配。

设置 Token 限制参数

Databricks 基础模型 REST API 参考使用 max_tokens 表示生成 Token 上限，而部分 OpenAI 客户端和集成使用较新的 max_completion_tokens 名称。

对于上游仍要求旧名称的精选服务提供方，AISIX 服务提供方目录会注册并自动应用重命名。Databricks 是社区目录条目，因此未注册重命名：AISIX 会原样转发调用方发送的名称。因此，发送 max_completion_tokens 的客户端会把文档 API 未命名的参数传给 Databricks。

如果客户端发送 max_completion_tokens，请在服务提供方密钥上配置请求重命名。

在 AISIX Cloud 中，创建带覆盖项的替代服务提供方密钥，并把模型别名重新指向它：

OVERRIDE_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-overrides",
    "provider": "databricks",
    "api_key": "'"${DATABRICKS_TOKEN}"'",
    "api_base": "https://'"${DATABRICKS_HOST}"'/serving-endpoints",
    "allowed_environments": ["'"${ENV_ID}"'"],
    "request": {
      "param_renames": {
        "max_completion_tokens": "max_tokens"
      }
    }
  }' | jq -r '.provider_key.id')

curl -sS -X PATCH "$AISIX_CP/environments/$ENV_ID/models/$MODEL_ID" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_key_id": "'"${OVERRIDE_PROVIDER_KEY_ID}"'"
  }'

对于开源 AISIX 网关，请在声明式资源文件的现有服务提供方密钥条目中添加 request 配置块：

resources.yaml
provider_keys:
  - display_name: "databricks-prod"
    provider: "databricks"
    adapter: "openai"
    api_key: ${DATABRICKS_TOKEN}
    api_base: "https://${DATABRICKS_HOST}/serving-endpoints"
    request:
      param_renames:
        max_completion_tokens: max_tokens

按照上文所述验证声明式资源文件并重新加载或重启。该重命名会重写流经服务提供方密钥的每个请求中的顶层参数，因此适用于引用它的每个模型别名。请求同时携带两个名称时，AISIX 会保留面向调用方的源名称中的值。请参阅服务提供方特定覆盖项。

警告

AISIX Cloud Admin API 在创建服务提供方密钥时接受 request 和 response 覆盖配置块。服务提供方密钥更新端点不携带这些字段，因此若要在现有 Databricks 密钥上添加或更改覆盖项，请创建带覆盖项的第二个服务提供方密钥，再修补每个模型的 provider_key_id，把模型别名重新指向该密钥。

验证时，请发送把 max_completion_tokens 设为较小值的 Chat Completions 请求，并确认补全结果在该长度处截断。

发送推理控制参数

Databricks 在统一的 OpenAI 形态接口后重新提供多个厂商的模型，因此推理控制取决于 Endpoint 后的模型系列。Databricks 在查询推理模型中记录当前控制项。AISIX 会原样转发无法识别的顶层 Chat Completions 参数，但上游接受的字段和值仍取决于具体模型。

对于 GPT OSS Endpoint，请在正文顶层发送 reasoning_effort。以下示例假设已在 databricks-gpt-oss-120b Serving Endpoint 上创建第二个别名 databricks-gptoss-prod：

{
  "model": "databricks-gptoss-prod",
  "messages": [
    {
      "role": "user",
      "content": "Plan a three-step migration."
    }
  ],
  "reasoning_effort": "low"
}

GPT OSS 接受 low、medium 或 high。其他模型系列使用不同值或 Anthropic 风格的 thinking 对象，因此请确认具体 Endpoint 的控制项。

Databricks 会把 Claude 扩展思考 Chat 输出作为由推理块和文本块组成的带类型数组返回。AISIX openai 适配器要求 message.content 或 delta.content 为字符串，因此无法在规范化 /v1/chat/completions 路由上解码该结构。需要 Claude 推理块时，请通过透传路由使用 Databricks 原生端点。透传路由会保留上游响应，且不会重写 AISIX 模型别名。AISIX 会从 messages 检测 Chat 信封，并在上游响应包含受支持的用量字段时记录 Token 用量。

本页的 /passthrough/databricks 路径假定一条透传路由认领该前缀，target_url 设为工作区 Serving 根地址（https://<workspace-instance>/serving-endpoints）并挂上 Databricks 服务提供方密钥；在调用方 Key 的 allowed_routes 上授予该路由。

访问 Databricks 原生路由

Databricks 提供 AISIX /v1/responses 桥接不会调用的原生 Responses 路由：

Databricks 路由	AISIX 透传路径	适用范围
`POST /serving-endpoints/open-responses`	`POST /passthrough/databricks/open-responses`	以 Open Responses 格式访问 Databricks 托管的开放模型、Anthropic Claude 和 Google Gemini。
`POST /serving-endpoints/responses`	`POST /passthrough/databricks/responses`	访问 Databricks 托管的 OpenAI 模型所提供的原生 OpenAI Responses API。

以下示例访问跨服务提供方的 Open Responses 路由。请在 model 中发送 Databricks Serving Endpoint 名称，而不是 AISIX 别名：

curl -sS -X POST "$AISIX_PROXY/passthrough/databricks/open-responses" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "databricks-claude-sonnet-4-5",
    "input": [
      {
        "role": "user",
        "content": "Plan a three-step migration."
      }
    ],
    "max_output_tokens": 256
  }'

支持的字段及各服务提供方的行为，请参阅使用 Open Responses API 查询模型。透传路由不会执行 Databricks 专用规范化，而是原样转发请求和响应。AISIX 会从 input 检测 Responses 信封，并记录响应携带的所有受支持 Token 维度，包括输入、输出、缓存和推理详情。如果服务提供方响应省略所有受支持的 Token 字段，Token 计数会保持为零，基于 Token 的预算和成本计算也不会计入这部分流量。

Databricks 也可通过 POST /serving-endpoints/{endpoint-name}/invocations 原生调用端点，该路由不是 OpenAI 形态。请使用透传路由访问它。

透传路由不借用模型别名，而是直接转发到 {target_url}/{rest}。由于路由的 target_url 以 /serving-endpoints 结尾，通配符剩余部分应从端点名称开始。不要在透传路径中重复 serving-endpoints：

curl -sS -X POST "$AISIX_PROXY/passthrough/databricks/databricks-claude-sonnet-4-5/invocations" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Say hello from Databricks."
      }
    ],
    "max_tokens": 64
  }'

原生调用正文在路径中指定 Endpoint，不携带顶层 model 字段，因此该调用仅应用调用方 API Key 限流。在 inject 模式透传路由上，模型范围请求数限制根据请求正文中指向路由服务提供方已配置模型的 model 字段匹配。必须产生 Token 用量或计入模型 Token 配额的流量，应优先使用规范化 AISIX 端点。

端点覆盖范围

Databricks 别名通过 openai 适配器解析，因此路由支持情况取决于 Serving Endpoint 的实现以及每条路由自身的服务提供方规则。

路由	Databricks 别名的行为
`/v1/chat/completions`	Databricks 返回兼容 OpenAI 的字符串内容时支持，包括 `stream: true`。Claude 扩展思考响应使用带类型的内容块数组，因此需要透传路由。
`/v1/responses`	通过 Chat 适配器路径上的 Responses 桥接提供支持，因为别名的服务提供方值为 `databricks` 而不是 `openai`。它不会调用 Databricks 原生 `/serving-endpoints/responses` 或 `/serving-endpoints/open-responses` 路由。没有 Chat 等价项的 OpenAI 特定 Responses 字段会被忽略。
`/v1/messages`	通过转换支持 Anthropic 形态的调用方。Claude 系列 Serving Endpoint 也会被转换，因为别名解析到 `openai` 适配器，而不是 Anthropic 适配器。Claude 扩展思考响应与 `/v1/chat/completions` 具有相同的内容块限制。`/v1/messages/count_tokens` 要求服务提供方值为 `anthropic` 的模型，因此此处不可用。
`/v1/embeddings`	当别名指定 Databricks Embedding Serving Endpoint 时受支持。Databricks 在使用自定义 Model Serving 提供自定义 LLM中记录了针对同一 `/serving-endpoints` 根路径的 `client.embeddings.create`，因此一个服务提供方密钥可以同时服务 Chat 和 Embedding 别名。请参阅 Embedding。
`/v1/images/generations`	拒绝。该路由只接受服务提供方为 `openai` 的模型。
`/v1/rerank`	拒绝。该路由只接受 `openai`、`cohere` 和 `jina` 服务提供方值。
`/v1/videos`	拒绝。该路由的服务提供方允许列表中不包含 `databricks`。
`/passthrough/databricks/*`	通过已配置的透传路由可用于 Databricks 原生路由，包括 `/responses`、`/open-responses` 和 Endpoint Invocations。路由会转发到其 `target_url`，且不会重写 AISIX 别名。可识别的 Chat、Completions 和 Responses 信封会记录受支持的用量字段；其他操作保持不透明。

后续步骤

你已将 AISIX 接入 Databricks，并验证了模型别名。接下来可以阅读：

模型别名：为该别名配置路由、重试行为或成本元数据。
路由和故障转移：在 Databricks 端点与另一个服务提供方之间进行故障转移。
服务提供方特定覆盖项：当上游 API 与其适配器不同时，调整请求和响应形态。
服务提供方兼容性：查看支持的代理端点和服务提供方特定边界。

准备工作​

使用 AISIX Cloud 配置​

创建服务提供方密钥​

创建模型​

创建调用方 API Key​

使用开源 AISIX 网关配置​

验证服务提供方连接​

设置 Token 限制参数​

发送推理控制参数​

访问 Databricks 原生路由​

端点覆盖范围​

后续步骤​