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 を使用します。

• DeepAgents：--root-run-name LangGraph
• カスタムエージェント：ルートノード名を使用します

データセットの種類

1. 最終応答

期待される出力を含む会話全体 — エージェントの動作全体をテストします。

# 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 を省略すると、すべてのレベルが対象になります（サブエージェントのツール呼び出しを含む）
• --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 を使用する - 特定のエージェントフレームワーク（例：「LangGraph」）で絞り込みます
2. 成功したトレースから始める - 最近の成功した実行をベースラインデータセットとして使用します
3. 時間範囲を指定する - 過去24時間のデータには --last-n-minutes 1440 を使用します
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 がエージェントのルートノードと一致していることを確認します
• ルート実行に 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 スキルを使用します