
可观测性AI 评测LLMOpsAI 应用人工智能【免费下载链接】phoenixAI Observability Evaluation项目地址https://gitcode.com/gh_mirrors/phoenix13/phoenix点击查看免费下载导读本指南以仓库中 CLI Agent Starter Kit 的 CLAUDE.md 文档为核心讲解如何为一个基于 AI SDKVercel AI SDK与 Anthropic Claude 构建的 TypeScript CLI Agent 接入 Phoenix 可观测性并重点演示如何使用arizeai/phoenix-cli命令快速验证 Trace 是否被正确捕获、如何以结构化 JSON 检查关键 Span 属性。读完本文你将掌握phoenix-cli traces与phoenix-cli trace两个调试命令的完整用法以及 CLI 场景下 Telemetry 初始化的底层原理与常见排错要点。一、项目定位一个带 Phoenix 可观测性的 CLI Agent 示例CLI Agent Starter Kit 是仓库中位于 js/examples/apps/cli-agent-starter-kit 的一个 TypeScript CLI Agent 启动套件技术栈为AI SDK Anthropic 集成并以 Phoenix 作为其可观测性后端。它同时演示了一个「Phoenix 文档助手」通过 MCP 工具 实时检索 Phoenix 官方文档来回答用户问题。从 package.json 可以看到它的几个关键特征private: true——这是私有示例包不会发布到 npm因此任何改动都不需要 changesets、版本号或 changelog 条目直接修改、直接运行即可依赖aiAI SDK、ai-sdk/anthropic、ai-sdk/mcp以及arizeai/phoenix-otel、arizeai/phoenix-client、arizeai/phoenix-evals等 Phoenix 家族包Node.js 22包管理器使用 pnpm。CLAUDE.md 明确说明了该项目的开发约束它属于 example/starter kit 而非发布型库改动无需版本化管理。这对 Agent 协作开发是一个重要的上下文提示——可以直接修改、无需走发布流程。可用的 Phoenix Skills项目关联了三个 Phoenix 技能skillsphoenix-cli、phoenix-tracing、phoenix-evals。在处理 Phoenix 相关 tracing、evals 或 CLI 操作时应优先调用这些技能获取最新的命令用法与最佳实践。这体现了该仓库「以技能驱动 Agent 开发」的工程组织方式技能定义可参考仓库根目录的 skills-lock.json 与 AGENTS.md。二、可观测性初始化原理instrumentation.ts 做了什么在进入 CLI 调试之前先理解 Trace 数据从何而来。核心文件是 src/instrumentation.ts它必须在任何 AI SDK 调用之前被导入。import { register } from arizeai/phoenix-otel; const provider register({ projectName: cli-agent-starter-kit, // 默认连接本地 Phoenix可通过 PHOENIX_COLLECTOR_ENDPOINT 覆盖 url: process.env.PHOENIX_COLLECTOR_ENDPOINT || http://localhost:6006, // 用于 Phoenix Cloud 的 API key可选 apiKey: process.env.PHOENIX_API_KEY, // 使用批量处理以获得更好性能 batch: true, });关键配置点配置项作用取值说明projectName指定 Trace 归属的项目名必须与 CLI 调试命令中的--project参数一致当前为cli-agent-starter-kiturlCollector 端点默认http://localhost:6006可用环境变量PHOENIX_COLLECTOR_ENDPOINT覆盖apiKeyPhoenix Cloud 鉴权可选本地部署无需设置batch批量导出 Spantrue时合并导出性能更好该文件还导出了一个flush()函数用于在进程退出前冲刷所有挂起的 Span并通过beforeExit、SIGINT、SIGTERM、uncaughtException、unhandledRejection五个事件钩子保证 CLI 应用在任意退出路径上都不会丢 Traceexport async function flush() { try { await provider.shutdown(); } catch (error) { console.error(Error flushing Phoenix spans:, error); } } process.on(beforeExit, async () { await flush(); }); process.on(SIGINT, async () { await flush(); process.exit(0); });为什么 CLI 应用必须显式 flush与常驻服务不同CLI 进程可能在 AI SDK 完成响应后立即退出批量导出的 Span 尚未发送就会被进程终止。这正是 src/cli.ts 在对话循环结束后打印Flushing traces...并调用await flush()的原因也是「没有 Trace」时首先要排查的环节。instrumentation.ts还导出一个会话级标识SESSION_ID每次 CLI 会话生成一个 UUID在 src/ui/interaction.ts 中通过withSpan包裹每次交互并写入session.id属性从而把同一轮对话的所有 Span 串联在一起const handleInteraction withSpan( async (input: string) agent.generate({ prompt: input }), { name: cli.interaction, kind: CHAIN, attributes: { session.id: SESSION_ID }, processInput: (input: string) getInputAttributes(input), processOutput: (result) getOutputAttributes(result.text), } );三、开发与运行从 dev 到 startCLAUDE.md 给出的三个核心脚本详见 package.json 的scripts字段pnpm dev # 运行 agenttsx 直接执行源码且会先自动启动 Phoenix pnpm build # 用 tsc 编译 TypeScript 到 dist/ pnpm start # 运行编译产物node dist/cli.jspnpm dev实际执行pnpm phoenix:ensure tsx --env-file.env src/cli.ts其中phoenix:ensure通过 scripts/ensure-phoenix.sh 确保本地 Phoenixdocker-compose见 docker-compose.yml已启动pnpm start对应node --env-file.env dist/cli.js适合运行构建后的版本另有pnpm dev:verbose可开启VERBOSEtrue在交互界面中逐步打印 agent 的思考步骤与工具调用见interaction.ts中的onStepFinish回调逻辑。环境变量ANTHROPIC_API_KEY——必需用于 Anthropic API 调用。若未设置cli.ts会直接报错并以非零码退出PHOENIX_COLLECTOR_ENDPOINT——可选覆盖默认的本地 Phoenix 地址PHOENIX_API_KEY——可选连接 Phoenix Cloud 时使用VERBOSE——可选true时输出逐步日志。参考 README.md 的快速开始pnpm install、复制.env.example为.env并填入ANTHROPIC_API_KEY然后pnpm dev即可需 Node.js 22、pnpm、Docker Desktop。启动后 Phoenix UI 位于http://localhost:6006CLI 内可使用/help、/exit命令。四、用 Phoenix CLI 调试 Trace三个核心命令CLAUDE.md 的核心章节是「Debugging with Phoenix CLI」提供了从「快速确认」到「逐条深挖」的三级调试手段。所有命令都通过npx arizeai/phoenix-cli调用无需本地安装。4.1 快速 Trace 检查验证 Trace 是否被捕获的最快方式npx arizeai/phoenix-cli traces \ --endpoint http://localhost:6006 \ --project cli-agent-starter-kit \ --limit 5参数说明参数含义--endpointPhoenix 服务地址与instrumentation.ts中的 collector URL 对应--project项目名必须与src/instrumentation.ts中的projectName一致当前为cli-agent-starter-kit--limit最多返回的 Trace 条数若此处返回空说明 Trace 根本没有到达 Phoenix应优先检查 Phoenix 容器是否健康pnpm phoenix:logs以及instrumentation.ts是否在 AI SDK 调用前被导入。4.2 查看最近 Trace 的关键详情--limit 5只能确认「有 Trace」要快速了解每次调用的模型与操作类型可结合--format raw与jq做结构化提取npx arizeai/phoenix-cli traces \ --endpoint http://localhost:6006 \ --project cli-agent-starter-kit \ --limit 5 \ --format raw \ --no-progress | jq .[] | { traceId: .traceId, startTime: .spans[0].start_time, operation: .spans[0].attributes[operation.name], model: .spans[0].attributes[ai.model.id] }这条命令的输出形如{ traceId: …, startTime: 2026-…, operation: ai.generateText, model: claude-haiku-4-5-20251001 }这里有两个关键细节CLAUDE.md 的「Important Notes」也专门强调--format raw输出原始 JSON 而非人类可读的表格这是管道给jq的前提--no-progress关闭进度条输出避免污染标准输出流否则jq会因混入进度信息而解析失败。4.3 检查单个 Trace含工具调用当需要深入某个 Trace特别是查看 agent 调用了哪些工具、走了哪些步骤时使用trace子命令npx arizeai/phoenix-cli trace trace-id \ --endpoint http://localhost:6006 \ --project cli-agent-starter-kit \ --format raw \ --no-progress | jq { traceId: .traceId, spanCount: (.spans | length), spans: [.spans[] | { name, span_kind, tool: .attributes[ai.toolCall.name], model: .attributes[ai.model.id] }] }该命令会返回traceId、Span 总数spanCount以及每个 Span 的名称、span_kindAGENT / LLM / TOOL / CHAIN 等、调用的工具名与所用模型。对于本项目的 ToolLoopAgent 场景TOOL Span 上的ai.toolCall.name会显示dateTime或phoenixDocs工具注册见 src/agents/index.ts 与 src/tools/index.ts可直接确认工具链路是否正确。4.4 调试要点速查CLAUDE.md 将最常见的坑总结为四条Project NameCLI 的--project必须与src/instrumentation.ts中的projectName完全一致当前均为cli-agent-starter-kit拼写不一致会导致查不到任何 TraceEndpoint本地 Phoenix 默认在http://localhost:6006Format需要管道给jq时必须使用--format raw --no-progressTelemetryToolLoopAgent 必须在构造函数中开启experimental_telemetry: { isEnabled: true }否则 agent 内部的 Span 不会被生成——这一点在源码 src/agents/index.ts 中有直接体现export const agent new ToolLoopAgent({ model: anthropic(claude-haiku-4-5-20251001), instructions: AGENT_INSTRUCTIONS, tools: { dateTime: dateTimeTool, phoenixDocs: phoenixDocsTool, }, stopWhen: stepCountIs(10), // 启用 telemetry 以产生 Phoenix Trace experimental_telemetry: { isEnabled: true }, });从源码还可以看到Agent 使用claude-haiku-4-5-20251001作为默认模型、最多执行 10 步stepCountIs(10)这些都会反映在 Trace 的ai.model.id与 Span 数量上可作为调试时的预期参照。五、常用 Span 属性参考CLAUDE.md 给出了调试中最常用的 Span 属性它们在 OpenInference 语义约定下由 Phoenix 自动写入属性含义示例值operation.name操作类型ai.generateTextai.model.id模型名称claude-sonnet-4-20250514ai.toolCall.nameTOOL Span 的工具名dateTime、phoenixDocsai.usage.completionTokens生成 token 数整数ai.usage.promptTokens输入 token 数整数span_kindSpan 类型AGENT、LLM、TOOL、CHAIN等结合上一节的jq过滤表达式即可用这些属性快速实现「只看 LLM 调用」「只看工具调用」「统计 token 消耗」等常见调试需求。例如将ai.usage.completionTokens与ai.usage.promptTokens纳入jq投影即可按 Trace 汇总成本与用量。六、从调试到验证技能、评估与进一步阅读CLAUDE.md 的定位是「Agent 开发协作规范 CLI 调试手册」而该项目本身还配套了完整的评估体系可作为 Trace 验证之外的质量保障手段评估框架项目内置了基于arizeai/phoenix-evals与arizeai/phoenix-client的评估 harness见 evals/README.md运行pnpm eval即可对 agent 输出执行「终端安全格式」等评估结果可在 Phoenix UI 的http://localhost:6006/datasets查看Benchmark 策略evals/README.md 还阐述了「评估器的评估」方法论——用人工标注的 golden dataset 计算 TPR/TNR/Accuracy并把 benchmark 实验与任务实验放在不同 dataset 下以保持历史隔离Seed 数据pnpm seed会调用scripts/seed-traces.ts为项目注入示例 Trace适合在调试命令尚未产生真实数据时先验证 Phoenix 连接与查询链路。phoenix-cli本身是仓库 js/packages/phoenix-cli 中维护的 TypeScript 包其子命令traces、trace的完整参数可在该包源码中进一步查阅。结语围绕phoenix-cli的三条调试命令traces快速确认、traces --format raw结构化提取、trace id深挖工具链路配合--project/--endpoint/--format raw --no-progress四个关键参数开发者可以在几秒钟内完成「Trace 是否上报 → 模型与操作是否预期 → 工具调用是否完整」的完整闭环验证。而这一切的前提是instrumentation.ts的早期导入、projectName的一致性、ToolLoopAgent的experimental_telemetry开启以及进程退出前的flush()——理解这四个底层环节才能真正读懂 Phoenix 为 CLI Agent 绘制的每一份 Trace。赞分享可观测性AI 评测LLMOpsAI 应用人工智能【免费下载链接】phoenixAI Observability Evaluation项目地址https://gitcode.com/gh_mirrors/phoenix13/phoenix点击查看免费下载相关推荐agents-cli 可观测性实战从 Cloud Trace 到 BigQuery Agent Analytics 的四层观测体系agents cli 可观测性实战从 Cloud Trace 到 BigQuery Agent Analytics 的四层观测体系 本文基于 agents cCLIAI 应用开发者工具AI 技能Phoenix 编程代理技能Coding Agent Skills体系实战指南用 Skills 驱动 Phoenix CLI、错误分析与 LLM 可观测性Phoenix 编程代理技能Coding Agent Skills体系实战指南用 Skills 驱动 Phoenix CLI、错误分析与 LLM 可观测性可观测性AI 评测LLMOpsAI 应用人工智能Phoenix 接入 ATIF用 Python 将 Agent 轨迹批量导入为可观测 TracePhoenix 接入 ATIF用 Python 将 Agent 轨迹批量导入为可观测 Trace ATIFAgent Trajectory Intercha可观测性AI 评测LLMOpsAI 应用人工智能上一篇GitHub Actions自动化实践AI News Radar如何实现30分钟新闻更新下一篇深入解析VSCode-GitLens错误处理从AuthenticationError到GitSearchError的完整指南创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考