Interrogare i servizi del modello

Important

Questa funzionalità è in versione beta. Gli amministratori dell'account possono controllare l'accesso a questa funzionalità dalla pagina Anteprime della console dell'account. Vedere Gestire le anteprime di Azure Databricks.

Questa pagina descrive come eseguire query sui servizi del modello in Unity Catalog usando le API supportate.

Requirements

Anteprima del Gateway di Intelligenza Artificiale Unity abilitata per l'account. Vedere Gestire le anteprime di Azure Databricks.
Un'area di lavoro Azure Databricks in un'area Unity AI Gateway supportata.
Catalogo Unity abilitato per l'area di lavoro. Vedere Abilitare un'area di lavoro per il Catalogo Unity.

API e integrazioni supportate

Unity AI Gateway supporta le API e le integrazioni seguenti:

API unificate: interfacce compatibili con OpenAI per eseguire query sui modelli in Azure Databricks. Passare facilmente da modelli da provider diversi senza modificare la modalità di esecuzione di query su ogni modello.
API native: interfacce specifiche del provider per accedere alle funzionalità più recenti specifiche del modello e del provider.
Agenti di coding: Integra i tuoi agenti di coding con Unity AI Gateway per aggiungere governance e monitoraggio centralizzati ai flussi di lavoro di sviluppo assistiti dall'AI. Vedere Integrazione dell'agente di codifica.
Agenti nelle app di Databricks: creare e distribuire agenti di intelligenza artificiale in App Databricks che instradano il traffico LLM attraverso Unity AI Gateway. Vedere Passaggio 4. Governare l'uso degli LLM da parte degli agenti su Databricks Apps con Unity AI Gateway.
ai_query: usare ai_query per eseguire query sui servizi di modello forniti Azure Databricks da SQL o Python per l'inferenza batch. Vedi come interrogare i servizi del modello con ai_query.

Interrogare i servizi del modello con `ai_query`

È possibile usare la ai_query funzione per eseguire query sui servizi di modello forniti Azure Databricks direttamente da SQL o Python. In questo modo è possibile acquisire informazioni di rilevamento dell'utilizzo per i carichi di lavoro di inferenza batch.

Note

ai_queryIl supporto per Unity AI Gateway è disponibile solo per i servizi di modello forniti da Azure Databricks ,ad esempio databricks-gpt-5-4 o databricks-claude-sonnet-4. I servizi modello creati in Unity AI 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 AI Gateway, ad esempio limiti di frequenza, guardrail, tabelle di inferenza e fallback non si applicano.

Per iniziare:

Abilita l'anteprima di Unity AI Gateway per il tuo account. Vedere Gestire le anteprime di Azure Databricks.
Eseguire query su un servizio modello fornito da Azure Databricks usando ai_query:

SELECT ai_query(
  'databricks-gpt-5-4',
  'Summarize the following text: ' || text_column
) AS summary
FROM my_table
LIMIT 10

Le richieste effettuate tramite ai_query ai servizi modello forniti da Azure Databricks vengono acquisite nella tabella del sistema di rilevamento dell'utilizzo (system.ai_gateway.usage). 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.

Interrogare i servizi dei modelli 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.

API di completamento chat di MLflow

API di completamento della chat di MLflow

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="<model-service>",
  max_tokens=256
)

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

REST API

curl \
  -u token:$DATABRICKS_TOKEN \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model-service>",
    "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

Sostituire <workspace-url> con l'URL dell'area di lavoro Azure Databricks e <model-service> con il nome completo del servizio modello.

API Embeddings MLflow

API di incorporazioni MLflow

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

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

Sostituire <workspace-url> con l'URL dell'area di lavoro Azure Databricks e <model-service> con il nome completo del servizio modello.

Supervisor API

Supervisor API

L'API Supervisor (/mlflow/v1/responses) è un'API indipendente dal provider OpenResponses per la creazione di agenti in fase Beta. Gli amministratori dell'account possono abilitare l'accesso dalla pagina Anteprime . Vedere Gestire le anteprime di Azure Databricks. Scegliere il modello migliore per il caso d'uso dell'agente tra provider, senza modificare il codice.

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

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

Sostituire <workspace-url> con l'URL dell'area di lavoro Azure Databricks e <model-service> con il nome completo del servizio modello.

Interrogare i servizi del modello con API native

Le API native offrono interfacce specifiche del provider per eseguire query sui modelli in Azure Databricks. Usare le API native per accedere alle funzionalità più recenti specifiche del provider.

API Risposte OpenAI

API Risposte OpenAI

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/openai/v1"
)

response = client.responses.create(
  model="<model-service>",
  max_output_tokens=256,
  input=[
    {
      "role": "user",
      "content": [{"type": "input_text", "text": "Hello!"}]
    },
    {
      "role": "assistant",
      "content": [{"type": "output_text", "text": "Hello! How can I assist you today?"}]
    },
    {
      "role": "user",
      "content": [{"type": "input_text", "text": "What is Databricks?"}]
    }
  ]
)

print(response.output)

REST API

curl \
  -u token:$DATABRICKS_TOKEN \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model-service>",
    "max_output_tokens": 256,
    "input": [
      {
        "role": "user",
        "content": [{"type": "input_text", "text": "Hello!"}]
      },
      {
        "role": "assistant",
        "content": [{"type": "output_text", "text": "Hello! How can I assist you today?"}]
      },
      {
        "role": "user",
        "content": [{"type": "input_text", "text": "What is Databricks?"}]
      }
    ]
  }' \
  https://<workspace-url>/ai-gateway/openai/v1/responses

Sostituire <workspace-url> con l'URL dell'area di lavoro Azure Databricks e <model-service> con il nome completo del servizio modello.

API dei messaggi di Anthropic

API Messaggi Anthropic

Python

import anthropic
import os

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

client = anthropic.Anthropic(
  api_key="unused",
  base_url="https://<workspace-url>/ai-gateway/anthropic",
  default_headers={
    "Authorization": f"Bearer {DATABRICKS_TOKEN}",
  },
)

message = client.messages.create(
  model="<model-service>",
  max_tokens=256,
  messages=[
    {"role": "user", "content": "Hello!"},
    {"role": "assistant", "content": "Hello! How can I assist you today?"},
    {"role": "user", "content": "What is Databricks?"},
  ],
)

print(message.content[0].text)

REST API

curl \
  -u token:$DATABRICKS_TOKEN \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model-service>",
    "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/anthropic/v1/messages

Sostituire <workspace-url> con l'URL dell'area di lavoro Azure Databricks e <model-service> con il nome completo del servizio modello.

Google Gemini API

Google Gemini API

Python

from google import genai
from google.genai import types
import os

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

client = genai.Client(
  api_key="databricks",
  http_options=types.HttpOptions(
    base_url="https://<workspace-url>/ai-gateway/gemini",
    headers={
      "Authorization": f"Bearer {DATABRICKS_TOKEN}",
    },
  ),
)

response = client.models.generate_content(
  model="<model-service>",
  contents=[
    types.Content(
      role="user",
      parts=[types.Part(text="Hello!")],
    ),
    types.Content(
      role="model",
      parts=[types.Part(text="Hello! How can I assist you today?")],
    ),
    types.Content(
      role="user",
      parts=[types.Part(text="What is Databricks?")],
    ),
  ],
  config=types.GenerateContentConfig(
    max_output_tokens=256,
  ),
)

print(response.text)

REST API

curl \
  -u token:$DATABRICKS_TOKEN \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [{"text": "Hello!"}]
      },
      {
        "role": "model",
        "parts": [{"text": "Hello! How can I assist you today?"}]
      },
      {
        "role": "user",
        "parts": [{"text": "What is Databricks?"}]
      }
    ],
    "generationConfig": {
      "maxOutputTokens": 256
    }
  }' \
  https://<workspace-url>/ai-gateway/gemini/v1beta/models/<model-service>:generateContent

Sostituire <workspace-url> con l'URL dell'area di lavoro Azure Databricks e <model-service> con il nome completo del servizio modello.

Contrassegna le richieste di rilevamento dell'utilizzo

È possibile associare tag chiave-valore personalizzati a singole richieste usando l'intestazione Databricks-Ai-Gateway-Request-Tags HTTP. I tag delle richieste vengono registrati nella request_tags colonna sia nelle tabelle di sistema di rilevamento dell'utilizzo che nelle tabelle di inferenza, consentendo di tenere traccia dei costi, dell'utilizzo degli attributi e filtrare l'analisi in base a progetto, team, ambiente o qualsiasi altra dimensione.

Il valore dell'intestazione deve essere un oggetto JSON che associa chiavi stringa a valori stringa. Per esempio:

{ "project": "chatbot", "team": "ml-platform", "environment": "production" }

Usare il parametro extra_headers (Python) o passare direttamente l'intestazione (API REST) per allegare tag a una richiesta:

Python (OpenAI SDK)

from openai import OpenAI
import json
import os

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

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

request_tags = {"project": "chatbot", "team": "ml-platform"}

chat_completion = client.chat.completions.create(
  messages=[
    {"role": "user", "content": "What is Databricks?"},
  ],
  model="<model-service>",
  max_tokens=256,
  extra_headers={
    "Databricks-Ai-Gateway-Request-Tags": json.dumps(request_tags)
  }
)

Python (Anthropic SDK)

import anthropic
import json
import os

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

request_tags = {"project": "chatbot", "team": "ml-platform"}

client = anthropic.Anthropic(
  api_key="unused",
  base_url="https://<workspace-url>/ai-gateway/anthropic",
  default_headers={
    "Authorization": f"Bearer {DATABRICKS_TOKEN}",
    "Databricks-Ai-Gateway-Request-Tags": json.dumps(request_tags),
  },
)

message = client.messages.create(
  model="<model-service>",
  max_tokens=256,
  messages=[
    {"role": "user", "content": "What is Databricks?"},
  ],
)

REST API

curl \
  -u token:$DATABRICKS_TOKEN \
  -X POST \
  -H "Content-Type: application/json" \
  -H 'Databricks-Ai-Gateway-Request-Tags: {"project": "chatbot", "team": "ml-platform"}' \
  -d '{
    "model": "<model-service>",
    "max_tokens": 256,
    "messages": [
      {"role": "user", "content": "What is Databricks?"}
    ]
  }' \
  https://<workspace-url>/ai-gateway/mlflow/v1/chat/completions

Sostituire <workspace-url> con l'URL dell'area di lavoro Azure Databricks e <model-service> con il nome completo del servizio modello.

Passaggi successivi

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-06-30

Interrogare i servizi del modello

Requirements

API e integrazioni supportate

Interrogare i servizi del modello con ai_query

Interrogare i servizi dei modelli con API unificate

API di completamento della chat di MLflow

Python

REST API

API di incorporazioni MLflow

Python

REST API

Supervisor API

Python

REST API

Interrogare i servizi del modello con API native

API Risposte OpenAI

Python

REST API

API Messaggi Anthropic

Python

REST API

Google Gemini API

Python

REST API

Contrassegna le richieste di rilevamento dell'utilizzo

Python (OpenAI SDK)

Python (Anthropic SDK)

REST API

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive

Interrogare i servizi del modello con `ai_query`