O que acontece dentro do pipeline da sua aplicação LLM?

Disclaimer

Este texto foi inicialmente concebido pela IA Generativa em função da transcrição de um vídeo do canal de Daniel Romero (a pessoa que lidera nossa Especialização em Engenharia de IA). Se preferir acompanhar por vídeo, é só dar o play.

Introdução

Quando colocamos uma aplicação LLM em produção, entender o que está acontecendo internamente deixa de ser opcional. Qual prompt foi montado? Quantos tokens foram consumidos? Onde exatamente uma chamada falhou? LangSmith é uma plataforma de observabilidade do ecossistema LangChain projetada para responder essas perguntas em todos os estágios do ciclo de vida de uma aplicação LLM, da prototipagem à produção.

Um ponto relevante: apesar de fazer parte do ecossistema LangChain, o LangSmith funciona de maneira independente. Isso significa que você pode monitorar chains e agentes desenvolvidos com qualquer framework, incluindo DSPy, LlamaIndex, CrewAI, LangGraph e outros.

Configuração inicial

Para começar a utilizar o LangSmith, o processo é direto. Você cria uma conta em smith.langchain.com e, uma vez logado, tem acesso às principais seções da plataforma:

• Projetos: coleções de rastreamento organizadas por aplicação
• Annotations: para anotar e revisar execuções
• Playground: ambiente para testes rápidos
• Datasets: conjuntos de dados para avaliação de qualidade
• Hub: funciona como um repositório compartilhado de prompts, ferramentas e chains, similar ao Docker Hub

A configuração no código também é simples. Você gera uma chave de API nas configurações da plataforma e define algumas variáveis de ambiente:

LANGCHAIN_TRACING_V2=true
LANGCHAIN_ENDPOINT=https://api.smith.langchain.com
LANGCHAIN_PROJECT=default
LANGSMITH_API_KEY=sua-chave-aqui

Com essas variáveis configuradas, toda a telemetria da sua aplicação é enviada automaticamente para o LangSmith. Se você já utiliza o LangChain, não precisa instalar nenhuma biblioteca adicional. O suporte ao LangSmith já vem embutido no pacote.

Exemplo 1: Monitorando uma chain do LangChain

No primeiro exemplo, temos uma chain simples que simula o comportamento de um RAG. Um system prompt orienta o assistente a responder com base apenas no contexto fornecido, e a pergunta do usuário recebe esse contexto como parâmetro.

from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser

prompt = ChatPromptTemplate.from_messages([
    ("system", "Você é um assistente útil. Responda a solicitação do usuário com base apenas no contexto fornecido."),
    ("user", "{question}\n\nContexto: {context}")
])

model = ChatOpenAI(model="gpt-4o-mini")
chain = prompt | model | StrOutputParser()

chain.invoke({"question": "Resuma o texto", "context": texto})

Ao executar essa chain, o LangSmith captura automaticamente todo o fluxo. No painel da plataforma, podemos ver:

• RunnableSequence: um resumo completo da execução, com todo o input enviado ao LLM
• ChatOpenAI: detalhes do modelo utilizado, parâmetros como temperatura (0.7 por padrão, quando não configurada explicitamente), provider e nome do modelo
• Metadata: versão do LangChain, sistema operacional de origem, versão do Python e outros dados de contexto

Na lateral, o LangSmith exibe informações operacionais importantes: timestamp, latência da chamada, quantidade de tokens consumidos e um cálculo estimado de custo.

Rastreamento por etapas

Um dos recursos mais úteis é a visualização passo a passo de cada etapa da execução. Você consegue acompanhar desde a montagem do prompt com o ChatPromptTemplate, passando pelo envio para a OpenAI, até o retorno formatado pelo StrOutputParser. Cada etapa aparece separada, o que facilita a identificação de gargalos ou comportamentos inesperados.

Captura de erros

Para demonstrar a captura de erros, basta trocar o modelo para um que não existe, como "gpt-5". O LangSmith registra o erro e permite investigar exatamente em qual etapa a execução falhou. Nesse caso, o ChatPromptTemplate foi montado corretamente, mas a chamada para a OpenAI retornou um erro informando que o modelo não foi encontrado. A mensagem aparece de forma clara e direta no painel.

Exemplo 2: Monitorando aplicações sem LangChain

E se a sua aplicação LLM não utiliza o LangChain? O LangSmith também funciona nesse cenário, com algumas configurações adicionais.

No segundo exemplo, temos uma aplicação que usa diretamente o client da OpenAI, com uma função Retriever que simula a recuperação de contexto de um banco vetorial. Para habilitar o rastreamento, são necessários dois passos.

Passo 1: Wrapper do client OpenAI

O LangSmith oferece um wrapper para o client da OpenAI que habilita a coleta de métricas:

from langsmith.wrappers import wrap_openai
from openai import OpenAI

client = wrap_openai(OpenAI())

Com essa configuração, o LangSmith passa a rastrear as chamadas ao ChatOpenAI. Porém, como não há as abstrações do LangChain, o rastreamento mostra apenas a chamada ao LLM como um bloco único.

Passo 2: Rastreamento granular com @traceable

Para obter mais detalhes sobre o pipeline completo, o LangSmith fornece o decorator @traceable:

from langsmith import traceable

@traceable
def retriever(query):
    # Simula recuperação de contexto
    return "LangSmith serve para observabilidade"

@traceable
def rag(query):
    context = retriever(query)
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[
            {"role": "system", "content": f"Responda com base no contexto: {context}"},
            {"role": "user", "content": query}
        ]
    )
    return response.choices[0].message.content

Com o @traceable aplicado nas funções, o LangSmith passa a rastrear cada etapa individualmente. No painel, a execução aparece hierarquicamente: a função RAG contém a chamada ao Retriever e, dentro dela, a chamada ao ChatOpenAI. A progressão fica visível: primeiro apenas o ChatOpenAI, depois a função RAG com o ChatOpenAI dentro, e por fim a cadeia completa com Retriever e ChatOpenAI.

Monitoramento e métricas

Em projetos com maior volume de execuções, a seção Monitor do LangSmith oferece gráficos com métricas operacionais:

• Contagem de erros
• Quantidade de chamadas ao LLM
• Taxa de sucesso nas chamadas
• Métricas de latência (p50, p95)
• Tokens por segundo

Essas métricas ajudam a acompanhar a saúde da aplicação em produção e identificar degradações de performance ao longo do tempo.

Avaliação de qualidade com datasets

Além do monitoramento em tempo real, o LangSmith oferece recursos para avaliar a qualidade das respostas geradas pela sua aplicação. O fluxo funciona assim:

1. Você cria um dataset com pares de perguntas e respostas esperadas
2. Carrega o dataset na plataforma
3. Executa a avaliação contra diferentes versões da aplicação ou diferentes modelos

No exemplo apresentado, uma comparação entre GPT-4o Mini e GPT-3.5 Turbo mostra diferenças de verbosidade, consumo de tokens, latência e custo. É possível definir um baseline e comparar o desempenho de cada modelo contra ele. Na prática, isso permite implementar testes A/B entre versões da aplicação ou entre modelos diferentes, com dados concretos para embasar a decisão.

Conclusão

LangSmith resolve um problema prático de quem desenvolve aplicações LLM: saber o que está acontecendo dentro do pipeline. A configuração é simples, funciona com ou sem LangChain, e oferece desde rastreamento básico de chamadas até avaliação comparativa de modelos. Para quem está colocando aplicações LLM em produção, ter esse nível de visibilidade sobre o comportamento do sistema pode ser a diferença entre resolver um problema em minutos ou passar horas investigando logs.

Especialização em Engenharia de IA

Conheça a Especialização em Engenharia de IA Dev + Eficiente. O curso aborda RAG, Vector Search, Busca Híbrida, Agentes, Tools e muito mais, sempre com aulas 100% práticas e com exemplos reais.

Acesse https://deveficiente.com/especializacao-engenharia-ia .