Back to Details

phoenix-cli

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Phoenix CLI

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

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应用程序

  1. Fetch recent traces to see what's happening:
bash
px traces --limit 10
  1. Find failed traces:
bash
px traces --limit 50 --format raw --no-progress | jq '.[] | select(.status == "ERROR")'
  1. Get details on a specific trace:
bash
px trace <trace-id>
  1. Look for errors in spans:
bash
px trace <trace-id> --format raw | jq '.spans[] | select(.status_code != "OK")'
  1. 获取近期追踪数据，了解运行情况：
bash
px traces --limit 10
  1. 筛选出失败的追踪数据：
bash
px traces --limit 50 --format raw --no-progress | jq '.[] | select(.status == "ERROR")'
  1. 获取特定追踪数据的详情：
bash
px trace <trace-id>
  1. 在调用链（span）中查找错误：
bash
px trace <trace-id> --format raw | jq '.spans[] | select(.status_code != "OK")'

Find performance issues

排查性能问题

  1. Get the slowest traces:
bash
px traces --limit 20 --format raw --no-progress | jq 'sort_by(-.duration) | .[0:5]'
  1. 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}'
  1. 获取最慢的追踪数据：
bash
px traces --limit 20 --format raw --no-progress | jq 'sort_by(-.duration) | .[0:5]'
  1. 分析单个追踪数据中各调用链的耗时：
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

查看实验结果

  1. List datasets:
bash
px datasets
  1. List experiments for a dataset:
bash
px experiments --dataset my-dataset
  1. Analyze experiment failures:
bash
px experiment <experiment-id> --format raw --no-progress | \
  jq '.[] | select(.error != null) | {input: .input, error}'
  1. Calculate average latency:
bash
px experiment <experiment-id> --format raw --no-progress | \
  jq '[.[].latency_ms] | add / length'
  1. 列出所有数据集：
bash
px datasets
  1. 列出指定数据集的实验：
bash
px experiments --dataset my-dataset
  1. 分析实验中的失败案例：
bash
px experiment <experiment-id> --format raw --no-progress | \
  jq '.[] | select(.error != null) | {input: .input, error}'
  1. 计算平均延迟：
bash
px experiment <experiment-id> --format raw --no-progress | \
  jq '[.[].latency_ms] | add / length'

Command Reference

命令参考

px traces

px traces

Fetch recent traces from a project.
bash
px traces [directory] [options]
OptionDescription
[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

px trace

Fetch a specific trace by ID.
bash
px trace <trace-id> [options]
OptionDescription
--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

px datasets

List all datasets.
bash
px datasets [options]
列出所有数据集。
bash
px datasets [options]

px dataset

px dataset

Fetch examples from a dataset.
bash
px dataset <dataset-name> [options]
OptionDescription
--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

px experiments

List experiments for a dataset.
bash
px experiments --dataset <name> [directory]
OptionDescription
--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

px experiment

Fetch a single experiment with run data.
bash
px experiment <experiment-id> [options]
获取包含运行数据的单个实验信息。
bash
px experiment <experiment-id> [options]

px prompts

px prompts

List all prompts.
bash
px prompts [options]
列出所有提示词。
bash
px prompts [options]

px prompt

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
    : 失败时的错误信息