项目概述

Phoenix 是由 Arize AI 开发的一个开源可观测性平台，专注于 LLM（大型语言模型）应用的评估与追踪。该项目提供了一套完整的工具集，帮助开发者监控、调试和优化 AI 应用。

核心功能

技术栈

Phoenix 采用前后端分离架构，主要由以下部分组成：

• 后端：Python（基于 FastAPI/Gradio）
• 前端：React + TypeScript
• 数据收集：OpenTelemetry
• 评估库：TypeScript/JavaScript（phoenix-evals）

快速开始

Python 环境快速配置

#### 安装依赖

使用 pip 安装 Phoenix OTEL 包：

pip install arize-phoenix-otel

资料来源：PythonProjectGuide.tsx:15

#### 环境变量配置

Phoenix 支持通过环境变量自动配置。以下是核心环境变量：

资料来源：phoenix-config/README.md:18-26

#### Python 集成代码

将以下代码添加到应用最开头位置，确保在所有代码执行前初始化追踪：

from phoenix.otel import register

# 注册追踪配置
tracer_provider = register(project_name="your-project-name")

资料来源：PythonProjectGuide.tsx:52-54

TypeScript/JavaScript 环境快速配置

#### 安装依赖

npm install @arizeai/phoenix-otel

#### 快速开始代码

import { register } from "@arizeai/phoenix-otel";

// 初始化追踪
register({ projectName: "your-project-name" });

资料来源：TypeScriptProjectGuide.tsx:14-18

使用 Phoenix Evals 进行评估

phoenix-evals 是一个独立的 TypeScript 评估库，可用于创建自定义分类器：

import { createClassifier } from "@arizeai/phoenix-evals/llm";
import { openai } from "@ai-sdk/openai";

const model = openai("gpt-4o-mini");

const classifier = createClassifier({
  model,
  promptTemplate: `
    评估任务：判断答案是否包含虚假信息。
    参考文本：{reference}
    待评估答案：{answer}
  `
});

资料来源：phoenix-evals/README.md:25-37

架构概览

系统组件架构

graph TD
    A[AI 应用] -->|OTel 追踪| B[Phoenix Collector]
    B --> C[Phoenix Server]
    C --> D[前端 UI]
    C --> E[API 接口]
    
    F[评估请求] -->|phoenix-evals| E
    G[MCP 客户端] -->|MCP 协议| E
    
    style A fill:#e1f5fe
    style C fill:#fff3e0
    style D fill:#e8f5e8

追踪数据流

sequenceDiagram
    participant App as AI 应用
    participant OTel as OpenTelemetry
    participant Phoenix as Phoenix Server
    participant UI as 前端界面
    
    App->>OTel: 发送追踪数据
    OTel->>Phoenix: 收集并转发 Span 数据
    Phoenix->>UI: 提供实时可视化
    UI->>App: 展示追踪链路

认证与 API 密钥管理

当启用认证功能时，Phoenix 提供两种 API 密钥类型：

资料来源：PythonProjectGuide.tsx:40-47

生成 API 密钥

在项目设置页面中，已认证用户可以通过"生成 API 密钥"按钮创建新的密钥：

<GenerateAPIKeyButton
  onApiKeyGenerated={setGeneratedApiKey}
  keyName="project-setup-generated"
/>

密钥生成后会自动填充到环境变量配置中。

MCP 服务器集成

Phoenix 提供 MCP（Model Context Protocol）服务器支持，可通过以下配置集成：

{
  "mcpServers": {
    "phoenix": {
      "command": "npx",
      "args": [
        "-y",
        "@arizeai/phoenix-mcp@latest",
        "--baseUrl",
        "https://my-phoenix.com",
        "--apiKey",
        "your-api-key"
      ]
    }
  }
}

资料来源：phoenix-mcp/README.md:45-57

MCP 工具覆盖范围

文档与资源

下一步

• 配置你的第一个追踪项目
• 使用 phoenix-evals 创建自定义评估器
• 通过 MCP 集成扩展工具能力
• 探索 Playground 进行提示词调试

概述

Phoenix 是一个开源的可观测性平台，主要用于 LLM 应用的可观测性和评估。该系统采用前后端分离架构，支持分布式追踪、评估和数据分析功能。架构设计围绕以下几个核心目标展开：

• 可观测性：提供完整的追踪、日志和指标采集能力
• 评估能力：支持基于 LLM 的自动化评估框架
• 多语言支持：提供 Python、TypeScript/JavaScript 客户端 SDK
• 可扩展性：支持通过 MCP (Model Context Protocol) 进行扩展

整体架构

Phoenix 系统采用分层架构设计，包含以下主要层次：

graph TD
    subgraph 客户端层
        A[Python SDK<br/>arize-phoenix-otel] 
        B[TypeScript SDK<br/>@arizeai/phoenix-otel]
        C[Phoenix Client<br/>SDK]
    end
    
    subgraph 服务层
        D[Phoenix Server<br/>HTTP/gRPC]
        E[Phoenix MCP<br/>Model Context Protocol]
    end
    
    subgraph 数据层
        F[(SQLite/PostgreSQL<br/>数据库)]
        G[(矢量数据库<br/>可选)]
    end
    
    subgraph 前端层
        H[React Web App<br/>TypeScript]
    end
    
    A --> D
    B --> D
    C --> D
    D --> F
    D --> G
    H --> D

架构组件说明

资料来源：js/packages/phoenix-config/README.md

数据模型架构

Phoenix 的数据模型定义在 src/phoenix/db/models.py 中，核心实体包括：

核心数据实体

资料来源：src/phoenix/db/models.py

数据模型关系图

erDiagram
    PROJECT ||--o{ TRACE : contains
    PROJECT ||--o{ EXPERIMENT : contains
    TRACE ||--o{ SPAN : contains
    SPAN ||--o{ ANNOTATION : has
    DATASET ||--o{ EXPERIMENT : used_in
    SPAN }o--|| DATASET : references

API 架构

Phoenix 提供两套 API 接口体系：REST API 和 GraphQL API。

REST API (OpenAPI)

REST API 基于 OpenAPI 规范定义，提供标准的 HTTP 接口：

graph LR
    A[Client] -->|HTTPS| B[FastAPI Router]
    B --> C[Service Layer]
    C --> D[(Database)]

#### 主要 API 端点

资料来源：schemas/openapi.json

GraphQL API

GraphQL API 定义在 app/schema.graphql，提供更灵活的查询能力：

type Project {
  id: ID!
  name: String!
  traces: [Trace!]!
  experiments: [Experiment!]!
}

type Trace {
  id: ID!
  projectId: ID!
  spans: [Span!]!
  startTime: DateTime!
}

type Span {
  id: ID!
  traceId: ID!
  name: String!
  attributes: JSON!
  annotations: [Annotation!]!
}

资料来源：app/schema.graphql

前端路由架构

React 前端应用的路由定义在 app/src/Routes.tsx：

graph TD
    subgraph 路由结构
        A[/] --> B[Projects]
        A --> C[/projects/:id]
        C --> D[Traces]
        C --> E[Spans]
        C --> F[Experiments]
        C --> G[Evals]
        A --> H[/datasets]
        A --> I[/prompts]
        A --> J[/settings]
    end

前端组件分布

客户端 SDK 架构

Python SDK

Python SDK (arize-phoenix-otel) 提供 OpenTelemetry 标准的集成能力：

graph LR
    A[User Application] --> B[Phoenix OTEL SDK]
    B --> C[OTEL Collector]
    C --> D[Phoenix Server]
    D --> E[(Database)]

#### 环境变量配置

资料来源：js/packages/phoenix-config/README.md

TypeScript SDK

TypeScript SDK 提供 Node.js 和浏览器环境支持：

// 核心配置接口
interface PhoenixConfig {
  host: string;          // 服务器地址
  apiKey?: string;       // 认证密钥
  headers?: Record<string, string>;  // 自定义请求头
}

资料来源：js/packages/phoenix-client/README.md

评估框架架构

Phoenix Evals 提供基于 LLM 的自动化评估能力：

graph TD
    A[评估器配置] --> B[createClassifier]
    B --> C[Prompt 模板]
    C --> D[LLM Provider]
    D --> E[评估结果]
    E --> F[Annotation]

评估器创建流程

资料来源：js/packages/phoenix-evals/README.md

MCP 扩展架构

Phoenix MCP (Model Context Protocol) 服务器提供工具化扩展能力：

graph TD
    A[MCP Client<br/>Claude Desktop] --> B[Phoenix MCP Server]
    B --> C[Phoenix Client SDK]
    C --> D[Phoenix REST API]
    D --> E[(Database)]

MCP 工具覆盖

资料来源：js/packages/phoenix-mcp/README.md

服务器初始化流程

Phoenix 服务器的初始化定义在 src/phoenix/server/__init__.py：

# 核心初始化流程
def create_app() -> FastAPI:
    # 1. 配置加载
    # 2. 数据库连接初始化
    # 3. 中间件注册
    # 4. 路由注册
    # 5. WebSocket 支持
    # 6. CORS 配置

服务器组件初始化顺序

资料来源：src/phoenix/server/__init__.py

部署架构

Phoenix 支持多种部署模式：

graph LR
    subgraph 本地开发
        A[开发机器] --> B[Docker Compose]
    end
    
    subgraph 云端部署
        C[云服务器] --> D[Container/K8s]
    end
    
    subgraph 托管服务
        E[Arize Cloud] --> F[托管 Phoenix]
    end

部署配置矩阵

安全架构

认证机制

数据隔离

• 项目级隔离：数据按 Project 隔离
• 租户隔离：支持多租户部署
• API Key 权限：系统级和个人级 API Key

技术栈汇总

扩展性设计

SDK 扩展点

1. OTEL 处理器：支持自定义 Span 处理器
2. 评估器：可扩展的 LLM 评估框架
3. 存储后端：支持多种数据库适配器
4. MCP 工具：可注册的 MCP 工具扩展

前端扩展点

资料来源：app/src/Routes.tsx

总结

Phoenix 系统采用现代化的微服务风格架构设计，通过前后端分离、SDK 多语言支持、标准化的 OpenTelemetry 集成以及灵活的 MCP 扩展机制，为 LLM 应用提供了完整的可观测性解决方案。架构设计注重开发者体验，支持从本地开发到云端托管的多种部署场景。

数据库模型与迁移

phoenix 是一个面向「软件开发与交付」的开源项目，重点覆盖 浏览器 Agent、网页任务自动化；Doramagic 已整理安装入口、说明书、上下文包和风险边界，方便先判断再试用。

概述

Phoenix 的 Tracing 系统是一个完整的可观测性解决方案，用于捕获、分析和可视化 LLM 应用和代理的运行时行为。该系统基于 OpenTelemetry 标准构建，支持多语言客户端（Python 和 TypeScript），能够追踪从简单的函数调用到复杂的多代理工作流。

Tracing 的核心作用是记录分布式系统中的请求链路，将每个操作分解为 span（跨度），并关联到对应的项目（Project）和会话（Session）中。资料来源：src/phoenix/db/README.md

核心数据模型

Trace 与 Span 层级结构

Phoenix 使用分层的数据模型来组织追踪数据：

erDiagram
    Project ||--o{ Trace : has
    Trace ||--o{ Span : contains
    Trace ||--o{ TraceAnnotation : has
    Span ||--o{ SpanAnnotation : has
    Span ||--o{ DocumentAnnotation : has

资料来源：src/phoenix/db/README.md

Span 数据结构

Span 是追踪系统的基本单元，包含以下关键信息：

• 输入/输出消息：记录函数调用的参数和返回值
• 时间戳：操作的开始和结束时间
• Token 使用量：LLM 调用的 token 消耗统计
• 延迟信息：操作的响应时间
• 元数据：Prompts、Responses 等详细信息

资料来源：js/examples/apps/langchain-quickstart/README.md

架构设计

系统组件架构

graph TD
    A[Application Code] --> B[Phoenix OTEL SDK]
    B --> C[OTLP Exporter]
    C --> D[Phoenix Server]
    D --> E[(Database)]
    
    F[Phoenix Client] --> D
    G[Phoenix Evals] --> D
    H[Phoenix UI] --> D
    
    D --> F
    D --> G
    D --> H

资料来源：packages/phoenix-otel/src/phoenix/otel/otel.py

OTEL 注册流程

Phoenix OTEL SDK 的核心是 register() 函数，用于初始化追踪：

graph LR
    A[register config] --> B[Create TracerProvider]
    B --> C[Setup OTLP Exporter]
    C --> D[Register Phoenix]
    D --> E[Return Provider]

register() 函数配置参数：

资料来源：js/packages/phoenix-otel/README.md

数据加载与查询

Span 数据加载器

Phoenix Server 提供了 SpanByID 数据加载器用于高效获取 Span 数据：

# 数据加载器接口
client.spans.get_spans_dataframe(
    project_identifier="my-llm-app",
    limit=1000,
    root_spans_only=True,  # 仅获取顶级 Span
    start_time=datetime.now() - timedelta(hours=24)
)

资料来源：packages/phoenix-client/README.md

注解数据查询

# 获取 Span 注解
annotations_df = client.spans.get_span_annotations_dataframe(
    spans_dataframe=spans_df,
    project_identifier="my-llm-app",
    include_annotation_names=["relevance", "accuracy"],
    exclude_annotation_names=["note"]
)

资料来源：packages/phoenix-client/README.md

追踪帮助函数

TypeScript 追踪工具

Phoenix OTEL 提供了多个追踪辅助函数，简化函数和链路的instrumentation：

资料来源：js/packages/phoenix-otel/README.md

Python 环境变量配置

资料来源：js/packages/phoenix-config/README.md

注解系统

注解配置

Phoenix 支持为项目配置多种类型的注解：

erDiagram
    Project ||--o{ ProjectAnnotationConfig : has
    AnnotationConfig ||--o{ ProjectAnnotationConfig : configures
    User ||--o{ SpanAnnotation : creates
    User ||--o{ DocumentAnnotation : creates
    User ||--o{ TraceAnnotation : creates

注解数据流

graph TD
    A[Evaluation Run] --> B[Fetch Spans]
    B --> C[Run LLM Evaluator]
    C --> D[Create Annotations]
    D --> E[Store in DB]
    E --> F[Display in UI]

内置评估器

Phoenix 提供了预构建的正确性评估器：

// 预构建评估器
const result = await runnableCorrectness评估(spans, {
  rubric: "travel_rubric",
  model: fireworksModel
});

资料来源：js/examples/apps/langchain-quickstart/README.md

UI 可视化

Trace 视图

Phoenix UI 提供了完整的 Trace 可视化功能：

• LangGraph 追踪：显示代理的整体执行链路
• 工具调用详情：展示 essential_info、budget_basics、local_flavor 等工具的执行
• Token 使用统计：记录每个 LLM 调用的 token 消耗
• 延迟分析：显示各操作的响应时间
• 评估注释：在 Trace 上直接展示正确性评分

资料来源：js/examples/apps/langchain-quickstart/README.md

文档注释

在 RAG 场景中，每个检索到的文档都有独立的注释区域：

<DocumentAnnotationsSection
  spanNodeId={spanNodeId}
  documentPosition={documentPosition}
  documentAnnotations={documentAnnotations}
  canAnnotate={canAnnotate}
/>

资料来源：app/src/pages/trace/DocumentItem.tsx

快速开始

TypeScript 集成

import { register, traceChain } from "@arizeai/phoenix-otel";

const provider = register({
  projectName: "my-app",
});

const answerQuestion = traceChain(
  async (question: string) => `Handled: ${question}`,
  { name: "answer-question" }
);

await answerQuestion("What is Phoenix?");
await provider.shutdown();

Python OTEL 设置

pip install arize-phoenix-otel

import os
from phoenix.otel import register

# 自动从环境变量读取配置
os.environ["PHOENIX_HOST"] = "http://localhost:6006"

register(project_name="my-project")

资料来源：app/src/components/project/PythonProjectGuide.tsx

相关文档

• Phoenix OTEL SDK
• Phoenix Client API
• Phoenix Evals
• API 参考文档

概述

Phoenix 的 Evaluation（评估）系统是一个用于评估 LLM 应用输出质量的核心模块。该系统提供了基于 LLM 的自动评估能力，支持幻觉检测、相关性评分、二分类和多分类等评估任务。

评估系统在架构上分为前后端两部分：

• 前端：React 组件负责展示评估配置、评估结果和注解标注界面
• 后端：Python API 提供评估器的注册、配置和管理功能
• 客户端库：@arizeai/phoenix-evals TypeScript 包提供独立的评估能力

资料来源：js/packages/phoenix-evals/README.md:1-30

核心架构

系统组件关系图

graph TD
    A[用户应用] --> B[Phoenix Client]
    B --> C[Traces 数据]
    C --> D[Span Annotations]
    C --> E[Trace Annotations]
    D --> F[Retrieval Metrics]
    F --> G[评估结果展示]
    E --> G
    H[评估配置] --> I[AnnotationConfigList]
    I --> J[AnnotationSummaryGroupTokens]
    G --> J

评估类型分类

评估系统支持多种评估类型，主要分为：

资料来源：app/src/pages/project/SpansTable.tsx:180-210

评估器实现

创建分类评估器

@arizeai/phoenix-evals 包提供了 createClassifier 函数，用于创建自定义评估器：

import { createClassifier } from "@arizeai/phoenix-evals/llm";
import { openai } from "@ai-sdk/openai";

const model = openai("gpt-4o-mini");

const classifier = createClassifier({
  model,
  evaluatorName: "hallucination-detector",
  promptTemplate: `
    In this task, you will be presented with a query, a reference text and an answer. 
    The answer is generated to the question based on the reference text. 
    The answer may contain false information. You must use the reference text 
    to determine if the answer to the question contains false information.
  `,
});

资料来源：js/packages/phoenix-evals/README.md:25-45

评估器工作流程

sequenceDiagram
    participant U as 用户应用
    participant C as Classifier
    participant M as LLM Model
    participant P as Phoenix Server
    
    U->>C: 传入 Input + Reference
    C->>M: 发送评估 Prompt
    M-->>C: 返回评估结果
    C-->>U: 返回分类标签
    U->>P: 上报评估结果作为 Annotation
    P-->>U: 存储并返回更新

评估注解系统

注解配置管理

评估注解通过 AnnotationConfigList 组件进行管理：

// 注解配置列表数据结构
{
  id: string,
  name: string,
  annotationType: "human" | "llm" | "api"
}

资料来源：app/src/components/trace/AnnotationConfigList.tsx:1-50

注解显示组件

评估结果通过以下组件层级展示：

资料来源：app/src/pages/project/SpansTable.tsx:150-230

检索评估指标

检索评估支持以下三个标准指标：

{row.original.documentRetrievalMetrics.map((retrievalMetric) => {
  return (
    <>
      <RetrievalEvaluationLabel
        name={retrievalMetric.evaluationName}
        metric="ndcg"
        score={retrievalMetric.ndcg}
      />
      <RetrievalEvaluationLabel
        name={retrievalMetric.evaluationName}
        metric="precision"
        score={retrievalMetric.precision}
      />
      <RetrievalEvaluationLabel
        name={retrievalMetric.evaluationName}
        metric="hit"
        score={retrievalMetric.hit}
      />
    </>
  );
})}

资料来源：app/src/pages/project/SpansTable.tsx:190-215

实验运行评估

评估追踪

评估结果与实验运行关联，支持在 ExampleExperimentRunsTable 中查看评估追踪：

// 评估追踪数据结构
{
  annotation: {
    name: string,
    label: string,
    score?: number,
    trace?: {
      projectId: string,
      traceId: string
    }
  }
}

点击评估标签可导航到对应的 trace 详情页面：

onClick={() => {
  if (annotation.trace) {
    navigate(
      `/projects/${annotation.trace.projectId}/traces/${annotation.trace.traceId}`
    );
  }
}}

资料来源：app/src/pages/example/ExampleExperimentRunsTable.tsx:1-80

工具输出评估

工具调用状态

评估系统也用于标注工具调用的输出状态：

{part.state === "output-available" ? (
  <>
    <ToolPartLabel>Output</ToolPartLabel>
    <ToolPartCodeBlock>{outputStr}</ToolPartCodeBlock>
  </>
) : null}
{part.state === "output-error" ? (
  <>
    <ToolPartLabel variant="danger">Error</ToolPartLabel>
    <ToolPartCodeBlock>{part.errorText ?? ""}</ToolPartCodeBlock>
  </>
) : null}

资料来源：app/src/components/agent/ToolPart.tsx:1-60

文档工具评估

文档搜索工具支持特殊的输出格式评估：

export function truncateDocsOutput(text: string): string {
  if (text.length <= OUTPUT_PREVIEW_LENGTH) {
    return text;
  }
  return text.slice(0, OUTPUT_PREVIEW_LENGTH) + "…";
}

资料来源：app/src/components/agent/DocsToolDetails.tsx:1-60

环境配置

Phoenix 配置变量

评估系统依赖以下环境变量进行配置：

资料来源：js/packages/phoenix-config/README.md:20-35

客户端配置

使用 Phoenix 客户端连接评估服务：

# 安装客户端
npm install @arizeai/phoenix-client

# 配置连接
PHOENIX_HOST='http://localhost:12345' 
PHOENIX_API_KEY='xxxxxx' 
pnpx tsx examples/list_datasets.ts

import { Client } from "@arizeai/phoenix-client";

const client = new Client();
// 自动从环境变量读取配置

资料来源：js/packages/phoenix-client/README.md:1-40

安装依赖

Python 环境

pip install arize-phoenix-otel
pip install arize-phoenix-client

JavaScript/TypeScript 环境

npm install @arizeai/phoenix-evals
npm install @arizeai/phoenix-client
npm install @arizeai/phoenix-config

资料来源：app/src/components/project/PythonProjectGuide.tsx:1-30

数据流总览

flowchart LR
    subgraph 应用层
        A[用户应用] --> B[Phoenix OTEL]
        A --> C[Phoenix Client]
    end
    
    subgraph 评估层
        B --> D[Traces]
        C --> E[Datasets]
        D --> F[Spans]
        F --> G[Span Annotations]
        G --> H[Retrieval Metrics]
        E --> I[Evaluations]
    end
    
    subgraph 展示层
        G --> J[AnnotationSummary]
        H --> J
        I --> K[Experiment Runs]
        K --> L[Evaluation Labels]
    end

最佳实践

评估配置建议

1. 使用 LLM 评估器：利用 createClassifier 创建领域特定的评估器
2. 配置检索指标：为 RAG 应用配置 NDCG、Precision 和 Hit 指标
3. 关联 Trace：确保评估结果与对应的 trace 正确关联
4. 设置阈值：根据业务需求设置评估分数阈值

性能优化

• 批量处理评估请求减少 API 调用
• 使用流式处理处理大型文档评估
• 缓存常用的评估 Prompt 模板

概述

Phoenix 的 Datasets 与 Experiments 模块构成了一个完整的数据管理和实验执行框架。该系统允许用户创建数据集（Dataset）来存储示例数据，并通过实验（Experiment）对数据集进行任务执行和评估。

核心功能：

• 数据集管理：创建、读取、更新、删除数据集
• 示例管理：为数据集添加输入（input）、输出（output）和元数据（metadata）
• 实验执行：基于数据集运行任务并收集结果
• 评估系统：通过评估器（Evaluator）对实验结果进行评分

资料来源：packages/phoenix-client/src/phoenix/client/resources/datasets/__init__.py:1-50

系统架构

整体架构图

graph TD
    A[Phoenix Client] --> B[REST API]
    B --> C[Dataset Service]
    C --> D[(PostgreSQL Database)]
    
    E[Experiments API] --> C
    F[Experiment Runners] --> E
    
    G[Evaluators] --> E
    
    D --> H[Traces & Spans]
    D --> I[Annotations]

数据流架构

graph LR
    A[Create Dataset] --> B[Add Examples]
    B --> C[Run Experiment]
    C --> D[Define Task]
    D --> E[Apply Evaluators]
    E --> F[Collect Results]
    F --> G[View Annotations]

资料来源：js/packages/phoenix-client/README.md:1-80

数据集（Dataset）模型

数据结构

每个 Dataset 包含以下核心字段：

示例（Example）结构

资料来源：src/phoenix/server/api/input_types/CreateDatasetInput.py:1-30

Python SDK 数据模型

from phoenix.client import Client

client = Client()

# 创建数据集示例
dataset = client.datasets.create(
    name="my-dataset",
    description="数据集描述",
    examples=[
        {
            "input": {"question": "What is the capital of France?"},
            "output": {"answer": "Paris"},
            "metadata": {"difficulty": "easy"}
        }
    ]
)

资料来源：packages/phoenix-client/README.md:40-70

数据集操作 API

创建数据集

from phoenix.client import Client

client = Client()

# 基础创建
dataset = client.datasets.create(
    name="questions",
    description="问题数据集",
    examples=[
        {
            "input": {"question": "What is the capital of France"},
            "output": {"answer": "Paris"},
            "metadata": {}
        }
    ]
)

# 获取返回的 dataset_id
dataset_id = dataset["id"]

资料来源：packages/phoenix-client/src/phoenix/client/resources/datasets/__init__.py:50-80

获取数据集

# 通过 ID 获取
dataset = client.datasets.get_dataset(
    dataset="dataset-id-string",
    version_id="optional-version-id"  # 可选，指定版本
)

# 列出所有数据集
datasets = client.datasets.list_datasets()

更新数据集

# 添加新示例
updated_dataset = client.datasets.upsert_dataset(
    dataset="dataset-id-or-name",
    examples=[
        {
            "input": {"question": "What is the capital of the USA"},
            "output": {"answer": "Washington D.C."},
            "metadata": {}
        }
    ]
)

资料来源：packages/phoenix-client/src/phoenix/client/resources/datasets/__init__.py:100-150

插入参数说明

资料来源：packages/phoenix-client/src/phoenix/client/resources/datasets/__init__.py:80-120

实验（Experiment）系统

实验工作流

graph TD
    A[创建或获取 Dataset] --> B[定义 Task 函数]
    B --> C[定义 Evaluators]
    C --> D[执行 runExperiment]
    D --> E[收集结果]
    E --> F[查看 Annotations]
    
    G[Task Function] --> H[对每个 Example 执行]
    H --> I[返回实际输出]
    
    J[Evaluators] --> K[评估输出质量]
    K --> L[生成分数/标签]

资料来源：js/packages/phoenix-client/README.md:80-150

TypeScript 实验执行示例

import { createDataset } from "@arizeai/phoenix-client/datasets";
import { asExperimentEvaluator, runExperiment } from "@arizeai/phoenix-client/experiments";

// 1. 创建数据集
const { datasetId } = await createDataset({
  name: "names-dataset",
  description: "名字数据集",
  examples: [
    {
      input: { name: "John" },
      output: { text: "Hello, John!" },
      metadata: {}
    }
  ]
});

// 2. 定义任务函数
const task = async (example) => `hello ${example.input.name}`;

// 3. 定义评估器
const evaluators = [
  asExperimentEvaluator({
    name: "matches",
    kind: "CODE",
    evaluate: async ({ output, expected }) => {
      return { correct: output === expected };
    }
  })
];

// 4. 运行实验
const results = await runExperiment({
  datasetId,
  task,
  evaluators,
  experimentName: "my-first-experiment"
});

资料来源：js/packages/phoenix-client/README.md:100-160

Python 实验执行

from phoenix.client import Client
from phoenix.experiments import run_experiment

client = Client()

# 运行实验
results = run_experiment(
    experiment_name="evaluation-run",
    dataset_name="my-dataset",
    task=my_task_function,
    evaluators=[accuracy_evaluator, relevance_evaluator]
)

# 查看结果
print(results.metrics)
print(results.traces)

评估器（Evaluator）系统

评估器类型

内置评估器

Phoenix 提供了预构建的评估器，包括：

• 准确性评估器：检查输出是否正确
• 相关性评估器：评估与输入的相关程度
• 文档相关性分类：判断文档是否回答了问题

资料来源：src/phoenix/__generated__/classification_evaluator_configs/_document_relevance_classification_evaluator_config.py:1-40

自定义评估器

from phoenix.experiments import Evaluator

my_evaluator = Evaluator(
    name="custom_eval",
    evaluate_fn=async def evaluate(example, output):
        # 自定义评估逻辑
        score = calculate_score(output)
        return {"score": score, "label": "good" if score > 0.8 else "poor"}
)

API 端点参考

REST API

获取 Span 数据

from phoenix.client import Client
from datetime import datetime, timedelta

client = Client()

# 获取 spans 作为 DataFrame
spans_df = client.spans.get_spans_dataframe(
    project_identifier="my-llm-app",
    limit=1000,
    root_spans_only=True,
    start_time=datetime.now() - timedelta(hours=24)
)

# 获取 span 标注
annotations_df = client.spans.get_span_annotations_dataframe(
    spans_dataframe=spans_df,
    project_identifier="my-llm-app",
    include_annotation_names=["relevance", "accuracy"]
)

资料来源：packages/phoenix-client/README.md:150-200

认证与授权

API Key 配置

当启用认证时，需要配置 API Key：

# 环境变量方式
import os
os.environ["PHOENIX_API_KEY"] = "your-api-key"

# 或初始化时指定
client = Client(
    api_key="your-api-key",
    endpoint="http://localhost:6006"
)

OTEL SDK 认证

# 使用 Bearer Token
OTEL_EXPORTER_OTLP_HEADERS='Authorization=Bearer your-api-key'

资料来源：app/src/components/auth/OneTimeAPIKeyDialog.tsx:50-80

最佳实践

数据集设计

1. 清晰的输入输出结构：使用一致的 JSON 结构
2. 充分的元数据：添加有助于分析的元数据
3. 版本控制：使用版本ID追踪数据集变更
4. 合理划分：使用 split_key 进行 train/test/eval 划分

实验设计

1. 单一职责任务：每个任务函数只做一件事
2. 可组合评估器：将复杂评估拆分为多个评估器
3. 结果追踪：使用 experiment_name 命名便于追踪
4. 批量处理：利用异步执行提高效率

代码生成示例

Phoenix 提供交互式代码生成功能，帮助用户快速上手：

# 在 UI 中选择数据集后自动生成的代码
import arize_phoenix as phoenix

client = phoenix.Client()

# 获取数据集
dataset = client.datasets.get_dataset(
    dataset="my-dataset-name",
    version_id="optional-version-id"
)

# 数据集现已可用于实验

资料来源：app/src/components/experiment/RunExperimentCodeDialog.tsx:1-50

总结

Phoenix 的 Datasets 与 Experiments 系统为 LLM 应用评估提供了完整的数据管理和实验执行能力。通过标准化的数据集结构、灵活的评估器系统和丰富的客户端支持，开发者可以高效地进行模型评估和迭代优化。

该系统支持：

• 多语言客户端：Python、TypeScript/JavaScript
• 丰富的评估方法：代码评估、LLM 评估、人工评估
• 完整的实验追踪：记录每次运行的结果和标注
• 灵活的部署选项：本地部署或云端服务

概述

Phoenix 的 Prompt Playground 是一个交互式环境，用于测试、调试和管理 LLM（大型语言模型）提示词。该功能允许开发者：

• 实时编辑和测试提示词
• 查看模型响应
• 管理多个提示词版本
• 与 Phoenix 的追踪和评估系统集成

核心架构

graph TD
    A[Prompt Playground UI] --> B[Phoenix Client SDK]
    B --> C[Phoenix API]
    C --> D[Prompt 管理服务]
    D --> E[OpenAI 兼容转换层]
    E --> F[后端 LLM 提供商]
    
    G[追踪系统] --> C
    H[评估系统] --> C

提示词管理 API

Phoenix 提供了 Python 和 TypeScript 两种 SDK 方式来管理提示词。

Python SDK

importarize-phoenix-client

client = Client()
prompts = client.prompts

TypeScript SDK

import { Client } from "@arizeai/phoenix-client";

const client = new Client({
  host: process.env.PHOENIX_HOST,
  apiKey: process.env.PHOENIX_API_KEY,
});

环境配置

Phoenix Client 支持以下环境变量进行配置：

与 OpenTelemetry 集成

Prompt Playground 与 Phoenix 的追踪系统紧密集成。通过配置 OpenTelemetry，可以自动记录：

• 提示词输入和输出
• Token 使用量
• 延迟信息
• 模型响应元数据

from phoenix.otel import register

register(
    project_name="prompt-playground",
    endpoint="http://localhost:6007/v1/traces"
)

快速开始

1. 安装依赖

# Python
pip install arize-phoenix-client

# TypeScript
npm install @arizeai/phoenix-client

2. 配置环境变量

export PHOENIX_HOST="http://localhost:6006"
export PHOENIX_API_KEY="your-api-key"

3. 访问 Playground

启动 Phoenix 后，在浏览器中访问：

http://localhost:6006/playground

相关资源

• 官方文档：https://arize-ai.github.io/phoenix/
• GitHub 仓库：https://github.com/Arize-ai/phoenix
• Slack 社区：https://join.slack.com/t/arize-ai/shared_invite/zt-3r07iavnk-ammtATWSlF0pSrd1DsMW7g

概述

Phoenix 前端是一个基于 React 的单页应用（SPA），采用 TypeScript 开发，使用 React Router 进行路由管理。该应用主要负责可视化 LLM 应用产生的追踪数据（Traces）、管理项目配置、以及提供评估和实验功能。前端架构遵循组件化设计原则，通过 Zustand 进行状态管理，并使用 Apollo Client 与后端 GraphQL API 通信。

架构的核心目标是提供一个直观的界面，让开发者能够深入了解其 AI 应用的运行时行为，包括追踪调用链、查看 span 详情、分析标注结果等。

环境变量配置

Phoenix 使用环境变量进行运行时配置，这些变量贯穿整个应用程序的生命周期。

核心配置变量

资料来源：js/packages/phoenix-config/README.md

配置读取机制

Phoenix 的配置模块提供了类型化的配置读取辅助函数。这些辅助函数能够：

• 自动从环境变量中读取配置值
• 提供类型安全的配置访问接口
• 支持默认值和必需配置项的验证

// TypeScript 客户端配置示例
import { register } from "@arizeai/phoenix-otel";

register({
  projectName: "my-app",
  url: "https://app.phoenix.arize.com",
  apiKey: process.env.PHOENIX_API_KEY,
});

资料来源：js/packages/phoenix-otel/README.md

Docker 部署

Phoenix 提供官方 Docker 镜像，支持单机快速部署场景。

Docker 镜像架构

graph TD
    A[phoenix Docker Image] --> B[Python Runtime]
    A --> C[Phoenix Application]
    A --> D[OpenTelemetry Collector]
    B --> C
    C --> E[SQLite/数据库]
    D --> C

端口配置

Phoenix 容器使用以下默认端口：

环境变量配置

在 Docker 环境中，可通过 -e 参数或 .env 文件传递配置：

docker run -d \
  -p 6006:6006 \
  -e PHOENIX_PORT=6006 \
  -e PHOENIX_GRPC_PORT=4317 \
  -e PHOENIX_HOST=http://localhost:6006 \
  arizephoenix/phoenix:latest

Docker Compose 部署

对于本地开发和多服务协作场景，Phoenix 支持 Docker Compose 编排部署。

服务编排架构

graph LR
    A[Phoenix Container] --> B[SQLite Volume]
    A --> C[OpenTelemetry Collector]
    D[Application] -->|Traces| C
    C -->|Export| A

docker-compose.yml 结构

典型配置文件包含以下服务定义：

• phoenix：主应用程序服务
• collector：OpenTelemetry 收集器服务
• volumes：持久化存储卷

services:
  phoenix:
    image: arizephoenix/phoenix:latest
    ports:
      - "6006:6006"
    environment:
      - PHOENIX_PORT=6006
      - PHOENIX_GRPC_PORT=4317
    volumes:
      - phoenix-data:/data

  collector:
    image: otel/opentelemetry-collector-contemporary
    ports:
      - "4317:4317"
      - "4318:4318"

Kubernetes 部署

Phoenix 提供 Helm Chart 用于 Kubernetes 集群部署，支持生产环境的高可用配置。

Helm Chart 架构

graph TD
    A[Phoenix Helm Release] --> B[Deployment]
    A --> C[Service]
    A --> D[ConfigMap]
    A --> E[Ingress]
    B --> F[Pod: phoenix-app]
    F --> G[ConfigMap: 环境变量]
    F --> H[Secret: API密钥]

Chart 配置

Chart.yaml 定义了 Chart 的基本元数据：

values.yaml 配置选项

Helm Chart 通过 values.yaml 提供灵活的部署配置：

# 镜像配置
image:
  repository: arizephoenix/phoenix
  tag: latest
  pullPolicy: IfNotPresent

# 副本配置
replicaCount: 1

# 服务配置
service:
  type: ClusterIP
  port: 6006
  grpcPort: 4317

# 环境变量配置
env:
  PHOENIX_HOST: ""
  PHOENIX_PORT: "6006"
  PHOENIX_GRPC_PORT: "4317"
  PHOENIX_PROJECT: "default"

# 资源限制
resources:
  limits:
    cpu: 1000m
    memory: 2Gi
  requests:
    cpu: 100m
    memory: 512Mi

# Ingress 配置
ingress:
  enabled: false
  className: ""
  annotations: {}
  hosts:
    - host: phoenix.local
      paths:
        - path: /
          pathType: Prefix

部署命令

# 添加 Helm 仓库
helm repo add arize https://arize-ai.github.io/phoenix

# 安装 Phoenix
helm install phoenix arize/phoenix

# 自定义配置部署
helm install phoenix arize/phoenix -f custom-values.yaml

# 查看部署状态
helm status phoenix

# 升级版本
helm upgrade phoenix arize/phoenix --set image.tag=v2.0.0

Python SDK 配置

Python 应用程序通过 arize-phoenix-otel 包与 Phoenix 集成。

自动环境变量读取

arize-phoenix-otel 包会自动从环境变量中读取配置，无需显式编码：

import os

# 设置环境变量
os.environ["PHOENIX_HOST"] = "http://localhost:6006"
os.environ["PHOENIX_API_KEY"] = "your-api-key"
os.environ["PHOENIX_PROJECT"] = "my-project"

OTEL 初始化代码

from phoenix.otel import register

# 注册 Phoenix 作为 OTEL provider
provider = register(project_name="my-app")

# 你的应用代码...

# 关闭时清理资源
await provider.shutdown()

资料来源：app/src/components/project/PythonProjectGuide.tsx

认证与安全配置

API Key 配置

当启用认证时，Phoenix 需要 API Key 进行身份验证：

// TypeScript 客户端认证配置
const client = new PhoenixClient({
  host: process.env.PHOENIX_HOST,
  apiKey: process.env.PHOENIX_API_KEY,
  headers: {
    "X-Custom-Header": "value"
  }
});

自定义请求头配置

通过 PHOENIX_CLIENT_HEADERS 环境变量设置自定义请求头：

# JSON 格式编码的自定义头
PHOENIX_CLIENT_HEADERS='{"X-Org-Id": "12345", "X-Team": "ml-team"}'

资料来源：js/packages/phoenix-client/README.md

MCP 服务器配置

Phoenix MCP (Model Context Protocol) 服务器支持独立的开发部署。

开发环境配置

创建 .env 文件配置 MCP 服务器：

PHOENIX_API_KEY=your-api-key
PHOENIX_HOST=https://my-phoenix.com
PHOENIX_PROJECT=default-project
PHOENIX_CLIENT_HEADERS={}

MCP 服务器启动

{
  "mcpServers": {
    "phoenix": {
      "command": "npx",
      "args": [
        "-y",
        "@arizeai/phoenix-mcp@latest",
        "--baseUrl",
        "https://my-phoenix.com",
        "--apiKey",
        "your-api-key"
      ]
    }
  }
}

资料来源：js/packages/phoenix-mcp/README.md

部署架构总览

graph TB
    subgraph "客户端层"
        A[Python App<br/>arize-phoenix-otel]
        B[TypeScript App<br/>@arizeai/phoenix-otel]
        C[CLI Agent<br/>phoenix-cli]
    end

    subgraph "网络层"
        D[Ingress Controller]
        E[Load Balancer]
    end

    subgraph "Kubernetes 集群"
        F[Phoenix Pod]
        G[OTEL Collector Pod]
        H[PostgreSQL/MySQL]
    end

    A -->|OTLP Protocol| G
    B -->|OTLP Protocol| G
    C -->|REST API| F
    G -->|Export| F
    D --> F
    E --> D
    F --> H

常见部署场景

本地开发环境

# 使用 Docker Compose 快速启动
docker-compose up -d

# 或使用 pnpm 开发模式
cd js
pnpm install
pnpm dev

生产环境部署

# 1. 创建 Kubernetes 命名空间
kubectl create namespace phoenix

# 2. 创建 Secret 存储 API Key
kubectl create secret generic phoenix-secrets \
  --from-literal=PHOENIX_API_KEY=your-key \
  --namespace phoenix

# 3. 安装 Helm Chart
helm install phoenix arize/phoenix \
  --namespace phoenix \
  --set ingress.enabled=true \
  --set ingress.hostname=phoenix.example.com \
  --set replicaCount=3

云端托管部署

对于云端托管的 Phoenix Cloud，使用生产配置：

import { register } from "@arizeai/phoenix-otel";

register({
  projectName: "production-app",
  url: "https://app.phoenix.arize.com",
  apiKey: process.env.PHOENIX_API_KEY,
});

配置优先级

Phoenix 配置按以下优先级生效（从高到低）：

1. 代码级别配置：直接在代码中传递的参数
2. 环境变量：运行时环境变量
3. 配置文件：values.yaml 或 config.py 中的默认值
4. 编译时默认值：镜像内置的默认值

故障排查

常见配置问题

诊断命令

# 查看 Phoenix 日志
kubectl logs -n phoenix deployment/phoenix

# 检查服务健康状态
curl http://phoenix-service:6006/health

# 验证环境变量
kubectl exec -n phoenix deployment/phoenix -- env | grep PHOENIX

概述

Phoenix Python SDK 主要包含两个核心包：

SDK 支持以下主要功能：

• 追踪管理：查询和分析分布式追踪数据
• 跨度操作：检索和过滤跨度（Span）信息
• 数据集管理：创建、追加和版本化管理数据集
• 实验跟踪：运行评估实验并追踪结果
• 评估注释：添加人工反馈和自动化评估

资料来源：packages/phoenix-client/README.md

安装

使用 pip 安装 Phoenix Python 客户端：

pip install arize-phoenix-client

对于需要 OpenTelemetry 集成的场景：

pip install arize-phoenix-otel

资料来源：packages/phoenix-client/README.md

核心架构

架构图

graph TD
    A[应用程序] --> B[OpenTelemetry SDK]
    A --> C[Phoenix Client]
    B --> D[OTLP Exporter]
    D --> E[Phoenix Collector]
    C --> E
    E --> F[(Phoenix Database)]
    
    G[追踪数据] --> H[Spans API]
    G --> I[Traces API]
    C --> H
    C --> I

组件层次

环境变量配置

Phoenix SDK 支持通过环境变量自动配置：

云端配置示例

# 本地 Phoenix 服务器
export PHOENIX_BASE_URL="http://localhost:6006"

# Phoenix 云端实例
export PHOENIX_API_KEY="your-api-key"
export PHOENIX_BASE_URL="https://app.phoenix.arize.com/s/your-space"

# 自定义请求头
export PHOENIX_CLIENT_HEADERS="Authorization=Bearer your-api-key,custom-header=value"

资料来源：js/packages/phoenix-config/README.md

客户端初始化

同步客户端

from phoenix.client import Client

# 自动从环境变量读取配置
client = Client()

# 显式指定配置
client = Client(base_url="http://localhost:6006")

# 云端实例带 API 密钥
client = Client(
    base_url="https://app.phoenix.arize.com/s/your-space",
    api_key="your-api-key"
)

# 自定义认证头
client = Client(
    base_url="https://your-phoenix-instance.com",
    headers={"Authorization": "Bearer your-api-key"}
)

异步客户端

from phoenix.client import AsyncClient

# 异步客户端（支持相同配置选项）
async_client = AsyncClient()
async_client = AsyncClient(base_url="http://localhost:6006")
async_client = AsyncClient(
    base_url="https://app.phoenix.arize.com/s/your-space",
    api_key="your-api-key"
)

资料来源：packages/phoenix-client/README.md

Spans API

Spans API 提供对追踪中跨度的查询和分析能力。

主要功能

• 查询跨度数据并支持强大的过滤条件
• 提取跨度属性用于 RAG 评估工作流
• 获取特定项目的跨度列表

使用示例

from phoenix.client import Client

client = Client()

# 获取项目中的跨度列表
spans = client.spans.list_spans(project_name="my-project")

# 过滤特定类型的跨度
llm_spans = client.spans.list_spans(
    project_name="my-project",
    span_type="llm"
)

# 获取跨度详情
span = client.spans.get_span(span_id="span-123")

资料来源：packages/phoenix-client/src/phoenix/client/resources/spans/__init__.py

Traces API

Traces API 用于追踪级别的操作和查询。

主要功能

• 列出项目中的追踪
• 获取追踪详情
• 过滤和搜索追踪数据

使用示例

from phoenix.client import Client

client = Client()

# 获取追踪列表
traces = client.traces.list_traces(project_name="my-project")

# 按时间范围过滤
recent_traces = client.traces.list_traces(
    project_name="my-project",
    start_time="2024-01-01T00:00:00Z",
    end_time="2024-01-31T23:59:59Z"
)

资料来源：packages/phoenix-client/src/phoenix/client/resources/traces/__init__.py

Datasets API

功能概述

• 从 DataFrame、CSV 文件或字典创建数据集
• 追加数据到现有数据集
• 版本化管理数据集

使用示例

from phoenix.client import Client
import pandas as pd

client = Client()

# 从 DataFrame 创建数据集
df = pd.DataFrame({
    "input": ["What is Phoenix?", "How to install?"],
    "output": ["Phoenix is...", "Run pip install..."]
})
dataset = client.datasets.create_dataset(
    name="my-dataset",
    dataframe=df
)

# 获取数据集
dataset = client.datasets.get_dataset(
    dataset="my-dataset",
    version_id="v1.0.0"  # 可选，指定版本
)

# 追加数据
client.datasets.append_to_dataset(
    dataset_name="my-dataset",
    dataframe=new_df
)

资料来源：packages/phoenix-client/README.md

OpenTelemetry 集成

快速开始

import { register } from "@arizeai/phoenix-otel";

register({
  projectName: "my-app",
  url: "https://app.phoenix.arize.com",
  apiKey: process.env.PHOENIX_API_KEY,
});

配置选项

Python 端环境变量配置

# 本地 Phoenix 服务器
export PHOENIX_COLLECTOR_ENDPOINT="http://localhost:6006"

# Phoenix 云端
export PHOENIX_COLLECTOR_ENDPOINT="https://app.phoenix.arize.com"
export PHOENIX_API_KEY="your-api-key"

资料来源：js/packages/phoenix-otel/README.md

认证机制

API Key 认证

Phoenix 支持多种认证方式：

from phoenix.client import Client

# 方式一：环境变量
# 设置 PHOENIX_API_KEY 环境变量
client = Client()

# 方式二：客户端初始化时传入
client = Client(
    base_url="https://app.phoenix.arize.com/s/your-space",
    api_key="your-api-key"
)

OpenTelemetry SDK 认证

当使用 OpenTelemetry SDK 时，通过环境变量配置认证：

# 方式一：环境变量
export PHOENIX_API_KEY="your-api-key"

# 方式二：OTEL 头信息
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-api-key"

REST/GraphQL API 认证

# Bearer Token 认证
Authorization: Bearer your-api-key

资料来源：app/src/components/auth/OneTimeAPIKeyDialog.tsx

数据流架构

sequenceDiagram
    participant App as 应用程序
    participant OTel as OpenTelemetry SDK
    participant Exporter as OTLP Exporter
    participant Phoenix as Phoenix Server
    participant Client as Phoenix Client
    
    App->>OTel: 业务逻辑执行
    OTel->>OTel: 自动instrumentation
    OTel->>Exporter: 发送Span数据
    Exporter->>Phoenix: HTTP/gRPC传输
    Phoenix->>Phoenix: 存储到数据库
    
    App->>Client: API请求
    Client->>Phoenix: REST API调用
    Phoenix->>Client: 返回数据
    Client->>App: 查询结果

最佳实践

1. 客户端管理

# 推荐：使用上下文管理器
from phoenix.client import Client

with Client() as client:
    spans = client.spans.list_spans(project_name="my-project")
    # 自动处理连接关闭

# 不推荐：手动管理生命周期
client = Client()
# ... 使用 client
# client.close()  # 容易遗漏

2. 环境配置

import os

# 显式环境变量设置优于硬编码
base_url = os.getenv("PHOENIX_BASE_URL", "http://localhost:6006")
api_key = os.getenv("PHOENIX_API_KEY")

client = Client(
    base_url=base_url,
    api_key=api_key
)

3. 错误处理

from phoenix.client import Client
from phoenix.exceptions import PhoenixError

try:
    client = Client()
    dataset = client.datasets.get_dataset(dataset="my-dataset")
except PhoenixError as e:
    print(f"获取数据集失败: {e}")

4. 性能优化

• 生产环境启用批量处理（默认 batch=true）
• 使用异步客户端处理大量请求
• 合理设置过滤条件减少数据传输

类型定义

SDK 提供完整的类型提示支持：

from phoenix.client import Client
from phoenix.client.resources.spans import SpanModel

client = Client()

# 类型安全的响应
spans: list[SpanModel] = client.spans.list_spans(project_name="my-project")

for span in spans:
    print(span.span_id, span.name, span.attributes)

相关资源

• 完整 API 文档：访问 Phoenix 官方文档
• 示例代码：查看 examples/ 目录下的 Jupyter Notebook
• 集成指南：参考 Integrations 了解各框架集成

Pitfall Log / 踩坑日志

项目：Arize-ai/phoenix

摘要：发现 17 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。

1. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:564072810 | https://github.com/Arize-ai/phoenix | README/documentation is current enough for a first validation pass.

2. 运行坑 · 来源证据：arize-phoenix: v15.3.0

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：arize-phoenix: v15.3.0
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_d364a0a28a14428baff5ca692cb00578 | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.3.0 | 来源类型 github_release 暴露的待验证使用条件。

3. 运行坑 · 来源证据：arize-phoenix: v15.5.0

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：arize-phoenix: v15.5.0
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_ad2696a72e314b52b79d157bf261f7bd | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.5.0 | 来源类型 github_release 暴露的待验证使用条件。

4. 运行坑 · 来源证据：arize-phoenix: v15.5.1

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：arize-phoenix: v15.5.1
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_b75368026b414d1bbe31d7d3e90b2731 | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.5.1 | 来源类型 github_release 暴露的待验证使用条件。

5. 运行坑 · 来源证据：arize-phoenix: v15.6.0

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：arize-phoenix: v15.6.0
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_49d41c4c92f24db2b382ebd014f9bd14 | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.6.0 | 来源类型 github_release 暴露的待验证使用条件。

6. 运行坑 · 来源证据：arize-phoenix: v15.7.0

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：arize-phoenix: v15.7.0
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_826b7f8e0d2342cabfedab3cabb1a2dc | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.7.0 | 来源类型 github_release 暴露的待验证使用条件。

7. 运行坑 · 来源证据：arize-phoenix: v15.9.0

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：arize-phoenix: v15.9.0
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_0d47708aa40b4b99b3f132751181cf43 | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.9.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

8. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:564072810 | https://github.com/Arize-ai/phoenix | last_activity_observed missing

9. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:564072810 | https://github.com/Arize-ai/phoenix | no_demo; severity=medium

10. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:564072810 | https://github.com/Arize-ai/phoenix | no_demo; severity=medium

11. 安全/权限坑 · 来源证据：GenerativeModelStore: _last_fetch_id can regress and defeat incremental fetch

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：GenerativeModelStore: _last_fetch_id can regress and defeat incremental fetch
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_547816d87273465a88a09397fc2c4ab1 | https://github.com/Arize-ai/phoenix/issues/13241 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

12. 安全/权限坑 · 来源证据：[security] setup deepsec

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[security] setup deepsec
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_153e6ddc8487493e893542da4c348bbe | https://github.com/Arize-ai/phoenix/issues/13275 | 来源类型 github_issue 暴露的待验证使用条件。

13. 安全/权限坑 · 来源证据：arize-phoenix: v15.10.0

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：arize-phoenix: v15.10.0
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_1ce89c62b10a43288f4c6394276bc97c | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.10.0 | 来源类型 github_release 暴露的待验证使用条件。

14. 安全/权限坑 · 来源证据：arize-phoenix: v15.4.0

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：arize-phoenix: v15.4.0
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_fea401ed7b774dc7885c245774e87cce | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.4.0 | 来源类型 github_release 暴露的待验证使用条件。

15. 安全/权限坑 · 来源证据：arize-phoenix: v15.8.0

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：arize-phoenix: v15.8.0
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_2ecb08e3e7e04b60ac87fab18439546d | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.8.0 | 来源类型 github_release 暴露的待验证使用条件。

16. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:564072810 | https://github.com/Arize-ai/phoenix | issue_or_pr_quality=unknown

17. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:564072810 | https://github.com/Arize-ai/phoenix | release_recency=unknown