Phoenix TypeScript 环境搭建指南：安装与配置 @arizeai/phoenix-client、phoenix-evals 与 phoenix-otel

可观测性AI 评测LLMOpsAI 应用人工智能【免费下载链接】phoenixAI Observability Evaluation项目地址https://gitcode.com/gh_mirrors/phoenix13/phoenix点击查看免费下载本指南基于 Phoenix 官方技能库中的 setup-typescript.md 展开系统讲解在 TypeScript/Node.js 项目中搭建 Phoenix 评估Evals与实验Experiments环境所需的全部步骤三个核心 npm 包的安装、运行时与编译期版本要求、LLM-as-judge 提供方的安装方式以及安装完成后的快速验证与联动用法。读完本文你将能在一台满足版本要求的机器上从零完成 Phoenix TypeScript 工具链的安装并确认客户端、评估器与 OpenTelemetry 追踪三个包可以正常协同工作。一、三个核心包的角色与分工TypeScript 侧搭建 Phoenix 评估与实验环境需要安装三个包它们各司其职包名职责仓库内源码位置arizeai/phoenix-clientPhoenix API 客户端用于访问数据集、实验、Prompts、Span/Trace 等资源js/packages/phoenix-clientarizeai/phoenix-evals评估工具库提供 LLM 评估器、代码评估器、预置指标等js/packages/phoenix-evalsarizeai/phoenix-otelPhoenix OpenTelemetry 追踪 SDK负责注册 tracing、手动 span 辅助与 LLM 可观测性上下文属性js/packages/phoenix-otel从各包的package.json描述可以看到phoenix-client是 A client for the Phoenix APIphoenix-evals是 A library for running evaluations for AI use casesphoenix-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 与 TypeScriptarizeai/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 v7phoenix-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也可以选择使用提供方的直接 SDKnpm 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_ENDPOINThttp://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.mdPython 侧对照安装说明setup-python.md八、安装注意事项小结最后把最容易踩坑的几点汇总如下Node 版本先对齐phoenix-evals2.x 要求 Node.js 22.12低于该版本会直接报 engines 错误。AI SDK 必须 v7提供方包ai-sdk/openai等需要选择 v4 这类与 AI SDK v7 匹配的版本避免与ai^7依赖树冲突。TypeScript 版本若使用arizeai/phoenix-client的 prompts 入口并对发布声明做类型检查请将 TypeScript 升级到 5.3。端点配置默认连接http://localhost:6006远程实例需通过PHOENIX_COLLECTOR_ENDPOINT等环境变量指定。赞分享可观测性AI 评测LLMOpsAI 应用人工智能【免费下载链接】phoenixAI Observability Evaluation项目地址https://gitcode.com/gh_mirrors/phoenix13/phoenix点击查看免费下载相关推荐Phoenix Python 环境搭建指南arize-phoenix 安装、LLM Provider 配置与 Evals 2.0 导入Phoenix Python 环境搭建指南arize phoenix 安装、LLM Provider 配置与 Evals 2.0 导入 本文是 Phoenix可观测性AI 评测LLMOpsAI 应用人工智能Phoenix TypeScript 追踪接入指南使用 arizeai/phoenix-otel 完成 LLM 可观测性配置Phoenix TypeScript 追踪接入指南使用 arizeai/phoenix otel 完成 LLM 可观测性配置 导读 本文基于 Phoenix可观测性AI 评测LLMOpsAI 应用人工智能Phoenix TypeScript 实验数据集指南用 arizeai/phoenix-client 创建与管理评估数据集Phoenix TypeScript 实验数据集指南用 arizeai/phoenix client 创建与管理评估数据集 本指南以 Phoenix 的 T可观测性AI 评测LLMOpsAI 应用人工智能上一篇Numi与教育工作流从学生作业到教师评分的计算应用下一篇Zed开发者指南如何为超结构化数据平台贡献代码创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考