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

<cli_feedback> 在 CLI 实际运行失败、需要使用未记录的变通方法、输出令人困惑或缺少功能后，请针对任务中每个不同问题提交一条简洁的产品反馈。不要报告常规成功，也不要报告与 CLI 无关的数据集质量问题。

CLI 要求： langsmith feedback 需要 LangSmith CLI v0.2.58 或更高版本。使用 langsmith --version 检查已安装的版本。

检查 langsmith feedback --help，确认是否支持 feedback <note> 和 --category；如果不支持，请跳过反馈，不要使用原始 HTTP 请求或未发布版本。使用现有的已认证配置文件、端点和工作区。反馈会发送到 LangSmith Cloud，包括通过 BYOC 中继发送的情况；独立的自托管部署请跳过。遵守用户和组织的限制；如果不确定是否获准发送反馈，请先询问。

用自己的话概述 CLI 的预期行为与实际观察到的行为，以及使用的变通方法。切勿发送机密、客户数据、数据集内容、追踪负载、提示词、完整堆栈跟踪、复制的命令输出、原始参数、环境变量值、本地路径或资源标识符。CLI 会添加版本、操作系统和架构信息，但不会替你删去反馈文本中的敏感内容；如果无法安全地删去敏感信息，请跳过反馈。

请选择 bug、feature-request、usability、documentation 或 other。这是 CLI 产品反馈，不是数据集或运行评估反馈。以下仅为格式示例——除非确实遇到相关问题，否则不要提交：

langsmith feedback --category documentation --format json "The dataset upload help did not explain the required JSON structure."

不要重试失败或遭遇速率限制的反馈提交，不要切换凭据或端点来绕过失败，也不要因反馈而耽误原任务。 </cli_feedback>

使用 `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")

Pass examples as a list of dicts. The parallel inputs=/outputs= lists

are still accepted but only as legacy keyword arguments.

client.create_examples( dataset_id=dataset.id, examples=[ {"inputs": {"query": "What is AI?"}, "outputs": {"answer": "AI is..."}}, {"inputs": {"query": "Explain RAG"}, "outputs": {"answer": "RAG is..."}}, ], )

</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",
});

// Pass an array of examples. The `{ inputs, outputs, datasetName }` form is
// deprecated in the JS SDK; each example carries its own dataset_id.
await client.createExamples([
  {
    inputs: { query: "What is AI?" },
    outputs: { answer: "AI is..." },
    dataset_id: dataset.id,
  },
  {
    inputs: { query: "Explain RAG" },
    outputs: { answer: "RAG is..." },
    dataset_id: dataset.id,
  },
]);

<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" 检查远程数量
• 与本地文件进行比较，确认上传完整