Modèles de fondation et d’intégration de query

Databricks propose plusieurs façons de query les modèles de fondation. Choisissez une interface selon que vous avez besoin d'une API indépendante du fournisseur, de fonctionnalités spécifiques au fournisseur ou de l'inférence par batch.

Moyens d’interroger un modèle

Approche	Quand l’utiliser
APIs unifiées	Utilisez des interfaces compatibles avec OpenResponses et OpenAI Chat Completions. Databricks traduit chaque requête dans le format natif du modèle en aval, ce qui vous permet de changer de modèle d’un fournisseur à l’autre sans modifier le code client.
APIs natives du fournisseur	Utilisez des fonctionnalités spécifiques au fournisseur ou le code SDK OpenAI, Anthropic ou Google existant.
ai_query	Exécutez une inférence par batch à partir de SQL ou de Python.

Approche	Quand l’utiliser
APIs unifiées	Utilisez des interfaces compatibles avec OpenResponses et OpenAI Chat Completions. Databricks traduit chaque requête dans le format natif du modèle en aval, ce qui vous permet de changer de modèle d’un fournisseur à l’autre sans modifier le code client.
APIs natives du fournisseur	Utilisez des fonctionnalités spécifiques au fournisseur ou le code SDK OpenAI, Anthropic ou Google existant.
ai_query	Exécutez une inférence par batch à partir de SQL ou de Python.

Guide de démarrage rapide

Interrogez un service de modèle en deux étapes :

Étape 1 : Choisir un modèle

Databricks fournit des modèles prêts à l’emploi, tels que claude-sonnet-4-5 ou gpt-5-6-sol. Les modèles fournis par Databricks sont enregistrés dans Unity Catalog sous system.ai.

Étape 2 : Envoyer une requête à l’aide de l’API unifiée compatible avec OpenAI

Utilisez l’API MLflow Chat Completions avec le SDK Python OpenAI :

Python

from openai import OpenAI
import os

DATABRICKS_TOKEN = os.environ.get('DATABRICKS_TOKEN')

client = OpenAI(
  api_key=DATABRICKS_TOKEN,  # your personal access token
  base_url="https://<workspace-url>/ai-gateway/mlflow/v1"  # your Databricks workspace instance
)

chat_completion = client.chat.completions.create(
  messages=[
    {"role": "user", "content": "What is Databricks?"},
  ],
  model="system.ai.claude-sonnet-4-5",
  max_tokens=256
)

print(chat_completion.choices[0].message.content)

Exigences

• Un workspace Databricks dans une région prise en charge par Unity Gateway.
• Unity Catalog activé pour votre workspace. Consultez Activer un workspace pour Unity Catalog.
• Droit Workspace pour la query : Workspace access ou Consumer access avec l'aperçu Consumer access to Unity Gateway activé pour votre compte (Public Preview). Consultez Gérer les droits et Gérer les aperçus Databricks.

Interroger les services de modèle avec des APIs unifiées

Les APIs unifiées offrent une interface compatible avec OpenAI pour interroger les modèles sur Databricks. Utilisez des APIs unifiées pour passer de manière transparente d'un modèle à l'autre entre différents fournisseurs sans modifier votre code.

API de réponses unifiées

API de réponses unifiées

L’API Unified Responses (/mlflow/v1/responses) est une API agnostique vis-à-vis des fournisseurs et compatible avec OpenResponsespour interroger des modèles sur Databricks. Databricks la recommande de préférence à l’API MLflow Chat Completions. Choisissez le meilleur modèle pour votre cas d’utilisation parmi différents fournisseurs, sans modifier votre code.

Python

Python

from openai import OpenAI
import os

DATABRICKS_TOKEN = os.environ.get('DATABRICKS_TOKEN')

client = OpenAI(
  api_key=DATABRICKS_TOKEN,
  base_url="https://<workspace-url>/ai-gateway/mlflow/v1"
)

response = client.responses.create(
  model="<model-service>",
  input=[{"role": "user", "content": "What is Databricks?"}]
)

print(response.output_text)

REST API

Bash

curl \
  -u token:$DATABRICKS_TOKEN \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model-service>",
    "input": [
      {"role": "user", "content": "What is Databricks?"}
    ]
  }' \
  https://<workspace-url>/ai-gateway/mlflow/v1/responses

Remplacez <workspace-url> par l'URL de votre workspace Databricks et <model-service> par le nom complet de votre service de modèle.

API MLflow Chat Completions

API MLflow Chat Completions

Python

Python

from openai import OpenAI
import os

DATABRICKS_TOKEN = os.environ.get('DATABRICKS_TOKEN')

client = OpenAI(
  api_key=DATABRICKS_TOKEN,
  base_url="https://<workspace-url>/ai-gateway/mlflow/v1"
)

chat_completion = client.chat.completions.create(
  messages=[
    {"role": "user", "content": "Hello!"},
    {"role": "assistant", "content": "Hello! How can I assist you today?"},
    {"role": "user", "content": "What is Databricks?"},
  ],
  model="system.ai.gpt-5-6-sol",
  max_tokens=256
)

print(chat_completion.choices[0].message.content)

REST API

Bash

curl \
  -u token:$DATABRICKS_TOKEN \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "model": "system.ai.gpt-5-6-sol",
    "max_tokens": 256,
    "messages": [
      {"role": "user", "content": "Hello!"},
      {"role": "assistant", "content": "Hello! How can I assist you today?"},
      {"role": "user", "content": "What is Databricks?"}
    ]
  }' \
  https://<workspace-url>/ai-gateway/mlflow/v1/chat/completions

Remplacez <workspace-url> par l’URL de votre workspace Databricks.

API d'embeddings MLflow

API d’embeddings MLflow

Python

Python

from openai import OpenAI
import os

DATABRICKS_TOKEN = os.environ.get('DATABRICKS_TOKEN')

client = OpenAI(
  api_key=DATABRICKS_TOKEN,
  base_url="https://<workspace-url>/ai-gateway/mlflow/v1"
)

embeddings = client.embeddings.create(
  input="What is Databricks?",
  model="<model-service>"
)

print(embeddings.data[0].embedding)

REST API

Bash

curl \
  -u token:$DATABRICKS_TOKEN \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model-service>",
    "input": "What is Databricks?"
  }' \
  https://<workspace-url>/ai-gateway/mlflow/v1/embeddings

Remplacez <workspace-url> par l'URL de votre workspace Databricks et <model-service> par le nom complet de votre service de modèle.

Query model services with ai_query

Vous pouvez utiliser la fonction ai_query pour query les services de modèle directement depuis SQL ou Python. Cela vous permet de capturer des informations de suivi de l'utilisation pour vos charges de travail d'inférence par batch.

Pour query un service de modèle avec ai_query, exécutez ai_query sur un service de modèle :

SQL

SELECT ai_query(
  'system.ai.claude-sonnet-4-5',
  'Summarize the following text: ' || text_column
) AS summary
FROM my_table
LIMIT 10

La table système de suivi de l'utilisation (system.ai_gateway.usage) capture les requêtes effectuées via ai_query vers les services de modèle. Ces requêtes apparaissent également dans le tableau de bord d'utilisation intégré.

Pour la syntaxe complète ai_query et la référence des paramètres, consultez la fonctionai_query. Pour les bonnes pratiques et les modèles pris en charge, consultez Utiliser ai_query.

Limitations

• ai_query La prise en charge de Unity Gateway est uniquement disponible pour les modèles fournis par Databricks. Transmettez le nom du service de modèle system.ai (par exemple, system.ai.claude-sonnet-4-5 ou system.ai.gpt-5-6-sol). Les services de modèle que vous créez dans Unity Gateway ne sont pas encore pris en charge.
• Seul le suivi de l’utilisation s’applique aux charges de travail d’inférence batch ai_query. Les autres fonctionnalités de Unity Gateway telles que les limites de débit, les garde-fous implémentés avec des politiques de service, les tables d’inférence et les fallbacks ne s’appliquent pas.

Interroger les services de modèle avec des APIs natives

Les APIs natives offrent des interfaces spécifiques aux fournisseurs pour interroger les modèles sur Databricks. Utilisez les APIs natives pour accéder aux dernières fonctionnalités spécifiques aux fournisseurs.

Chaque API native fonctionne uniquement avec les services de modèles dont le modèle sous-jacent utilise le format d'API correspondant :

• Utilisez l'OpenAI Responses API pour interroger les services de modèles soutenus par les modèles OpenAI (GPT).
• Utilisez l'Anthropic Messages API pour interroger les services de modèle pris en charge par les modèles Claude.
• Utilisez l'Google Gemini API pour interroger les services de modèle reposant sur les modèles Gemini.

Pour interroger un service de modèle quel que soit son modèle sous-jacent, utilisez plutôt les APIs unifiées.

Étapes suivantes

• Découvrez et gouvernez l’accès aux services de modèle
• Intégration avec les agents de codage