可观测性AI 评测LLMOpsAI 应用人工智能【免费下载链接】phoenixAI Observability Evaluation项目地址https://gitcode.com/gh_mirrors/phoenix13/phoenix点击查看免费下载本篇技术指南围绕当前仓库中的可运行示例项目 js/examples/apps/tracing-tutorial 展开完整演示如何用 TypeScriptAI SDK Phoenix SDK构建一个客服支持 AgentSupportBot并借助 Phoenix 对每一次 LLM 调用、工具执行、RAG 检索进行追踪通过 Annotation 与 LLM-as-Judge 评估回答质量最终用 Sessions 把多轮对话串成完整会话。读完本文你将掌握 Phoenix 可观测性体系的四个核心能力接入 Tracing、阅读 Trace 执行树、运行自动化评估、跟踪并评估多轮会话。教程概览与前置条件该示例是一个随官方文档发布的配套工程对应文档中的三个章节第 1 章你的第一批 Trace构建支持 Agent 并追踪所有内部操作第 2 章Annotation 与评估用人工反馈与 LLM-as-Judge 评估回答质量第 3 章Sessions将多轮对话作为会话进行跟踪与评估运行示例需要满足以下前提Node.js 18本仓库当前依赖的 AI SDK 版本较新若使用最新 AI SDK 可能需要 Node.js 22本地运行中的 Phoenix 服务uvx arize-phoenix serve或pip install arize-phoenix phoenix serveOpenAI API Key示例使用gpt-4o-mini与text-embedding-ada-002从 package.json 可以看到该工程的依赖组成它们正好对应追踪链路的每一环依赖包在教程中的作用arizeai/phoenix-otel注册 OpenTelemetry把 Trace 发往 Phoenixarizeai/phoenix-client通过 Phoenix Client 获取 Span、回写 Annotationarizeai/phoenix-evals提供createClassificationEvaluator等 LLM-as-Judge 评估器arizeai/openinference-core提供setSession等会话上下文传播能力arizeai/openinference-semantic-conventions提供 OpenInference 语义约定常量如SESSION_IDaiai-sdk/openaiAI SDK 的generateText、embed、toolAPI 与 OpenAI 模型接入zod工具输入参数的运行时校验 Schema工程还依赖tsxTypeScript 直接运行器与typescript四个 npm scripts 对应本教程的三个章节见 package.jsonscripts: { evaluate: npx tsx evaluate-traces.ts, evaluate:sessions: npx tsx evaluate-traces.ts --sessions, sessions: npx tsx support-agent.ts --sessions, start: npx tsx support-agent.ts }环境搭建安装依赖、配置环境变量、启动 Phoenix1. 安装依赖在 js/examples/apps/tracing-tutorial 目录下执行pnpm install2. 设置环境变量# OpenAI API key必填 export OPENAI_API_KEYyour-openai-api-key # 可选自定义 Phoenix 端点默认为 http://localhost:6006 export PHOENIX_COLLECTOR_ENDPOINThttp://localhost:6006关于PHOENIX_COLLECTOR_ENDPOINT的解析逻辑可以从 js/packages/phoenix-otel/src/register.ts 的源码注释得到印证register()的url参数若未提供会优先读取PHOENIX_COLLECTOR_ENDPOINT环境变量URL 若未带/v1/traces路径会被自动规范化补全。此外工程还支持PHOENIX_PROJECT项目名、PHOENIX_API_KEY认证自动以 Bearer Token 形式加入 Authorization 头等环境变量。3. 启动 Phoenix若使用本地方式运行 Phoenix 服务pip install arize-phoenix phoenix serve服务启动后默认监听http://localhost:6006这也是 Trace 收集端点的默认地址。追踪接入理解 instrumentation.ts 做了什么追踪的开关在 instrumentation.ts 中它必须在每个脚本的最顶部被导入import { register } from arizeai/phoenix-otel; // Register with Phoenix - this handles all the OpenTelemetry boilerplate export const provider register({ projectName: support-bot, // Optional: set batch to false for immediate span delivery during development batch: false, });这里的register()一次性完成了 OpenTelemetry 的全部样板工作。从 register.ts 的类型定义可以了解到它支持的核心配置项配置项默认值说明projectNamedefaultSpan 在 Phoenix 中归属的项目名用于 UI 分组与过滤未传时读PHOENIX_PROJECT环境变量url读PHOENIX_COLLECTOR_ENDPOINTPhoenix 服务地址自动补全/v1/traces路径apiKey读PHOENIX_API_KEY云端/认证场景下以 Bearer Token 认证batchtruetrue用批量 Span 处理器生产推荐减少网络开销false用简单处理器即时导出调试方便globaltrue是否把 TracerProvider 注册为全局 Providerinstrumentations无需要自动注册的 OpenTelemetry 插桩列表注意 ESM 项目可能需手动注册spanProcessors无自定义 Span 处理器提供后会覆盖由url/apiKey/batch生成的默认处理器教程中把batch显式设为false是为了让开发调试阶段的 Span 立即送达 Phoenix不必等待批处理窗口。对应的实现位于 lazyOpenInferenceSpanProcessor.ts它根据batch标志在批量处理器与简单处理器之间切换。另外注意示例代码在每次 Agent 执行完毕后会调用provider.forceFlush()见 support-agent.ts确保脚本退出前所有 Span 已落盘这一点在手动跑脚本时很关键。第 1 章你的第一批 Trace运行单轮演示pnpm start这条命令运行 support-agent.ts 的默认路径用 7 条精心设计的测试查询去压测Agentconst queries [ Whats the status of order ORD-12345?, // → 订单状态 → 工具调用订单存在 How can I get a refund?, // → FAQ → RAG知识库中已有 Where is my order ORD-67890?, // → 订单状态 → 工具调用订单存在 I forgot my password, // → FAQ → RAG知识库中已有 Whats the status of order ORD-99999?, // → 订单不存在触发失败路径 How do I upgrade to a premium plan?, // → 知识库中没有Agent 无法回答 Can you help me with something random?,// → 模糊请求 ];其中前 4 条是好查询后 3 条刻意设计为坏查询用来制造真实的失败场景供后续章节的评估环节分析。Agent 内部结构与 Trace 形态handleSupportQuery是整个 Agent 的核心见 support-agent.ts它用tracer.startActiveSpan(support-agent, ...)开启一个openinference.span.kind: AGENT的父 Span把一次请求内的所有操作都嵌套进去。流程分为两步Step 1 - 查询分类用generateText让gpt-4o-mini输出 JSONcategory/confidence/reasoning把查询路由到order_status或faq。分类结果会被写回父 Span 的属性classification.category、classification.confidence供 Phoenix UI 直接查看。Step 2 - 按分类路由订单状态路径用 AI SDK 的tool()定义lookupOrderStatus工具输入 Schema 由 zod 校验maxSteps: 2允许决定调用工具 → 拿到结果两步工具内部先模拟 300ms 延迟再从内存中的orderDatabase查订单查不到时返回{ error: Order ... not found in our system }。拿到结果后再用一次generateText汇总成面向客户的友好回复。FAQ 路径RAG先用text-embedding-ada-002对查询做embed再与 FAQ 库中预先嵌入的向量做余弦相似度排序取 Top-2 作为上下文最后让gpt-4o-mini只使用给定上下文生成答案。由于 AI SDK 的generateText、embed、tool调用都带experimental_telemetry: { isEnabled: true }它们会被自动打点为子 Span。因此在 Phoenix 中每条support-agentTrace 的执行树如下订单状态查询support-agent (AGENT) ├── ai.generateText (classification → order_status) ├── ai.generateText (with tool call) │ └── tool: lookupOrderStatus └── ai.generateText (summarizes tool result)FAQ 查询support-agent (AGENT) ├── ai.generateText (classification → faq) ├── ai.embed (query embedding) └── ai.generateText (RAG generation)每个 LLM Span 会记录输入消息system/user 提示词、输出、模型名与提供商、调用参数、Token 用量与延迟RAG 的生成 Span 系统提示词里直接包含检索到的上下文方便你一眼看出检索是否找对了文档。交互式反馈采集Agent 跑完所有查询后会进入交互式反馈环节collectUserFeedback见 support-agent.ts对每条响应输入y 有用、n 无用或s跳过。关键点在于Agent 在父 Span 创建时通过agentSpan.spanContext().spanId捕获了 Span ID见第 L219 行反馈随之通过logSpanAnnotations以user_feedback的名义、annotatorKind: HUMAN写回 Phoenixawait logSpanAnnotations({ spanAnnotations: annotations, sync: false, // async mode - Phoenix processes in background });annotatorKind字段区分标注来源HUMAN人工 /LLM模型评估metadata 里记录了分类类别与来源interactive_tutorial方便后续按维度聚合。第 2 章Annotation 与 LLM-as-Judge 评估跑完 Agent、收集完人工反馈后运行评估脚本pnpm evaluate该命令对应 evaluate-traces.ts 的默认路径核心流程是取 Span → 分类评估 → 回写 Annotation → 输出汇总。流程一从 Phoenix 拉取 Span通过arizeai/phoenix-client/spans的getSpans按项目名support-bot拉取最近 100 条 Span见 evaluate-traces.ts。如果 Phoenix 未启动或尚未生成 Trace脚本会给出明确的排查提示。流程二工具结果检查tool_result从 Span 列表里过滤出name ai.toolCall的工具 Span对output.value做纯代码级检查——输出中若包含error或not found则判为error否则为success见 evaluate-traces.tsconst hasError output.toLowerCase().includes(error) || output.toLowerCase().includes(not found); const status hasError ? ❌ ERROR : ✅ SUCCESS; annotations.push({ spanId, name: tool_result, label: hasError ? error : success, score: hasError ? 0 : 1, explanation: hasError ? Tool returned an error or not found response : Tool executed successfully, annotatorKind: LLM as const, // 代码级检查仅为了与评估流程统一 metadata: { evaluator: tool_result, type: code }, });这正是排查回答为什么没用的第一层证据只要在 Phoenix 中看到tool_result error的 Annotation就知道是订单在数据库里不存在例如 ORD-99999。流程三检索相关性评估retrieval_relevanceLLM-as-Judge对 RAG 生成阶段的 LLM Span按系统提示词特征过滤见 evaluate-traces.ts使用arizeai/phoenix-evals的createClassificationEvaluator创建评估器const retrievalRelevanceEvaluator createClassificationEvaluator({ name: retrieval_relevance, model: openai(gpt-4o-mini), choices: { relevant: 1, irrelevant: 0, }, promptTemplate: You are evaluating whether the retrieved context is relevant to answering the users prompt. Classify the retrieval as: - RELEVANT: The context contains information that directly helps answer the question - IRRELEVANT: The context does NOT contain useful information for the question You are comparing the Context object and the prompt object. [Context and Prompt]: {{input}} , });createClassificationEvaluator的本质是返回一个ClassificationEvaluator实例见 js/packages/phoenix-evals/src/llm/createClassificationEvaluator.ts它把自定义promptTemplate与choices标签到分数的映射绑定到指定模型上调用evaluate({ input })即返回{ label, score, explanation }。评估器还会自动生成 explanation解释为什么相关/不相关便于快速定位原因。评估输入取自 RAG 生成 Span 的input.value其中包含检索上下文每评估完一条 Span 会setTimeout 500ms做限流见第 L301 行。流程四回写 Annotation 与结果汇总两类评估结果统一通过logSpanAnnotations以异步模式sync: false写回 Phoenix落在子 Span上——这正是点开一条不理想的 Trace立刻知道哪一步出了问题的关键设计。脚本最后会打印两类汇总 Tool Calls (lookupOrderStatus): Success: N | Errors: M FAQ Retrieval: Relevant: N | Irrelevant: M可复用的排障工作流至此你拥有了一个完整的闭环与文档 annotations-and-evaluations.mdx 的 The Debugging Workflow 小节一致运行 Agentpnpm start对响应给出 /运行评估pnpm evaluate给子 Span 打 Annotation在 Phoenix 中点开被标记为不理想的 Trace查看子 Span 的 Annotation 定位根因tool_result error→ 订单不存在retrieval_relevance irrelevant→ FAQ 不在知识库中。这正是可扩展的调试方式用人工反馈定位失败用自动化评估诊断原因用 Trace 细节理解根因而不是逐条人工翻看。第 3 章Sessions 多轮会话跟踪运行多轮会话演示pnpm sessionspnpm sessions等价于npx tsx support-agent.ts --sessions运行三组预置的会话场景见 support-agent.ts订单咨询Order Inquiry客户问订单状态再追问到货时间、追踪号FAQ 会话FAQ Conversation同一会话里连续问密码重置、退款政策混合会话Mixed Conversation在订单与 FAQ 主题间来回切换测试 Agent 的上下文保持能力。每个会话通过crypto.randomUUID()生成唯一 Session ID所有轮次共享同一个 ID。演示还会维护conversationHistory消息历史与sessionContext记住客户提到过的订单号并在每轮之后用正则/ORD-\d/i从消息中提取订单号存入上下文见 support-agent.ts这样客户在后续轮次说my order时 Agent 能接得上。会话如何被追踪Sessions 的核心机制在handleSupportQuery中见 support-agent.ts// If we have a session ID, propagate it to all child spans if (sessionId) { return context.with(setSession(context.active(), { sessionId }), runAgent); }关键点有三父 Span 上写入标准属性session.id源码中用SemanticConventions.SESSION_ID常量见第 L213 行同时记录conversation.turn轮次号setSession()来自arizeai/openinference-core把会话 ID 注入到 OpenTelemetry 的 Context 中context.with()确保整个 Agent 执行期间该上下文处于激活状态从而让所有子 Span 自动继承会话 ID。文档 sessions.mdx 中把这一机制总结得很精辟Session ID 本质上只是 Span 属性——在父 Span 上设置它Phoenix 就会自动把所有相关 Trace 按会话分组。在 Phoenix 中查看会话打开 Phoenix 的Sessions标签页可以看到对话线程Conversation threads所有轮次按 Session ID 分组聊天视图Chat view点进某个会话看到完整的你来我往会话级 Annotation落在最后一轮上的连贯性与解决状态评估。你可以按conversation_coherence或resolution_status过滤会话快速挑出有问题的对话。会话级评估pnpm evaluate:sessions等价于npx tsx evaluate-traces.ts --sessions执行 evaluate-traces.ts 中的evaluateSessions()。流程如下1. 按会话分组拉取最多 200 条 Span过滤出name support-agent的 Span读取session.id属性分组见groupSpansBySession第 L184-L195 行。2. 构建会话转录transcript组内 Span 按conversation.turn排序把每轮的input.value/output.value拼成Turn N:\nUser: ...\nAgent: ...格式的完整对话文本。3. 运行两个会话级评估器均使用gpt-5模型conversation_coherence对话连贯性判断 Agent 是否记住了前文信息、有没有重复询问、回复是否承接上文。coherent: 1 / incoherent: 0。resolution_status问题解决状态判断对话结束时客户的诉求是否得到满足。resolved: 1 / unresolved: 0。两个评估器的判定标准都写在promptTemplate里并且自动生成 explanation——被标记为 incoherent 或 unresolved 时点进去即可看到具体原因。4. 写回会话级 Annotation与 Span 级不同这里使用arizeai/phoenix-client/sessions的logSessionAnnotationsAnnotation 落在会话而非单个 Span 上见第 L504-L516 行metadata 中记录model: gpt-5与turnCount。5. 汇总输出 Conversation Coherence: Coherent: N/M ✅ Issue Resolution: Resolved: N/M会话评估的价值一个真实的上下文保持案例文档 sessions.mdx 给出了一个很有说服力的分析案例。在混合会话场景中第 1 轮用户问 ORD-67890 的状态Agent 正确查单并回复处理中预计 12 月 15 日送达第 2 轮用户完全切换话题——怎么取消订阅Agent 走 RAG 给出正确指引第 3 轮真正的考验用户只说回到我的订单——承运商是谁没有重复订单号。Agent 正确回忆起 ORD-67890 并回答承运商 pending全程没让用户重复。会话级 Annotation 印证了这一点conversation_coherence: coherent (1.0)、resolution_status: resolved (1.0)explanation 明确指出Agent 跨轮正确引用了订单号与一致细节同时没有丢失对订阅问题的处理。这就是会话级评估的意义不用逐轮人工检查通过连贯性与解决率即可扫描全部会话发现异常后点进去看 explanation 就能定位问题。在 Phoenix 中应该看什么打开http://localhost:6006按章节对照查看Traces第 1 章每条support-agentTrace 展示完整请求流。订单路径能看到分类 → 工具决策 → 工具执行 → 结果汇总四段FAQ 路径能看到分类 → 嵌入 → RAG 生成。注意分类置信度属性如果某条查询的confidence: low通常意味着查询超出了 Agent 的能力范围例如Can you help me with something random?。Annotations第 2 章每个 Trace 的Annotations标签页会显示三类标注user_feedback用户在终端交互输入的 /HUMANtool_result代码级 success/error 检查retrieval_relevanceLLM 评估的 relevant/irrelevant。按 Annotation 值过滤 Trace可以快速发现失败模式例如所有tool_result error的 Trace 都对应不存在的订单号。Sessions第 3 章Sessions标签页展示完整对话线程与聊天视图会话级 Annotation 落在最后一轮。按conversation_coherence/resolution_status过滤即可找到忘记上下文或问题未解决的会话。项目结构速览js/examples/apps/tracing-tutorial/ ├── package.json # 依赖与脚本start / sessions / evaluate / evaluate:sessions ├── tsconfig.json # TypeScript 配置ES2022 / strict / bundler 解析 ├── instrumentation.ts # Phoenix/OpenTelemetry 接入register batch:false ├── support-agent.ts # 第 1 3 章支持 Agent含会话支持与交互反馈 ├── evaluate-traces.ts # 第 2 3 章LLM-as-Judge 评估Span 级 会话级 └── README.md # 本教程说明各模块的底层实现可以在对应包中找到追踪注册逻辑见 js/packages/phoenix-otel/src/register.tsSpan Annotation 写入见 js/packages/phoenix-client/src/spans/logSpanAnnotations.ts会话 Annotation 写入见 js/packages/phoenix-client/src/sessions/logSessionAnnotations.ts分类评估器工厂见 js/packages/phoenix-evals/src/llm/createClassificationEvaluator.ts。总结通过这个 TypeScript 教程工程你掌握了一套完整的 LLM 应用可观测性方法论追踪接入arizeai/phoenix-otel后AI SDK 的每次generateText、embed、tool调用都会自动成为 Trace 中的节点再用父 Span 把一次请求的全部操作聚合成一棵执行树评估用人工反馈/标注好坏用代码级检查与 LLM-as-Judge 自动化诊断失败原因Annotation 直接落在对应的 Span 上会话通过setSessioncontext.with让会话 ID 沿上下文传播把孤立的单次查询串成对话线程并用会话级评估器回答上下文是否保持问题是否解决。这套观察一切 → 度量重点 → 用数据改进的模式适用于任何 LLM 应用评估器和指标会随业务变化但追踪、标注、评估、会话的闭环方法是通用的。你也可以参照仓库中其余示例如 js/examples/apps 目录下的其他应用将同样的模式迁移到 LangGraph、OpenAI Agents 等不同框架之上。赞分享可观测性AI 评测LLMOpsAI 应用人工智能【免费下载链接】phoenixAI Observability Evaluation项目地址https://gitcode.com/gh_mirrors/phoenix13/phoenix点击查看免费下载相关推荐如何永久保存微信聊天记录开源工具完整指南与实战应用如何永久保存微信聊天记录开源工具完整指南与实战应用 你是否曾因手机更换而丢失珍贵的聊天记录那些与亲友的温馨对话、工作群的重要信息、学习交流的宝贵内容都值得人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音Phoenix TypeScript 追踪接入指南使用 arizeai/phoenix-otel 完成 LLM 可观测性配置Phoenix TypeScript 追踪接入指南使用 arizeai/phoenix otel 完成 LLM 可观测性配置 导读 本文基于 Phoenix可观测性AI 评测LLMOpsAI 应用人工智能Ragas 可观测性实战指南用 Phoenix 与 LangSmith 打通 RAG 评估的追踪与可视化Ragas 可观测性实战指南用 Phoenix 与 LangSmith 打通 RAG 评估的追踪与可视化 构建一个可用的 RAG 基线并不困难但要让它在生产人工智能大模型模型评测RAG上一篇如何轻松提升暗黑破坏神3游戏效率智能按键工具的终极指南下一篇网盘直链下载助手如何轻松获取8大网盘真实下载链接创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考