Pular para o conteúdo principal
Última atualização em

Consulte um agente implantado no Databricks

Saiba como enviar solicitações a agentes implantados nos Databricks Apps ou no endpoint de Model Serving. O Databricks fornece vários métodos de consulta para atender a diferentes casos de uso e necessidades de integração.

Selecione a abordagem de consulta que melhor se adapta ao seu caso de uso:

Método

Principais benefícios

Cliente Databricks OpenAI (Recomendado)

Integração nativa, suporte completo a recursos, funcionalidades de transmissão

API REST

Compatível com OpenAI, independente de linguagem, funciona com ferramentas existentes

AI Functions: ai_query

Compatível com OpenAI, consulte apenas agentes legados hospedados em endpoint de Model Serving

A Databricks recomenda o **Cliente OpenAI da Databricks** para novas aplicações. Escolha a **API REST** ao integrar com plataformas que esperam endpoints compatíveis com OpenAI.

Cliente OpenAI Databricks (Recomendado)​

Databricks recomenda que você use o Databricks OpenAI Client para consultar um agente implantado. Dependendo da API do seu agente implantado, você usará as respostas ou o cliente de conclusões de chat:

Use o exemplo a seguir para agentes hospedados no Databricks Apps seguindo a interface ResponsesAgent, que é a abordagem recomendada para construir agentes. Você deve usar um token OAuth do Databricks para consultar agentes hospedados no Databricks Apps.

Python
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 deseja inserir custom_inputs, pode adicioná-los com o parâmetro extra_body:

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

Para recuperar um ID de rastreamento da resposta, inclua o cabeçalho x-mlflow-return-trace-id usando extra_headers. Em seguida, use o MLflow get_trace para recuperar o rastreamento completo.

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

API REST​

A API REST do Databricks fornece endpoints para modelos que são compatíveis com OpenAI. Isso permite que você use agentes do Databricks para disponibilizar aplicativos que exigem interfaces OpenAI.

Esta abordagem é ideal para:

  • Aplicativos agnósticos de linguagem que usam solicitações HTTP
  • Integração com plataformas de terceiros que esperam APIs compatíveis com OpenAI
  • Migrando do OpenAI para o Databricks com alterações mínimas no código

Autentique-se com a API REST usando um tokens OAuth do Databricks. Consulte a documentação de autenticação da Databricks para obter mais opções e informações.

Use o exemplo a seguir para agentes hospedados no Databricks Apps seguindo a interface ResponsesAgent, que é a abordagem recomendada para construir agentes. Você deve usar um token OAuth do Databricks para consultar agentes hospedados no Databricks Apps.

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

Para passar custom_inputs, é possível adicioná-los ao corpo da solicitação:

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

Para recuperar um ID de rastreamento da resposta, inclua o cabeçalho x-mlflow-return-trace-id em sua solicitação. O corpo da resposta inclui um campo metadata.trace_id contendo o ID de rastreamento. Para solicitações de transmissão, o ID de rastreamento é enviado como um evento SSE separado (data: {"trace_id": "tr-..."}) próximo ao final da transmissão. Então, use o MLflow get_trace para recuperar o rastreamento completo usando o ID de rastreamento.

Bash
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" }]
  }'

AI Functions: ai_query​

É possível utilizar ai_query para consultar um agente implantado hospedado em servindo modelo utilizando SQL. Consulte ai_query function para a sintaxe SQL e definições de parâmetros.

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

Próximos os passos​

Monitore aplicativos GenAI em produção

Nesta página