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 - 期待される出力を含む会話全体です。エージェントの動作全体をテストします。
• single_step - 単一ノードの入力と出力です。特定のノードの動作（例：LLM 呼び出し 1 回またはツール 1 つ）をテストします。
• 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" を使ってリモートの件数を確認してください
• ローカルファイルと比較して、アップロードが完全に行われたことを確認してください