Consulta de un agente implementado en Azure Databricks

Obtenga información sobre cómo enviar solicitudes a los agentes implementados en aplicaciones de Databricks o puntos de conexión de servicio de modelos. Databricks proporciona varios métodos de consulta para adaptarse a diferentes casos de uso y necesidades de integración.

Seleccione el enfoque de consulta que mejor se adapte a su caso de uso:

Databricks recomienda el cliente de OpenAI de Databricks para las nuevas aplicaciones. Elija la API REST al integrar con plataformas que esperan puntos de conexión compatibles con OpenAI.

Cliente openAI de Databricks (recomendado)

Databricks recomienda usar el cliente de DatabricksOpenAI para consultar un agente implementado. En función de la API del agente implementado, usará las respuestas o el cliente de finalizaciones de chat:

Agentes implementados en aplicaciones

Utilice el siguiente ejemplo para los agentes hospedados en Aplicaciones de Databricks siguiendo la ResponsesAgent interfaz, que es el enfoque recomendado para crear agentes. Debe usar un token de OAuth de Databricks para consultar los agentes hospedados en Aplicaciones de Databricks.

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)

Si desea pasar custom_inputs, puede agregarlos con el parámetro 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)

Agentes en servicio de modelos

Utilice el ejemplo siguiente para los agentes heredados hospedados en Model Serving siguiendo el ResponsesAgent interfaz. Puede usar un token de OAuth de Databricks o un token de acceso personal (PAT) para consultar los agentes hospedados en 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)

Si desea pasar en custom_inputs o databricks_options, puede agregarlos con el parámetro extra_body.

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)

Utilice el siguiente ejemplo para los agentes heredados en el modelo de servicio, siguiendo las interfaces 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)

Si desea pasar en custom_inputs o databricks_options, puede agregarlos con el parámetro extra_body.

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

La API REST de Databricks proporciona puntos de conexión para los modelos compatibles con OpenAI. Esto le permite usar agentes de Databricks para atender aplicaciones que requieren interfaces openAI.

Este enfoque es ideal para:

• Aplicaciones independientes del lenguaje que usan solicitudes HTTP
• Integración con plataformas de terceros que esperan API compatibles con OpenAI
• Migración de OpenAI a Databricks con cambios mínimos de código

Autentíquese con la API REST mediante un token de OAuth de Databricks. Consulte la documentación de autenticación de Databricks para obtener más opciones e información.

Agentes implementados en aplicaciones

Utiliza el ejemplo siguiente para los agentes hospedados en Aplicaciones de Databricks siguiendo la interfaz ResponsesAgent, que es el enfoque recomendado para crear agentes. Debe usar un token de OAuth de Databricks para consultar los agentes hospedados en Aplicaciones de Databricks.

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

Si desea pasar custom_inputs, puede agregarlo al cuerpo de la solicitud:

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

Agentes en servicio de modelos

Utilice el ejemplo siguiente para los agentes heredados hospedados en Model Serving siguiendo el ResponsesAgent interfaz. Puede usar un token de OAuth de Databricks o un token de acceso personal (PAT) para consultar los agentes hospedados en Model Serving. La llamada a la API rest es equivalente a:

• Uso del Cliente OpenAI de Databricks con responses.create.
• Enviar una solicitud POST a la dirección URL del punto de conexión específico (por ejemplo: https://<host.databricks.com>/serving-endpoints/\<model-name\>/invocations). Para obtener más información, consulte la página Servicio de modelos del punto de conexión y la documentación de servicio de modelos.

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

Si desea incluir custom_inputs o databricks_options, puede agregarlos al cuerpo de la solicitud.

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

Use lo siguiente para los agentes creados con interfaces de ChatAgent o ChatModel heredadas. Esto equivale a:

• Uso del Cliente OpenAI de Databricks con chat.completions.create.
• Enviar una solicitud POST a la dirección URL del punto de conexión específico (por ejemplo: https://<host.databricks.com>/serving-endpoints/\<model-name\>/invocations). Para obtener más información, consulte la página Servicio de modelos del punto de conexión y la documentación de servicio de modelos.

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

Si quieres pasar custom_inputs o databricks_options, puedes agregarlos al cuerpo de la solicitud:

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

Funciones de IA: ai_query

Puede usar ai_query para consultar un agente implementado hospedado en el servicio de modelos mediante SQL. Consulte la función ai_query para la sintaxis SQL y las definiciones de parámetros.

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

Pasos siguientes

Supervisión de GenAI en producción