langsmith-dataset

LangSmith 数据集

从 LangSmith 跟踪记录自动生成评估数据集，用于测试和验证。

设置

环境变量

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

使用方法

进入 skills/langsmith-dataset/scripts/ 运行命令。

脚本

generate_datasets.py - 从跟踪记录创建评估数据集 query_datasets.py - 查看和检查数据集

常用标志

所有数据集生成命令均支持：

• --root-run-name <name> - 按根运行名称筛选跟踪记录（例如，DeepAgents 使用 "LangGraph"）
• --limit <n> - 要处理的跟踪记录数量（默认值：30）
• --last-n-minutes <n> - 仅处理最近的跟踪记录
• --output <path> - 输出文件（.json 或 .csv）
• --upload <name> - 使用此数据集名称上传到 LangSmith
• --replace - 覆盖现有文件/数据集（会提示确认）
• --yes - 跳过确认提示（谨慎使用）

重要 - 安全提示：

• 使用 --replace 删除现有数据集前，脚本会提示确认
• 务必遵从这些提示 - 等待用户输入后再继续
• 除非用户明确要求，否则绝不要使用 --yes 标志
• --yes 标志会跳过所有安全提示，仅应在用户明确授权的自动化工作流中使用

理解跟踪层级

跟踪记录根据父子关系划分深度级别：

Depth 0: Root agent (e.g., "LangGraph")
  ├── Depth 1: Middleware/chains (model, tools, SummarizationMiddleware)
  │     ├── Depth 2: Tool calls (sql_db_query, retriever, etc.)
  │     └── Depth 2: LLM calls (ChatOpenAI, ChatAnthropic)
  └── Depth 3+: Nested subagent calls

使用 --root-run-name 指定目标 Agent 框架：

• DeepAgents：--root-run-name LangGraph
• 自定义 Agent：使用根节点名称

数据集类型

1. 最终响应

包含预期输出的完整对话 - 用于测试 Agent 的完整行为。

# Basic usage
python generate_datasets.py --type final_response \
  --project my-project \
  --root-run-name LangGraph \
  --limit 30 \
  --output /tmp/final_response.json

# With custom output fields
python generate_datasets.py --type final_response \
  --project my-project \
  --output-fields "answer,result" \
  --output /tmp/final.json

# Messages only (ignore output dict keys)
python generate_datasets.py --type final_response \
  --project my-project \
  --messages-only \
  --output /tmp/final.json

结构：

{
  "trace_id": "...",
  "inputs": {"query": "What are the top 3 genres?"},
  "outputs": {
    "expected_response": "The top 3 genres based on the number of tracks are:\n\n1. Rock with 1,297 tracks\n2. Latin with 579 tracks\n3. Metal with 374 tracks"
  }
}

提取优先级：

1. 根运行中的消息（包含内容的 AI 响应）
2. 用户指定的输出字段（--output-fields）
3. 常见键（answer、output）
4. 完整输出字典

**重要：**始终优先检查根运行中的最终响应，以避免提取中间工具输出。

2. 单步

单个节点的输入/输出 - 用于测试任意特定节点的行为。支持每条跟踪记录包含多个出现实例，以捕捉对话演进过程。

# Extract all occurrences (default)
python generate_datasets.py --type single_step \
  --project my-project \
  --root-run-name LangGraph \
  --run-name model \
  --output /tmp/single_step.json

# Sample 2 occurrences per trace
python generate_datasets.py --type single_step \
  --project my-project \
  --root-run-name LangGraph \
  --run-name model \
  --sample-per-trace 2 \
  --output /tmp/single_step_sampled.json

# Target specific tool at depth 2
python generate_datasets.py --type single_step \
  --project my-project \
  --root-run-name LangGraph \
  --run-name sql_db_query \
  --output /tmp/sql_query.json

结构：

{
  "trace_id": "...",
  "run_id": "...",
  "occurrence": 2,
  "inputs": {
    "messages": [
      {"type": "human", "content": "What are the top 3 genres?"},
      {"type": "ai", "content": "", "tool_calls": [...]},
      {"type": "tool", "content": "...results..."},
      ...
    ]
  },
  "outputs": {
    "expected_output": {
      "messages": [
        {"type": "ai", "content": "", "tool_calls": [...]}
      ]
    },
    "node_name": "model"
  }
}

主要特性：

• occurrence 字段记录调用次数（第 1 次、第 2 次、第 3 次等）
• 后续出现实例包含更多对话历史 → 测试上下文处理能力
• --sample-per-trace 为每条跟踪记录随机抽取 N 个出现实例
• 使用 --run-name 指定任意深度的节点

常见目标：

• model（深度 1）- 包含不断增长上下文的 LLM 调用
• tools（深度 1）- 工具执行链
• 任意自定义节点名称

3. 轨迹

工具调用序列 - 用于测试可配置深度的执行路径。

# Include all tool calls (all depths)
python generate_datasets.py --type trajectory \
  --project my-project \
  --root-run-name LangGraph \
  --limit 30 \
  --output /tmp/trajectory_all.json

# Only tool calls up to depth 2
python generate_datasets.py --type trajectory \
  --project my-project \
  --root-run-name LangGraph \
  --depth 2 \
  --output /tmp/trajectory_depth2.json

# Only root-level tool calls (depth 0) - usually empty if tools are at depth 2+
python generate_datasets.py --type trajectory \
  --project my-project \
  --depth 0 \
  --output /tmp/trajectory_root.json

结构：

{
  "trace_id": "...",
  "inputs": {"query": "What are the top 3 genres?"},
  "outputs": {
    "expected_trajectory": [
      "sql_db_list_tables",
      "sql_db_schema",
      "sql_db_query_checker",
      "sql_db_query"
    ]
  }
}

深度控制：

• 省略 --depth = 所有级别（包括子 Agent 工具调用）
• --depth 2 = 根级别 + 2 个级别（通常用于捕获所有主要工具）
• --depth 1 = 通常只有中间件/链，不包含实际工具调用
• --depth 0 = 仅根级别（不包含工具调用）

**注意：**在 LangGraph/DeepAgents 架构中，工具调用通常位于深度 2。

4. RAG

问题/分块/答案/引用 - 用于测试检索质量。

python generate_datasets.py --type rag \
  --project my-project \
  --limit 30 \
  --output /tmp/rag_ds.csv  # Supports .json or .csv

结构（CSV 格式）：

question,retrieved_chunks,answer,cited_chunks
"How do I...","Chunk 1\n\nChunk 2","The answer is...","[\"Chunk 1\"]"

输出格式

所有数据集类型均支持 JSON 和 CSV：

# JSON output (default)
python generate_datasets.py --type trajectory --project my-project --output ds.json

# CSV output (use .csv extension)
python generate_datasets.py --type trajectory --project my-project --output ds.csv

上传到 LangSmith

# Generate and upload in one command
python generate_datasets.py --type trajectory \
  --project my-project \
  --root-run-name LangGraph \
  --limit 50 \
  --output /tmp/trajectory_ds.json \
  --upload "Skills: Trajectory"

# Use --replace to overwrite existing dataset
python generate_datasets.py --type final_response \
  --project my-project \
  --output /tmp/final.json \
  --upload "Skills: Final Response" \
  --replace

**命名规范：**统一使用 "Skills: " 格式：

• "Skills: Final Response"
• "Skills: Single Step (model)"
• "Skills: Single Step (sql_db_query)"
• "Skills: Trajectory (all depths)"
• "Skills: Trajectory (depth=2)"

查询数据集

# List all datasets
python query_datasets.py list-datasets

# Filter by name pattern
python query_datasets.py list-datasets | grep "Skills:"

# View dataset examples
python query_datasets.py show "Skills: Trajectory" --limit 5

# View local file
python query_datasets.py view-file /tmp/trajectory_ds.json --limit 3

# Analyze structure
python query_datasets.py structure /tmp/trajectory_ds.json

# Export from LangSmith to local
python query_datasets.py export "Skills: Final Response" /tmp/exported.json --limit 100

数据集生成提示

1. 始终使用 --root-run-name - 筛选特定 Agent 框架（例如，“LangGraph”）
2. 从成功的轨迹开始 - 使用近期成功的运行作为基线数据集
3. 使用时间范围 - --last-n-minutes 1440 表示最近 24 小时的数据
4. 为 single_step 采样 - 使用 --sample-per-trace 2 捕获对话演变过程
5. 根据需要匹配深度 - --depth 2 通常可以捕获所有主要工具调用
6. 上传前先检查 - 使用 query_datasets.py view-file 进行检查
7. 迭代优化 - 先生成小批量（10-20 条）并进行验证，再扩大规模
8. 谨慎使用 --replace - 此选项会覆盖现有数据集，适用于迭代

示例工作流

# 1. Generate fresh traces (if needed)
python tests/test_agent.py --batch  # Your test agent

# 2. Generate all dataset types from LangGraph traces
python generate_datasets.py --type final_response \
  --project skills --root-run-name LangGraph --limit 10 \
  --output /tmp/final.json --upload "Skills: Final Response" --replace

python generate_datasets.py --type single_step \
  --project skills --root-run-name LangGraph --run-name model \
  --sample-per-trace 2 --limit 10 \
  --output /tmp/model.json --upload "Skills: Single Step (model)" --replace

python generate_datasets.py --type trajectory \
  --project skills --root-run-name LangGraph --limit 10 \
  --output /tmp/traj.json --upload "Skills: Trajectory (all depths)" --replace

python generate_datasets.py --type trajectory \
  --project skills --root-run-name LangGraph --depth 2 --limit 10 \
  --output /tmp/traj_d2.json --upload "Skills: Trajectory (depth=2)" --replace

# 3. Review in LangSmith UI
# Visit https://smith.langchain.com → Datasets → Filter for "Skills:"

# 4. Query locally if needed
python query_datasets.py show "Skills: Final Response" --limit 3

故障排除

final_response 输出为空：

• 确保 --root-run-name 与 Agent 的根节点匹配
• 检查根运行是否包含 AI 响应消息
• 如果输出字典为空，请使用 --messages-only

没有轨迹示例：

• 工具可能位于不同深度 - 尝试移除 --depth，或使用 --depth 2
• 确认存在工具调用：python query_traces.py trace <id> --show-hierarchy

single_step 示例过多：

• 使用 --sample-per-trace 2 限制每条轨迹的示例数量
• 在保持多样性的同时减小数据集规模

数据集上传失败：

• 检查数据集是否已存在，或使用 --replace
• 确认已设置 LANGSMITH_API_KEY

相关技能

• 使用 langsmith-trace 技能查询和导出轨迹
• 使用 langsmith-evaluator 技能创建评估器并衡量性能