langsmith-trace

LangSmith Trace

主要包含两个主题：在应用中添加追踪，以及查询追踪记录以进行调试和分析。

设置

环境变量

LANGSMITH_API_KEY=lsv2_pt_your_api_key_here          # Required
LANGSMITH_PROJECT=your-project-name                   # Optional: default project
LANGSMITH_WORKSPACE_ID=your-workspace-id              # Optional: for org-scoped keys

依赖项

pip install langsmith click rich python-dotenv

在应用中添加追踪

LangChain/LangGraph 应用

只需设置环境变量，即可自动追踪：

export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY=<your-api-key>
export OPENAI_API_KEY=<your-openai-api-key>  # or your LLM provider's key

可选变量：

• LANGSMITH_PROJECT - 指定项目名称（默认为 "default"）
• LANGCHAIN_CALLBACKS_BACKGROUND=false - 用于无服务器环境，确保追踪记录在函数退出前完成

非 LangChain/LangGraph 应用

先检查代码库： 如果使用 OpenTelemetry，优先采用 OTel 集成（https://docs.langchain.com/langsmith/trace-with-opentelemetry）。对于 Vercel AI SDK、LlamaIndex、Instructor、DSPy 或 LiteLLM，请参阅 https://docs.langchain.com/langsmith/integrations 中的原生集成。

如果未使用集成，请使用 @traceable 装饰器并封装 LLM 客户端：

Python：

from langsmith import traceable
from langsmith.wrappers import wrap_openai
from openai import OpenAI

client = wrap_openai(OpenAI())

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

追踪记录会自动显示在你的 LangSmith 工作区中。

最佳实践

• 对所有希望在 LangSmith 中显示的嵌套函数应用 @traceable。 只有经过装饰的函数才会在追踪层级中显示为独立的跨度。
• 封装后的客户端会自动追踪所有调用——wrap_openai() 会自动记录每次 LLM 调用，无需额外装饰器。
• 为追踪记录命名，以便更轻松地筛选：@traceable(name="retrieve_docs") 或 traceable(myFunc, { name: "retrieve_docs" })
• 添加元数据，方便搜索：@traceable(metadata={"user_id": "123", "feature": "chat"})

# Example: nested tracing
@traceable
def rag_pipeline(question: str) -> str:
    docs = retrieve_docs(question)  # traced if @traceable applied
    return generate_answer(question, docs)  # traced if @traceable applied

@traceable(name="retrieve_docs")
def retrieve_docs(query: str) -> list[str]:
    # retrieval logic
    return docs

@traceable(name="generate_answer")
def generate_answer(question: str, docs: list[str]) -> str:
    # LLM calls via wrapped client are auto-traced
    return client.chat.completions.create(...)

---

查询追踪记录

使用下方脚本查询、分析和导出 LangSmith 中的追踪记录。

前往 skills/langsmith-trace/scripts/ 运行命令。

快速参考

# Show recent traces
python query_traces.py recent --limit 10 --project my-project

# Show with metadata (timing, tokens, costs)
python query_traces.py recent --limit 10 --include-metadata

# Filter by time
python query_traces.py recent --last-n-minutes 60
python query_traces.py recent --since 2025-01-20T10:00:00Z

# Get specific trace details
python query_traces.py trace <trace-id> --show-hierarchy

# Export traces to directory (recommended for bulk collection)
python query_traces.py export ./traces --limit 50 --include-metadata
python query_traces.py export ./traces --limit 20 --include-io    # With inputs/outputs
python query_traces.py export ./traces --limit 20 --full          # Everything

# Filter by run type
python query_traces.py export ./traces --run-type tool            # Only tool calls
python query_traces.py export ./traces --run-type llm             # Only LLM calls

# Search by name pattern
python query_traces.py search "agent" --project my-project

# Output as JSON
python query_traces.py recent --format json --limit 5

命令

recent - 列出最近的追踪记录（--limit、--project、--last-n-minutes、--include-metadata、--format）

trace <id> - 获取指定追踪记录（--show-hierarchy、--include-metadata、--output）

export <dir> - 批量导出到目录（--limit、--include-metadata、--include-io、--full、--run-type、--max-concurrent）

search <pattern> - 按名称查找运行记录（--limit、--last-n-minutes）

提示

• 使用 export 批量导出数据，务必指定 --project，临时文件请使用 /tmp
• 添加 --include-metadata 以分析性能/成本
• 对于大型导出，可将 --max-concurrent 增至 10
• 使用 --format json 配合 jq 进行分析

相关技能

• 使用 langsmith-dataset 技能根据追踪记录生成评估数据集
• 使用 langsmith-evaluator 技能创建评估器并衡量性能