Compartilhar via

Depurar um agente de IA implantado

Esta página aborda como depurar problemas comuns com agentes de IA implantados no Azure Databricks.

Ir para:

A maioria das seções de depuração nesta página se aplica a agentes implantados nos Aplicativos do Databricks. No entanto, você também pode encontrar informações de depuração para agentes implantados no Model Serving (legado) usando as guias de seleção.

Criar agentes usando as práticas recomendadas

Use as seguintes práticas recomendadas ao criar agentes:

  • Habilitar o rastreamento do MLflow: siga as práticas recomendadas em Criar um agente de IA e implante-o nos Aplicativos do Databricks. Habilite o registro automático de rastreamento do MLflow para facilitar a depuração de seus agentes.
  • Documente claramente as ferramentas: Descrições claras de ferramentas e parâmetros garantem que o agente entenda suas ferramentas e as utilize adequadamente. Consulte Aprimorar a chamada de ferramentas com documentação clara.
  • Adicionar tempos limite e limites de token a chamadas LLM: adicione tempos limite e limites de token às chamadas LLM em seu código para evitar atrasos causados por etapas de execução prolongada.
    • Se o agente usar o cliente OpenAI para consultar um ponto de extremidade de serviço do Azure Databricks LLM, defina tempos limite personalizados nas chamadas de ponto de extremidade de serviço, conforme necessário.
  • Validar a configuração antes da implantação: execute antes de databricks bundle validate implantar para detectar problemas de configuração do YAML antecipadamente. Isso ajuda a identificar referências de recursos incompatíveis, permissões inválidas e erros de sintaxe.
  • Teste localmente primeiro: use o desenvolvimento local para detectar problemas antes de implantar. Inicie o servidor do agente localmente, teste com solicitações de exemplo e verifique se os rastreamentos do MLflow aparecem corretamente antes de você implantar no Databricks Apps.

Depurar problemas de desenvolvimento local

Teste seu agente localmente para identificar problemas antes da implantação.

Antes de executar o agente localmente, verifique se o ambiente está configurado corretamente:

  1. Verifique a versão da CLI do Databricks: execute databricks -v para verificar se você tem a versão 0.283.0 ou posterior.

  2. Verificar perfis da CLI: execute databricks auth profiles para ver os perfis de autenticação configurados.

  3. Validar a configuração do ambiente: verifique se o .env arquivo contém as variáveis necessárias, especialmente MLFLOW_TRACKING_URI, que devem usar o formato databricks://PROFILE_NAME para incluir o perfil da CLI.

Erros comuns de desenvolvimento local

Erro Motivo Solução
The provided MLFLOW_EXPERIMENT_ID does not exist O formato ou experimento de URI de rastreamento incorreto foi excluído Verifique se MLFLOW_TRACKING_URI usa o formato databricks://PROFILE_NAME com o nome do perfil da CLI
Module not found Dependências não instaladas Executar uv sync para instalar dependências
Port already in use Outro processo usando a porta Usar --port sinalizador para especificar uma porta diferente (por exemplo, uv run start-app --port 8001)
Erros de autenticação ao executar localmente O ambiente não está configurado Execute o script de início rápido ou configure manualmente o arquivo com seu .env perfil da CLI

Testar localmente o agente

Para testar seu agente antes da implantação:

  1. Inicie o servidor do agente localmente:

    uv run start-app

  2. Em outro terminal, envie uma solicitação de teste:

    curl -X POST http://localhost:8000/invocations \
  -H "Content-Type: application/json" \
  -d '{"input": [{"role": "user", "content": "hello"}]}'

  3. Exiba rastreamentos do MLflow na interface do usuário do Azure Databricks para verificar se o agente está registrando rastreamentos corretamente.

Problemas de configuração de depuração

Erros de configuração dentro databricks.yml e app.yaml são fontes comuns de falhas de implantação.

Validar a configuração de Pacotes de Automação Declarativa

Valide a configuração de Pacotes de Automação Declarativa antes de implantar o aplicativo:

databricks bundle validate

Este comando verifica sua configuração em busca de:

  • Erros de sintaxe YAML
  • Campos obrigatórios ausentes
  • Referências de recurso não válidas
  • Problemas de configuração de permissão

Incompatibilidades de configuração comuns

Ponto de configuração Regra Como depurar
valueFrom referências em app.yaml Deve corresponder exatamente a um recurso name em databricks.yml Pesquise a cadeia de caracteres exata em ambos os arquivos para verificar se elas correspondem
Nome do aplicativo Deve começar com o agent- prefixo (por exemplo, agent-data-analyst) Verifique o campo name em resources.apps abaixo de databricks.yml
ID de espaço do Genie Deve ser a string hexadecimal de 32 caracteres da URL do Genie Extraia do caminho da URL: https://workspace.cloud.databricks.com/genie/rooms/{SPACE_ID}
Referência de função do Catálogo do Unity Deve usar o formato catalog.schema.function_name Verificar se a função existe usando databricks unity-catalog functions list
Referência da instância do Lakebase Deve usar value (não valueFrom) no app.yaml arquivo O nome da instância é uma cadeia de caracteres literal, não uma referência de recurso

Depurar problemas de implantação

Agentes implantados nos Aplicativos

Erro de aplicativo já existente

Erro: O aplicativo já existe

Se você vir Error: failed to create app - An app with the same name already exists, terá duas opções:

Opção 1: Associar ao aplicativo existente (recomendado)

# Get existing app configuration
databricks apps get <app-name> --output json

# Sync the configuration to your databricks.yml, then bind
databricks bundle deployment bind <bundle-name> <app-name> --auto-approve

# Deploy
databricks bundle deploy
databricks bundle run <bundle-name>

Opção 2: Excluir e recriar

databricks apps delete <app-name>
databricks bundle deploy
databricks bundle run <bundle-name>
O aplicativo não está atualizando após a implantação

O aplicativo não está atualizando após a implantação

databricks bundle deploy carrega apenas arquivos no workspace. Você também deve executar databricks bundle run <bundle-name> para reiniciar o aplicativo com o novo código.

Sempre implante usando ambos os comandos:

databricks bundle deploy && databricks bundle run <bundle-name>
Exibir o status e os logs de implantação

Exibir o status e os logs de implantação

Para verificar o status de implantação do aplicativo:

databricks apps get <app-name>

Para exibir os logs do aplicativo em tempo real:

databricks apps logs <app-name> --follow

Agentes no Serviço de Modelos (legado)

Se você implantou seu agente em um ponto de extremidade de Model Serving usando agents.deploy(), revise o guia de depuração para Model Serving para identificar problemas específicos da implantação.

Para depurar problemas de tempo de execução, como solicitações lentas ou com falha, consulte Depurar erros em tempo de execução.

Depurar erros de runtime

Agentes implantados nos Aplicativos

Use logs de aplicativo e teste de solicitação para identificar problemas com seu agente implantado.

Analisar os logs do aplicativo

Exiba logs em tempo real do aplicativo implantado:

databricks apps logs <app-name> --follow

Procurar por:

  • Rastreamentos de pilha que indicam erros de código
  • Mensagens de permissão negadas para recursos
  • Erros de conexão com serviços externos
  • Mensagens de tempo limite

Erros comuns de tempo de execução

Error Causa Solution
Redirecionamento 302 ao consultar o aplicativo Usando o Token de Acesso Pessoal em vez de OAuth Obter um token OAuth com databricks auth token
Agente que não usa ferramentas disponíveis Ferramentas não devolvidas do cliente MCP Verifique se a URL do servidor MCP está correta e se o recurso tem permissões adequadas em databricks.yml
A resposta de streaming é interrompida no meio da resposta Tempo limite da conexão Aumentar a variável de CHAT_PROXY_TIMEOUT_SECONDS ambiente em app.yaml
Agente retornando "Memória não disponível" Ausente user_id na solicitação Passar custom_inputs.user_id no payload da solicitação
Respostas vazias ou de erro apesar do status 200 Erro na resposta transmitida Verifique o conteúdo do fluxo real e os logs do aplicativo, não apenas o código de status HTTP

Agentes no Serviço de Modelos (legado)

Use tabelas de inferência e rastreamentos do MLflow para identificar problemas com agentes implantados em endpoints de Model Serving.

Identificar solicitações problemáticas

Se você habilitou o registro automático de rastreamento do MLflow durante a criação do agente, os rastreamentos serão registrados automaticamente em tabelas de inferência. Use esses rastreamentos para identificar os componentes do agente que estão lentos ou com falha.

  1. No espaço de trabalho, acesse a guia Serviço e selecione o nome da implantação.
  2. Na seção Tabelas de Inferência , localize o nome totalmente qualificado da tabela de inferência. Por exemplo, my-catalog.my-schema.my-table.
  3. Execute o seguinte em um notebook do Databricks: 
    %sql
SELECT * FROM my-catalog.my-schema.my-table
  4. Inspecione a coluna Resposta para obter informações detalhadas de rastreamento.
  5. Filtre em request_time, databricks_request_id ou status_code para restringir os resultados. 
    %sql
SELECT * FROM my-catalog.my-schema.my-table
WHERE status_code != 200

Analisar problemas de causa raiz

Depois de identificar solicitações com falha ou lentas, use a API mlflow.models.validate_serving_input para invocar seu agente contra a solicitação de entrada com falha. Exiba o rastreamento resultante e realize a análise da causa raiz na resposta que falhou.

Para obter um loop de desenvolvimento mais rápido, atualize o código do agente diretamente e itere invocando seu agente em relação ao exemplo de entrada com falha.

Depurar erros de autenticação

Agentes implantados nos Aplicativos

Autenticação de token OAuth necessária

Autenticação de token OAuth necessária

Você deve usar um token OAuth do Databricks para consultar agentes implantados em Aplicativos. Usar um PAT (Token de Acesso Pessoal) resulta em um erro de redirecionamento 302.

Para obter um token OAuth:

databricks auth token

Use o token em solicitações para seu aplicativo implantado:

TOKEN=$(databricks auth token | jq -r '.access_token')
curl -X POST <app-url>/invocations \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input": [{"role": "user", "content": "hello"}]}'
Erros de permissão de recurso

Erros de permissões de recursos

Quando o agente não puder acessar recursos do workspace, verifique se o recurso está configurado corretamente.databricks.yml Cada tipo de recurso requer permissões específicas:

Error Causa Solution
Permissão negada no espaço do Genie Recurso faltando genie_space Adicionar um genie_space recurso com permission: 'CAN_RUN'
Índice de pesquisa de vetor não acessível Recurso ausente uc_securable para o índice Adicionar um uc_securable recurso com securable_type: 'TABLE' e permission: 'SELECT'
Execução de função do Catálogo do Unity negada Falta de recurso uc_securable para a função Adicionar um uc_securable recurso com securable_type: 'FUNCTION' e permission: 'EXECUTE'
Acesso ao endpoint de serviço negado Recurso faltando serving_endpoint Adicionar um serving_endpoint recurso com permission: 'CAN_QUERY'
Acesso negado ao sql warehouse Recurso faltando sql_warehouse Adicionar um sql_warehouse recurso com permission: 'CAN_USE'

Configuração de recurso de exemplo em databricks.yml:

resources:
  apps:
    my_agent:
      name: 'agent-my-app'
      resources:
        - name: 'my_genie_space'
          genie_space:
            space_id: '01234567890abcdef01234567890abcd'
            permission: 'CAN_RUN'
        - name: 'my_vector_index'
          uc_securable:
            securable_full_name: 'catalog.schema.index_name'
            securable_type: 'TABLE'
            permission: 'SELECT'
Permissões personalizadas do servidor MCP

Permissões personalizadas do servidor MCP

Se o agente se conectar a um servidor MCP personalizado em execução como um aplicativo do Databricks, você deverá conceder permissões manualmente, pois os aplicativos ainda não têm suporte como dependências de recursos.databricks.yml

# Get your agent app's service principal
AGENT_SP=$(databricks apps get <agent-app-name> --output json | jq -r '.service_principal_name')

# Grant permission on the MCP server app
databricks apps update-permissions <mcp-server-app-name> \
  --json "{\"access_control_list\": [{\"service_principal_name\": \"$AGENT_SP\", \"permission_level\": \"CAN_USE\"}]}"

Agentes no Serviço de Modelos (legado)

Se o agente implantado encontrar erros de autenticação ao acessar recursos como índices de busca vetorial ou pontos de extremidade LLM, verifique se ele está registrado com os recursos necessários para efetuar a passagem automática de autenticação. Confira a passagem de autenticação automática.

Para inspecionar os recursos registrados, execute o seguinte em um notebook:

%pip install -U mlflow[databricks]
%restart_python

import mlflow
mlflow.set_registry_uri("databricks-uc")

# Replace with the model name and version of your deployed agent
agent_registered_model_name = ...
agent_model_version = ...

model_uri = f"models:/{agent_registered_model_name}/{agent_model_version}"
agent_info = mlflow.models.Model.load(model_uri)
print(f"Resources logged for agent model {model_uri}:", agent_info.resources)

Para adicionar novamente recursos ausentes ou incorretos, registre o agente e implante-o novamente.

Se você usar a autenticação manual para recursos, verifique se as variáveis de ambiente estão definidas corretamente. As configurações manuais substituem as configurações de autenticação automática. Consulte a autenticação manual.

Depurar problemas de memória e armazenamento

Para agentes que usam o Lakebase para armazenamento de memória, os seguintes problemas são comuns:

Error Causa Solution
relation 'store' does not exist Tabelas de memória não inicializadas Executar await store.setup() localmente antes de implantar para criar tabelas necessárias
Unable to resolve :re[LKB] instance Nome da instância incorreto ou configuração incorreta Verifique LAKEBASE_INSTANCE_NAME usa value (não valueFrom) em app.yaml e corresponde ao instance_name em databricks.yml
permission denied for table store Permissões do Lakebase ausentes Adicionar um database recurso em databricks.yml com permission: 'CAN_CONNECT_AND_CREATE'
A memória não está sendo mantida entre as conversas Diferente user_id por solicitação Certifique-se de passar um user_id consistente em custom_inputs para cada usuário

Exemplo de configuração de recursos do Lakebase:

resources:
  apps:
    my_agent:
      resources:
        - name: 'memory_database'
          database:
            instance_name: '<lakebase-instance-name>'
            database_name: 'postgres'
            permission: 'CAN_CONNECT_AND_CREATE'

Antes de implantar um agente com memória, inicialize as tabelas localmente:

import asyncio
from databricks_langchain import AsyncDatabricksStore

async def setup_memory():
    async with AsyncDatabricksStore(
        instance_name='your-lakebase-instance',
        embedding_endpoint='databricks-gte-large-en',
        embedding_dims=1024,
    ) as store:
        await store.setup()

asyncio.run(setup_memory())
  • Last updated on