artubss/SKILLS-CLAUDE-CODE / skills/skills/ai-research/observability-langsmith
langsmith-observability
VerifiedPlataforma 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
- Nomenclatura estruturada - Use convenções consistentes para nomes de projetos/runs
- Adicionar metadados - Inclua versão, ambiente, informações do usuário
- Sampling em produção - Use taxa de sampling para controlar volume
- Criar datasets - Construa conjuntos de testes a partir de casos interessantes em produção
- Automatizar avaliação - Execute avaliações em pipelines CI/CD
- 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
- Uso avançado - Avaliadores customizados, rastreamento distribuído, hub prompts
- Solução de problemas - Problemas comuns, depuração, performance
Recursos
- Documentação: https://docs.smith.langchain.com
- Python SDK: https://github.com/langchain-ai/langsmith-sdk
- Web App: https://smith.langchain.com
- Versão: 0.2.0+
- Licença: MIT
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| 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: 196k | Updated | Claude CodeCodex | Verified | Install |
| 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: 118k | Updated | Claude CodeCodex | Verified | Install |
| 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: 118k | Updated | Claude CodeCodex | Verified | Install |