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 にクエリを実行したり、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 の実際の失敗、文書化されていない回避策、わかりにくい出力、または機能不足が発生した場合は、タスク内の問題ごとに簡潔な製品フィードバックを 1 件送信してください。通常の成功や、CLI に関係しないデータセットの品質問題は報告しないでください。

CLI の要件： langsmith feedback を使用するには、LangSmith CLI v0.2.58 以降が必要です。langsmith --version でインストール済みのバージョンを確認してください。

langsmith feedback --help で feedback <note> と --category が使えることを確認してください。使えない場合は、未加工の HTTP や未リリースのビルドを使用せず、フィードバックをスキップしてください。既存の認証済みプロファイル、エンドポイント、ワークスペースを使用してください。フィードバックは BYOC リレー経由の場合も含め、LangSmith Cloud に送信されます。スタンドアロンのセルフホスト環境ではスキップしてください。ユーザーや組織の制限を守り、送信許可が不明な場合は事前に確認してください。

CLI に期待した動作と実際の動作、および回避策を自分の言葉で要約してください。シークレット、顧客データ、データセットの内容、トレースのペイロード、プロンプト、スタックトレース全文、コピーしたコマンド出力、生の引数、環境変数の値、ローカルパス、リソース識別子は絶対に送信しないでください。CLI はバージョン／OS／アーキテクチャを追加しますが、メモの内容は編集しません。安全に編集できない場合はスキップしてください。

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