langsmith-dataset

创建、管理评估数据集，并将其上传到 LangSmith，以进行测试和验证。 环境变量

LANGSMITH_API_KEY=lsv2_pt_your_api_key_here          # REQUIRED
LANGSMITH_PROJECT=your-project-name                   # Check this to know which project has traces
LANGSMITH_WORKSPACE_ID=your-workspace-id              # Optional: for org-scoped keys

必须进行身份验证：设置 LANGSMITH_API_KEY 环境变量，或在 CLI 命令中传入 --api-key 标志（推荐）：

langsmith dataset list --api-key $LANGSMITH_API_KEY

重要： 在查询或与 LangSmith 交互之前，务必检查环境变量或 .env 文件中的 LANGSMITH_PROJECT。该变量用于确定相关跟踪和数据所在的项目。如果无法找到 LangSmith 项目，请自行判断合适的项目。

Python 依赖项

pip install langsmith

JavaScript 依赖项

npm install langsmith

CLI 工具

curl -sSL https://raw.githubusercontent.com/langchain-ai/langsmith-cli/main/scripts/install.sh | sh

使用 `langsmith` CLI 管理数据集和示例。

数据集命令

• langsmith dataset list - 列出 LangSmith 中的数据集
• langsmith dataset get <name-or-id> - 查看数据集详情
• langsmith dataset create --name <name> - 创建新的空数据集
• langsmith dataset delete <name-or-id> - 删除数据集
• langsmith dataset export <name-or-id> <output-file> - 将数据集导出到本地 JSON 文件
• langsmith dataset upload <file> --name <name> - 将本地 JSON 文件作为数据集上传

示例命令

• langsmith example list --dataset <name> - 列出数据集中的示例
• langsmith example create --dataset <name> --inputs <json> - 向数据集添加示例
• langsmith example delete <example-id> - 删除示例

实验命令

• langsmith experiment list --dataset <name> - 列出数据集的实验
• langsmith experiment get <name> - 查看实验结果

常用标志

• --limit N - 限制结果数量
• --yes - 跳过确认提示（谨慎使用）

重要 - 安全提示：

• CLI 会在执行破坏性操作（删除、覆盖）前请求确认
• 如果正在等待用户输入： 务必等待用户输入；除非用户明确要求，否则绝不使用 --yes
• 如果以非交互方式运行： 使用 --yes 跳过确认提示

<dataset_types_overview> 常见的评估数据集类型：

• final_response - 包含预期输出的完整对话。用于测试 Agent 的完整行为。
• single_step - 单个节点的输入/输出。用于测试特定节点的行为（例如，一次 LLM 调用或工具调用）。
• trajectory - 工具调用序列。用于测试执行路径（按顺序排列的工具名称列表）。
• rag - 问题、文本块、答案和引用。用于测试检索质量。 </dataset_types_overview>

<creating_datasets>

创建数据集

数据集是包含示例数组的 JSON 文件。每个示例都有 inputs 和 outputs。

从导出的跟踪创建（程序化）

先导出跟踪，再使用代码将其处理为数据集格式：

# 1. Export traces to JSONL files
langsmith trace export ./traces --project my-project --limit 20 --full --api-key $LANGSMITH_API_KEY

```python import json from pathlib import Path from langsmith import Client

client = Client()

2. Process traces into dataset examples

examples = [] for jsonl_file in Path("./traces").glob("*.jsonl"): runs = [json.loads(line) for line in jsonl_file.read_text().strip().split("\n")] root = next((r for r in runs if r.get("parent_run_id") is None), None) if root and root.get("inputs") and root.get("outputs"): examples.append({ "trace_id": root.get("trace_id"), "inputs": root["inputs"], "outputs": root["outputs"] })

3. Save locally

with open("/tmp/dataset.json", "w") as f: json.dump(examples, f, indent=2)

</python>

<typescript>
```typescript
import { Client } from "langsmith";
import { readFileSync, writeFileSync, readdirSync } from "fs";
import { join } from "path";

const client = new Client();

// 2. Process traces into dataset examples
const examples: Array<{trace_id?: string, inputs: Record<string, any>, outputs: Record<string, any>}> = [];
const files = readdirSync("./traces").filter(f => f.endsWith(".jsonl"));

for (const file of files) {
  const lines = readFileSync(join("./traces", file), "utf-8").trim().split("\n");
  const runs = lines.map(line => JSON.parse(line));
  const root = runs.find(r => r.parent_run_id == null);
  if (root?.inputs && root?.outputs) {
    examples.push({ trace_id: root.trace_id, inputs: root.inputs, outputs: root.outputs });
  }
}

// 3. Save locally
writeFileSync("/tmp/dataset.json", JSON.stringify(examples, null, 2));

上传到 LangSmith

# Upload local JSON file as a dataset
langsmith dataset upload /tmp/dataset.json --name "My Evaluation Dataset" --api-key $LANGSMITH_API_KEY

直接使用 SDK

```python from langsmith import Client

client = Client()

Create dataset and add examples in one step

dataset = client.create_dataset("My Dataset", description="Evaluation dataset")

client.create_examples( inputs=[{"query": "What is AI?"}, {"query": "Explain RAG"}], outputs=[{"answer": "AI is..."}, {"answer": "RAG is..."}], dataset_name="My Dataset", )

</python>

<typescript>
```typescript
import { Client } from "langsmith";

const client = new Client();

// Create dataset and add examples
const dataset = await client.createDataset("My Dataset", {
  description: "Evaluation dataset",
});

await client.createExamples({
  inputs: [{ query: "What is AI?" }, { query: "Explain RAG" }],
  outputs: [{ answer: "AI is..." }, { answer: "RAG is..." }],
  datasetName: "My Dataset",
});

<dataset_structures>

各类型的数据集结构

最终响应

{"trace_id": "...", "inputs": {"query": "What are the top genres?"}, "outputs": {"response": "The top genres are..."}}

单步

{"trace_id": "...", "inputs": {"messages": [...]}, "outputs": {"content": "..."}, "metadata": {"node_name": "model"}}

执行轨迹

{"trace_id": "...", "inputs": {"query": "..."}, "outputs": {"expected_trajectory": ["tool_a", "tool_b", "tool_c"]}}

RAG

{"trace_id": "...", "inputs": {"question": "How do I..."}, "outputs": {"answer": "...", "retrieved_chunks": ["..."], "cited_chunks": ["..."]}}

</dataset_structures>

<script_usage>

CLI 用法

# List all datasets
langsmith dataset list --api-key $LANGSMITH_API_KEY

# Get dataset details
langsmith dataset get "My Dataset" --api-key $LANGSMITH_API_KEY

# Create an empty dataset
langsmith dataset create --name "New Dataset" --description "For evaluation" --api-key $LANGSMITH_API_KEY

# Upload a local JSON file
langsmith dataset upload /tmp/dataset.json --name "My Dataset" --api-key $LANGSMITH_API_KEY

# Export a dataset to local file
langsmith dataset export "My Dataset" /tmp/exported.json --limit 100 --api-key $LANGSMITH_API_KEY

# Delete a dataset
langsmith dataset delete "My Dataset" --api-key $LANGSMITH_API_KEY

# List examples in a dataset
langsmith example list --dataset "My Dataset" --limit 10 --api-key $LANGSMITH_API_KEY

# Add an example
langsmith example create --dataset "My Dataset" \
  --inputs '{"query": "test"}' \
  --outputs '{"answer": "result"}' --api-key $LANGSMITH_API_KEY

# List experiments
langsmith experiment list --dataset "My Dataset" --api-key $LANGSMITH_API_KEY
langsmith experiment get "eval-v1" --api-key $LANGSMITH_API_KEY

</script_usage>

<example_workflow> 从追踪记录到上传 LangSmith 数据集的完整工作流：

# 1. Export traces from LangSmith
langsmith trace export ./traces --project my-project --limit 20 --full --api-key $LANGSMITH_API_KEY

# 2. Process traces into dataset format (using Python/JS code)
# See "Creating Datasets" section above

# 3. Upload to LangSmith
langsmith dataset upload /tmp/final_response.json --name "Skills: Final Response" --api-key $LANGSMITH_API_KEY
langsmith dataset upload /tmp/trajectory.json --name "Skills: Trajectory" --api-key $LANGSMITH_API_KEY

# 4. Verify upload
langsmith dataset list --api-key $LANGSMITH_API_KEY
langsmith dataset get "Skills: Final Response" --api-key $LANGSMITH_API_KEY
langsmith example list --dataset "Skills: Final Response" --limit 3 --api-key $LANGSMITH_API_KEY

# 5. Run experiments
langsmith experiment list --dataset "Skills: Final Response" --api-key $LANGSMITH_API_KEY

</example_workflow>

**数据集上传失败：** - 确认已设置 LANGSMITH_API_KEY - 检查 JSON 文件是否有效：每个元素都需要 `inputs`（`outputs` 可选） - 数据集名称必须唯一；如果名称已存在，请先使用 `langsmith dataset delete` 删除

上传后数据集为空：

• 确认 JSON 文件包含一个带有 inputs 键的对象数组
• 检查文件是否为空：langsmith example list --dataset "Name"

导出内容没有数据：

• 确保使用 --full 标志导出追踪记录，以包含输入/输出
• 确认追踪记录中的 inputs 和 outputs 均已填充

示例数量不匹配：

• 使用 langsmith dataset get "Name" 检查远程数量
• 与本地文件进行比较，以确认上传完整