在终端或 agent 中调试 Phoenix LLM…

需要从命令行查询、调试、标注或管理 Arize Phoenix 实例中的 LLM 应用数据时使用。

适用场景

解决思路

1. 用全局安装调用：`px <resource> <action>`；或免安装调用：`npx @arizeai/phoenix-cli <resource> <action>`。
2. 使用单数资源命令加子命令：`px trace list/get/annotate/add-note/delete`、`px trace-annotations delete`、`px span list/annotate/add-note/delete`、`px span-annotations delete`、`px session list/get/annotate/add-note/delete`、`px session-annotations delete`、`px dataset list/get/delete`、`px experiment list/get/delete`、`px prompt list/get/delete`、`px project list/get/delete`、`px annotation-config list/get/create/update/delete`、`px auth login/logout/status`、`px profile list/show/create/use/edit/delete`、`px api graphql <query>`、`px docs fetch`、`px setup`、`px self update`。
3. 所有 `delete` 受门控：需要环境变量 `PHOENIX_CLI_DANGEROUSLY_ENABLE_DELETES=true`，并默认提示确认；传 `-y`/`--yes` 跳过确认；`px profile delete` 是本地操作，只需 `--yes` 而不需要该环境变量；没有环境变量时不执行删除。
4. 设置 API 访问环境变量：`export PHOENIX_ENDPOINT=http://localhost:6006`、`export PHOENIX_PROJECT=my-project`、`export PHOENIX_API_KEY=your-api-key`（启用认证时）。`PHOENIX_ENDPOINT` 是 API 基 URL；通常与 `PHOENIX_COLLECTOR_ENDPOINT` 相同；只设置 collector 变量时，CLI 也用它做 API 访问。
5. 交互式本地使用 `px auth login` 在所选 profile 中保存 OAuth 会话，会话以登录用户权限执行；同时配置 API key 和 OAuth token 时 API key 优先；OAuth access token 对 REST、GraphQL、PXI 请求自动刷新，轮换 token 持久化到所选 profile。
6. 管道到 `jq` 时总是使用 `--format raw --no-progress`。
7. 用 `px setup` onboarding 将当前目录连接到 Phoenix deployment 并写 `.env.phoenix`（mode 0600，gitignored）。从 agent 调用时总是传 `--no-input`：`px setup --no-input --endpoint http://localhost:6006 --project my-app --format raw`；headless 要求干净 git repo，默认只写文件不碰源码；启用认证时还要设置 `PHOENIX_API_KEY`；项目不需要预先存在，Phoenix 在首个 trace 时创建；缺少输入退出 `3` 并给精确修复信息，取消退出 `2`。
8. 要让 `px setup` 同时插桩应用，headless 必须同时命名 lane：`px setup --no-input --instrument --agent claude --yolo --format raw`；`--yolo` 很重要，后台 agent 没有终端批准编辑，否则运行会停顿直到 trace 验证超时；`--language python` 跳过 agent 的语言检测；`--docs-mcp` 将 Phoenix docs MCP server 连接到 hand-off agent（claude 用 `claude mcp add`，cursor/opencode 合并配置文件，codex 不支持）并跳过 `.px/docs` 下载，agent 按需搜索文档，任何失败回退到下载；`--no-docs-mcp` 抑制交互式提供。
9. 检查 `px setup` 的 `--format raw` 输出：JSON 为 `{"endpoint","project","files","instrumentation","tracesVerified","tracesUrl"}`；检查 `tracesVerified`，只有 API 确认 trace 到达时才置位，而不是 agent 声称完成；等待超时且无 trace 退出 `6` 不是 `0`，配置和编辑真实但 tracing 未确认工作，应作为失败报告，不要用 hand-off agent 自己的 exit code 或 summary 替代结论；注册-only 和人工在超时提示选 “verify later” 都退出 `0`；`tracesVerified` 对 registration-only 也为 `false`，需要区分 “nothing to verify” 与 “no trace arrived” 时读取 `verification`（`verified`/`notVerified`/`deferred`，无可验证内容时缺失）。
10. 可重跑的 setup slices：`px setup instrument --agent claude` 只插桩并验证；`px setup skills` 安装 Phoenix coding-agent skills。
11. 用 `px setup mcp` 注册 Phoenix remote MCP server（`<endpoint>/mcp`）到 coding agent，使其能查询 Phoenix 数据；endpoint 从 `--endpoint`、active profile 或 `PHOENIX_ENDPOINT` 推断；裸命令提示 scope（默认 global）再提示 agent，`--agent` 跳过两者；示例：`px setup mcp --agent codex --no-input --format raw`、`px setup mcp --agent claude --local`（写入本仓库 `.mcp.json`）。
12. `px setup mcp` 支持的 agents：`claude`、`codex`、`gemini`、`cursor`、`opencode`、`vscode`；scope 为 `--global`（默认）或 `--local`（repo；Codex 仅 global）；认证默认 OAuth（仅 URL 配置，首次使用浏览器登录）；传可重复的 `--header "Name: value"` 作为 API-key bearer fallback；对 Codex，`Authorization: Bearer ${VAR}` header 会变成 `bearer_token_env_var`；`--format raw` 输出 `{"endpoint","url","serverName","agent","scope","auth","file?"}`。
13. 认证命令：`px auth login` 浏览器 OAuth 登录；`px auth login --no-browser` 为 SSH/headless 打印 URL；`px auth logout` 清除 OAuth token，保留 API key；`px auth status` 检查连接和认证；`px auth status --endpoint http://other:6006` 检查特定 endpoint；`px auth status --profile staging` 检查命名 profile 连接；`px auth status --format raw` 输出机器可读 credential source。
14. `auth status` 报告 credential source（`flag`、`env`、`profile-key`、`oauth` 或 `none`）；OAuth 状态包含 token expiry；当存储 credential source 是 `oauth` 且认证探测失败时，`auth status` 会无凭据重试一次，仅当服务器明确表示匿名访问时才报告 anonymous access，避免 stale/expired profile token 被报告为 auth failure。
15. 使用命名 profiles 在多个 Phoenix 实例（local、staging、cloud）间切换，无需折腾环境变量；profiles 存于 `~/.px/settings.json` 或 `$XDG_CONFIG_HOME/px/settings.json`。配置优先级从高到低：CLI flags > env vars > active profile > 最近的 `.env.phoenix` 文件 > 内置默认值。CLI 还会在当前工作目录或以上发现最近的 `.env.phoenix`（即 `px setup` 写入的文件）；凭据作为一组解析，进程 API key 绝不与文件提供的 headers 组合；设置 `PHOENIX_DISCOVER_CONFIG=false` 禁用发现。
16. Profile 命令：`px profile list` 列出所有 profiles（显示 active）；`px profile show` 显示 active profile 设置；`px profile show staging` 显示命名 profile；`px profile create prod --endpoint https://app.phoenix.arize.com --api-key <key> --activate`；`px profile create local --endpoint http://localhost:6006 --project my-app`；`px profile use prod` 切换 active；`px profile edit prod` 在 `$EDITOR` 打开 profile JSON（保存时验证）；`px profile delete prod --yes` 删除 profile。`px profile create` 选项：`--endpoint <url>`、`--project <name>`、`--api-key <key>`、`--header <key=value>`（可重复）、`--activate`。
17. 在任何命令上用 `--profile <name>` 定位特定 profile 而不改变 active profile，例如 `px trace list --profile staging --limit 10 --format raw --no-progress | jq .`、`px auth status --profile prod`。
18. Projects 操作：`px project list` 列出项目；`px project list --format raw --no-progress | jq '.[].name'` 输出项目名 JSON；`px project list --name-contains prod` 按名称子串过滤（大小写不敏感）；`px project get my-project --format raw --no-progress` 按精确名称取单条记录；`px project get my-project --format raw --no-progress | jq -r '.id'` 提取 project id。`project list` 接受 `--limit <n>`（每页项目数）和 `--name-contains <filter>`，后者在服务端按大小写不敏感名称子串过滤，只知部分项目名时用它替代把 `list` 管道给 `grep`。`project get` 名称未命中退出 `ExitCode.FAILURE`（1），并在 `--format json|raw` 下向 stderr 写 `StructuredError` `{error, code: "FAILURE", hint}`。
19. Traces 查询：`px trace list --limit 20 --format raw --no-progress | jq .`；`px trace list --last-n-minutes 60 --limit 20 --format raw --no-progress | jq '.[] | select(.status == "ERROR")'`；`px trace list --since 2025-01-15T00:00:00Z --limit 50 --format raw --no-progress | jq .`；`px trace list --since 2025-01-15T00:00:00Z --until 2025-01-16T00:00:00Z --limit 50 --format raw --no-progress | jq .`（`until` 不含端点）；`px trace list --format raw --no-progress | jq 'sort_by(-.duration) | .[0:5]'`；`px trace list --include-notes --format raw --no-progress | jq '.[].notes'`；`px trace get <trace-id> --format raw | jq .`；`px trace get <trace-id> --format raw | jq '.spans[] | select(.status_code != "OK")'`；`px trace get <trace-id> --include-notes --format raw | jq '.notes'`。
20. Traces 标注与笔记：`px trace annotate <trace-id> --name reviewer --label pass`；`px trace annotate <trace-id> --name reviewer --score 0.9 --format raw --no-progress`；`px trace annotate <trace-id> --name reviewer --label pass --identifier "<coding-annotation-id>"` 用 coding annotation identifier 打标；`px trace add-note <trace-id> --text "needs follow-up"`；`px trace add-note <trace-id> --text "needs follow-up" --identifier "<coding-annotation-id>"` 打标并按 identifier upsert；`px trace-annotations delete --identifier "<coding-annotation-id>" --all -y` 删除与该 coding annotation identifier 关联的所有标注。`px <entity>-annotations delete` 需要 `--all` 或同时 `--start-time` 和 `--end-time`，成功输出 `{deleted: true, target, filter}`。
21. 读取 Trace JSON 时使用其结构：`traceId`、`status`（`"OK"|"ERROR"`）、`duration`（ms）、`startTime`、`endTime`；`annotations[]`（配 `--include-annotations`，排除 note）包含 `name`、`result { score, label, explanation }`；`notes[]`（配 `--include-notes`）包含 `name="note"`、`result { explanation }`；`rootSpan` 是顶层 span（`parent_id: null`）；`spans[]` 包含 `name`、`span_kind`（`"LLM"|"CHAIN"|"TOOL"|"RETRIEVER"|"EMBEDDING"|"AGENT"|"RERANKER"|"GUARDRAIL"|"EVALUATOR"|"UNKNOWN"`）、`status_code`（`"OK"|"ERROR"|"UNSET"`）、`parent_id`、`context.span_id`；`notes[]`（配 `--include-notes`）包含 `name="note"`、`result { explanation }`；`attributes` 包含 `input.value`、`output.value`、`llm.model_name`、`llm.provider`、`llm.token_count.prompt/completion/total`、`llm.token_count.prompt_details.cache_read`、`llm.token_count.completion_details.reasoning`、`llm.input_messages.{N}.message.role/content`、`llm.output_messages.{N}.message.role/content`、`llm.invocation_parameters`（JSON 字符串）、`exception.message`（span 出错时设置）。
22. Spans 查询：`px span list --limit 20`；`px span list --last-n-minutes 60 --limit 50`；`px span list --since 2025-01-15T00:00:00Z --limit 50`；`px span list --since 2025-01-15T00:00:00Z --until 2025-01-16T00:00:00Z --limit 50`（`until` 不含端点）；`px span list --span-kind LLM --limit 10`；`px span list --status-code ERROR --limit 20`；`px span list --name chat_completion --limit 10`；`px span list --trace-id <id> --format raw --no-progress | jq .`；`px span list --span-id <id> <id> --format raw --no-progress | jq .`（server >= 19.6.0）；`px span list --parent-id null --limit 10`；`px span list --parent-id <span-id> --limit 10`；`px span list --include-annotations --limit 10`；`px span list --include-notes --limit 10`；`px span list --attribute llm.model_name:gpt-4 --limit 10`；`px span list --attribute llm.token_count.total:500 --limit 10`；`px span list --attribute 'user.id:"12345"' --limit 10` 强制字符串匹配数字形值；`px span list --attribute session.id:sess:abc:123 --limit 20`（值中冒号可接受，只按第一个冒号分割）；`px span list --attribute llm.model_name:gpt-4 --attribute session.id:abc --limit 10` 多过滤 AND；`px span list output.json --limit 100` 保存到 JSON 文件；`px span list --format raw --no-progress | jq '.[] | select(.status_code == "ERROR")'`。
23. Spans 标注与笔记：`px span annotate <span-id> --name reviewer --label pass`；`px span annotate <span-id> --name checker --score 1 --annotator-kind CODE`；`px span annotate <span-id> --name reviewer --label pass --identifier "<coding-annotation-id>"`；`px span add-note <span-id> --text "verified by agent"`；`px span add-note <span-id> --text "verified by agent" --identifier "<coding-annotation-id>"`；`px span-annotations delete --identifier "<coding-annotation-id>" --all -y`。
24. 读取 Span JSON 时使用其结构：`name`、`span_kind`（`"LLM"|"CHAIN"|"TOOL"|"RETRIEVER"|"EMBEDDING"|"AGENT"|"RERANKER"|"GUARDRAIL"|"EVALUATOR"|"UNKNOWN"`）、`status_code`（`"OK"|"ERROR"|"UNSET"`）、`status_message`、`context.span_id`、`context.trace_id`、`parent_id`、`start_time`、`end_time`；`attributes` 包含 `input.value`、`output.value`、`llm.model_name`、`llm.provider`、`llm.token_count.prompt/completion/total`、`llm.input_messages.{N}.message.role/content`、`llm.output_messages.{N}.message.role/content`、`llm.invocation_parameters`（JSON 字符串）、`exception.message`；`annotations[]`（配 `--include-annotations`，排除 note）包含 `name`、`result { score, label, explanation }`；`notes[]`（配 `--include-notes`）包含 `name="note"`、`result { explanation }`。
25. Sessions 查询：`px session list --limit 10 --format raw --no-progress | jq .`；`px session list --order asc --format raw --no-progress | jq '.[].session_id'`；`px session list --include-annotations --include-notes --format raw --no-progress | jq '.[].notes'`；`px session get <session-id> --format raw | jq .`；`px session get <session-id> --include-annotations --format raw | jq '.session.annotations'`；`px session get <session-id> --include-notes --format raw | jq '.session.notes'`。
26. Sessions 标注、笔记与删除：`px session annotate <session-id> --name reviewer --label pass`；`px session annotate <session-id> --name reviewer --score 0.9 --format raw --no-progress`；`px session annotate <session-id> --name reviewer --label pass --identifier "<coding-annotation-id>"`；`px session add-note <session-id> --text "verified by agent"`；`px session add-note <session-id> --text "verified by agent" --identifier "<coding-annotation-id>"`；`px session-annotations delete --identifier "<coding-annotation-id>" --all -y`；`px session delete <session-id> -y`（需要 `PHOENIX_CLI_DANGEROUSLY_ENABLE_DELETES=true`）。`session list` 没有 filter flag；要按形状（错误数、token 总数、tool use、标注 labels）选择 sessions，通过 GraphQL 使用 session filter expression language。
27. 读取 Session JSON 时使用其结构：`SessionData` 包含 `id`、`session_id`、`project_id`、`start_time`、`end_time`、`token_count_prompt`、`token_count_completion`、`token_count_total`（所有 LLM spans 累计，int，默认 0）；`annotations[]`（配 `--include-annotations`，排除 note）包含 `name`、`result { score, label, explanation }`；`notes[]`（配 `--include-notes`）包含 `name="note"`、`result { explanation }`；`traces[]` 包含 `id`、`trace_id`、`start_time`、`end_time`。
28. Datasets / Experiments / Prompts：`px dataset list --format raw --no-progress | jq '.[].name'`；`px dataset get <name> --format raw | jq '.examples[] | {input, output: .expected_output}'`；`px dataset get <name> --split train --format raw | jq .`；`px dataset get <name> --version <version-id> --format raw | jq .`；`px experiment list --dataset <name> --format raw --no-progress | jq '.[] | {id, name, failed_run_count}'`；`px experiment get <id> --format raw --no-progress | jq '.[] | select(.error != null) | {input, error}'`；`px prompt list --format raw --no-progress | jq '.[].name'`；`px prompt get <name> --format text --no-progress` 输出纯文本，适合管道给 AI。
29. Annotation Configs 完整 CRUD：`px annotation-config list`；`px annotation-config list --format raw --no-progress | jq -r '.[].name'`；`px annotation-config get response-quality --format raw --no-progress`；类型为 `CATEGORICAL`（labels + 可选 scores）、`CONTINUOUS`（数值范围）、`FREEFORM`（自由文本）。
30. 创建 Annotation Configs：`px annotation-config create --type CATEGORICAL --name response-quality --value good=1 --value bad=0`；`px annotation-config create --type CONTINUOUS --name confidence --lower-bound 0 --upper-bound 1`；`px annotation-config create --type FREEFORM --name reviewer-notes --description 'Free-form reviewer feedback'`。更新：`px annotation-config update response-quality --name answer-quality --optimization-direction MAXIMIZE`；`px annotation-config update response-quality --value good=1 --value acceptable=0.5 --value bad=0`；`px annotation-config update response-quality --description "Updated" --format raw --no-progress | jq -r '.id'`。删除：`px annotation-config delete QW5ub3RhdGlvbkNvbmZpZzoxMjM= --yes`（需要 `PHOENIX_CLI_DANGEROUSLY_ENABLE_DELETES=true`）。
31. Annotation Config 细节：categorical values 在 `create` 和 `update` 中同样用可重复 `--value label[=score]`（score 可选），或单个 `--values '<json>'` payload，二者互斥；`update` 会获取 existing config，合并传入 flags，并通过 `PUT /v1/annotation_configs/{id}` 写回完整 body，且至少需要一个字段 flag；其他类型特定 flags：`--lower-bound`/`--upper-bound`（CONTINUOUS/FREEFORM）、`--threshold`（FREEFORM）；无效输入（坏 flags、类型不匹配、格式错误值）退出 `3`（`INVALID_ARGUMENT`），在 `raw`/`json` 模式向 stderr 输出 `{error, code, hint?}` JSON envelope；`get`/`create`/`update` 输出 config object（`raw`/`json` 是单对象，不是数组）。
32. GraphQL 用于上述命令未覆盖的 ad-hoc 查询，输出为 `{"data": {...}}`；示例：`px api graphql '{ projectCount datasetCount promptCount evaluatorCount }'`；`px api graphql '{ projects { edges { node { name traceCount tokenCountTotal } } } }' | jq '.data.projects.edges[].node'`；`px api graphql '{ datasets { edges { node { name exampleCount experimentCount } } } }' | jq '.data.datasets.edges[].node'`；`px api graphql '{ evaluators { edges { node { name kind } } } }' | jq '.data.evaluators.edges[].node'`（evaluator kind 值：`"LLM"|"CODE"|"BUILTIN"`；`CODE` = 沙箱中服务端代码 evaluator；`BUILTIN` = 预构建服务端 evaluator）；用 `px api graphql '{ __type(name: "Project") { fields { name type { name } } } }' | jq '.data.__type.fields[]'` 做 introspection。
33. GraphQL 关键 root fields：`projects`、`getProjectByName(name:)`、`datasets`、`prompts`、`evaluators`、`projectCount`、`datasetCount`、`promptCount`、`evaluatorCount`、`viewer`；`getProjectByName(name:)` 定位一个项目，`projects(first: 1)` 取任意一个；没有 `traces` connection：要列 traces，查询 `spans` 并传 `filterCondition: "parent_span is None"` 保留 root spans，就像 UI 的 traces table。写 condition 前读 `references/filter-expressions.md`，其中有完整词汇、操作符和编译示例。
34. GraphQL filter 参数按语言选择：`filterCondition` 匹配单个 spans，名称来自 reference 中穷尽表；`traceFilterCondition` 匹配整个 traces，名称来自 `traceFilterVocabulary`；`sessionFilterCondition` 匹配 sessions，名称来自 `sessionFilterVocabulary`。
35. GraphQL root spans 查询：`px api graphql '{ getProjectByName(name: "default") { spans( first: 20 filterCondition: "parent_id is None and status_code == \"ERROR\"" sort: { col: startTime, dir: desc } ) { edges { node { spanId name latencyMs } } } } }' | jq '.data.getProjectByName.spans.edges[].node'`。没有 `traces` connection 和 root-span argument；`filterCondition: "parent_span is None"` 保留 root spans，包括 parent 从未收到的 orphan，并且是 UI traces table 运行的查询；`parent_id is None` 只保留没有 parent id 的 spans；一个 root span 通常每个 trace 一个，两种 clause 都可与其余 filter 组合。
36. GraphQL annotations accessor 必须选对层级，错误层级匹配不到：`annotations["name"]` 匹配 span 自身（由 `px span annotate`、`px span add-note` 写入）；`trace_annotations["name"]` 匹配 span 的 parent trace（由 `px trace annotate`、`px trace add-note` 写入）；`session_annotations["name"]` 匹配 session（仅 session filter 使用，由 `px session annotate`、`px session add-note` 写入）。示例：`px api graphql '{ getProjectByName(name: "default") { spans( first: 20 filterCondition: "parent_id is None and trace_annotations[\"quality\"].label == \"poor\"" ) { edges { node { spanId name } } } } }' | jq '.data.getProjectByName.spans.edges[].node'`。
37. GraphQL traces 过滤：`traceFilterCondition` 保留匹配 traces 的 spans，并与 `filterCondition` 组合，例如 `px api graphql '{ getProjectByName(name: "default") { spans( first: 20 filterCondition: "parent_id is None" traceFilterCondition: "error_count > 0 and latency_ms > 1000" ) { edges { node { spanId name latencyMs } } } } }' | jq '.data.getProjectByName.spans.edges[].node'`。
38. GraphQL sessions 过滤：因为 `px session list` 没有 filter flag，按形状选择 sessions 走 GraphQL，例如 `px api graphql '{ projects(first: 1) { edges { node { sessions( first: 10 sessionFilterCondition: "num_traces > 5 and any(span.status_code == \"ERROR\" for span in spans)" ) { edges { node { sessionId numTraces numTracesWithError } } } } } } }' | jq '.data.projects.edges[0].node.sessions.edges[].node'`。
39. GraphQL 发现 filter 名称并验证：`px api graphql '{ projects(first: 1) { edges { node { traceFilterVocabulary { name type category description iterableName } } } } }' | jq '.data.projects.edges[0].node.traceFilterVocabulary[] | {name, type, category}'`；`px api graphql '{ projects(first: 1) { edges { node { validateSpanFilterCondition(condition: "parent_id is None") { isValid errorMessage } validateTraceFilterCondition(condition: "error_count > 0") { isValid errorMessage } validateSessionFilterCondition(condition: "num_traces > 5") { isValid errorMessage } } } } }'`。在同时接受两种层级的字段（如 `Project.recordCount`）上，`sessionFilterCondition` 和 `filterCondition` 互斥。
40. 用 `px docs fetch` 下载 Phoenix 文档 markdown 供 coding agents 本地使用：`px docs fetch` 下载默认 workflow docs 到 `.px/docs`；`px docs fetch --workflow tracing` 只抓 tracing docs；`px docs fetch --workflow tracing --workflow evaluation`；`px docs fetch --dry-run` 预览；`px docs fetch --refresh` 清空 `.px/docs` 并重新下载；`px docs fetch --output-dir ./my-docs` 自定义输出目录；关键选项：`--workflow`（可重复，值 `tracing`、`evaluation`、`datasets`、`prompts`、`integrations`、`sdk`、`self-hosting`、`all`）、`--dry-run`、`--refresh`、`--output-dir`（默认 `.px/docs`）、`--workers`（默认 10）。

适用边界 · 注意事项

• 没有可访问的 Phoenix 实例或未配置 `PHOENIX_ENDPOINT`/profile/.env.phoenix，无法从终端操作 Phoenix 数据。
• 没有 Node.js（用于 `npx`）或未安装 `@arizeai/phoenix-cli`，无法调用该 CLI。
• 需要删除数据但无法设置 `PHOENIX_CLI_DANGEROUSLY_ENABLE_DELETES=true` 或无法交互确认时，删除命令不会执行。