Introdução ao LangSmith para observabilidade de pipelines LLM

1. Fundamentos da Observabilidade em Pipelines LLM

A observabilidade em pipelines de Large Language Models (LLMs) vai muito além do monitoramento tradicional. Enquanto sistemas convencionais podem ser depurados com logs de erro e métricas de desempenho, aplicações com LLMs apresentam desafios únicos que exigem uma abordagem especializada.

Desafios específicos de pipelines LLM:

  • Alucinações: O modelo pode gerar informações factualmente incorretas com alta confiança
  • Latência variável: Tempos de resposta podem oscilar drasticamente dependendo do provedor e do tamanho do prompt
  • Custos imprevisíveis: Cada chamada consome tokens, e o custo total pode crescer exponencialmente em chains complexas
  • Debugging de cadeias: Em pipelines com múltiplas etapas (retrieval, geração, pós-processamento), identificar onde algo falhou é complexo

A diferença crucial entre logging tradicional e tracing estruturado para LLMs está na capacidade de rastrear o fluxo completo de uma requisição. Enquanto logs tradicionais registram eventos isolados, o tracing captura a árvore completa de chamadas, incluindo prompts enviados, respostas recebidas, metadados de contexto e tempo de execução de cada etapa.

2. Visão Geral do LangSmith: Ecossistema e Componentes

O LangSmith é uma plataforma de observabilidade desenvolvida pela LangChain, projetada especificamente para aplicações LLM. Ele se integra nativamente ao ecossistema LangChain, mas também funciona com outras estruturas e chamadas diretas a APIs.

Principais funcionalidades:

  • Tracing: Captura automática de cada etapa do pipeline, desde chamadas individuais até chains complexas com múltiplos componentes
  • Avaliação: Execução de testes automatizados com métricas predefinidas para medir qualidade das respostas
  • Monitoramento: Dashboards em tempo real com métricas de latência, custo e taxa de erro
  • Datasets: Criação e gerenciamento de conjuntos de exemplos para testes de regressão

Modelo de preços: A versão gratuita inclui 5.000 runs por mês e acesso ao dashboard básico. Planos pagos oferecem limites maiores, retenção estendida de dados e funcionalidades avançadas de equipe.

3. Configuração Inicial e Primeiros Passos

Para começar, crie uma conta no LangSmith e gere uma chave de API no painel de configurações.

Instalação do SDK:

pip install langsmith langchain-openai

Configuração do ambiente:

import os
os.environ["LANGCHAIN_TRACING_V2"] = "true"
os.environ["LANGCHAIN_API_KEY"] = "sua-chave-aqui"
os.environ["LANGCHAIN_PROJECT"] = "meu-primeiro-projeto"

Exemplo mínimo de tracing habilitado:

from langchain_openai import ChatOpenAI
from langchain.schema import HumanMessage

llm = ChatOpenAI(model="gpt-3.5-turbo", temperature=0)
response = llm.invoke([HumanMessage(content="Explique o que é observabilidade em IA")])

print(response.content)

Ao executar esse código, o LangSmith automaticamente captura a chamada, incluindo o prompt, a resposta, o modelo utilizado, a temperatura e o tempo de execução. Todas essas informações ficam disponíveis no dashboard.

4. Rastreamento (Tracing) de Pipelines com LangSmith

O tracing automático do LangSmith captura a estrutura hierárquica de execução. Cada chamada a um componente LangChain (LLM, chain, retriever, tool) gera um run com metadados específicos.

Exemplo de chain com tracing:

from langchain.chains import LLMChain
from langchain.prompts import PromptTemplate

prompt = PromptTemplate(
    input_variables=["pergunta"],
    template="Responda em português: {pergunta}"
)

chain = LLMChain(llm=llm, prompt=prompt)
resultado = chain.invoke({"pergunta": "Qual a capital do Brasil?"})
print(resultado["text"])

Estrutura de runs no dashboard:

  • Run pai: A chain completa
  • Runs filhos: Cada componente individual (prompt template, LLM call)
  • Metadados customizados: É possível adicionar tags, usuários e propriedades personalizadas
from langsmith import traceable

@traceable(name="processar_consulta", tags=["produção"], metadata={"usuario": "admin"})
def processar_consulta(pergunta: str):
    return chain.invoke({"pergunta": pergunta})

O dashboard interativo permite visualizar o fluxo completo, expandir cada etapa para ver detalhes do prompt, resposta e tempo de execução.

5. Avaliação de Desempenho com Datasets e Testes

Datasets no LangSmith permitem criar conjuntos de exemplos com inputs e outputs esperados para testes automatizados.

Criação de dataset:

from langsmith import Client

client = Client()
dataset = client.create_dataset(
    dataset_name="Perguntas Geografia",
    description="Perguntas básicas de geografia para teste"
)

client.create_examples(
    dataset_id=dataset.id,
    inputs=[{"pergunta": "Qual a capital da França?"}],
    outputs=[{"resposta": "Paris"}]
)

Execução de avaliação automatizada:

from langsmith.evaluation import evaluate

def avaliar_resposta(inputs: dict, outputs: dict, reference_outputs: dict) -> dict:
    resposta_esperada = reference_outputs["resposta"].lower()
    resposta_gerada = outputs["text"].lower()
    correta = resposta_esperada in resposta_gerada
    return {"score": 1.0 if correta else 0.0, "key": "exatidao"}

resultados = evaluate(
    chain.invoke,
    data=dataset,
    evaluators=[avaliar_resposta]
)

O LangSmith também oferece métricas predefinidas como relevância, toxicidade e similaridade semântica.

6. Monitoramento Contínuo e Alertas

Os dashboards do LangSmith fornecem métricas em tempo real essenciais para operação de pipelines LLM.

Métricas principais:

  • Latência média por chamada
  • Custo total e por token
  • Taxa de erro
  • Distribuição de modelos utilizados
  • Frequência de tokens de entrada vs. saída

Configuração de alertas:

# Exemplo conceitual (via dashboard web)
# 1. Acesse "Monitor" > "Alertas"
# 2. Crie regra: "Latência > 5 segundos por mais de 10 chamadas consecutivas"
# 3. Configure notificação via Slack ou e-mail

Alertas bem configurados permitem detectar rapidamente degradações de performance, como aumento de latência devido a mudanças no provedor ou erros em cadeia causados por alterações no modelo.

7. Armadilhas Comuns e Boas Práticas

Evitando vazamento de dados sensíveis:

from langsmith import traceable

@traceable(metadata={"redact": True})
def processar_dados_sensiveis(dados: dict):
    # Implementar lógica de sanitização
    dados_seguros = {k: "***" if k in ["senha", "token"] else v for k, v in dados.items()}
    return chain.invoke(dados_seguros)

Gerenciamento de custos com sampling:

import random

if random.random() < 0.1:  # Amostra 10% das chamadas
    os.environ["LANGCHAIN_TRACING_V2"] = "true"
else:
    os.environ["LANGCHAIN_TRACING_V2"] = "false"

Versionamento de prompts e modelos:

Mantenha um registro claro de qual versão de prompt e modelo está sendo utilizada. O LangSmith permite associar versões a runs específicos:

from langsmith import traceable

@traceable(metadata={"versao_prompt": "v2.3", "modelo": "gpt-4-turbo"})
def executar_pipeline(entrada: str):
    # Lógica do pipeline
    pass

A observabilidade com LangSmith transforma o desenvolvimento de aplicações LLM de uma atividade de "caixa preta" para um processo transparente e mensurável. Com tracing, avaliação automatizada e monitoramento contínuo, é possível identificar gargalos, medir qualidade e iterar com confiança.

Referências