Een query uitvoeren op een agent die is geïmplementeerd op Azure Databricks

Meer informatie over het verzenden van aanvragen naar agents die zijn geïmplementeerd in Databricks Apps of Model Serving-eindpunten. Databricks biedt meerdere querymethoden voor verschillende use cases en integratiebehoeften.

Selecteer de querybenadering die het beste past bij uw use-case:

Databricks raadt de Databricks OpenAI-client aan voor nieuwe toepassingen. Kies de REST API bij het integreren met platforms die openAI-compatibele eindpunten verwachten.

Databricks OpenAI-client (aanbevolen)

Databricks raadt u aan om de DatabricksOpenAI-client te gebruiken om een query uit te voeren op een geïmplementeerde agent. Afhankelijk van de API van uw geïmplementeerde agent gebruikt u de antwoorden of de voltooiingsclient voor chats:

Agents die zijn ingezet in apps

Gebruik het volgende voorbeeld voor agents die worden gehost op Databricks-apps volgens de ResponsesAgent interface. Dit is de aanbevolen benadering voor het bouwen van agents. U moet een Databricks OAuth-token gebruiken om agents op te vragen die worden gehost 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)

Als u custom_inputs wilt doorgeven, kunt u ze toevoegen met de extra_body parameter.

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)

Als u een tracerings-id wilt ophalen uit het antwoord, neemt u de x-mlflow-return-trace-id header op met behulp van extra_headers. Gebruik vervolgens MLflow get_trace om de volledige tracering op te halen.

response = client.responses.create(
    model=f"apps/{app_name}",
    input=input_msgs,
    extra_headers={"x-mlflow-return-trace-id": "true"},
)
trace_id = response.metadata["trace_id"]
trace = client.get_trace(trace_id)

Agents voor modelbediening

Gebruik het volgende voorbeeld voor verouderde agents die worden gehost op Model Serving volgens de ResponsesAgent interface. U kunt een Databricks OAuth-token of een PERSONAL Access Token (PAT) gebruiken om query's uit te voeren op agents die worden gehost op 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)

Als u custom_inputs of databricks_options wilt doorgeven, kunt u ze toevoegen met de extra_body parameter.

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)

Gebruik het volgende voorbeeld voor legacy agents bij het gebruik van modelserveren volgens de interfaces ChatAgent of 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)

Als u custom_inputs of databricks_options wilt doorgeven, kunt u ze toevoegen met de extra_body parameter.

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

De Databricks REST API biedt eindpunten voor modellen die compatibel zijn met OpenAI. Hiermee kunt u Databricks-agents gebruiken voor toepassingen waarvoor OpenAI-interfaces zijn vereist.

Deze methode is ideaal voor:

• Taalagnostische toepassingen die GEBRUIKMAKEN van HTTP-aanvragen
• Integreren met platformen van derden die openAI-compatibele API's verwachten
• Migreren van OpenAI naar Databricks met minimale codewijzigingen

Verifieer met de REST API met behulp van een Databricks OAuth-token. Raadpleeg de documentatie voor Databricks-verificatie voor meer opties en informatie.

Agents die zijn ingezet in apps

Gebruik het volgende voorbeeld voor agents die worden gehost op Databricks-apps volgens de ResponsesAgent interface. Dit is de aanbevolen benadering voor het bouwen van agents. U moet een Databricks OAuth-token gebruiken om agents op te vragen die worden gehost 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
  }'

Als u custom_inputs wilt doorgeven, kunt u deze toevoegen aan de aanvraagbody.

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 }
  }'

Als u een tracerings-id wilt ophalen uit het antwoord, neemt u de x-mlflow-return-trace-id header op in uw aanvraag. De hoofdtekst van het antwoord bevat een metadata.trace_id veld met de tracerings-id. Voor streamingaanvragen wordt de tracerings-id verzonden als een afzonderlijke SSE-gebeurtenis (data: {"trace_id": "tr-..."}) aan het einde van de stream. Gebruik vervolgens MLflow get_trace om de volledige tracering op te halen met behulp van de tracerings-id.

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

Agents voor modelbediening

Gebruik het volgende voorbeeld voor verouderde agents die worden gehost op Model Serving volgens de ResponsesAgent interface. U kunt een Databricks OAuth-token of een PERSONAL Access Token (PAT) gebruiken om query's uit te voeren op agents die worden gehost op Model Serving. De REST API-aanroep is gelijk aan:

• De Databricks OpenAI-client gebruiken met responses.create.
• Een POST-aanvraag verzenden naar de URL van het specifieke eindpunt (bijvoorbeeld: https://<host.databricks.com>/serving-endpoints/\<model-name\>/invocations). Zie voor meer informatie de pagina Model Serving van uw eindpunt en de Model Serving-documentatie.

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
  }'

Als u custom_inputs of databricks_options wilt doorgeven, kunt u deze toevoegen aan de aanvraagbody.

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 }
  }'

Gebruik het volgende voor agents die zijn gemaakt met verouderde ChatAgent- of ChatModel-interfaces. Dit komt overeen met:

• De Databricks OpenAI-client gebruiken met chat.completions.create.
• Een POST-aanvraag verzenden naar de URL van het specifieke eindpunt (bijvoorbeeld: https://<host.databricks.com>/serving-endpoints/\<model-name\>/invocations). Zie voor meer informatie de pagina Model Serving van uw eindpunt en de Model Serving-documentatie.

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
  }'

Als u custom_inputs of databricks_options wilt doorgeven, kunt u deze toevoegen aan de aanvraagbody.

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 }
  }'

AI-functies: ai_query

U kunt ai_query een query uitvoeren op een geïmplementeerde agent die wordt gehost op modelservers met behulp van SQL. Zie ai_query de functie voor SQL-syntaxis en parameterdefinities.

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

Volgende stappen

GenAI-apps monitoren in productie