Databricks

Databricks Model Serving hosts foundation models behind endpoints in your Databricks workspace. AISIX gives applications one OpenAI-compatible API for those endpoints while managing the workspace token, caller access, rate limits, and usage accounting.

Prerequisites

Before starting, prepare the following:

One AISIX setup:
- For AISIX Cloud, an environment with an attached gateway and a write-scoped admin token. For On-Premises, follow the AISIX Cloud Quickstart. To request Hybrid Cloud access, contact API7.
- For the open-source AISIX gateway, prepare either a local AISIX installation or the Docker setup from the Open-Source AISIX Gateway Quickstart. Configure the gateway to load a declarative resources file.
A Databricks workspace with Model Serving enabled and at least one serving endpoint you can query.
The workspace instance name for that workspace, which is the host portion of the per-workspace URL you sign in to. It looks like dbc-a1b2c3d4-e5f6.cloud.databricks.com on AWS, adb-<workspace-id>.<number>.azuredatabricks.net on Azure, and <workspace-id>.<number>.gcp.databricks.com on Google Cloud.
A Databricks API token whose identity has CAN QUERY permission on every serving endpoint that AISIX will access. The examples use a workspace personal access token. Databricks recommends OAuth machine-to-machine authentication for production, but AISIX stores the bearer token as a static provider-key credential and does not refresh it. If you use a short-lived OAuth access token, refresh the provider-key credential before the token expires.
curl and jq.

Configure with AISIX Cloud

Export the AISIX Cloud connection details:

# AISIX_CP is the Admin API base URL; include /api and omit a trailing slash
# The local On-Premises quickstart uses 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"

Create a provider key, model alias, and caller API key for the Databricks-backed chat-completions route.

Databricks is a community catalog provider with an OpenAI-compatible API. AISIX connects through the openai adapter and uses the workspace-specific serving root as api_base. AISIX does not supply a curated base URL or provider-specific request and response rewrites. The sections below also explain Databricks' token-limit parameter name.

Databricks exposes two OpenAI-compatible workspace surfaces. Keep each base URL paired with its own model naming scheme:

Databricks surface	`api_base`	Upstream `model_name`
Model Serving endpoint, used throughout this guide	`https://<workspace-instance>/serving-endpoints`	A serving endpoint name, such as `databricks-claude-sonnet-4-5` or a name you assigned.
Unity AI Gateway model service (Beta)	`https://<workspace-instance>/ai-gateway/mlflow/v1`	A fully qualified model service name, such as `system.ai.claude-sonnet-4-5`.

Databricks recommends its Beta model services for new access to Databricks-hosted foundation models. The Model Serving surface remains supported and also covers provisioned-throughput, external-model, and OpenAI-compatible custom endpoints. See Query a chat model for both request shapes. Do not use a system.ai.* model service name with the /serving-endpoints base configured below.

Create a Provider Key

Create the provider key that stores the Databricks token and the workspace serving root:

# Replace with your values
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 is databricks. The AISIX Cloud Admin API accepts the value because databricks is a models.dev catalog ID, and derives the openai adapter with bearer authentication from the community catalog rule. The adapter field is only accepted on BYO provider keys, so do not send it here.

❷ api_key stores the Databricks personal access token. Databricks authenticates its OpenAI-compatible surface with HTTP bearer authentication, which is what the openai adapter already sends. The value follows the credential-handling behavior in Provider Keys.

❸ api_base is https://<workspace-instance>/serving-endpoints. Databricks documents this root as the OpenAI client's base_url in External models in Model Serving, which makes the full chat endpoint https://<workspace-instance>/serving-endpoints/chat/completions. AISIX appends the endpoint path, such as /chat/completions, to api_base, so the configured value must stop at /serving-endpoints. If you paste the full endpoint URL instead, AISIX strips the trailing /chat/completions and any trailing slash, but the root above is the value to configure.

caution

api_base is required for Databricks. Databricks has no shared public API host: every request goes to your own workspace instance, so there is no value AISIX can supply on your behalf.

For a community-catalog provider, the AISIX Cloud Admin API falls back to the base URL published in the models.dev catalog entry when you omit api_base. The Databricks entry publishes https://${DATABRICKS_HOST}/ai-gateway/mlflow/v1. This is the Unity AI Gateway model-service root, but its workspace host is an unresolved template. AISIX performs no placeholder substitution, so the provider key stores the literal ${DATABRICKS_HOST} text and upstream requests fail. Setting api_base explicitly also ensures that its API surface matches the model naming scheme you selected.

This guide does not cover route-optimized serving endpoints. They use a dedicated endpoint URL and endpoint-scoped OAuth credentials rather than the workspace URL and personal access token shown here.

The command captures the returned provider key ID in PROVIDER_KEY_ID.

Create a Model

On Databricks, the value AISIX sends upstream in model is the name of a serving endpoint in your workspace, not a vendor model ID. Two workspaces can serve the same weights under different endpoint names, so read the name from your own workspace rather than from a vendor catalog.

Endpoint names fall into two groups:

Endpoint type	Naming	Example
Databricks-hosted foundation model, pay-per-token	Databricks pre-provisions the endpoint. The name carries a `databricks-` prefix and spells the model version with hyphens instead of dots.	`databricks-claude-sonnet-4-5`
OpenAI-compatible custom, provisioned-throughput, or external-model endpoint	You choose the name when you create the endpoint. There is no prefix and no naming rule.	`openai-chat-endpoint`

Current pay-per-token endpoint names include databricks-claude-sonnet-4-5, databricks-gpt-oss-120b, and databricks-gemini-2-5-pro. The set rotates as Databricks adds and retires hosted models, so confirm the name against the list of Databricks-hosted foundation models or the Serving page in your workspace before creating an alias.

Create the model alias callers will send in requests:

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 is the alias callers send in model.

❷ model_name is the Databricks serving endpoint name. Do not carry over the underlying vendor model ID, such as claude-sonnet-4-5, from a page that documents the vendor's own API. An endpoint name that does not exist in the workspace fails at the upstream, not at alias-creation time.

❸ provider_key_id attaches the alias to the Databricks provider key. The credential can reach only the serving endpoints its identity has permission to query. One provider key can serve aliases for all permitted endpoints, or you can use separate identities and keys to preserve least-privilege boundaries between endpoint groups.

Create a Caller API Key

Create the caller API key that can access the model alias. The plaintext key is server-generated and returned once in the create response, so capture it now:

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"

The allowed_models value must reference the model ID captured in the previous step. After the write, the configuration projects to attached gateways automatically.

Configure with the Open-Source AISIX Gateway

Export the upstream credential and choose the caller API key that applications will send to the gateway:

export DATABRICKS_TOKEN="YOUR_PROVIDER_API_KEY"
export DATABRICKS_HOST="YOUR_DATABRICKS_WORKSPACE_HOST"
export CALLER_API_KEY="YOUR_CALLER_API_KEY"

Create a complete declarative resources file for this provider:

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"

If AISIX is installed locally, validate the file before loading it:

aisix validate --resources resources.yaml

After validation, start the gateway with the referenced environment variables in its process environment. Reload an existing gateway only if those variables are already available to the process; otherwise, restart it with the updated environment.

If you use Docker, adapt the validation and startup commands in the Open-Source AISIX Gateway Quickstart. Mount this resources.yaml file and pass every environment variable it references with -e in both commands. After the resources load, prepare the shared verification request below:

export AISIX_API_KEY="$CALLER_API_KEY"

Verify the Provider Connection

Export the AISIX gateway origin:

# The local quickstarts use http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_ORIGIN"

Send a chat-completions request through the AISIX proxy:

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
  }'

The gateway returns an OpenAI-compatible response that echoes the caller-facing alias databricks-sonnet-prod. Because the workspace host, the token, and the endpoint name are three separate values, each failure mode has a distinct signature:

Symptom	Likely cause
Upstream authentication error	The Databricks API token is expired, or it belongs to a different workspace than the host in `api_base`.
Upstream `403` permission error	The token's identity does not have `CAN QUERY` permission on the serving endpoint.
Upstream `404` on the endpoint path	`api_base` does not stop at `/serving-endpoints`, so AISIX built a path Databricks does not serve.
Upstream error naming the endpoint	`model_name` does not match a serving endpoint in the workspace.

Set the Token-Limit Parameter

The Databricks foundation model REST API reference documents max_tokens as the generated-token cap. Some OpenAI clients and integrations use the newer max_completion_tokens name instead.

For featured providers whose upstream still expects the older name, the AISIX provider catalog registers the rename and applies it automatically. Databricks is a community-catalog entry, so no rename is registered for it: AISIX forwards whichever name the caller sent, unchanged. A client that sends max_completion_tokens therefore reaches Databricks with a parameter the documented API does not name.

If your clients send max_completion_tokens, configure a request rename on the provider key.

In AISIX Cloud, create a replacement provider key with the override and repoint the model alias:

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}"'"
  }'

For the open-source AISIX gateway, add the request block to the existing provider key entry in the declarative resources file:

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

Validate and reload or restart the declarative resources file as described above. The rename rewrites the top-level parameter on every request that flows through the provider key, so it applies to every model alias that references it. When a request carries both names, AISIX keeps the value from the caller-facing source name. See Provider-Specific Overrides.

caution

The AISIX Cloud Admin API accepts the request and response override blocks on provider-key creation. The provider-key update endpoint does not carry them, so to add or change an override on a Databricks key that already exists, create a second provider key with the override and repoint the model aliases at it by patching provider_key_id on each model.

To verify, send a chat-completions request with max_completion_tokens set to a small value and confirm that the completion is truncated at that length.

Send Reasoning Controls

Databricks re-serves models from several vendors behind one OpenAI-shaped surface, so reasoning controls depend on the model family behind the endpoint. Databricks documents the current controls in Query reasoning models. AISIX forwards unrecognized top-level chat-completions parameters unchanged, but the accepted fields and values still depend on the upstream model.

For a GPT OSS endpoint, send reasoning_effort at the top level of the body. The example below assumes a second alias, databricks-gptoss-prod, created over the databricks-gpt-oss-120b serving endpoint:

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

GPT OSS accepts low, medium, or high. Other model families use different values or an Anthropic-style thinking object, so confirm the control for the specific endpoint you configured.

Databricks returns Claude extended-thinking chat output as an array of typed reasoning and text blocks. The AISIX openai adapter expects a string in message.content or delta.content, so it cannot decode this block-array shape on the normalized /v1/chat/completions route. Use a Databricks-native endpoint through a passthrough route when you need Claude reasoning blocks. A passthrough route preserves the upstream response and does not rewrite an AISIX model alias. AISIX detects the chat envelope from messages and records token usage when the upstream response includes supported usage fields.

Reach Databricks-Native Routes

Databricks exposes native Responses routes that the AISIX /v1/responses bridge does not call:

Databricks route	AISIX passthrough path	Scope
`POST /serving-endpoints/open-responses`	`POST /passthrough/databricks/open-responses`	Open Responses format across Databricks-hosted open models, Anthropic Claude, and Google Gemini.
`POST /serving-endpoints/responses`	`POST /passthrough/databricks/responses`	Native OpenAI Responses API for OpenAI models served by Databricks.

The /passthrough/databricks paths on this page assume a passthrough route claiming that prefix, with the workspace serving root (https://<workspace-instance>/serving-endpoints) as its target_url and the Databricks provider key attached; grant the route on the caller key's allowed_routes.

The following example reaches the multi-provider Open Responses route. Send the Databricks serving endpoint name in model, not the AISIX alias:

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
  }'

See Query a model with the Open Responses API for its supported fields and provider-specific behavior. The passthrough route forwards the request and response without Databricks-specific normalization. AISIX detects the Responses envelope from input and records every supported token dimension the response carries, including input, output, cache, and reasoning details. If the provider response omits all supported token fields, token counts remain zero and token-based budgets and cost calculations do not account for the traffic.

Databricks also scores an endpoint at POST /serving-endpoints/{endpoint-name}/invocations, which is not an OpenAI-shaped route. Use a passthrough route to reach it.

The passthrough route forwards to {target_url}/{rest} without borrowing a model alias. Because the route's target_url ends with /serving-endpoints, the wildcard remainder starts at the endpoint name. Do not repeat serving-endpoints in the passthrough path:

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
  }'

The native invocations body names the endpoint in the path and carries no top-level model field, so only caller API key rate limits apply to this call. On an inject-mode passthrough route, model-scoped request-count limits are matched from a model field in the request body naming a configured model of the route's provider. Prefer a normalized AISIX endpoint for traffic that must produce token usage or count against a model's token quota.

Endpoint Coverage

A Databricks alias resolves through the openai adapter, so route support depends on what your serving endpoint implements and on each route's own provider rules.

Route	Behavior with a Databricks alias
`/v1/chat/completions`	Supported, including `stream: true`, when Databricks returns OpenAI-compatible string content. Claude extended-thinking responses require a passthrough route because they use typed content-block arrays.
`/v1/responses`	Supported through the Responses bridge over the chat adapter path because the alias's provider value is `databricks`, not `openai`. It does not call Databricks' native `/serving-endpoints/responses` or `/serving-endpoints/open-responses` route. OpenAI-specific Responses fields without a chat equivalent are ignored.
`/v1/messages`	Supported for Anthropic-shaped callers through translation. A Claude-family serving endpoint is translated as well, because the alias resolves to the `openai` adapter rather than the Anthropic one. Claude extended-thinking responses have the same content-block limitation as `/v1/chat/completions`. Token counting at `/v1/messages/count_tokens` requires a model whose provider value is `anthropic`, so it is not available here.
`/v1/embeddings`	Supported when the alias names a Databricks embedding serving endpoint. Databricks documents `client.embeddings.create` against the same `/serving-endpoints` root in Serve custom LLMs with Custom Model Serving, so one provider key serves both chat and embedding aliases. See Embeddings.
`/v1/images/generations`	Rejected. The route accepts only models whose provider is `openai`.
`/v1/rerank`	Rejected. The route accepts only the `openai`, `cohere`, and `jina` provider values.
`/v1/videos`	Rejected. The route's provider allowlist does not include `databricks`.
`/passthrough/databricks/*`	Available through a configured passthrough route for Databricks-native routes, including `/responses`, `/open-responses`, and endpoint invocations. The route forwards to its `target_url` and does not rewrite AISIX aliases. Recognized chat, completions, and Responses envelopes record supported usage fields; other operations remain opaque.

Next Steps

You have now connected AISIX to Databricks and verified the model alias. Continue with these guides:

Model Aliases: configure routing, retry behavior, or cost metadata for this alias.
Routing and Failover: fail over between a Databricks endpoint and a second provider.
Provider-Specific Overrides: adapt request and response shapes when an upstream API differs from its adapter.
Provider Compatibility: review supported proxy endpoints and provider-specific boundaries.

Prerequisites​

Configure with AISIX Cloud​

Create a Provider Key​

Create a Model​

Create a Caller API Key​

Configure with the Open-Source AISIX Gateway​

Verify the Provider Connection​

Set the Token-Limit Parameter​

Send Reasoning Controls​

Reach Databricks-Native Routes​

Endpoint Coverage​

Next Steps​