> ## Documentation Index
> Fetch the complete documentation index at: https://cndoc-langchain.site/llms.txt
> Use this file to discover all available pages before exploring further.

# LangSmith CLI

> 从终端查询和管理 LangSmith 项目、追踪、运行、数据集、评估器、实验和线程

LangSmith CLI 是一个用于查询和管理您的 LangSmith 数据的命令行工具。它专为开发者和 AI 编程代理设计，默认输出 JSON 格式以便于脚本编写，并提供 `--format pretty` 选项以生成人类可读的表格。当您需要对 LangSmith 数据进行可脚本化的访问时，例如批量导出、自动化或让编程代理直接访问您的[追踪、运行和数据集](/langsmith/observability-concepts)，可以使用此工具。

<Warning>
  LangSmith CLI 目前处于 **alpha** 阶段。命令、标志和输出模式可能会在版本之间发生变化。请在 [GitHub](https://github.com/langchain-ai/langsmith-cli/issues) 上报告问题。
</Warning>

## 安装

<CodeGroup>
  ```bash macOS / Linux (推荐) theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  curl -fsSL https://cli.langsmith.com/install.sh | sh
  ```

  ```powershell Windows theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  irm https://cli.langsmith.com/install.ps1 | iex
  ```

  ```bash GitHub Releases theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  # 下载适用于您平台的最新二进制文件：
  # https://github.com/langchain-ai/langsmith-cli/releases
  ```

  ```bash Go install theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  go install github.com/langchain-ai/langsmith-cli/cmd/langsmith@latest
  ```
</CodeGroup>

随时可以升级：

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
langsmith self-update
```

使用 `--dry-run` 标志可以预览更新而不实际安装。

## 认证

将您的 [API 密钥](/langsmith/create-account-api-key)设置为环境变量：

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
export LANGSMITH_API_KEY="lsv2_..."
```

可选地，为查询设置默认项目：

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
export LANGSMITH_PROJECT="my-default-project"
```

如果您使用 LangSmith [自托管](/langsmith/self-hosted)或[混合](/langsmith/hybrid)部署，还需设置端点：

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
export LANGSMITH_ENDPOINT="https://your-langsmith-instance.com"
```

或者，将它们作为每个命令的标志传递：

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
langsmith --api-key lsv2_... trace list --project my-app
```

## 快速入门

以下命令涵盖了核心资源类型：

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
# 列出追踪项目
langsmith project list

# 列出项目中的最近追踪
langsmith trace list --project my-app --limit 5

# 获取包含完整详情的特定追踪
langsmith trace get <trace-id> --project my-app --full

# 列出包含令牌计数的 LLM 运行
langsmith run list --project my-app --run-type llm --include-metadata

# 数据集和实验
langsmith dataset list
langsmith experiment list --dataset my-eval-set

# 对话线程
langsmith thread list --project my-chatbot

# 沙箱
langsmith sandbox list
langsmith sandbox tunnel my-vm --remote-port 5432
```

## 输出格式

**默认**

JSON 输出到标准输出 — 便于管道、脚本或传递给代理：

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
langsmith trace list --project my-app
```

**美化表格**

`--format pretty` 用于人类可读的输出：

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
langsmith --format pretty trace list --project my-app
```

**写入文件**

`-o <路径>`：

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
langsmith trace list --project my-app -o traces.json
```

## 命令

每个命令组针对特定的 LangSmith 资源。大多数命令支持 `--limit`、`--offset` 和一组共享的[过滤标志](#过滤标志)。

### 列出项目

默认返回最多 20 个项目，按最近活动排序。仅列出追踪项目。（使用 [`experiment list`](#查看实验) 列出评估实验。）

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
langsmith project list
langsmith project list --limit 50 --name-contains chatbot
langsmith --format pretty project list
```

### 查询追踪

默认为最近 7 天，最新在前。使用 `--since` 或 `--last-n-minutes` 更改时间窗口。

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
langsmith trace list --project my-app --limit 50 --last-n-minutes 60
langsmith trace list --project my-app --error                     # 仅错误
langsmith trace list --project my-app --min-latency 5             # 慢追踪 (>5秒)
langsmith trace list --project my-app --tags production           # 按标签过滤
langsmith trace list --project my-app --full                      # 所有字段
langsmith trace list --project my-app --show-hierarchy --limit 3  # 包含完整运行树
langsmith trace get <trace-id> --project my-app --full
langsmith trace export ./traces --project my-app --limit 20 --full
```

### 查询运行

默认返回 50 个结果（大多数其他命令默认为 20）。相同的 7 天时间窗口适用。使用 `--since` 或 `--last-n-minutes` 覆盖。

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
langsmith run list --project my-app --run-type llm
langsmith run list --project my-app --run-type tool --name search
langsmith run list --project my-app --min-tokens 1000 --include-metadata
langsmith run get <run-id> --full
langsmith run export llm_calls.jsonl --project my-app --run-type llm --full
```

### 查询线程

所有线程命令都需要 `--project`。

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
langsmith thread list --project my-chatbot --last-n-minutes 120
langsmith thread get <thread-id> --project my-chatbot --full
```

### 管理数据集

`dataset export` 导出数据集中的示例（行），而不是数据集元数据本身。

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
langsmith dataset list
langsmith dataset list --name-contains eval
langsmith dataset get my-dataset
langsmith dataset create --name my-eval-set --description "v2 的问答对"
langsmith dataset delete my-old-dataset --yes
langsmith dataset export my-dataset ./data.json --limit 500
langsmith dataset upload data.json --name new-dataset
```

### 管理示例

创建或列出时，使用 `--split` 将示例分配给命名的分割（例如 `test` 或 `train`）。

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
langsmith example list --dataset my-dataset --limit 50
langsmith example list --dataset my-dataset --split test
langsmith example create --dataset my-dataset \
  --inputs '{"question": "What is LangSmith?"}' \
  --outputs '{"answer": "A platform for LLM observability"}' \
  --split test
langsmith example delete <example-id> --yes
```

### 管理评估器

评估器可以是离线的（在实验期间针对数据集运行）或在线的（针对实时项目运行）。使用 `--sampling-rate` 仅评估一部分生产运行，使用 `--replace` 按名称覆盖现有评估器。

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
langsmith evaluator list
langsmith evaluator upload evals.py --name accuracy \
  --function check_accuracy --dataset my-eval-set
langsmith evaluator upload evals.py --name latency-check \
  --function check_latency --project my-app --sampling-rate 0.5
langsmith evaluator upload evals.py --name accuracy \
  --function check_accuracy_v2 --dataset my-eval-set --replace --yes
langsmith evaluator delete accuracy --yes
```

### 查看实验

`experiment list` 显示评估实验，而不是追踪项目。（使用 [`project list`](#列出项目) 列出追踪项目。）

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
langsmith experiment list
langsmith experiment list --dataset my-eval-set
langsmith experiment get my-experiment-2024-01-15
```

### 管理沙箱

沙箱命令允许您构建快照、创建沙箱、执行命令、打开交互式控制台，以及将 TCP 端口隧道连接到沙箱内运行的服务。

完整的沙箱命令参考，请参阅 [沙箱 CLI](/langsmith/sandbox-cli)。

## 过滤标志

大多数 `trace` 和 `run` 命令共享这些过滤器：

| 标志                                | 描述                   | 示例                               |
| --------------------------------- | -------------------- | -------------------------------- |
| `--project`                       | 项目名称                 | `--project my-app`               |
| `--limit, -n`                     | 最大结果数                | `-n 10`                          |
| `--offset`                        | 分页偏移量                | `--offset 20`                    |
| `--last-n-minutes`                | 覆盖 7 天默认值            | `--last-n-minutes 60`            |
| `--since`                         | ISO 时间戳之后            | `--since 2024-01-15T00:00:00Z`   |
| `--error` / `--no-error`          | 按错误状态过滤              | `--error`                        |
| `--name`                          | 名称搜索（不区分大小写）         | `--name ChatOpenAI`              |
| `--run-type`                      | 运行类型（`llm` 或 `tool`） | `--run-type llm`                 |
| `--min-latency` / `--max-latency` | 延迟范围（秒）              | `--min-latency 2.5`              |
| `--min-tokens`                    | 最小总令牌数               | `--min-tokens 1000`              |
| `--tags`                          | 标签，逗号分隔（OR 逻辑）       | `--tags prod,v2`                 |
| `--filter`                        | 原始 LangSmith 过滤器 DSL | `--filter 'eq(status, "error")'` |
| `--trace-ids`                     | 特定追踪 ID              | `--trace-ids abc123,def456`      |

**详情标志** — 控制响应中包含哪些字段：

| 标志                   | 添加内容          |
| -------------------- | ------------- |
| `--include-metadata` | 状态、持续时间、令牌、成本 |
| `--include-io`       | 输入、输出、错误      |
| `--include-feedback` | 反馈统计          |
| `--full`             | 以上所有          |
| `--show-hierarchy`   | 完整运行树（仅追踪）    |

***

<div className="source-links">
  <Callout icon="terminal-2">
    [连接这些文档](/use-these-docs)到 Claude、VSCode 等，通过 MCP 获取实时答案。
  </Callout>

  <Callout icon="edit">
    [在 GitHub 上编辑此页面](https://github.com/langchain-ai/docs/edit/main/src/langsmith/langsmith-cli.mdx) 或 [提交问题](https://github.com/langchain-ai/docs/issues/new/choose)。
  </Callout>
</div>