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 Personal 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 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 Personal Access 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 可以完全避免该回退行为。

该命令会把返回的服务提供方密钥 ID 保存到 PROVIDER_KEY_ID。

创建模型

在 Databricks 上，AISIX 在 model 中发送给上游的值是工作区中的 Serving Endpoint 名称，而不是厂商模型 ID。两个工作区可以使用不同端点名称提供相同权重，因此应从自己的工作区读取名称，而不是从厂商目录中获取。

端点名称分为两类：

端点类型	命名方式	示例
Databricks 托管、按 Token 计费的基础模型	Databricks 会预置该端点。名称带有 databricks- 前缀，并使用连字符而不是点号表示模型版本。	databricks-claude-sonnet-4-5
自定义、预置吞吐量或外部模型端点	创建端点时自行选择名称，不使用前缀，也没有命名规则。	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 服务提供方密钥。工作区 Token 可以访问该工作区中的每个 Serving Endpoint，因此一个服务提供方密钥通常可以服务环境中的每个 Databricks 别名。

创建调用方 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 和端点名称是三个独立值，因此每种失败模式都有不同的表现：

现象	可能原因
上游身份认证错误	Personal Access Token 已过期，或它所属的工作区与 api_base 中的主机不同。
端点路径返回上游 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 形态界面后重新提供多个厂商的模型，因此推理控制取决于端点后的模型系列，而不是路由。Databricks 在查询推理模型中记录了两种形态：GPT 端点使用 reasoning_effort，Claude 端点使用 Anthropic 风格的 thinking 对象。AISIX 不会从 Chat Completions 正文中剥离无法识别的顶层参数，因此两种形态都会按调用方发送的形式到达上游。

对于 GPT 系列端点，请在正文顶层发送推理强度。以下示例假设已在 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"
}

对于 Claude 系列端点，请改为发送思考预算。Databricks 要求 budget_tokens 至少为 1024，且低于 max_tokens：

{
  "model": "databricks-sonnet-prod",
  "messages": [
    {
      "role": "user",
      "content": "Plan a three-step migration."
    }
  ],
  "max_tokens": 4096,
  "thinking": {
    "type": "enabled",
    "budget_tokens": 2048
  }
}

请确认所配置具体端点接受的控制项及其值，因为一个 Databricks 端点接受的正文可能会被同一工作区中的另一个端点拒绝。

Databricks 是社区目录条目，因此 AISIX 未为其注册推理字段覆盖项，并会保留上游已在规范 reasoning_content 字段中返回的推理。如果 Serving Endpoint 在其他 delta 路径下传输推理，请在服务提供方密钥上设置 response.reasoning_field。

访问 Databricks 原生路由

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

透传会选择调用方 API Key 有权使用、且服务提供方为 databricks 的模型别名，然后转发到 {api_base}/{rest}。由于 api_base 已以 /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
  }'

原生调用正文在路径中指定端点，不携带顶层 model 字段，因此该调用仅应用调用方 API Key 限流。透传中的模型范围限流根据请求正文的 model 字段匹配。必须计入模型配额的流量应优先使用 /v1/chat/completions。

端点覆盖范围

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

路由	Databricks 别名的行为
/v1/chat/completions	支持，包括 stream: true。
/v1/responses	通过聊天适配器路径上的 Responses 桥接提供支持。别名的服务提供方值为 databricks 而不是 openai，因此会使用桥接。
/v1/messages	通过转换支持 Anthropic 形态的调用方。Claude 系列 Serving Endpoint 也会被转换，因为别名解析到 openai 适配器，而不是 Anthropic 适配器。/v1/messages/count_tokens 的 Token 计数要求服务提供方值为 anthropic 的模型，因此此处不可用。
/v1/embeddings	当别名指定 Databricks Embedding Serving Endpoint 时受支持。Databricks 在查询 Embedding 模型中记录了针对同一 /serving-endpoints 根路径的 client.embeddings.create，因此一个服务提供方密钥可以同时服务聊天和 Embedding 别名。请参阅 Embedding。
/v1/images/generations	拒绝。该路由只接受服务提供方为 openai 的模型。
/v1/rerank	拒绝。该路由只接受 openai、cohere 和 jina 服务提供方值。
/v1/videos	拒绝。该路由的服务提供方允许列表中不包含 databricks。
/passthrough/databricks/*	支持 Databricks 原生路由，网关只执行有限的标准化。该服务提供方值没有内置基础 URL，因此透传依赖服务提供方密钥上配置的 api_base。

后续步骤

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

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