Modelli di fondazione e incorporamento delle query

Databricks offre diversi modi per interrogare i modelli di fondazione. Scegli un'interfaccia in base al fatto che tu abbia bisogno di un'API indipendente dal provider, funzionalità specifiche del provider o inferenza batch.

Modi per interrogare un modello

Quickstart

Interroga un servizio modello in due passaggi:

Passo 1: Scegli un modello

Azure Databricks fornisce modelli pronti all'uso, come claude-sonnet-4-5 o gpt-5-6-sol. I modelli forniti da Azure Databricks sono registrati nel Catalogo Unity sotto system.ai.

Passo 2: Invia una richiesta utilizzando l'API unificata compatibile con OpenAI

Usa l'API MLflow Chat Completions con l'SDK Python OpenAI:

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)

Requirements

• Uno spazio di lavoro Azure Databricks in una regione supportata da Unity Gateway.
• Catalogo Unity abilitato per l'area di lavoro. Vedere Abilitare un'area di lavoro per il Catalogo Unity.
• Diritto di accesso al workspace per eseguire query: Accesso allo spazio di lavoro o accesso del consumatore. Si veda Gestione dei diritti di accesso.

Eseguire query sui servizi del modello con API unificate

Le API unificate offrono un'interfaccia compatibile con OpenAI per eseguire query sui modelli in Azure Databricks. Usare API unificate per passare facilmente da modelli a provider diversi senza modificare il codice.

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)

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

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)

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

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)

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

Interrogare i servizi del modello con ai_query

Puoi usare la ai_query funzione per interrogare i servizi del modello direttamente da SQL o Python. In questo modo è possibile acquisire informazioni di rilevamento dell'utilizzo per i carichi di lavoro di inferenza batch.

Per interrogare un servizio modello con ai_query, esegui ai_query contro un servizio modello:

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

La tabella del sistema di monitoraggio dell'uso (system.ai_gateway.usage) cattura le richieste effettuate ai ai_query servizi modello. Queste richieste vengono visualizzate anche nel dashboard di utilizzo predefinito.

Per la sintassi completa ai_query e il riferimento ai parametri, vedere ai_query funzione. Per le procedure consigliate e i modelli supportati, vedere Usare ai_query.

Limitations

• ai_queryil supporto per Unity Gateway è disponibile solo per i modelli forniti da Azure Databricks. Passa il nome del system.ai servizio modello (ad esempio, system.ai.claude-sonnet-4-5 o system.ai.gpt-5-6-sol). I servizi modello che crei in Unity Gateway non sono ancora supportati.
• Solo il monitoraggio dell'utilizzo si applica ai carichi di lavoro di ai_query inferenza in batch. Altre funzionalità di Unity Gateway, come i limiti di velocità, i vincoli di protezione implementati con criteri di servizio, le tabelle di inferenza e i meccanismi di fallback, non si applicano.

Esegui query sui modelli con API native

Le API native offrono interfacce specifiche per il provider per interrogare i modelli su Azure Databricks. Usare le API native per accedere alle funzionalità più recenti specifiche del provider.

Ogni API nativa funziona solo con i servizi modello il cui modello sottostante usa il formato API corrispondente:

• Utilizza l'OpenAI Responses API per interrogare i servizi del modello basati sui modelli OpenAI (GPT).
• Utilizza l'Anthropic Messages API per interrogare i servizi di modello basati sui modelli Claude.
• Usare l'API Google Gemini per eseguire query sui servizi del modello supportati dai modelli Gemini.

Per eseguire query su un servizio modello indipendentemente dal modello sottostante, usare invece le API unificate .

Passaggi successivi

• Individuare e gestire l'accesso ai servizi del modello
• Integrazione con agenti di codifica