可观测性AI 评测LLMOpsAI 应用人工智能【免费下载链接】phoenixAI Observability Evaluation项目地址https://gitcode.com/gh_mirrors/phoenix13/phoenix点击查看免费下载本篇文章以arizeai/phoenix-mcp的官方变更日志js/packages/phoenix-mcp/CHANGELOG.md为骨架结合其 TypeScript 源码js/packages/phoenix-mcp/src与测试用例系统解读 Arize Phoenix MCP Server 在 2.0.0 → 4.3.13 演进过程中的核心能力如何解析服务地址与凭证、如何加载配置、覆盖了哪些 MCP 工具以及 4.0.0 引入的破坏性参数变更为何重要。读完本文你可以掌握该包的安装接线方式、环境变量优先级规则、工具清单与分页/注解加载的底层实现并能在升级到 4.x 时快速对齐新参数规范。一、包定位Phoenix 的官方 MCP Serverarizeai/phoenix-mcp是 Arize Phoenix 平台对 Model Context ProtocolMCP的官方实现为 LLM 客户端如 Claude Desktop、Cursor提供访问 Phoenix 可观测性数据与评估能力的统一工具接口。从 js/packages/phoenix-mcp/package.json 可以看到bin入口为arizeai/phoenix-mcp指向./build/index.js可直接通过npx启动运行时依赖arizeai/phoenix-clientREST 客户端、arizeai/phoenix-config统一配置解析与modelcontextprotocol/sdk参数解析使用minimist工具入参校验使用zodv4构建后产物为可执行的二进制脚本build脚本会执行chmod 755 build/index.js。在 src/index.ts 中服务端启动流程清晰可见先用minimist解析命令行参数调用resolveConfig合并环境变量与命令行配置再通过createPhoenixClient构建 REST 客户端最后创建McpServer实例并依次注册九组工具Prompts、Experiments、Datasets、Projects、Traces、Spans、Sessions、AnnotationConfigs、Support。二、安装与接线一条可直接使用的 MCP 配置变更日志中反复强调该包与phoenix-client、phoenix-config的版本联动说明它始终作为 Phoenix TypeScript 生态的一部分发布。标准接入方式如下来自 js/packages/phoenix-mcp/README.md{ mcpServers: { phoenix: { command: npx, args: [ -y, arizeai/phoenix-mcplatest, --baseUrl, https://my-phoenix.com, --apiKey, your-api-key ] } } }本地开发调试时包内提供了三个脚本见 package.json# 开发模式读取 .env 后直接运行源码 pnpm dev # 构建tsc 编译并赋予入口可执行权限 pnpm build # 调试构建后启动 MCP Inspector 可视化检查工具调用 pnpm inspect其中pnpm dev会从.env读取PHOENIX_API_KEY与PHOENIX_ENDPOINT并透传给入口参数便于在 Phoenix 后端上联调工具。三、配置解析的演进从 PHOENIX_HOST 到统一的 getBaseUrlFromEnvironmentWithSource变更日志 4.3.0 记录了一次重要的配置行为变更MCP Server 的 base URL 解析从只读PHOENIX_HOST升级为与 API 客户端和pxCLI 完全一致的规则——优先读PHOENIX_ENDPOINT当只设置了 trace 导出变量PHOENIX_COLLECTOR_ENDPOINT或OTEL_EXPORTER_OTLP_ENDPOINT时从其推断最后才回退到旧版PHOENIX_HOST。该逻辑在 src/config.ts 中通过arizeai/phoenix-config的getBaseUrlFromEnvironmentWithSource()落地其返回值同时携带source来源类型与envKey命中的变量名供后续告警与诊断使用。配置合并的完整优先级如下对应 src/config.ts 的resolveConfig命令行参数--baseUrl、--apiKey、--project优先级最高其次为进程环境变量再次为.env.phoenix文件发现见 4.1.1最终兜底DEFAULT_PHOENIX_ENDPOINT即DEFAULT_PHOENIX_BASE_URL。值得注意的实现细节getStringCommandLineOptions只接受typeof value string的命令行值避免minimist将无值裸标志解析为布尔true后错误覆盖环境默认值。同时若 endpoint 来自 env 文件而凭证来自命令行或进程环境会触发一次性的warnIfUsingFileEndpointWithCredentials告警防止端点与凭证来源错配。凭证侧src/client.ts 会同时发送Authorization: Bearer apiKey与api_key: apiKey两种认证头兼容不同 Phoenix 部署习惯并优先注入User-Agent: phoenix-mcp调用方自定义 headers 仍可覆盖对应 4.0.15 的修复Node 全局fetch默认的undiciUA 会被某些 Phoenix Cloud 边缘节点 302 重定向到 HTML 落地页导致 JSON 解析失败见 src/constants.ts 中USER_AGENT的注释与 issue #13742。环境变量速查4.3.x 有效变量作用优先级/说明PHOENIX_ENDPOINTPhoenix API 基础 URL规范来源高于PHOENIX_HOSTPHOENIX_COLLECTOR_ENDPOINT/OTEL_EXPORTER_OTLP_ENDPOINT仅设置二者时作为 base URL 推断来源次优先PHOENIX_HOST遗留变量最低优先PHOENIX_API_KEYAPI 密钥与 endpoint 来源错配时会一次性告警PHOENIX_PROJECT别名PHOENIX_PROJECT_NAME项目作用域工具的默认项目PHOENIX_PROJECT优先显式参数最高PHOENIX_CLIENT_HEADERSJSON 编码的附加请求头可覆盖默认 User-AgentPHOENIX_DISCOVER_CONFIG设为false关闭.env.phoenix发现默认开启发现.env.phoenix文件发现机制4.1.14.1.1 为整个 TypeScript 生态引入了.env.phoenix文件发现当进程环境中缺少某项配置时arizeai/phoenix-config会从当前工作目录向上逐级查找最近的.env.phoenix按 dotenv 格式读取PHOENIX_前缀键。关键规则进程环境值优先于文件值相关配置凭证、OTel 端点/端口按组从单一来源解析避免跨源混搭非当前用户拥有的文件被忽略并对跳过文件、其他用户可读文件、端点与凭证来源不匹配分别做一次性告警可通过PHOENIX_DISCOVER_CONFIGfalse关闭调用clearEnvFileCache()可刷新缓存结果浏览器构建使用无 Node 的实现通过条件导出选择phoenix-cli将发现值排在已配置 profile 之下phoenix-mcp与phoenix-otel通过共享解析读取。项目名解析的统一4.1.04.1.0 将项目名环境变量统一为所有 TypeScript 包都读取PHOENIX_PROJECT规范名与PHOENIX_PROJECT_NAME别名PHOENIX_PROJECT优先显式参数/标志仍然最高两者冲突时使用规范值并发出一次性告警。解析逻辑集中在arizeai/phoenix-config的getProjectFromEnvironment()MCP 侧在 src/config.ts 中直接消费并作为defaultProject传给 trace/span/session 工具。项目标识的最终裁决逻辑见 src/projectUtils.ts显式project_identifier优先其次为PHOENIX_PROJECT/--project配置的默认值二者皆缺时报projectIdentifier is required。四、4.0.0破坏性变更与新工具全景4.0.0 是包历史上最大的一次重构对应 changesete4bdcf6expand phoenix-mcp server coverage with breaking parameter changes 概括了它的全部要点破坏性变更升级必读参数改为 snake_case如datasetIdentifier→dataset_id/dataset_nameprompt_identifier、project_identifier等统一采用下划线命名resolveTraceIdByPrefix被移除get-trace现在要求精确的 trace ID不再支持前缀模糊匹配遗留标识符回退模式被删除requirePreferredIdentifier、legacyProjectIdentifier不再存在。这与 zod v4 升级3.0.0一脉相承3.0.0 引入z.looseObject()原.passthrough()、ZodError.issues替代ZodError.errors、z.record()需显式键 schema、zod-to-json-schema被原生z.toJSONSchema()取代——工具入参 schema 体系整体现代化。新工具清单4.x 完整覆盖来自 js/packages/phoenix-mcp/README.md 的 Tool Coverage 章节可按业务域归类Promptslist-prompts、get-prompt、get-latest-prompt、get-prompt-by-identifier、get-prompt-version、list-prompt-versions、get-prompt-version-by-tag、list-prompt-version-tags、add-prompt-version-tag、upsert-promptProjectslist-projects、get-projectTraceslist-traces、get-traceSpansget-spans、get-span-annotationsSessionslist-sessions、get-sessionAnnotation Configslist-annotation-configsDatasetslist-datasets、get-dataset、get-dataset-examples、get-dataset-experiments、add-dataset-examplesExperimentslist-experiments-for-dataset、get-experiment-by-idSupportphoenix-support2.2.0 引入2.3.0 修复端点工程化改进4.0.0 还重构了内部实现通用fetchAllPages分页助手取代重复的游标循环见 src/pagination.ts集中化常量并去重extractSpanIds缓存 RunLLM 客户端ENV_PHOENIX_PROJECT移到phoenix-config复用。默认分页/限制常量集中在 src/constants.ts单页默认 100 条、span 单次查询上限 1000、list 端点 limit 上限 500、annotation 分块 100、并发上限 5、list-traces默认 10 条且上限 100。五、源码级原理trace 查询如何工作以list-traces为例src/traceTools.ts 展示了完整的工具链路时间窗口解析resolveStartTimesrc/spanUtils.ts优先使用显式sinceISO 时间戳否则用last_n_minutes相对当前时间计算now - n * 60_000并toISOString()项目解析resolveProjectIdentifier按显式参数 → 默认项目裁决列 trace调用phoenix-client的getTraces按start_time倒序取limit条默认 10、上限 100MAX_TRACE_PAGE_SIZE拉 span用这批 trace ID 调用fetchProjectSpans拉取全部 spantotalLimit不设上限单页 clamp 到MAX_SPAN_QUERY_LIMIT内部游标循环直到耗尽可选注解include_annotations为 true 时extractSpanIds抽取 span IDfetchSpanAnnotations按 100 个 ID 分块、最多 5 个 chunk 并发MAX_CONCURRENT_ANNOTATION_REQUESTS每 chunk 内部以 1000 条/页游标翻页支持include_annotation_names/exclude_annotation_names过滤最终通过attachAnnotationsToSpans按span_id合并组装 tracegroupSpansByTrace按trace_id分组后buildTracesrc/traceUtils.ts生成摘要——包含traceId、全部 spans、无父节点的rootSpan、最早startTime、最晚endTime、毫秒级duration以及聚合状态任一 span 为ERROR状态码或携带 error 属性则整条 trace 标记为ERROR否则OK。get-trace则要求精确trace_id4.0.0 起移除前缀匹配通过traceIds: [traceId]过滤拉取 span查不到时抛出Trace not found for project project: traceId。此外src/identifiers.ts 实现了 Relay GlobalID 解析base64 解码出TypeName:nodeId结构并做 round-trip 校验拒绝有损解码的字符串getRelayGlobalIdIfType用于区分人类可读名称与 Relay ID从而选择正确的 API 调用路径src/projectUtils.ts 配套提供项目标识裁决。相关工具函数extractSpanIds、groupSpansByTrace、buildTrace等均有独立单测见 js/packages/phoenix-mcp/test 目录下的spanUtils.test.ts、traceUtils.test.ts、projectUtils.test.ts。六、版本演进时间线小结版本类型关键变更2.0.0Majorarizeai/phoenix-mcp初始发布2.1.x–2.2.xMinor/Patch扁平化目录结构、二进制入口、phoenix-support工具2.2.03.0.0Majorzod v3 → v4 升级schema 推断类型与错误 API 变更3.1.0MinorgetSpans/get-spans增加traceIds过滤参数4.0.0Major工具参数全面 snake_case、移除前缀 trace ID 解析、移除遗留标识符回退、新增 9 类工具、fetchAllPages重构4.0.15Patch显式User-Agent: phoenix-mcp规避 Cloud 边缘 302 重定向4.1.0MinorPHOENIX_PROJECT/PHOENIX_PROJECT_NAME项目名统一解析4.1.1Minor.env.phoenix文件发现机制4.2.0Minor新增px setup脚本用于 agent onboarding4.3.0Minorbase URL 解析对齐phoenix-client与pxCLIPHOENIX_ENDPOINT优先trace 导出变量推断PHOENIX_HOST兜底4.3.13Patch依赖phoenix-client7.14.0当前版本自 4.3.x 起绝大多数发布为 Patch 级别内容仅为跟随phoenix-client的依赖升级对应各版本 Updated dependencies 条目说明 MCP Server 的能力面已趋于稳定核心演进集中在底层 REST 客户端与共享配置层。七、升级与使用建议升级到 4.x 前审查调用方传入的工具参数命名将所有 camelCase 标识符改为 snake_casedataset_id、prompt_identifier、project_identifier、trace_id等get-trace必须提供完整精确的 trace ID。多环境部署优先统一通过PHOENIX_ENDPOINTPHOENIX_API_KEY配置如需兼容仅设置 OTel 导出变量的场景4.3.0 起会自动推断 base URL涉及多用户共享主机的场景可关闭.env.phoenix发现PHOENIX_DISCOVER_CONFIGfalse。项目隔离为项目作用域工具配置默认项目时使用PHOENIX_PROJECT或--project两个候选值冲突时以PHOENIX_PROJECT为准并触发一次性告警。大结果集查询注意各工具的硬性上限span 单查询 1000、list 端点 500、list-traces100需要全量数据时依赖工具内部的分页/分块与并发机制而非自行提高limit。文档检索场景本包面向 Phoenix 平台数据操作如需检索 Phoenix 官方文档应使用独立的 Phoenix Docs MCP Server。对于希望深入源码的读者建议按以下顺序阅读入口与工具注册src/index.ts→ 配置解析src/config.ts→ 客户端构建src/client.ts→ 常量与限制src/constants.ts→ 分页与 span 工具链src/pagination.ts、src/spanUtils.ts、src/traceUtils.ts。赞分享可观测性AI 评测LLMOpsAI 应用人工智能【免费下载链接】phoenixAI Observability Evaluation项目地址https://gitcode.com/gh_mirrors/phoenix13/phoenix点击查看免费下载相关推荐Phoenix TypeScript 配置体系深度解析arizeai/phoenix-config 的环境变量解析、.env.phoenix 发现与版本演进Phoenix TypeScript 配置体系深度解析 arizeai/phoenix config 的环境变量解析、 .env.phoenix 发现与版本可观测性AI 评测LLMOpsAI 应用人工智能Unstract LLMWhisperer V2 X2Text Adapter 深度解析环境变量、V2 API 破坏性变更与源码实现Unstract LLMWhisperer V2 X2Text Adapter 深度解析环境变量、V2 API 破坏性变更与源码实现 导读 本文以 LLMWh人工智能AI 应用大模型后端Tcell v2 升级完全解析lazydocker 终端 UI 依赖的破坏性变更与新特性深度解读Tcell v2 升级完全解析lazydocker 终端 UI 依赖的破坏性变更与新特性深度解读 Lazydocker 的终端界面建立在 gocui 之上而开发工具CLI上一篇DZNEmptyDataSet与Azure微软云服务的空状态设计下一篇为什么OpenHuman能省80%的TokenTokenJuice智能压缩原理完整揭秘创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
