Observabilidade e depuração
A observabilidade conecta os resultados com as etapas que os produzem.
O que você aprenderá
- Explique: erros precisam de caminhos explícitos
- Aplique a ideia em um exemplo: Observabilidade e depuração
- Reconheça as limitações e verifique o resultado do exercício
A observabilidade conecta os resultados com as etapas que os produzem. Os dados de diagnóstico devem ajudar sem expor segredos.
Você pode seguir este curso sem conta ou programação. Os exemplos usam dados sintéticos e os resultados da IA precisam ser verificados.
Como funciona, passo a passo
Erros precisam de caminhos explícitos
Um tempo limite é diferente de um erro de permissão. Tente novamente apenas erros transitórios, com tentativas limitadas e atrasos crescentes. Uma operação com efeitos colaterais pode ser executada antes que sua resposta seja perdida; tentar novamente sem uma chave de idempotência pode duplicar o efeito. O streaming mostra o progresso, mas não garante a conclusão. Os pontos de verificação podem permitir que estágios com falha sejam retomados dentro dos limites de tempo de execução. Armazene o identificador de execução, estágio, duração e erro enquanto remove segredos dos logs. Meça caminhos lentos, bem como médias.
Defina o sucesso antes de otimizar
Prepare solicitações representativas e respostas ou propriedades esperadas. Inclui casos comuns, ambiguidade, dados faltantes e erros de ferramentas. Para RAG, meça a recuperação de evidências separadamente da correção da resposta. Recall@k mede a parcela de evidências relevantes encontradas nos primeiros k resultados; Precision@k mede a parcela de resultados retornados que são relevantes. Para agentes, rastreie também ações, permissões e paradas. Um LLM como juiz pode acelerar a avaliação, mas precisa de calibração em humanos. Não altere prompt, modelo e índice simultaneamente se quiser entender o que melhorou os resultados.
Verifique o acesso antes de usar
As permissões devem ser aplicadas pelos servidores e pela camada de dados. Não deixe o modelo decidir se um usuário pode ver um documento. Filtre as fontes antes que elas entrem no contexto, não depois de gerar a resposta. Use credenciais de acesso mínimo, mantenha-as fora de prompts, capturas de tela e códigos do navegador e alterne as chaves expostas. Uma lista de permissões de domínio de widget não substitui a autenticação de API. A autenticação identifica você; a autorização determina as operações e os dados que você pode usar. Teste o acesso negado também.
O esquema explicativo
Siga as setas sólidas para o fluxo principal. As setas azuis tracejadas fornecem dados ou contexto; setas rosa tracejadas mostram feedback ou retorno de resultados. Cores e formas distinguem modelos, lojas, decisões e resultados. Em telas pequenas, role na horizontal para acompanhar o esquema completo.
Um exemplo completo
Uma resposta lenta tem recuperação de 0,2 s, reclassificação de 0,4 se ferramenta externa de 8 s. Um identificador de execução conecta estágios; as versões do prompt e do modelo são registradas.
Experimente você mesmo
- Crie uma linha do tempo com estágio, duração, resultado e identificador de execução.
- Registre a entrada, a fonte e o resultado esperado antes de executar o experimento. Use apenas os dados fictícios do exemplo.
- Siga as etapas do diagrama. A cada passo registre quais informações são recebidas e produzidas; não confunda o resultado intermediário com o resultado final.
- Repita após remover as informações necessárias ou tornar a entrada ambígua. Verifique se o sistema esclarece, interrompe ou inventa uma resposta.
- Compare com a solução explicada. Guarde a configuração, data, resultado e explicação das diferenças. Mude uma coisa e teste novamente.
Uma solução explicada
Identifique a ferramenta como a origem da latência e retenha o contexto do erro sem credenciais. Um exercício bem-sucedido permite mostrar a conexão entre entradas, etapas e resultados. Quando falta informação, uma resposta cautelosa é mais útil do que detalhes inventados. Compare mais do que estilo: verifique também as condições, fontes e operações.
Quando esta abordagem ajuda e quais são seus limites
Ferramentas de rastreamento externas não são controles de UI assumidos. Escolha esta abordagem quando ela melhorar uma necessidade medida. Mantenha uma linha de base simples e compare os resultados usando dados idênticos. Um exemplo de sucesso não estabelece confiabilidade em todas as situações.
Verifique o que aprendeu
O tempo limite prova que a operação não foi executada?
Não. Verifique o estado antes de tentar novamente uma ação com efeitos colaterais.
Uma boa pontuação de estilo prova o sucesso do agente?
Não. O agente pode escrever lindamente depois de usar a ferramenta ou os dados errados.
Que resultado este exercício deve produzir?
Identifique a ferramenta como a origem da latência e retenha o contexto do erro sem credenciais.
Termos para lembrar
- Idempotência: Repetição controlada sem duplicar um efeito.
- Regressão / Regressão: uma alteração que quebra um caso anteriormente correto.
- Autorizar / Autorização: Verificando o direito de acesso a uma operação ou recurso.
Fontes e sua próxima etapa
Para preparar: E03 — Avaliando agentes e equipes