Condividi tramite

Interrogare un agente AI Mosaic distribuito

Scopri come inviare richieste agli agenti implementati a un endpoint di servizio del modello. Databricks offre più metodi di query per soddisfare diversi casi d'uso e esigenze di integrazione.

Per informazioni su come distribuire gli agenti, vedere Distribuire un agente per applicazioni di intelligenza artificiale generative.

Selezionare l'approccio di query più adatto al caso d'uso:

Metodo Vantaggi principali
Client OpenAI di Databricks (scelta consigliata) Integrazione nativa, supporto completo delle funzionalità, funzionalità di streaming
Client di distribuzioni MLflow Modelli MLflow esistenti, pipeline di Machine Learning stabilite
REST API Compatibile con OpenAI, indipendente dal linguaggio, funziona con gli strumenti esistenti
Funzioni di intelligenza artificiale: ai_query Compatibile con OpenAI, funziona con gli strumenti esistenti

Databricks consiglia il client OpenAI di Databricks per le nuove applicazioni. Scegliere l'API REST durante l'integrazione con le piattaforme che prevedono endpoint compatibili con OpenAI.

Databricks consiglia di usare il client OpenAI di Databricks per eseguire query su un agente distribuito. A seconda dell'API dell'agente distribuito, si useranno le risposte o il client di completamento della chat:

Endpoint di ResponsesAgent

Usare l'esempio seguente per gli agenti creati con l'interfaccia ResponsesAgent, che è l'approccio consigliato per la creazione degli agenti.

from databricks.sdk import WorkspaceClient

input_msgs = [{"role": "user", "content": "What does Databricks do?"}]
endpoint = "<agent-endpoint-name>" # TODO: update this with your endpoint name

w = WorkspaceClient()
client = w.serving_endpoints.get_open_ai_client()

## Run for non-streaming responses. Invokes `predict`
response = client.responses.create(model=endpoint, input=input_msgs)
print(response)

## Include stream=True for streaming responses. Invokes `predict_stream`
streaming_response = client.responses.create(model=endpoint, input=input_msgs, stream=True)
for chunk in streaming_response:
  print(chunk)

Se si vuole passare custom_inputs o databricks_options, è possibile aggiungerli con il extra_body parametro :

streaming_response = client.responses.create(
    model=endpoint,
    input=input_msgs,
    stream=True,
    extra_body={
        "custom_inputs": {"id": 5},
        "databricks_options": {"return_trace": True},
    },
)
for chunk in streaming_response:
    print(chunk)

Gli endpoint ChatAgent o ChatModel

Usare l'esempio seguente per gli agenti creati con interfacce ChatAgent o ChatModel legacy, che sono ancora supportate ma non consigliate per i nuovi agenti.

from databricks.sdk import WorkspaceClient

messages = [{"role": "user", "content": "What does Databricks do?"}]
endpoint = "<agent-endpoint-name>" # TODO: update this with your endpoint name

w = WorkspaceClient()
client = w.serving_endpoints.get_open_ai_client()

## Run for non-streaming responses. Invokes `predict`
response = client.chat.completions.create(model=endpoint, messages=messages)
print(response)

## Include stream=True for streaming responses. Invokes `predict_stream`
streaming_response = client.chat.completions.create(model=endpoint, messages=messages, stream=True)
for chunk in streaming_response:
  print(chunk)

Se si vuole passare custom_inputs o databricks_options, è possibile aggiungerli con il extra_body parametro :

streaming_response = client.chat.completions.create(
    model=endpoint,
    messages=messages,
    stream=True,
    extra_body={
        "custom_inputs": {"id": 5},
        "databricks_options": {"return_trace": True},
    },
)
for chunk in streaming_response:
    print(chunk)

Client di implementazioni MLflow

Utilizzare il client di distribuzioni MLflow quando si lavora all'interno di flussi di lavoro e pipeline esistenti di MLflow. Questo approccio si integra naturalmente con la gestione del rilevamento e dell'esperimento di MLflow.

Gli esempi seguenti illustrano come eseguire query su un agente usando il client di distribuzione MLflow. Per le nuove applicazioni, Databricks consiglia di usare il client OpenAI di Databricks per le funzionalità avanzate e l'integrazione nativa.

A seconda dell'API dell'agente distribuito, si userà il formato ResponsesAgent o ChatAgent:

Endpoint di ResponsesAgent

Usare l'esempio seguente per gli agenti creati con l'interfaccia ResponsesAgent, che è l'approccio consigliato per la creazione degli agenti.

from mlflow.deployments import get_deploy_client

client = get_deploy_client()
input_example = {
    "input": [{"role": "user", "content": "What does Databricks do?"}],
    ## Optional: Include any custom inputs
    ## "custom_inputs": {"id": 5},
    "databricks_options": {"return_trace": True},
}
endpoint = "<agent-endpoint-name>" # TODO: update this with your endpoint name

## Call predict for non-streaming responses
response = client.predict(endpoint=endpoint, inputs=input_example)

## Call predict_stream for streaming responses
streaming_response = client.predict_stream(endpoint=endpoint, inputs=input_example)

Gli endpoint ChatAgent o ChatModel

Usare questa opzione per gli agenti creati con interfacce ChatAgent o ChatModel legacy, che sono ancora supportate ma non consigliate per i nuovi agenti.

from mlflow.deployments import get_deploy_client

client = get_deploy_client()
input_example = {
    "messages": [{"role": "user", "content": "What does Databricks do?"}],
    ## Optional: Include any custom inputs
    ## "custom_inputs": {"id": 5},
    "databricks_options": {"return_trace": True},
}
endpoint = "<agent-endpoint-name>" # TODO: update this with your endpoint name

## Call predict for non-streaming responses
response = client.predict(endpoint=endpoint, inputs=input_example)

## Call predict_stream for streaming responses
streaming_response = client.predict_stream(endpoint=endpoint, inputs=input_example)

client.predict() e client.predict_stream() chiamano le funzioni dell'agente definite da te durante la creazione dell'agente. Consulta Streaming delle risposte.

REST API

L'API REST di Databricks fornisce endpoint per i modelli compatibili con OpenAI. In questo modo è possibile usare gli agenti Databricks per gestire applicazioni che richiedono interfacce OpenAI.

Questo approccio è ideale per:

  • Applicazioni indipendenti dal linguaggio che usano richieste HTTP
  • Integrazione con piattaforme di terze parti che prevedono API compatibili con OpenAI
  • Migrazione da OpenAI a Databricks con modifiche minime al codice

Eseguire l'autenticazione con l'API REST usando un token OAuth di Databricks o un token di accesso personale (PAT). Gli esempi seguenti usano un token OAuth di Databricks, fare riferimento alla documentazione sull'autenticazione di Databricks per altre opzioni e informazioni.

Endpoint di ResponsesAgent

Usare l'esempio seguente per gli agenti creati con l'interfaccia ResponsesAgent, che è l'approccio consigliato per la creazione degli agenti. La chiamata API REST equivale a:

  • Utilizzare il client OpenAI di Databricks con responses.create.
  • Invio di una richiesta POST all'URL dell'endpoint specifico (ad esempio: https://<host.databricks.com>/serving-endpoints/\<model-name\>/invocations). Per altre informazioni, vedere la pagina relativa alla gestione del modello dell'endpoint e la documentazione sulla gestione dei modelli.
curl --request POST \
  --url https://<host.databricks.com\>/serving-endpoints/responses \
  --header 'Authorization: Bearer <OAuth token>' \
  --header 'content-type: application/json' \
  --data '{
    "model": "\<model-name\>",
    "input": [{ "role": "user", "content": "hi" }],
    "stream": true
  }'

Se si vuole passare custom_inputs o databricks_options, è possibile aggiungerli con il extra_body parametro :

curl --request POST \
  --url https://<host.databricks.com\>/serving-endpoints/responses \
  --header 'Authorization: Bearer <OAuth token>' \
  --header 'content-type: application/json' \
  --data '{
    "model": "\<model-name\>",
    "input": [{ "role": "user", "content": "hi" }],
    "stream": true,
    "extra_body": {
      "custom_inputs": { "id": 5 },
      "databricks_options": { "return_trace": true }
    }
  }'

Gli endpoint ChatAgent o ChatModel

Usare questa opzione per gli agenti creati con interfacce ChatAgent o ChatModel legacy, che sono ancora supportate ma non consigliate per i nuovi agenti. Equivale a:

  • Utilizzare il client OpenAI di Databricks con chat.completions.create.
  • Invio di una richiesta POST all'URL dell'endpoint specifico (ad esempio: https://<host.databricks.com>/serving-endpoints/\<model-name\>/invocations). Per altre informazioni, vedere la pagina relativa alla gestione del modello dell'endpoint e la documentazione sulla gestione dei modelli.
curl --request POST \
  --url https://<host.databricks.com\>/serving-endpoints/chat/completions \
  --header 'Authorization: Bearer <OAuth token>' \
  --header 'content-type: application/json' \
  --data '{
    "model": "\<model-name\>",
    "messages": [{ "role": "user", "content": "hi" }],
    "stream": true
  }'

Se si vuole passare custom_inputs o databricks_options, è possibile aggiungerli con il extra_body parametro :

curl --request POST \
  --url https://<host.databricks.com\>/serving-endpoints/chat/completions \
  --header 'Authorization: Bearer <OAuth token>' \
  --header 'content-type: application/json' \
  --data '{
    "model": "\<model-name\>",
    "messages": [{ "role": "user", "content": "hi" }],
    "stream": true,
    "extra_body": {
      "custom_inputs": { "id": 5 },
      "databricks_options": { "return_trace": true }
    }
  }'

Funzioni di intelligenza artificiale: ai_query

È possibile usare ai_query per eseguire query su un agente di intelligenza artificiale distribuito usando SQL. Vedere ai_query la funzione per la sintassi SQL e le definizioni dei parametri.

SELECT ai_query(
  "<model name>", question
) FROM (VALUES ('what is MLflow?'), ('how does MLflow work?')) AS t(question);

Passaggi successivi

Monitorare genAI nell'ambiente di produzione

  • Last updated on