Skip to main content
API7.ai Logo

Databricks

Connect AISIX AI Gateway to Databricks Model Serving so applications can call the foundation models served from your Databricks workspace through the gateway's OpenAI-compatible API. AISIX keeps the Databricks token on the gateway side. It authorizes model access with caller API keys and allowlists, and applies the same rate-limit and usage-accounting controls as other model aliases.

Databricks Model Serving exposes an OpenAI-compatible API, so it uses the openai adapter with a workspace-specific api_base.

Databricks reaches AISIX through the community section of the provider catalog, which AISIX sources from models.dev. The Cloud Admin API accepts databricks as a provider value and assigns the openai adapter with bearer authentication, but AISIX does not curate a base URL or any request and response rewrites for it. Everything the wire needs beyond the plain OpenAI shape is yours to configure on the provider key. Two of those details matter in practice for Databricks, and both are covered below: the base URL, which is workspace-specific and required, and the token-limit parameter name.

Prerequisites​

The following examples configure the upstream through the AISIX Cloud Admin API. Before configuring the upstream, prepare the following:

  • Access to AISIX Cloud with an environment, an attached gateway, and a write-scoped admin token. For On-Premises, follow the AISIX Cloud Quickstart. To request Hybrid Cloud access, contact API7.
  • 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 personal access token scoped to that workspace.

Export the connection details used by every request below:

# Replace with your values
export AISIX_CP="http://localhost:8080/api"
export AISIX_TOKEN="aisix_pat_YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"

Configure the Databricks Upstream​

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

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 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 Credentials.

❸ 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 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 — a template, not a resolved URL, because every workspace has its own host. AISIX performs no placeholder substitution, and the fallback value is stored as written. The create request still succeeds, so the provider key ends up carrying the literal ${DATABRICKS_HOST} text in place of a workspace host, and the first chat request fails at the upstream. That template also names the Databricks AI Gateway root rather than the /serving-endpoints root this page configures. Setting api_base explicitly avoids the fallback entirely.

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 typeNamingExample
Databricks-hosted foundation model, pay-per-tokenDatabricks 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
Custom, provisioned-throughput, or external-model endpointYou 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. A workspace token can reach every serving endpoint in that workspace, so one provider key normally serves every Databricks alias in the environment.

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.

Verify the Provider Connection​

Send a chat-completions request through the AISIX proxy:

curl -sS -X POST "http://127.0.0.1:3000/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:

SymptomLikely cause
Upstream authentication errorThe personal access token is expired, or it belongs to a different workspace than the host in api_base.
Upstream 404 on the endpoint pathapi_base does not stop at /serving-endpoints, so AISIX built a path Databricks does not serve.
Upstream error naming the endpointmodel_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. Current OpenAI clients send max_completion_tokens 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, add the rename to the request block when you create the Databricks provider key:

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}"'"],
    "request": {
      "param_renames": {
        "max_completion_tokens": "max_tokens"
      }
    }
  }'

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.

note

The 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 the reasoning control depends on the model family behind the endpoint rather than on the route. Databricks documents both shapes in Query reasoning models: reasoning_effort for its GPT endpoints, and an Anthropic-style thinking object for its Claude endpoints. AISIX does not strip unrecognized top-level parameters from a chat-completions body, so either shape reaches the upstream as the caller sent it.

For a GPT-family endpoint, send the effort level 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"
}

For a Claude-family endpoint, send a thinking budget instead. Databricks requires budget_tokens to be at least 1024 and lower than max_tokens:

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

Confirm the accepted control and its values for the specific endpoint you configured, because a body that one Databricks endpoint accepts can be rejected by another endpoint in the same workspace.

Because Databricks is a community-catalog entry, AISIX registers no reasoning-field override for it and preserves reasoning that the upstream already returns in the canonical reasoning_content field. If a serving endpoint streams reasoning on a different delta path, set response.reasoning_field on the provider key.

Reach Databricks-Native Routes​

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

Passthrough forwards to {api_base}/{rest} after selecting a model alias whose provider is databricks that the caller API key is allowed to use. Because api_base already 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 "http://127.0.0.1:3000/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. Model-scoped rate limits on passthrough are matched from a model field in the request body. Prefer /v1/chat/completions for traffic that must count against a model's 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.

RouteBehavior with a Databricks alias
/v1/chat/completionsSupported, including stream: true.
/v1/responsesSupported through the Responses bridge over the chat adapter path. The bridge is used because the alias's provider value is databricks, not openai.
/v1/messagesSupported 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. Token counting at /v1/messages/count_tokens requires a model whose provider value is anthropic, so it is not available here.
/v1/embeddingsSupported when the alias names a Databricks embedding serving endpoint. Databricks documents client.embeddings.create against the same /serving-endpoints root in Query an embedding model, so one provider key serves both chat and embedding aliases. See Embeddings.
/v1/images/generationsRejected. The route accepts only models whose provider is openai.
/v1/rerankRejected. The route accepts only the openai, cohere, and jina provider values.
/v1/videosRejected. The route's provider allowlist does not include databricks.
/passthrough/databricks/*Supported for Databricks-native routes, with limited gateway normalization. There is no built-in base URL for this provider value, so passthrough depends on the api_base configured on the provider key.

Next Steps​

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