Skip to content

artubss/SKILLS-CLAUDE-CODE / skills/skills/ai-research/observability-langsmith

langsmith-observability

Verified

Plataforma de observabilidade para LLM com rastreamento, avaliação e monitoramento. Use ao depurar aplicações LLM, avaliar saídas de modelos em datasets, monitorar sistemas em produção ou construir pipelines de testes sistemáticos para aplicações de IA.

LangSmith - Plataforma de Observabilidade para LLM

Plataforma de desenvolvimento para depuração, avaliação e monitoramento de modelos de linguagem e aplicações de IA.

Quando usar LangSmith

Use LangSmith quando:

  • Depurar problemas em aplicações LLM (prompts, chains, agents)
  • Avaliar saídas de modelos sistematicamente contra datasets
  • Monitorar sistemas LLM em produção
  • Construir testes de regressão para features de IA
  • Analisar latência, uso de tokens e custos
  • Colaborar em engenharia de prompts

Recursos principais:

  • Tracing: Capturar entradas, saídas, latência para todas as chamadas LLM
  • Evaluation: Testes sistemáticos com avaliadores built-in e customizados
  • Datasets: Criar conjuntos de testes a partir de traces em produção ou manualmente
  • Monitoring: Rastrear métricas, erros e custos em produção
  • Integrações: Funciona com OpenAI, Anthropic, LangChain, LlamaIndex

Use alternativas:

  • Weights & Biases: Rastreamento de experimentos em deep learning, treinamento de modelos
  • MLflow: Ciclo de vida geral de ML, foco em registro de modelos
  • Arize/WhyLabs: Monitoramento de ML, detecção de data drift

Início rápido

Instalação

pip install langsmith

# Defina variáveis de ambiente
export LANGSMITH_API_KEY="your-api-key"
export LANGSMITH_TRACING=true

Rastreamento básico com @traceable

from langsmith import traceable
from openai import OpenAI

client = OpenAI()

@traceable
def generate_response(prompt: str) -> str:
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": prompt}]
    )
    return response.choices[0].message.content

# Automaticamente rastreado no LangSmith
result = generate_response("What is machine learning?")

Wrapper OpenAI (rastreamento automático)

from langsmith.wrappers import wrap_openai
from openai import OpenAI

# Envolver cliente para rastreamento automático
client = wrap_openai(OpenAI())

# Todas as chamadas automaticamente rastreadas
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}]
)

Conceitos principais

Runs e traces

Um run é uma unidade de execução única (chamada LLM, chain, tool). Runs formam traces hierárquicas mostrando o fluxo completo de execução.

from langsmith import traceable

@traceable(run_type="chain")
def process_query(query: str) -> str:
    # Run pai
    context = retrieve_context(query)  # Run filha
    response = generate_answer(query, context)  # Run filha
    return response

@traceable(run_type="retriever")
def retrieve_context(query: str) -> list:
    return vector_store.search(query)

@traceable(run_type="llm")
def generate_answer(query: str, context: list) -> str:
    return llm.invoke(f"Context: {context}\n\nQuestion: {query}")

Projetos

Projetos organizam runs relacionadas. Configure via ambiente ou código:

import os
os.environ["LANGSMITH_PROJECT"] = "my-project"

# Ou por função
@traceable(project_name="my-project")
def my_function():
    pass

Client API

from langsmith import Client

client = Client()

# Listar runs
runs = list(client.list_runs(
    project_name="my-project",
    filter='eq(status, "success")',
    limit=100
))

# Obter detalhes da run
run = client.read_run(run_id="...")

# Criar feedback
client.create_feedback(
    run_id="...",
    key="correctness",
    score=0.9,
    comment="Good answer"
)

Datasets e avaliação

Criar dataset

from langsmith import Client

client = Client()

# Criar dataset
dataset = client.create_dataset("qa-test-set", description="QA evaluation")

# Adicionar exemplos
client.create_examples(
    inputs=[
        {"question": "What is Python?"},
        {"question": "What is ML?"}
    ],
    outputs=[
        {"answer": "A programming language"},
        {"answer": "Machine learning"}
    ],
    dataset_id=dataset.id
)

Executar avaliação

from langsmith import evaluate

def my_model(inputs: dict) -> dict:
    # Sua lógica de modelo
    return {"answer": generate_answer(inputs["question"])}

def correctness_evaluator(run, example):
    prediction = run.outputs["answer"]
    reference = example.outputs["answer"]
    score = 1.0 if reference.lower() in prediction.lower() else 0.0
    return {"key": "correctness", "score": score}

results = evaluate(
    my_model,
    data="qa-test-set",
    evaluators=[correctness_evaluator],
    experiment_prefix="v1"
)

print(f"Average score: {results.aggregate_metrics['correctness']}")

Avaliadores built-in

from langsmith.evaluation import LangChainStringEvaluator

# Usar avaliadores LangChain
results = evaluate(
    my_model,
    data="qa-test-set",
    evaluators=[
        LangChainStringEvaluator("qa"),
        LangChainStringEvaluator("cot_qa")
    ]
)

Rastreamento avançado

Contexto de rastreamento

from langsmith import tracing_context

with tracing_context(
    project_name="experiment-1",
    tags=["production", "v2"],
    metadata={"version": "2.0"}
):
    # Todas as chamadas traceable herdam o contexto
    result = my_function()

Runs manuais

from langsmith import trace

with trace(
    name="custom_operation",
    run_type="tool",
    inputs={"query": "test"}
) as run:
    result = do_something()
    run.end(outputs={"result": result})

Processar entradas/saídas

def sanitize_inputs(inputs: dict) -> dict:
    if "password" in inputs:
        inputs["password"] = "***"
    return inputs

@traceable(process_inputs=sanitize_inputs)
def login(username: str, password: str):
    return authenticate(username, password)

Sampling

import os
os.environ["LANGSMITH_TRACING_SAMPLING_RATE"] = "0.1"  # 10% sampling

Integração com LangChain

from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate

# Rastreamento habilitado automaticamente com LANGSMITH_TRACING=true
llm = ChatOpenAI(model="gpt-4o")
prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a helpful assistant."),
    ("user", "{input}")
])

chain = prompt | llm

# Todas as runs da chain rastreadas automaticamente
response = chain.invoke({"input": "Hello!"})

Monitoramento em produção

Hub prompts

from langsmith import Client

client = Client()

# Buscar prompt do hub
prompt = client.pull_prompt("my-org/qa-prompt")

# Usar na aplicação
result = prompt.invoke({"question": "What is AI?"})

Client assíncrono

from langsmith import AsyncClient

async def main():
    client = AsyncClient()

    runs = []
    async for run in client.list_runs(project_name="my-project"):
        runs.append(run)

    return runs

Coleta de feedback

from langsmith import Client

client = Client()

# Coletar feedback do usuário
def record_feedback(run_id: str, user_rating: int, comment: str = None):
    client.create_feedback(
        run_id=run_id,
        key="user_rating",
        score=user_rating / 5.0,  # Normalizar para 0-1
        comment=comment
    )

# Na sua aplicação
record_feedback(run_id="...", user_rating=4, comment="Helpful response")

Integração de testes

Integração com Pytest

from langsmith import test

@test
def test_qa_accuracy():
    result = my_qa_function("What is Python?")
    assert "programming" in result.lower()

Avaliação em CI/CD

from langsmith import evaluate

def run_evaluation():
    results = evaluate(
        my_model,
        data="regression-test-set",
        evaluators=[accuracy_evaluator]
    )

    # Falhar CI se a acurácia cair
    assert results.aggregate_metrics["accuracy"] >= 0.9, \
        f"Accuracy {results.aggregate_metrics['accuracy']} below threshold"

Melhores práticas

  1. Nomenclatura estruturada - Use convenções consistentes para nomes de projetos/runs
  2. Adicionar metadados - Inclua versão, ambiente, informações do usuário
  3. Sampling em produção - Use taxa de sampling para controlar volume
  4. Criar datasets - Construa conjuntos de testes a partir de casos interessantes em produção
  5. Automatizar avaliação - Execute avaliações em pipelines CI/CD
  6. Monitorar custos - Rastreie tendências de uso de tokens e latência

Problemas comuns

Traces não aparecem:

import os
# Garanta que o rastreamento está habilitado
os.environ["LANGSMITH_TRACING"] = "true"
os.environ["LANGSMITH_API_KEY"] = "your-key"

# Verifique a conexão
from langsmith import Client
client = Client()
print(client.list_projects())  # Deve funcionar

Alta latência do rastreamento:

# Habilitar batching em background (padrão)
from langsmith import Client
client = Client(auto_batch_tracing=True)

# Ou use sampling
os.environ["LANGSMITH_TRACING_SAMPLING_RATE"] = "0.1"

Payloads grandes:

# Ocultar campos sensíveis/grandes
@traceable(
    process_inputs=lambda x: {k: v for k, v in x.items() if k != "large_field"}
)
def my_function(data):
    pass

Referências

Recursos

writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 319kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall