langsmith datasets

用途

LangSmith Datasets 用于从导出的追踪（trace）数据创建评测数据集、将数据集上传到 LangSmith，以及查询数据集。它属于 langchain-ai/langchain-skills 技能，提供 Python 与 TypeScript/JavaScript 两套脚本。

主要能力

工具支持四种数据集类型（通过 --type 指定）：

• final_response：完整对话与预期输出，测试完整的智能体行为。
• single_step：单节点输入/输出，测试特定节点行为，可用 --run-name 指定目标节点。
• trajectory：工具调用序列，测试执行路径，可用 --depth 控制深度。
• rag：问题/分块/答案/引用，测试检索质量，仅匹配 run_type="retriever"。

脚本分为生成与查询两类：

• generate_datasets.py / generate_datasets.ts：从导出的追踪文件创建评测数据集。
• query_datasets.py / query_datasets.ts：查看与检查数据集。

查询脚本支持的命令示例：

python query_datasets.py list-datasets
python query_datasets.py show "Skills: Trajectory" --limit 5
python query_datasets.py view-file /tmp/trajectory_ds.json --limit 3

使用方式

环境与依赖

环境变量：

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

Python 依赖：

pip install langsmith click rich python-dotenv

TypeScript/JavaScript 依赖：

npm install langsmith commander chalk cli-table3 dotenv

输入格式

脚本要求追踪以 JSONL 格式导出（每行一个 run）。每行必须是包含以下字段的 JSON 对象：

{"run_id": "...", "trace_id": "...", "name": "...", "run_type": "...", "parent_run_id": "...", "inputs": {...}, "outputs": {...}}

字段说明：

• run_id：该 run 的唯一标识符。
• trace_id：将多个 run 归组为同一 trace（用于重建层级结构）。
• name：run 名称（例如 "model"、"classify_email"）。
• run_type：取值为 chain、llm、tool、retriever 之一。
• parent_run_id：父 run ID（根 run 为 null）。
• inputs：run 的输入（生成数据集时必需）。
• outputs：run 的输出（生成数据集时必需）。

重要：必须同时具备 inputs 和 outputs 才能正确生成数据集。生成数据集前，请先确认追踪确实存在：检查输出目录中是否有 JSONL 文件；确认追踪同时包含 inputs 和 outputs；检查追踪层级以了解其结构。

常用参数

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

• --input <path>：输入追踪，.jsonl 文件所在目录或单个 .jsonl 文件（必需）。
• --type <type>：数据集类型，final_response、single_step、trajectory、rag（必需）。
• --output <path>：输出文件（.json 或 .csv）（必需）。
• --input-fields：要提取的输入键，逗号分隔（例如 "query,question"）。
• --output-fields：要提取的输出键，逗号分隔（例如 "answer,response"）。
• --messages-only：仅从 messages 数组中提取，跳过其他字段。
• --upload <name>：以该数据集名称上传到 LangSmith。
• --replace：覆盖已有文件/数据集（会提示确认）。
• --yes：跳过确认提示（谨慎使用）。

安全提示：脚本在使用 --replace 删除已有数据集前会提示确认。若有用户输入，始终等待用户输入；除非用户明确要求，切勿使用 --yes。若非交互式运行，需同时使用 --replace --yes 以确保正确替换。

Python 脚本用法示例

提取指定字段：

python generate_datasets.py --input ./traces --type final_response 
--input-fields "email_content" 
--output-fields "response" 
--output /tmp/final.json

生成 trajectory 数据集：

python generate_datasets.py --input ./traces --type trajectory --output /tmp/trajectory.json

生成并上传：

python generate_datasets.py --input ./traces --type trajectory 
--output /tmp/trajectory.json 
--upload "Skills: Trajectory"

TypeScript/JavaScript 脚本用法示例

基本用法（原始输入、提取输出）：

npx tsx generate_datasets.ts --input ./traces --type final_response --output /tmp/final_response.json

提取指定字段：

npx tsx generate_datasets.ts --input ./traces --type final_response \
  --input-fields "email_content" \
  --output-fields "response" \
  --output /tmp/final.json

生成 trajectory 数据集：

npx tsx generate_datasets.ts --input ./traces --type trajectory --output /tmp/trajectory.json

生成并上传：

npx tsx generate_datasets.ts --input ./traces --type trajectory \
  --output /tmp/trajectory.json \
  --upload "Skills: Trajectory"

适用场景（示例工作流）

从导出的追踪到 LangSmith 数据集的完整流程：

python generate_datasets.py --input ./traces --type single_step 
--run-name model 
--sample-per-trace 2 
--output /tmp/model.json 
--upload "Skills: Single Step (model)" --replace

python generate_datasets.py --input ./traces --type trajectory 
--output /tmp/traj.json 
--upload "Skills: Trajectory (all depths)" --replace

本地查询：

python query_datasets.py show "Skills: Final Response" --limit 3

TypeScript 版本可从导出追踪生成所有数据集类型并上传：

npx tsx generate_datasets.ts --input ./traces --type final_response \
  --output /tmp/final.json \
  --upload "Skills: Final Response" --replace

npx tsx generate_datasets.ts --input ./traces --type single_step \
  --run-name model \
  --sample-per-trace 2 \
  --output /tmp/model.json \
  --upload "Skills: Single Step (model)" --replace

npx tsx generate_datasets.ts --input ./traces --type trajectory \
  --output /tmp/traj.json \
  --upload "Skills: Trajectory (all depths)" --replace

限制与常见问题

• final_response 输出为空：检查根 run 是否有 outputs；使用 --output-fields 定位特定字段；若输出为 messages 格式，使用 --messages-only。
• 没有 trajectory 示例：工具可能位于不同深度，可尝试去掉 --depth 或使用 --depth 2；确认导出的 JSONL 文件中存在工具调用。
• single_step 示例过多：使用 --sample-per-trace 2 限制每条 trace 的示例数，在保持多样性的同时减小数据集规模。
• 没有 RAG 数据：RAG 仅匹配 run_type="retriever"；对于自定义 retriever 名称，改用 single_step --run-name <retriever>。
• 数据集上传失败：检查数据集是否已存在或使用 --replace；确认已设置 LANGSMITH_API_KEY。

关于收费、价格、平台限制等更多信息暂未提供。