Eseguire query su un modello di chat

Questo articolo illustra come scrivere richieste di query per i modelli di base ottimizzati per le attività di chat e per utilizzo generico e gestite da Unity AI Gateway.

Tip

Genie Code (modalità agente) può farlo per te. Provare questo prompt di esempio:

Query the databricks-claude-sonnet-4-5 chat model using the OpenAI client. Send a system prompt and a user question, and print the response.

Gli esempi in questo articolo si applicano all'esecuzione di query sui modelli di base resi disponibili tramite:

Requisiti

Esempi di query

Note

Gli esempi seguenti si basano su Unity AI Gateway e sui servizi di modelli. Se si usa il modello che gestisce gli endpoint anziché i servizi modello, sostituire il nome del servizio modello con un nome di endpoint. Per un elenco dei modelli di base disponibili e dei relativi nomi del servizio del modello e degli endpoint, vedere Modelli di base ospitati da Databricks disponibili nelle API Foundation Model.

Gli esempi in questa sezione illustrano come interrogare un servizio di modelli API Foundation Model con pagamento per token, utilizzando le diverse opzioni client.

Completamento della chat OpenAI

Per usare il client OpenAI, specificare il nome del servizio modello come model input. L'esempio seguente presuppone che tu abbia un token API Databricks e che sia installato sul tuo sistema informatico. È anche necessaria l'istanza dell'area di lavoro di Databricks per connettere il client OpenAI a Databricks.


import os
import openai
from openai import OpenAI

client = OpenAI(
    api_key="dapi-your-databricks-token",
    base_url="https://example.staging.cloud.databricks.com/ai-gateway/mlflow/v1"
)

response = client.chat.completions.create(
    model="system.ai.claude-sonnet-4-5",
    messages=[
      {
        "role": "system",
        "content": "You are a helpful assistant."
      },
      {
        "role": "user",
        "content": "What is a mixture of experts model?",
      }
    ],
    max_tokens=256
)

Ad esempio, di seguito è riportato il formato di richiesta previsto per un modello di chat quando si usa l'API REST. Per i modelli esterni, è possibile includere parametri aggiuntivi validi per un determinato provider e configurazione dell'endpoint. Consulta Parametri aggiuntivi di query.

{
  "messages": [
    {
      "role": "user",
      "content": "What is a mixture of experts model?"
    }
  ],
  "max_tokens": 100,
  "temperature": 0.1
}

Di seguito è riportato un formato di risposta previsto per una richiesta effettuata tramite l'API REST:

{
  "model": "databricks-claude-sonnet-4-5",
  "choices": [
    {
      "message": {},
      "index": 0,
      "finish_reason": null
    }
  ],
  "usage": {
    "prompt_tokens": 7,
    "completion_tokens": 74,
    "total_tokens": 81
  },
  "object": "chat.completion",
  "id": null,
  "created": 1698824353
}

Risposte OpenAI

Importante

Questa sezione illustra l'API Risposte OpenAI, un pass-through nativo che supporta il set completo di parametri OpenAI Responses per i modelli OpenAI. Per usare il formato di richiesta risposte con Anthropic Claude, Google Gemini o Modelli aperti ospitati in Databricks, vedere Eseguire query su un modello con l'API Open Responses.

Per utilizzare l'API Responses di OpenAI, specifica il nome del servizio del modello come input model. L'esempio seguente presuppone che tu abbia un token API di Azure Databricks e openai installato nel tuo ambiente di calcolo. È anche necessaria l'istanza dell'area di lavoro di Azure Databricks per connettere il client OpenAI ad Azure Databricks.


import os
import openai
from openai import OpenAI

client = OpenAI(
    api_key="dapi-your-databricks-token",
    base_url="https://example.staging.cloud.databricks.com/ai-gateway/mlflow/v1"
)

response = client.responses.create(
    model="system.ai.gpt-5",
    input=[
      {
        "role": "system",
        "content": "You are a helpful assistant."
      },
      {
        "role": "user",
        "content": "What is a mixture of experts model?",
      }
    ],
    max_output_tokens=256
)

Ad esempio, di seguito è riportato il formato di richiesta previsto quando si usa l'API Risposte OpenAI. Il percorso URL per questa API è /serving-endpoints/responses.

{
  "model": "databricks-gpt-5",
  "input": [
    {
      "role": "user",
      "content": "What is a mixture of experts model?"
    }
  ],
  "max_output_tokens": 100,
  "temperature": 0.1
}

Di seguito è riportato un formato di risposta previsto per una richiesta effettuata tramite l'API Risposte:

{
  "id": "resp_abc123",
  "object": "response",
  "created_at": 1698824353,
  "model": "databricks-gpt-5",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": []
    }
  ],
  "usage": {
    "input_tokens": 7,
    "output_tokens": 74,
    "total_tokens": 81
  }
}

REST API (Interfaccia di Programmazione delle Applicazioni REST)

Importante

L'esempio seguente usa i parametri dell'API REST per l'esecuzione di query sugli endpoint che servono modelli esterni. Questi parametri si trovano in anteprima pubblica e la definizione potrebbe cambiare. Vedi POST /serving-endpoints/{name}/invocations.

curl \
-u token:$DATABRICKS_TOKEN \
-X POST \
-H "Content-Type: application/json" \
-d '{
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": " What is a mixture of experts model?"
    }
  ]
}' \
https://<workspace_host>.databricks.com/serving-endpoints/<your-external-model-endpoint>/invocations \

Ad esempio, di seguito è riportato il formato di richiesta previsto per un modello di chat quando si usa l'API REST. Per i modelli esterni, è possibile includere parametri aggiuntivi validi per un determinato provider e configurazione dell'endpoint. Consulta Parametri aggiuntivi di query.

{
  "messages": [
    {
      "role": "user",
      "content": "What is a mixture of experts model?"
    }
  ],
  "max_tokens": 100,
  "temperature": 0.1
}

Di seguito è riportato un formato di risposta previsto per una richiesta effettuata tramite l'API REST:

{
  "model": "databricks-claude-sonnet-4-5",
  "choices": [
    {
      "message": {},
      "index": 0,
      "finish_reason": null
    }
  ],
  "usage": {
    "prompt_tokens": 7,
    "completion_tokens": 74,
    "total_tokens": 81
  },
  "object": "chat.completion",
  "id": null,
  "created": 1698824353
}

MLflow Deployments SDK

Importante

L'esempio seguente usa l'API predict() di MLflow Deployments SDK.


import mlflow.deployments

# Only required when running this example outside of a Databricks Notebook
export DATABRICKS_HOST="https://<workspace_host>.databricks.com"
export DATABRICKS_TOKEN="dapi-your-databricks-token"

client = mlflow.deployments.get_deploy_client("databricks")

chat_response = client.predict(
    endpoint="system.ai.claude-sonnet-4-5",
    inputs={
        "messages": [
            {
              "role": "user",
              "content": "Hello!"
            },
            {
              "role": "assistant",
              "content": "Hello! How can I assist you today?"
            },
            {
              "role": "user",
              "content": "What is a mixture of experts model??"
            }
        ],
        "temperature": 0.1,
        "max_tokens": 20
    }
)

Ad esempio, di seguito è riportato il formato di richiesta previsto per un modello di chat quando si usa l'API REST. Per i modelli esterni, è possibile includere parametri aggiuntivi validi per un determinato provider e configurazione dell'endpoint. Consulta Parametri aggiuntivi di query.

{
  "messages": [
    {
      "role": "user",
      "content": "What is a mixture of experts model?"
    }
  ],
  "max_tokens": 100,
  "temperature": 0.1
}

Di seguito è riportato un formato di risposta previsto per una richiesta effettuata tramite l'API REST:

{
  "model": "databricks-claude-sonnet-4-5",
  "choices": [
    {
      "message": {},
      "index": 0,
      "finish_reason": null
    }
  ],
  "usage": {
    "prompt_tokens": 7,
    "completion_tokens": 74,
    "total_tokens": 81
  },
  "object": "chat.completion",
  "id": null,
  "created": 1698824353
}

Databricks Python SDK

Questo codice deve essere eseguito in un notebook nell'area di lavoro. Vedi Usare lo SDK di Databricks per Python da un notebook di Azure Databricks.

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.serving import ChatMessage, ChatMessageRole

w = WorkspaceClient()
response = w.serving_endpoints.query(
    name="system.ai.claude-sonnet-4-5",
    messages=[
        ChatMessage(
            role=ChatMessageRole.SYSTEM, content="You are a helpful assistant."
        ),
        ChatMessage(
            role=ChatMessageRole.USER, content="What is a mixture of experts model?"
        ),
    ],
    max_tokens=128,
)
print(f"RESPONSE:\n{response.choices[0].message.content}")

Ad esempio, di seguito è riportato il formato di richiesta previsto per un modello di chat quando si usa l'API REST. Per i modelli esterni, è possibile includere parametri aggiuntivi validi per un determinato provider e configurazione dell'endpoint. Consulta Parametri aggiuntivi di query.

{
  "messages": [
    {
      "role": "user",
      "content": "What is a mixture of experts model?"
    }
  ],
  "max_tokens": 100,
  "temperature": 0.1
}

Di seguito è riportato un formato di risposta previsto per una richiesta effettuata tramite l'API REST:

{
  "model": "databricks-claude-sonnet-4-5",
  "choices": [
    {
      "message": {},
      "index": 0,
      "finish_reason": null
    }
  ],
  "usage": {
    "prompt_tokens": 7,
    "completion_tokens": 74,
    "total_tokens": 81
  },
  "object": "chat.completion",
  "id": null,
  "created": 1698824353
}

Modelli supportati

Vedere Tipi di modelli di base per i modelli di chat supportati.

Risorse aggiuntive

  • Last updated on