可观测性AI 评测LLMOpsAI 应用人工智能【免费下载链接】phoenixAI Observability Evaluation项目地址https://gitcode.com/gh_mirrors/phoenix13/phoenix点击查看免费下载导读本文基于 Phoenix 仓库中的 langchain-quickstart 示例完整讲解一个基于 LangChain TypeScript 的旅行规划 Agent 从环境搭建、Tracing 接入到 LLM 评估Eval的全流程实战。你将学会用arizeai/phoenix-otel注册 Phoenix 并自动插桩 LangChain构建带 Tavily 搜索工具的多工具 Agent再通过phoenix-client拉取 Span、用phoenix-evals内置正确性评估器与自定义评估模板打分并回写注解最终在 Phoenix UI 中观察完整调用链与评估结果。前置条件示例运行需要满足以下环境要求见 README.mdNode.js 18以及可用的包管理器示例使用 npm / npx。Phoenix 服务本地运行pip install arize-phoenix phoenix serve或使用 Phoenix Cloud 实例。OpenAI API KeyOPENAI_API_KEY供 Agent 的 LLM 使用模型为openai:gpt-3.5-turbo。Tavily API KeyTAVILY_API_KEY供三个工具调用搜索 API。Fireworks API KeyFIREWORKS_API_KEY仅运行自定义评估脚本时需要。一、快速启动六步走SETUP.md 核心流程SETUP.md 给出六步启动流程下面逐步骤展开并补充源码细节。步骤 1进入示例目录cd js/examples/apps/langchain-quickstart步骤 2安装依赖npm install根据 package.json安装的依赖包括版本以当前仓库 lockfile 为准依赖作用langchainLangChain 主体与 Agent 抽象createAgentlangchain/core回调管理器与工具基类StructuredTool、CallbackManagerzod工具入参的 Schema 校验arizeai/phoenix-otelPhoenix Tracing 注册与导出arizeai/openinference-instrumentation-langchainLangChain 自动插桩arizeai/phoenix-client拉取 Span、回写 Span 注解arizeai/phoenix-evals内置/自定义评估器ai-sdk/openaiOpenAI 兼容模型封装Agent 与评估共用dotenv加载.env环境变量tsx直接运行 TypeScript 的开发工具其中arizeai/phoenix-client与arizeai/phoenix-evals在仓库内以workspace:*形式引用monorepo 工作区源码位于 js/packages/phoenix-client 与 js/packages/phoenix-evals。步骤 3配置环境变量从.env.example复制生成.env至少配置以下变量# Agent 必需 OPENAI_API_KEYyour-key-here TAVILY_API_KEYyour-tavily-key-here # Phoenix默认值如下。Trace 导出到 PHOENIX_COLLECTOR_ENDPOINT # 评估脚本通过 PHOENIX_ENDPOINT 调用 Phoenix API。 PHOENIX_COLLECTOR_ENDPOINThttp://localhost:6006 PHOENIX_ENDPOINThttp://localhost:6006 PHOENIX_PROJECT_NAMElangchain-travel-agent运行npm run custom_evals还需额外配置FIREWORKS_API_KEYyour-fireworks-key-here环境变量在 src/index.ts 中用于注册 PhoenixprojectName缺省时回退到langchain-travel-agentsrc/tools.ts 中TAVILY_API_KEY缺失会直接抛出错误提示。步骤 4启动 Phoenix本地运行场景在另一个终端中pip install arize-phoenix phoenix serve启动后 Phoenix UI 默认监听http://localhost:6006。若此前安装过旧版 Phoenix运行pip install -U arize-phoenix升级后再启动以避免评估注解 APIspan annotations缺失导致的 404详见 README 的 Troubleshooting 一节。步骤 5运行应用npm start该命令实际执行npx tsx src/index.ts见 package.json。预期输出包括三条旅行规划查询爱尔兰 5 天、日本 7 天、葡萄牙 3 天每条包含目的地、时长与兴趣点Agent 依次调用三个工具essential_info、budget_basics、local_flavor后给出的回答在http://localhost:6006的 Phoenix UI 中可看到完整 Trace。步骤 6可选运行评估Agent 运行并产生 Trace 后# 内置正确性评估OpenAI npm run pre_built_evals # 自定义正确性评估旅行评估模板Fireworks npm run custom_evals二、理解示例的代码结构与数据流SETUP.md 给出了文件结构整理如下langchain-quickstart/ ├── src/ │ ├── index.ts # Phoenix 注册 LangChain 旅行 Agent │ ├── tools.ts # essential_info / budget_basics / local_flavorTavily │ ├── pre_built_evals.ts # 内置正确性评估 → Phoenix 注解 │ ├── custom_evals.ts # 自定义正确性评估旅行模板Fireworks │ └── instrumentation.ts # 可选独立 Phoenix 配置index.ts 未使用 ├── package.json # 脚本start / pre_built_evals / custom_evals ├── .env.example # OPENAI、TAVILY、PHOENIX、FIREWORKS 示例 ├── README.md # 完整文档 └── SETUP.md # 本文所依据的快速启动文档注意index.ts在文件顶部自行完成 Phoenix 注册与 LangChain 插桩并未 importinstrumentation.ts后者是留给希望以独立模块方式管理追踪初始化的读者的参考实现。数据流总览index.ts启动时注册 Phoenix 并对 LangChain 做自动插桩三条旅行查询依次调用createAgent生成的 AgentAgent 按系统提示词强制依次调用三个工具每个工具的_call内部调用 Tavily 搜索 API 取回实时资料Agent 调用过程以 OpenInference 语义约定导出为 Trace 到 Phoenix评估脚本通过getSpans拉取LangGraph父 Span交给 LLM 评估器打分再通过logSpanAnnotations回写注解。三、源码解析Tracing 接入与 Agent 构建index.tssrc/index.ts 是主入口核心代码分三段。1. Phoenix 注册与 LangChain 自动插桩import { LangChainInstrumentation } from arizeai/openinference-instrumentation-langchain; import { register } from arizeai/phoenix-otel; import * as CallbackManagerModule from langchain/core/callbacks/manager; import dotenv/config; const provider register({ projectName: process.env.PHOENIX_PROJECT_NAME ?? langchain-travel-agent, }); const lcInstrumentation new LangChainInstrumentation(); lcInstrumentation.manuallyInstrument(CallbackManagerModule);关键点register({ projectName })来自arizeai/phoenix-otel负责 OpenTelemetry 初始化与 OTLP 导出Trace 默认导出到PHOENIX_COLLECTOR_ENDPOINTLangChainInstrumentation.manuallyInstrument(CallbackManagerModule)手动对 LangChain 回调管理器插桩这样createAgent产生的中枢agent调用与工具调用都会被记录为 Span。若希望将追踪初始化独立成模块可参考 src/instrumentation.ts它在任何其他 import 之前设置OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT25000防止 Span 属性值被截断并可传batch: false让 Span 即时投递开发期调试更直观。2. Agent 构建与系统提示词const agent createAgent({ model: openai:gpt-3.5-turbo, systemPrompt: You are a travel planner. You must produce a trip plan that includes exactly three sections, each backed by a tool call. RULES: 1. You MUST call all three tools for every trip plan: essential_info, budget_basics, and local_flavor... 2. Use only information returned by the tools. Do not invent facts, prices, or recommendations. 3. Structure your reply strictly as: (a) Essentials ... (b) Budget ... (c) Local flavor ... 4. Keep the total response under 800 words..., tools: travelTools, });系统提示词通过四条硬规则约束 Agent 行为这与后面评估模板的评分标准一一对应必须三次工具调用、只依据工具返回、回答分三段、总字数小于 800。这种「提示词约束 评估模板度量」的组合是 Eval-Driven Development 的典型做法。3. 三条旅行查询与强制 Flushconst queries [ { destination: Ireland, duration: 5 days, interests: food, culture }, { destination: Japan, duration: 7 days, interests: temples, cuisine }, { destination: Portugal, duration: 3 days, interests: beaches, wine }, ]; // ...for 循环内 agent.invoke({ messages: [{ role: user, content: query }] }) await provider.forceFlush();provider.forceFlush()在程序退出前强制将缓冲区中的 Span 导出避免快速退出的脚本丢失 Trace。入口在启动时还会校验OPENAI_API_KEY与TAVILY_API_KEY缺失即打印错误并process.exit(1)。四、源码解析三个 Tavily 工具与 Zod Schematools.tssrc/tools.ts 基于langchain/core/tools的StructuredTool定义了三个工具每个工具都有 name、description 与 zod schema供 LLM 进行结构化工具调用。共享的搜索封装async function searchApi(query: string): Promisestring | null { const tavilyKey process.env.TAVILY_API_KEY; if (!tavilyKey) { throw new Error(TAVILY_API_KEY environment variable is not set...); } const response await fetch(https://api.tavily.com/search, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ api_key: tavilyKey, query, max_results: 3, search_depth: basic, include_answer: true, }), }); // ...将 answer 与各条结果 content 合并截断到 400 字符后返回 }同时提供了一个compact()函数将搜索结果压缩为单行并限制长度默认 200 字符保证 Span 属性与工具输出可控。三个工具的参数 Schemaconst destinationSchema z.string().min(1, Destination is required).max(100); const durationSchema z.string().regex(/^\d\s*days?$/i, Duration must be like 3 days or 7 days); const interestsSchema z.string().min(1, Interests are required).max(200);essential_info入参仅destination查询旅行 essentials weather best time attractions etiquettebudget_basics入参destinationduration查询budget average daily costs durationlocal_flavor入参destinationinterests查询authentic local experiences interests。每个工具的 description 都明确写出「Required」及使用边界例如 essential_info 明确Do not use for budget or local experiences帮助 LLM 在规划中正确分派工具。工具实现中还内置了搜索无结果时的兜底文案避免返回空字符串破坏 Agent 流程。五、源码解析内置正确性评估pre_built_evals.tssrc/pre_built_evals.ts 演示「拉取 Span → 内置评估器打分 → 回写注解」的闭环。1. 构造内置评估器const base_model openai(gpt-4o-mini); const evaluator createCorrectnessEvaluator({ model: base_model });createCorrectnessEvaluator来自arizeai/phoenix-evals实现位于 js/packages/phoenix-evals/src/llm/createCorrectnessEvaluator.ts。文件内还预留了切换自定义端点 LLM 的注释块Fireworks 的qwen3-235b-a22b-instruct-2507取消注释并同时修改createCorrectnessEvaluator中的模型即可替换评估模型。2. 拉取 Agent Spanconst { spans } await getSpans({ project: { projectName }, limit: 500 }); // 筛选 name LangGraph 的父 Span提取 input.value / output.value 与 span_idgetSpans来自arizeai/phoenix-client/spans实现在 js/packages/phoenix-client/src/spans/getSpans.ts。脚本只挑选名为LangGraph的 Agent 中枢 SpangetInputOutput依次读取input.value/input与output.value/output属性确保评估对象是整个 Agent 的完整回答而非单次工具调用。3. 评估并回写注解const spanAnnotations await Promise.all( parentSpans.map(async ({ spanId, input, output }) { const r await evaluator.evaluate({ input, output }); return { spanId, name: correctness, label: r.label, score: r.score, explanation: r.explanation, annotatorKind: LLM, metadata: { evaluator: correctness, input, output } }; }) ); await logSpanAnnotations({ spanAnnotations, sync: true });logSpanAnnotations同样来自arizeai/phoenix-client/spans实现在 js/packages/phoenix-client/src/spans/logSpanAnnotations.ts。sync: true表示同步等待写入完成。评估结果以correctness为名、annotatorKind: LLM附着在 LangGraph Span 上打开 Phoenix UI 即可在对应 Trace 上看到该注解及 label/score/explanation。六、源码解析自定义评估模板custom_evals.tssrc/custom_evals.ts 展示如何针对业务定制评估标准评估结果命名为custom_correctness。1. 自定义评估模板const correctnessTemplate You are an expert evaluator judging whether a travel planner agents response is correct. ... CORRECT - The response: - Accurately addresses the users destination, duration, and stated interests - Includes essential travel info (e.g., weather, best time to visit, key attractions, etiquette) - Includes a budget or cost breakdown appropriate to the destination and trip duration - Includes local experiences, cultural highlights, or authentic recommendations matching the users interests - Is factually accurate, logically consistent, and helpful for planning the trip - Uses precise, travel-appropriate terminology INCORRECT - The response contains any of: - Factual errors about the destination, costs, or local info - Missing essential info / Missing or irrelevant budget information / Missing or generic local experiences - Wrong destination, duration, or interests addressed - Contradictions, misleading statements, or unhelpful/off-topic content [BEGIN DATA] [User Input]: {{input}} [Travel Plan]: {{output}} [END DATA] ...;模板使用{{input}}、{{output}}占位符注入待评估内容评估标准与 index.ts 的系统提示词严格对应essential info / budget / local flavor 三段齐全 事实准确保证「先约束、后度量」的闭环。2. 分类评估器构造const evaluator createClassificationEvaluator({ model: base_model, promptTemplate: correctnessTemplate, choices: { correct: 1, incorrect: 0 }, name: EVAL_NAME, // custom_correctness });createClassificationEvaluator实现在 js/packages/phoenix-evals/src/llm/createClassificationEvaluator.ts。choices定义二分类标签及对应分数correct1, incorrect0name作为评估器名称随后回写的注解名即为custom_correctness。3. 与内置评估流程的差异数据拉取与过滤逻辑与 pre_built_evals 相同同取LangGraph父 Span、limit: 500评估结果通过evaluator.evaluate({ input, output })拿到{ label, score, explanation }回写的注解name为custom_correctnessmetadata记录evaluator: custom_correctness。通过对比两个脚本可以直观理解内置评估器开箱即用自定义评估器则允许完全掌控模板、标签与分数语义。七、在 Phoenix 中查看什么应用运行后打开http://localhost:6006在项目langchain-travel-agent下可以看到Trace每次 Agent 调用生成一条 Trace包含LangGraphagentSpan 与三条工具调用 Spanessential_info、budget_basics、local_flavor并展示 Token 用量、延迟、提示词与响应内容注解运行评估脚本后LangGraphSpan 上会出现correctness或custom_correctness注解附带 label、score 与 LLM 的 explanation可直接在 Trace 详情中核对每条旅行计划的评分理由。注意PHOENIX_PROJECT_NAME需与你在 UI 中打开的项目名一致默认langchain-travel-agent否则看不到 Trace。八、常见问题排查结合 README.md 的 Troubleshooting 部分现象排查与修复OPENAI_API_KEY/TAVILY_API_KEY未设置报错在.env中配置或export OPENAI_API_KEY...后运行Phoenix 中看不到 Trace确认phoenix serve在运行、PHOENIX_COLLECTOR_ENDPOINT可访问默认http://localhost:6006、PHOENIX_PROJECT_NAME与 UI 中打开的项目一致TypeScript / 模块报错重新npm install使用 Node.js 18确认type: module与 import 路径匹配评估脚本报404 Not Found注解写入失败服务端缺少 span annotations API执行pip install -U arize-phoenix phoenix serve升级重启或在仓库根目录运行uv run phoenix serve。评估本身仍会运行并打印结果仅注解回写失败custom_evals报需要PHOENIX_ENDPOINT在.env中设置PHOENIX_ENDPOINThttp://localhost:6006并确保FIREWORKS_API_KEY已配置九、下一步扩展方向SETUP.md 末尾给出的扩展建议结合源码可落地的方向有更换查询数据修改 src/index.ts 中queries数组的目的地、时长与兴趣点增删工具在 src/tools.ts 中按StructuredTool模式新增工具并加入travelTools数组注意同步调整系统提示词与评估模板调整系统提示词修改createAgent的systemPrompt例如放宽「必须调用三个工具」的约束或改变回答格式定制评估模板在 src/custom_evals.ts 中修改correctnessTemplate例如增加「预算是否合理」「推荐是否可落地」等业务维度更换评估模型参考pre_built_evals.ts中注释掉的 Fireworks 配置块将评估器模型切换为自定义端点模型。这套「Agent 提示词约束 Phoenix Tracing 观测 LLM 评估回写」的闭环可以直接迁移到你的 LangChain TypeScript 生产项目中把register与LangChainInstrumentation的初始化提取到应用入口把评估脚本接入 CI 或定时任务即可持续度量 Agent 输出质量。赞分享可观测性AI 评测LLMOpsAI 应用人工智能【免费下载链接】phoenixAI Observability Evaluation项目地址https://gitcode.com/gh_mirrors/phoenix13/phoenix点击查看免费下载相关推荐Opik TypeScript SDK 实战指南LLM 应用追踪、评估与集成Opik TypeScript SDK 实战指南LLM 应用追踪、评估与集成 Opik TypeScript SDKnpm 包名 opik 是 Opik人工智能LLMOps模型评测可观测性AI AgentAI 应用后端前端Phoenix Harbor 插件实战指南将 Harbor Agent 评估沉淀为版本化数据集、实验与 ATIF 追踪Phoenix Harbor 插件实战指南将 Harbor Agent 评估沉淀为版本化数据集、实验与 ATIF 追踪 Harbor 负责在沙箱环境中运行 A可观测性AI 评测LLMOpsAI 应用人工智能impeccable 设计评审critique实战指南双 Agent 隔离评估、Nielsen 启发式评分与快照追踪impeccable 设计评审critique实战指南双 Agent 隔离评估、Nielsen 启发式评分与快照追踪 impeccable 是面向 AIAI 技能前端CLIdsh-plugin上一篇免费股票行情数据获取实战用 easyquotation 从零搭建实时行情脚本下一篇WTF-Solidity 工具篇Foundry 极简入门 —— 用 Solidity 贯穿开发、测试与部署的以太坊开发工具链创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
