phoenix-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Phoenix CLI

Debug and analyze LLM applications using the Phoenix CLI (

px

使用Phoenix CLI（

px

）调试和分析LLM应用程序。

Quick Start

快速开始

Installation

安装

bash

npm install -g @arizeai/phoenix-cli

bash

npm install -g @arizeai/phoenix-cli

Or run directly with npx

npx @arizeai/phoenix-cli

undefined

npx @arizeai/phoenix-cli

undefined

Configuration

配置

Set environment variables before running commands:

bash

export PHOENIX_HOST=http://localhost:6006
export PHOENIX_PROJECT=my-project
export PHOENIX_API_KEY=your-api-key  # if authentication is enabled

CLI flags override environment variables when specified.

运行命令前设置环境变量：

bash

export PHOENIX_HOST=http://localhost:6006
export PHOENIX_PROJECT=my-project
export PHOENIX_API_KEY=your-api-key  # if authentication is enabled

指定CLI参数时，会覆盖环境变量的设置。

Debugging Workflows

调试工作流

Debug a failing LLM application

调试故障LLM应用程序

Fetch recent traces to see what's happening:

bash

px traces --limit 10

Find failed traces:

bash

px traces --limit 50 --format raw --no-progress | jq '.[] | select(.status == "ERROR")'

Get details on a specific trace:

bash

px trace <trace-id>

Look for errors in spans:

bash

px trace <trace-id> --format raw | jq '.spans[] | select(.status_code != "OK")'

获取近期追踪数据，了解运行情况：

bash

px traces --limit 10

筛选出失败的追踪数据：

bash

px traces --limit 50 --format raw --no-progress | jq '.[] | select(.status == "ERROR")'

获取特定追踪数据的详情：

bash

px trace <trace-id>

在调用链（span）中查找错误：

bash

px trace <trace-id> --format raw | jq '.spans[] | select(.status_code != "OK")'

Find performance issues

排查性能问题

Get the slowest traces:

bash

px traces --limit 20 --format raw --no-progress | jq 'sort_by(-.duration) | .[0:5]'

Analyze span durations within a trace:

bash

px trace <trace-id> --format raw | jq '.spans | sort_by(-.duration_ms) | .[0:5] | .[] | {name, duration_ms, span_kind}'

获取最慢的追踪数据：

bash

px traces --limit 20 --format raw --no-progress | jq 'sort_by(-.duration) | .[0:5]'

分析单个追踪数据中各调用链的耗时：

bash

px trace <trace-id> --format raw | jq '.spans | sort_by(-.duration_ms) | .[0:5] | .[] | {name, duration_ms, span_kind}'

Analyze LLM usage

分析LLM使用情况

Extract models and token counts:

bash

px traces --limit 50 --format raw --no-progress | \
  jq -r '.[].spans[] | select(.span_kind == "LLM") | {model: .attributes["llm.model_name"], prompt_tokens: .attributes["llm.token_count.prompt"], completion_tokens: .attributes["llm.token_count.completion"]}'

提取模型信息和token数量：

bash

px traces --limit 50 --format raw --no-progress | \
  jq -r '.[].spans[] | select(.span_kind == "LLM") | {model: .attributes["llm.model_name"], prompt_tokens: .attributes["llm.token_count.prompt"], completion_tokens: .attributes["llm.token_count.completion"]}'

Review experiment results

查看实验结果

List datasets:

bash

px datasets

List experiments for a dataset:

bash

px experiments --dataset my-dataset

Analyze experiment failures:

bash

px experiment <experiment-id> --format raw --no-progress | \
  jq '.[] | select(.error != null) | {input: .input, error}'

Calculate average latency:

bash

px experiment <experiment-id> --format raw --no-progress | \
  jq '[.[].latency_ms] | add / length'

列出所有数据集：

bash

px datasets

列出指定数据集的实验：

bash

px experiments --dataset my-dataset

分析实验中的失败案例：

bash

px experiment <experiment-id> --format raw --no-progress | \
  jq '.[] | select(.error != null) | {input: .input, error}'

计算平均延迟：

bash

px experiment <experiment-id> --format raw --no-progress | \
  jq '[.[].latency_ms] | add / length'

Command Reference

命令参考

px traces

Fetch recent traces from a project.

bash

px traces [directory] [options]

Option	Description
`[directory]`	Save traces as JSON files to directory
`-n, --limit <number>`	Number of traces (default: 10)
`--last-n-minutes <number>`	Filter by time window
`--since <timestamp>`	Fetch since ISO timestamp
`--format <format>`	`pretty` , `json` , or `raw`
`--include-annotations`	Include span annotations

从项目中获取近期的追踪数据。

bash

px traces [directory] [options]

选项	描述
`[directory]`	将追踪数据保存为JSON文件到指定目录
`-n, --limit <number>`	追踪数据的数量（默认：10）
`--last-n-minutes <number>`	按时间窗口筛选
`--since <timestamp>`	从指定ISO时间戳开始获取
`--format <format>`	输出格式： `pretty` 、 `json` 或 `raw`
`--include-annotations`	包含调用链的注释信息

px trace

Fetch a specific trace by ID.

bash

px trace <trace-id> [options]

Option	Description
`--file <path>`	Save to file
`--format <format>`	`pretty` , `json` , or `raw`
`--include-annotations`	Include span annotations

通过ID获取特定的追踪数据。

bash

px trace <trace-id> [options]

选项	描述
`--file <path>`	将数据保存到指定文件
`--format <format>`	输出格式： `pretty` 、 `json` 或 `raw`
`--include-annotations`	包含调用链的注释信息

px datasets

List all datasets.

bash

px datasets [options]

列出所有数据集。

bash

px datasets [options]

px dataset

Fetch examples from a dataset.

bash

px dataset <dataset-name> [options]

Option	Description
`--split <name>`	Filter by split (repeatable)
`--version <id>`	Specific dataset version
`--file <path>`	Save to file

从数据集中获取样本数据。

bash

px dataset <dataset-name> [options]

选项	描述
`--split <name>`	按数据拆分筛选（可重复指定）
`--version <id>`	指定数据集版本
`--file <path>`	将数据保存到指定文件

px experiments

List experiments for a dataset.

bash

px experiments --dataset <name> [directory]

Option	Description
`--dataset <name>`	Dataset name or ID (required)
`[directory]`	Export experiment JSON to directory

列出指定数据集的所有实验。

bash

px experiments --dataset <name> [directory]

选项	描述
`--dataset <name>`	数据集名称或ID（必填）
`[directory]`	将实验数据导出为JSON文件到指定目录

px experiment

Fetch a single experiment with run data.

bash

px experiment <experiment-id> [options]

获取包含运行数据的单个实验信息。

bash

px experiment <experiment-id> [options]

px prompts

List all prompts.

bash

px prompts [options]

列出所有提示词。

bash

px prompts [options]

px prompt

Fetch a specific prompt.

bash

px prompt <prompt-name> [options]

获取特定的提示词信息。

bash

px prompt <prompt-name> [options]

Output Formats

输出格式

pretty
(default): Human-readable tree view
json
: Formatted JSON with indentation
raw
: Compact JSON for piping to
```
jq
```
or other tools

Use

--format raw --no-progress

when piping output to other commands.

pretty
（默认）：易读的树形视图
json
：带缩进的格式化JSON
raw
：紧凑的JSON格式，可通过管道传递给
```
jq
```
或其他工具

当需要将输出通过管道传递给其他命令时，使用

--format raw --no-progress

参数。

Trace Structure

追踪数据结构

Traces contain spans with OpenInference semantic attributes:

json

{
  "traceId": "abc123",
  "spans": [{
    "name": "chat_completion",
    "span_kind": "LLM",
    "status_code": "OK",
    "attributes": {
      "llm.model_name": "gpt-4",
      "llm.token_count.prompt": 512,
      "llm.token_count.completion": 256,
      "input.value": "What is the weather?",
      "output.value": "The weather is sunny..."
    }
  }],
  "duration": 1250,
  "status": "OK"
}

Key span kinds:

LLM

CHAIN

TOOL

RETRIEVER

EMBEDDING

AGENT

Key attributes for LLM spans:

```
llm.model_name
```
: Model used
```
llm.provider
```
: Provider name (e.g., "openai")

llm.token_count.prompt

llm.token_count.completion

: Token counts

```
llm.input_messages.*
```
: Input messages (indexed, with role and content)
```
llm.output_messages.*
```
: Output messages (indexed, with role and content)
```
input.value
```
/
```
output.value
```
: Raw input/output as text
```
exception.message
```
: Error message if failed

追踪数据包含带有OpenInference语义属性的调用链（span）：

json

{
  "traceId": "abc123",
  "spans": [{
    "name": "chat_completion",
    "span_kind": "LLM",
    "status_code": "OK",
    "attributes": {
      "llm.model_name": "gpt-4",
      "llm.token_count.prompt": 512,
      "llm.token_count.completion": 256,
      "input.value": "What is the weather?",
      "output.value": "The weather is sunny..."
    }
  }],
  "duration": 1250,
  "status": "OK"
}

主要的调用链类型：

LLM

、

CHAIN

、

TOOL

、

RETRIEVER

、

EMBEDDING

、

AGENT

。

LLM调用链的关键属性：

```
llm.model_name
```
: 使用的模型
```
llm.provider
```
: 模型提供商名称（例如："openai"）

llm.token_count.prompt

llm.token_count.completion

: Token数量

```
llm.input_messages.*
```
: 输入消息（带索引，包含角色和内容）
```
llm.output_messages.*
```
: 输出消息（带索引，包含角色和内容）
```
input.value
```
/
```
output.value
```
: 原始输入/输出文本
```
exception.message
```
: 失败时的错误信息