Phoenix 核心功能与实现流程

4.1 Tracing（OTLP 链路追踪摄入）#

① 功能作用

记录请求在 LLM 应用内部的传播路径（检索 → 工具调用 → 生成），形成一棵可追溯的 Trace 树。这是 Phoenix 最基础的能力，其他所有功能都建立在 Trace 数据之上。

② 核心执行流程

1. 用户应用调用 phoenix.otel.register() 创建 TracerProvider，并用 openinference-instrumentation-* 自动探针化 OpenAI / LangChain 等 SDK，或手动用 decorator 创建 Span。
2. 应用执行 LLM 调用时，OpenTelemetry SDK 生成 Span，并写入 OpenInference 语义属性（span kind、token 计数、prompt 模板、检索文档与分数）。
3. SpanProcessor（推荐 BatchSpanProcessor）把 Span 攒成批次，经 OTLP 导出——gRPC 到 4317，或 HTTP 到 6006。
4. 服务端解析 OTLP payload，把 Span 归一化成内部结构并入队 BulkInserter。
5. BulkInserter 异步批量写入数据库（SQLAlchemy ORM，SQLite / PostgreSQL 皆可），事务边界按批而不是按条。
6. React 前端通过 GraphQL 查出某个项目下的 Trace 树，渲染时间线、属性、异常与 token 统计。

③ 执行流程

1
sequenceDiagram
2
    participant App as 用户应用（OTel SDK）
3
    participant Col as Phoenix OTLP 接入层
4
    participant BI as BulkInserter 队列
5
    participant DB as 数据库
6
    participant UI as React UI（GraphQL）
7

8
    App->>App: 执行 LLM 调用，生成 Span
9
    Note over App: Span 携带 OpenInference 语义属性
10
    App->>Col: BatchSpanProcessor 导出 OTLP batch（4317 / 6006）
11
    Col->>Col: 解析 payload，归一化 Span 结构
12
    Col->>BI: 入队
13
    BI->>DB: 批量 INSERT Span / Trace
14
    UI->>DB: GraphQL 查询 Trace 树
15
    DB-->>UI: Span 列表 + 属性

④ 核心实现原理

• OTLP 双通道摄入：gRPC（4317）与 HTTP（6006）共用同一套解析与落库逻辑，只在前端接入层分叉。前者适合生产（长连接、二进制编码、压缩率更高），后者适合本地与受限网络（防火墙放行一个 HTTP 端口即可）。
• OpenInference 语义约定：Span 的属性不是随手写的日志字段，而是一套约定——span kind 区分 LLM / Tool / Retriever / Chain，llm.token_count、llm.prompts、retrieval.documents 等属性让摄入端可以结构化解析。这正是”能按模型聚合 token 成本""能展开某条检索的文档与分数”的前提：存的是结构化字段，不是原始文本。
• 异步批量写入：BulkInserter 用队列把”接收”和”落库”解耦。摄入延迟敏感、落库吞吐导向，两者用队列隔开后，写入峰值被吸收成批量事务，单条 Span 写失败也不会阻塞接收链路。

⑤ 实际例子

一个 LangChain RAG 应用收到提问”这份合同里违约金怎么算”：探针自动创建 Retriever Span（记录召回的 4 段文档与各自相似度分数）和 LLM Span（记录完整 prompt、temperature、输入输出 token 数），外层再挂一个 Chain Span 表示整次请求。导出后 Phoenix 入库，前端展示成一棵三层调用树。点开 LLM Span，你能看到实际发给模型的 prompt 里拼进了哪几段文档——答案错了，问题出在检索还是生成，一眼就能分辨。

4.2 Evaluation（LLM-as-judge 评估）#

① 功能作用

用 LLM 或程序化 evaluator 给 Span / Trace 打分（相关性、faithfulness、幻觉、毒性），结果作为 Annotation 附回 Trace。它回答的是”这条回答到底好不好”，把主观判断变成可筛选、可聚合的数值。

② 核心执行流程

1. 通过 arize-phoenix-evals 选择内置或自定义 evaluator（模板 prompt + LLM provider adapter）。
2. 从 Phoenix 拉取一批 Span（REST 接口或 DataFrame 导出）。
3. input_mapping 把嵌套的 Span 数据绑定到 evaluator 期望的字段（比如把召回文档映射成 context）。
4. 并发调用 judge LLM 批量评分，返回 label / score / explanation。
5. 评估结果作为 Span Annotation 写回 Phoenix，在 UI 与指标里呈现。

③ 执行流程

1
flowchart TB
2
    Spans["Phoenix 中的 Span"] -->|"导出"| Eval["phoenix-evals 评估器"]
3
    Map["input_mapping 字段绑定"] --> Eval
4
    Eval -->|"并发调用"| Judge["Judge LLM"]
5
    Judge -->|"原始输出"| Score["评估结果<br/>label / score / explanation"]
6
    Score -->|"作为 Annotation 写回"| Server["Phoenix Server"]
7
    Server --> UI["UI 与指标展示"]

④ 核心实现原理

核心是 Annotation 数据模型：评估结果不与 Trace 混存，而是作为独立实体标注在 Span / Trace / Session 上。同一条 Span 可以同时挂人审结论、LLM 评分、用户点赞，互不覆盖，也能按来源区分。另一个机制是 adapter 层：evaluator 只描述”评什么、怎么评”，provider 差异（OpenAI / Anthropic / 本地模型）与并发批处理由 adapter 屏蔽，换 judge 模型不用改写评估逻辑。

⑤ 实际例子

对客服 RAG 应用当天 500 条 Trace 跑 hallucination evaluator：每条响应连同召回文档一起送进 judge prompt，产出 faithful / hallucinated 标签写回 Phoenix。然后在 UI 里按标签过滤，把被判为幻觉的 case 逐条排查——其中不少是检索召回了过期的旧版条款，问题不在模型，而在检索库。

4.3 Datasets & Experiments#

① 功能作用

把样例（input / 期望输出）存成版本化 Dataset，在其上运行 Experiment（换 Prompt、换模型、换代码），对比输出与评估分数。它解决的是”改完之后有没有变好、有没有回归”。

② 核心执行流程

1. 用 phoenix-client 从 DataFrame / CSV / 线上 Trace 创建 Dataset，每个 example 含 input、reference output、metadata。
2. Dataset 的修改产生新版本，实现内容版本控制。
3. 定义 task 函数（你的应用逻辑）与 evaluators，启动 Experiment。
4. 框架对每个 example 并发执行 task，执行过程自动打 Trace 到 Phoenix。
5. 结果、评估分数、Trace 关联存入 Experiment 记录，UI 并排对比多次实验。

③ 执行流程

1
sequenceDiagram
2
    participant Dev as 开发者
3
    participant Task as task 函数
4
    participant API as REST API
5
    participant DB as 数据库
6

7
    Dev->>API: 上传 Dataset（examples）
8
    API->>DB: 保存 Dataset 版本
9
    Dev->>Task: 启动 Experiment（dataset、task、evaluators）
10
    loop 每个 example 并发执行
11
        Task->>Task: 执行应用逻辑（自动打 Trace）
12
        Task->>API: Trace 上报
13
        Task-->>Dev: 返回 output
14
    end
15
    Dev->>API: 提交结果与评估分数
16
    API->>DB: 保存 Experiment Run + Annotation

④ 核心实现原理

两个机制值得记住：Dataset 版本化让实验可复现——Experiment 绑定的是某个确定的 Dataset 版本，而不是”当时那份数据”，否则一周后回看实验结论就站不住脚。**实验自追踪（tracing the experiment itself）**则让 Experiment 跑在自家 OTel 管线上：每条 example 的执行本身就是一条 Trace，某条输出错了，可以直接点进去看那次执行内部的检索与 prompt。

⑤ 实际例子

把线上 50 条 bad case 导出成 Dataset，改完 Prompt 跑 v2 实验：50 条并发执行，每条都产生一条 Trace，judge 打分随结果一起入库。UI 并排对比 v1 / v2，看到 v2 修好了 38 条且没有新增回归；剩下 12 条点进 Trace，发现都是检索没召回到对应条款——说明下一轮该调的是切分策略，而不是继续改 Prompt。

4.4 Metrics Dashboard#

① 功能作用

对摄入的 Trace 自动聚合指标：延迟分位、token 用量、成本估算、错误率。不需要手工定义指标或写查询，打开就有。

② 核心执行流程

Span 摄入时携带 token 计数、模型名、延迟、错误状态等 OpenInference 属性 → 规范化入库 → 查询时对项目内 Trace 做聚合 → GraphQL 返回时间序列与分布 → React 仪表盘渲染预置面板（trace 量、延迟分位、USD 成本、按模型的 token 排行、Annotation 均分等）。

③ 执行流程

1
flowchart LR
2
    Span["Span 摄入<br/>token / model / latency / error"] --> Store[("Span 表")]
3
    Store -->|"查询侧按项目聚合"| GQL["GraphQL 聚合查询"]
4
    GQL --> Dash["仪表盘预置面板"]

④ 核心实现原理

指标不在摄入时预聚合，而是查询侧实时聚合。好处是不用维护物化视图或流式计算任务，新增一个维度只是改查询；代价是要求写入时的属性必须规范——token 计数、模型名、错误标记必须是结构化字段且口径统一，否则聚合会算错或算空。这也是 OpenInference 语义约定在数据链路上真正兑现价值的地方。

⑤ 实际例子

某个周一仪表盘显示 p95 延迟从 1.8s 涨到 4.2s，同时某模型的 token 成本翻倍。按模型过滤 Span 后发现：新上的 Prompt 把 few-shot 示例从 2 个加到 6 个，输出没变长、输入长了一倍——延迟和成本其实是同一个原因。

4.5 PXI / Remote MCP（AI Agent 集成）#

① 功能作用

PXI 是内置在 Phoenix 里的 AI 工程 Agent，用工具调用调查 Trace、迭代 Prompt、操作页面；/mcp 端点则让 Claude Code、Cursor 等 MCP 客户端直接查询 Phoenix 里的 Trace、Dataset 与 Experiment。

② 核心执行流程

1. 用户在浏览器 Chat UI 提问（比如”这条调用为什么失败”）。
2. 服务端 Agent 组装 system prompt、skills 与当前页面可用的工具集，调用用户自己配置的 LLM（用户自带 API Key）。
3. LLM 返回 tool call：查数据类走服务端沙箱 bash，通过 phoenix-gql 执行 GraphQL 查询；页面操作类则下发到浏览器执行。
4. 工具结果回填给 LLM，循环直到得出结论，最终流式返回 UI。

③ 执行流程

1
flowchart LR
2
    User(("用户")) <--> ChatUI["浏览器 Chat UI"]
3
    ChatUI <--> Agent["PXI Agent（服务端）"]
4
    Agent -->|"LLM 调用"| LLM["LLM Provider<br/>用户自带 API Key"]
5
    LLM -->|"tool call"| Agent
6
    Agent --> Bash["沙箱 bash<br/>phoenix-gql"]
7
    Bash --> GQL["GraphQL API"]
8
    Agent -->|"页面操作指令"| ChatUI

④ 核心实现原理

能力按上下文门控：Agent 只暴露当前页面真正可执行的工具——在 Trace 详情页它能查这条 Trace，在 Dataset 页它才拿到 Dataset 相关工具。权限复用：服务端沙箱 bash 里的 phoenix-gql 用的是与登录用户相同的权限面，不为 Agent 单开一条高权限通道，沙箱本身也没有对外网络出口。两条合起来，既避免 Agent”什么都能干”带来的安全面扩张，也让模型不必在几十个工具里做选择。

⑤ 实际例子

在一条失败的 Trace 页面问 PXI”为什么这条调用失败”：Agent 加载 trace-debugging skill，用 GraphQL 查出该 Trace 的 Span 树，发现 LLM Span 状态是 error、异常信息是限流（429），且重试在 3 次后放弃。回答按可能性排序给出根因假设与下一步动作，而不是把原始 Span 一股脑倒给你。