企业官网建设流程全解析

• 可观测性
• AI 评测
• LLMOps
• AI 应用
• 人工智能

本指南基于 Phoenix 官方技能库中的 setup-typescript.md 展开，系统讲解在 TypeScript/Node.js 项目中搭建 Phoenix 评估（Evals）与实验（Experiments）环境所需的全部步骤：三个核心 npm 包的安装、运行时与编译期版本要求、LLM-as-judge 提供方的安装方式，以及安装完成后的快速验证与联动用法。读完本文，你将能在一台满足版本要求的机器上从零完成 Phoenix TypeScript 工具链的安装，并确认客户端、评估器与 OpenTelemetry 追踪三个包可以正常协同工作。

一、三个核心包的角色与分工

TypeScript 侧搭建 Phoenix 评估与实验环境，需要安装三个包，它们各司其职：

从各包的package.json描述可以看到：phoenix-client是 "A client for the Phoenix API"，phoenix-evals是 "A library for running evaluations for AI use cases"，phoenix-otel则定位为 "Phoenix OpenTelemetry tracing SDK for Node.js"。三者叠加即构成"调用 Phoenix 服务端、运行 LLM 评估、采集追踪数据"的完整闭环。

二、安装方式：npm 与 pnpm

使用 npm 或 pnpm 一次性安装三个包：

# Using npm npm install @arizeai/phoenix-client @arizeai/phoenix-evals @arizeai/phoenix-otel # Using pnpm pnpm add @arizeai/phoenix-client @arizeai/phoenix-evals @arizeai/phoenix-otel

仓库本身使用 pnpm workspace 管理这些包（见 js/pnpm-workspace.yaml），因此在 monorepo 内以 pnpm 添加依赖是与上游开发环境最一致的方式。

三、版本要求：Node.js、AI SDK 与 TypeScript

@arizeai/phoenix-evals2.x 对运行环境有明确要求，安装前请先核对：

• Node.js >= 22.12：这是phoenix-evals2.x 的engines硬性门槛（见 js/packages/phoenix-evals/package.json）。相比之下，phoenix-client与phoenix-otel仅要求 Node.js >= 18。
• AI SDK v7：phoenix-evals直接依赖ai@^7与@ai-sdk/otel@^1，因此你无需再显式安装 AI SDK 核心包，只需安装一个模型提供方包即可——但该提供方必须是 AI SDK v7 兼容版本（例如@ai-sdk/openaiv4）。
• phoenix-client7.x 的 peer 依赖：它把ai声明为可选的 peer 依赖，版本要求为^7.0.0（见 js/packages/phoenix-client/package.json）。也就是说，只要你的项目使用 AI SDK v7 生态，phoenix-client与phoenix-evals即可共存于同一依赖树。
• TypeScript >= 5.3：对已发布的@arizeai/phoenix-client类型声明做类型检查时，需要 TypeScript 5.3 或更高版本。原因是其 prompts 入口使用了with { "resolution-mode": "import" }导入属性语法，而skipLibCheck无法抑制这类声明文件中的导入属性错误，必须由较新的 TypeScript 编译器原生支持。

四、安装 LLM 提供方：LLM-as-judge 的前提

评估器如果采用"大模型当裁判"（LLM-as-judge）模式，则需要安装对应的模型提供方 SDK。官方推荐使用 Vercel AI SDK 提供方包：

npm install @ai-sdk/openai # OpenAI npm install @ai-sdk/anthropic # Anthropic npm install @ai-sdk/google # Google

也可以选择使用提供方的直接 SDK：

npm install openai # OpenAI direct npm install @anthropic-ai/sdk # Anthropic direct

注意：直接 SDK（如openai、@anthropic-ai/sdk）与 AI SDK 提供方包（@ai-sdk/*）是两种不同的接入路径。前者面向直接调用原始 API 的场景，后者则能无缝接入phoenix-evals中基于 AI SDK 的评估器实现（如createClassificationEvaluator接收的就是 AI SDK 的 model 对象）。在 js/packages/phoenix-evals/package.json 中可以看到，phoenix-evals直接依赖ai@^7.0.99与@ai-sdk/otel@^1.0.99，这也印证了其 LLM 评估器构建在 AI SDK v7 之上。

五、连接 Phoenix 服务端：端点与环境变量

三个包安装完成后，代码默认会连接本地的 Phoenix 服务端。仓库内 js/packages/phoenix-config/src/constants.ts 给出了默认值：

export const DEFAULT_PHOENIX_PORT = 6006; export const DEFAULT_PHOENIX_COLLECTOR_ENDPOINT = "http://localhost:6006";

即默认采集端点为http://localhost:6006。你可以通过环境变量覆盖端点配置，例如设置PHOENIX_COLLECTOR_ENDPOINT（其优先级高于OTEL_EXPORTER_OTLP_ENDPOINT等通用 OTLP 变量，相关行为在 js/packages/phoenix-config/src/endpointConformance.test.ts 中有系统化的测试覆盖）。若使用 Docker 或远程部署的 Phoenix 实例，请将端点指向实际地址，例如：

export PHOENIX_COLLECTOR_ENDPOINT="http://<your-phoenix-host>:6006"

六、快速验证安装

安装完成后，可用下面的代码一次性验证三个包的核心导出是否可用：

import { createClient } from "@arizeai/phoenix-client"; import { createClassificationEvaluator } from "@arizeai/phoenix-evals"; import { register } from "@arizeai/phoenix-otel"; // All imports should work console.log("Phoenix TypeScript setup complete");

这段代码依次验证了三条导入链路：

• createClient：来自phoenix-client主入口，用于创建访问 Phoenix API 的客户端实例；
• createClassificationEvaluator：来自phoenix-evals主入口，是创建 LLM 分类评估器的工厂函数。其实现（见 js/packages/phoenix-evals/src/llm/createClassificationEvaluator.ts）非常轻量，直接返回一个ClassificationEvaluator实例，类型参数约束了评估器模板所需的字段结构；
• register：来自phoenix-otel主入口，用于注册 OpenTelemetry 追踪。

七、安装之后：子路径导入与典型用法

三个包都通过exports字段暴露了丰富的子路径入口，安装完成后可按需引入更精细的 API。以phoenix-client为例（见 js/packages/phoenix-client/package.json），除主入口外还提供：

• @arizeai/phoenix-client/spans、/traces：查询 Span 与 Trace（采样、错误分析）；
• @arizeai/phoenix-client/experiments：运行实验（runExperiment、asExperimentEvaluator）、评估实验；
• @arizeai/phoenix-client/datasets、/prompts：数据集与 Prompts 管理；
• @arizeai/phoenix-client/vitest、/jest：在 Vitest / Jest 测试运行器中将评估作为 CI 门禁。

phoenix-evals同样提供@arizeai/phoenix-evals/code（代码评估器与 Precision/Recall/F1 指标）、/llm/*、/templates/*等子路径。

搭好环境后，典型的下一步是把它们组合起来使用：用phoenix-otel注册追踪，用phoenix-client的createClient连接服务端，再用phoenix-evals的createClassificationEvaluator（传入 AI SDK v7 的模型对象，如openai("gpt-4o")）构建 LLM 评估器。更完整的用法可继续阅读技能库中的配套文档：

• LLM 评估器构建：evaluators-llm-typescript.md
• 代码评估器构建：evaluators-code-typescript.md
• 运行实验：experiments-running-typescript.md
• 追踪采样策略：observe-sampling-typescript.md
• 测试运行器集成（CI 门禁）：integrations-vitest-jest.md
• Python 侧对照安装说明：setup-python.md

八、安装注意事项小结

最后把最容易踩坑的几点汇总如下：

1. Node 版本先对齐：phoenix-evals2.x 要求 Node.js >= 22.12，低于该版本会直接报 engines 错误。
2. AI SDK 必须 v7：提供方包（@ai-sdk/openai等）需要选择 v4 这类与 AI SDK v7 匹配的版本，避免与ai@^7依赖树冲突。
3. TypeScript 版本：若使用@arizeai/phoenix-client的 prompts 入口并对发布声明做类型检查，请将 TypeScript 升级到 >= 5.3。
4. 端点配置：默认连接http://localhost:6006，远程实例需通过PHOENIX_COLLECTOR_ENDPOINT等环境变量指定。

• 可观测性
• AI 评测
• LLMOps
• AI 应用
• 人工智能