Condividi tramite

Interrogare un agente distribuito su Azure Databricks

Informazioni su come inviare richieste agli agenti distribuiti agli endpoint di Databricks Apps o Model Serving. Databricks offre più metodi di query per soddisfare diversi casi d'uso e esigenze di integrazione.

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
REST API Compatibile con OpenAI, indipendente dal linguaggio, funziona con gli strumenti esistenti
Funzioni di intelligenza artificiale: ai_query Compatibile con OpenAI, eseguire query sugli agenti legacy ospitati solo sugli endpoint di gestione dei modelli

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 DatabricksOpenAI 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:

Agenti distribuiti nelle app

Usare l'esempio seguente per gli agenti ospitati in Databricks Apps seguendo l'interfaccia ResponsesAgent, che è l'approccio consigliato per la creazione di agenti. È necessario usare un token OAuth di Databricks per eseguire query sugli agenti ospitati in Databricks Apps.

from databricks.sdk import WorkspaceClient
from databricks_openai import DatabricksOpenAI

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

# The WorkspaceClient must be configured with OAuth authentication
# See: https://docs.databricks.com/aws/en/dev-tools/auth/oauth-u2m.html
w = WorkspaceClient()

client = DatabricksOpenAI(workspace_client=w)

# Run for non-streaming responses. Calls the "invoke" method
# Include the "apps/" prefix in the model name
response = client.responses.create(model=f"apps/{app_name}", input=input_msgs)
print(response)

# Include stream=True for streaming responses. Calls the "stream" method
# Include the "apps/" prefix in the model name
streaming_response = client.responses.create(
    model=f"apps/{app_name}", input=input_msgs, stream=True
)
for chunk in streaming_response:
    print(chunk)

Se si vuole passare custom_inputs, è possibile aggiungerlo con il parametro extra_body

streaming_response = client.responses.create(
    model=f"apps/{app_name}",
    input=input_msgs,
    stream=True,
    extra_body={
        "custom_inputs": {"id": 5},
    },
)
for chunk in streaming_response:
    print(chunk)

Agenti nella gestione dei modelli

Usare l'esempio seguente per gli agenti legacy ospitati in Model Serving seguendo l'interfaccia ResponsesAgent . È possibile usare un token OAuth di Databricks o un token di accesso personale per eseguire query sugli agenti ospitati in Model Serving.

from databricks_openai import DatabricksOpenAI

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

client = DatabricksOpenAI()

# 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)

Usare l'esempio seguente per gli agenti legacy nel modello che segue le interfacce ChatAgent o ChatModel.

from databricks.sdk import WorkspaceClient

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

ws_client = WorkspaceClient()
client = ws_client.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)

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. Per altre opzioni e informazioni, vedere la documentazione sull'autenticazione di Databricks .

Agenti distribuiti nelle app

Usare l'esempio seguente per gli agenti ospitati in Databricks Apps utilizzando l'interfaccia ResponsesAgent, che costituisce l'approccio consigliato per la creazione di agenti. È necessario usare un token OAuth di Databricks per eseguire query sugli agenti ospitati in Databricks Apps.

curl --request POST \
  --url <app-url>.databricksapps.com/responses \
  --header 'Authorization: Bearer <OAuth token>' \
  --header 'content-type: application/json' \
  --data '{
    "input": [{ "role": "user", "content": "hi" }],
    "stream": true
  }'

Se si vuole passare custom_inputs, è possibile aggiungerlo al corpo della richiesta.

curl --request POST \
  --url <app-url>.databricksapps.com/responses \
  --header 'Authorization: Bearer <OAuth token>' \
  --header 'content-type: application/json' \
  --data '{
    "input": [{ "role": "user", "content": "hi" }],
    "stream": true,
    "custom_inputs": { "id": 5 }
  }'

Agenti nel servizio dei modelli

Usare l'esempio seguente per gli agenti legacy ospitati in Model Serving seguendo l'interfaccia ResponsesAgent . È possibile usare un token OAuth di Databricks o un token di accesso personale per eseguire query sugli agenti ospitati in Model Serving. 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 Model Serving 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 vuoi passare custom_inputs o databricks_options, è possibile aggiungerli al corpo della richiesta:

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,
    "custom_inputs": { "id": 5 },
    "databricks_options": { "return_trace": true }
  }'

Usare quanto segue per gli agenti creati con interfacce ChatAgent o ChatModel legacy. 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 Model Serving 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 vuoi passare custom_inputs o databricks_options, puoi aggiungerli al corpo della richiesta.

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,
    "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 distribuito ospitato nella gestione di modelli 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