Phoenix：开源LLM追踪与评估可观测性平台安装与使用指南

一、项目背景

大语言模型应用上线之后，开发者最先遇到的问题不是"模型能不能跑"，而是"线上到底发生了什么"。一次请求背后可能串联着 RAG 检索、向量库召回、Prompt 拼装、多轮工具调用、二次重排等多个环节，任何一环出问题都会导致最终输出漂移。传统 APM 工具只看 HTTP 状态码和延迟，根本看不到 Prompt 内容、Token 消耗、检索到的切片、模型打分这些 LLM 特有信号。

Arize Phoenix 由 Arize AI 公司开源，正是为了解决 LLM 应用的可观测性盲区而生。它是一个开源的 LLM 追踪与评估平台，能够无缝接入 LangChain、LlamaIndex、OpenAI、Anthropic、Bedrock、Vertex 等主流框架与模型，把每一次 LLM 调用的完整树形结构——包括嵌套的子调用、工具调用、检索上下文——以 Trace 的形式记录下来，并在 Web UI 中可视化展示延迟、Token 消耗、错误率、成本等指标。

Phoenix 既可以作为 Notebook 里的本地实验工具，也可以通过 Docker、Kubernetes 部署成团队共享的自托管服务，后端可切换 PostgreSQL 实现 Trace 持久化。它同时内置了 LLM-as-a-Judge 评估器、Embedding 可视化、数据集管理等能力，是目前开源生态中最接近 LangSmith 体验的自托管替代方案。

二、核心特性

• OpenTelemetry 原生追踪：基于 OTel 标准，自动捕获 LLM/Embedding/工具调用 Span，支持嵌套树形 Trace。
• 多框架自动插桩：一行代码接入 LangChain、LlamaIndex、OpenAI SDK、Anthropic SDK、Bedrock、Vertex AI、DSPy 等。
• 在线评估（Evals）：内置 Hallucination、Qamp (Q&A Correctness)、Context Relevancy、Tone、Retrieval Relevancy 等评估器，支持自定义 LLM-as-a-Judge。
• Embedding 可视化：对向量库召回结果做 UMAP/TSNE 降维，在二维平面上观察聚类、离群点与错误检索。
• 数据集与实验对比：把 Trace 沉淀为 Dataset，运行离线评估并对比不同 Prompt/模型版本的指标差异。
• 自托管友好：支持 Docker Compose、Kubernetes、Helm Chart，可接 PostgreSQL 持久化，支持 SSO/OIDC。
• 跨语言客户端：提供 Python、TypeScript、Ruby 等 SDK，也支持原生 OTLP/gRPC 上报。
• 开源免费：核心追踪与评估能力完全开源，无需付费即可在生产环境自托管。

三、环境要求

• 操作系统：Linux / macOS / Windows（WSL2 推荐）。
• Docker：Docker 20.10+ 与 Docker Compose v2（推荐方式）。
• Python：客户端 SDK 需要 Python 3.9+，推荐 3.10 / 3.11。
• 内存：最小 2 GB 可用内存，生产推荐 4 GB+。
• 磁盘：Trace 数据每日约数百 MB 至数 GB，建议预留 20 GB 以上。
• 端口：Web UI 默认 6006，OTLP/gRPC 默认 4317，OTLP/HTTP 默认 6006。
• 网络：如果使用云端 LLM API（OpenAI/Anthropic），需要能访问对应接口。

四、详细部署步骤

方式一：Docker 快速启动（推荐体验）

这是最快上手的方式，适合本地开发与小规模验证：

# 拉取最新镜像
docker pull arizephoenix/phoenix:latest

# 启动 Phoenix，暴露 Web UI (6006) 与 OTLP/gRPC (4317)
docker run -d \
  --name phoenix \
  --restart unless-stopped \
  -p 6006:6006 \
  -p 4317:4317 \
  -i -t arizephoenix/phoenix:latest

# 查看日志确认启动成功
docker logs -f phoenix

启动后浏览器访问 http://localhost:6006 即可看到 Phoenix 控制台。首次打开无需登录，本地模式默认匿名访问。

注意：生产环境请不要使用 latest 浮动标签，应固定到具体版本，例如 arizephoenix/phoenix:4.18.0，避免意外升级。

方式二：Docker Compose + PostgreSQL 持久化（生产推荐）

默认容器内 SQLite 仅适合单机临时验证，重启后 Trace 不丢失但容器删除即清空。生产环境建议使用 PostgreSQL：

mkdir -p ~/phoenix && cd ~/phoenix
cat > docker-compose.yml <<'EOF'
services:
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: phoenix
      POSTGRES_PASSWORD: phoenix_pwd_change_me
      POSTGRES_DB: phoenix
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U phoenix"]
      interval: 5s
      timeout: 5s
      retries: 10

  phoenix:
    image: arizephoenix/phoenix:latest
    depends_on:
      db:
        condition: service_healthy
    ports:
      - "6006:6006"
      - "4317:4317"
    environment:
      PHOENIX_SQL_DATABASE_URL: postgresql+psycopg://phoenix:phoenix_pwd_change_me@db:5432/phoenix
      PHOENIX_ENABLE_AUTH: "true"
      PHOENIX_SECRET: "change-this-to-a-long-random-string-at-least-32-chars"
    restart: unless-stopped

volumes:
  pgdata:
EOF

docker compose up -d

开启 PHOENIX_ENABLE_AUTH=true 后首次访问会引导创建管理员账号，请务必设置强密码，并把 PHOENIX_SECRET 替换为至少 32 位随机字符串（可用 openssl rand -hex 32 生成）。

方式三：pip 本地运行（适合 Notebook 实验）

# 创建虚拟环境
python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

# 安装 phoenix 客户端与服务器
pip install -U 'arize-phoenix[evals]' nest_asyncio

# 命令行启动
phoenix serve

启动后同样访问 http://localhost:6006。在 Jupyter Notebook 中还可以直接内嵌启动：

import phoenix as px
session = px.launch_app()
print("Phoenix UI:", session.url)   # 输出如 http://localhost:6006

方式四：Kubernetes / Helm 部署

团队级大规模部署可使用官方 Helm Chart：

helm repo add arize-ai https://arize-ai.github.io/phoenix
helm repo update
helm install phoenix arize-ai/phoenix \
  --set ingress.enabled=true \
  --set ingress.hostName=phoenix.yourdomain.com \
  --set env.PHOENIX_ENABLE_AUTH=true

应用接入：给 LLM 应用加上追踪

Phoenix 跑起来后，需要在你的业务代码里"插桩"。以 OpenAI SDK 为例：

import os
from openai import OpenAI
from phoenix.otel import register

# 1) 配置上报端点（自托管地址）
os.environ["PHOENIX_COLLECTOR_ENDPOINT"] = "http://localhost:6006"
# 如果开启了鉴权：
# os.environ["PHOENIX_API_KEY"] = "你的Phoenix API Key"

# 2) 注册 OTel Tracer（自动包裹 OpenAI / LangChain 等库）
tracer_provider = register(
    project_name="my-chatbot",   # 在 Phoenix 里区分不同应用
    auto_instrument=True,        # 自动探测并插桩已安装的 LLM 库
)

# 3) 正常调用 OpenAI，Trace 会自动上报
client = OpenAI()
resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "用一句话介绍杭州"}],
)
print(resp.choices[0].message.content)

刷新 Phoenix Web UI，即可在 my-chatbot 项目下看到这次请求的完整 Trace，包括 Prompt、Completion、Token 数、延迟、模型名。

五、使用方法示例

启动验证：

curl http://localhost:6006/healthz
# 期望返回: OK

运行一次 LLM 评估：

from phoenix.evals import llm_classify, HallucinationEvaluator
from phoenix.client import Client

client = Client(web_endpoint="http://localhost:6006")
# 拉取最近一次 Trace 作为待评估样本
dataset = client.download_exported_dataset("my-chatbot", version="v1")

# 用 GPT-4o 做幻觉检测
eval_results = llm_classify(
    data=dataset,
    template=HallucinationEvaluator(),
    model="gpt-4o",
    provide_prompt_headers=True,
)
print(eval_results)

默认账号密码：Docker 本地匿名模式无账号密码；启用 PHOENIX_ENABLE_AUTH 后，首次访问 Web UI 会进入初始化向导，由你自行创建管理员邮箱与密码，无默认口令。

六、常见问题（FAQ）

Q1：容器启动后访问 6006 端口打不开？

检查三件事：(1) docker ps 确认容器状态是 Up；(2) docker logs phoenix 看是否报数据库连接失败；(3) 云服务器安全组放行 6006 与 4317。如果是云服务器公网暴露，务必开启 PHOENIX_ENABLE_AUTH 并配置反向代理 HTTPS，否则任何人都能看到你的 Prompt 数据。

Q2：Trace 上报成功但 UI 里看不到数据？

确认 PHOENIX_COLLECTOR_ENDPOINT 指向的是 Phoenix Web 端口（6006）而不是 gRPC 端口（4317）；确认 project_name 拼写正确；在 UI 左上角切换到对应 project。

Q3：Trace 数据量很大，存储撑不住怎么办？

在环境变量中设置 PHOENIX_QUILT_* 系列参数控制保留策略，或直接在 PostgreSQL 侧定期归档老 Trace；也可以开启采样（head-based sampling）只上报一定比例请求。

Q4：可以只看本地日志、不部署 Web 服务吗？

可以。Phoenix 支持把 Trace 直接导出为 JSON/OpenTelemetry 格式，或对接 Arize SaaS。但可视化、评估、数据集功能都需要 Web UI。

Q5：和 LangSmith、Langfuse 有什么区别？

三者都是 LLM 可观测平台。Phoenix 由 Arize 出品，在评估（Evals）与 Embedding 可视化上最强，且原生基于 OpenTelemetry；Langfuse 偏产品化、自带 Prompt Management；LangSmith 与 LangChain 耦合最深。Phoenix 的优势是完全开源、OTel 标准中立。

七、跳转链接

• GitHub 仓库：https://github.com/Arize-ai/phoenix
• 官方文档：https://docs.arize.com/phoenix
• Docker 镜像：https://hub.docker.com/r/arizephoenix/phoenix
• PyPI 包：https://pypi.org/project/arize-phoenix/
• Helm Chart：Phoenix Helm Chart