人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆【免费下载链接】voltagentAI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework项目地址https://gitcode.com/gh_mirrors/vo/voltagent点击查看免费下载本文是一份面向 AI 应用开发者的 LLM 可观测性LLM Observability入门与实践指南。你会先理解为什么大模型应用需要日志、追踪、成本与质量监控再以开源框架 VoltAgent 及其配套的 VoltOps LLM 可观测性平台为例掌握从环境变量接入、Span/Trace 心智模型、采样配置到反馈闭环的完整落地路径。读完本文你将具备为 AI Agent 搭建「看得见、可定位、能省钱、可评估」的观测体系的能力。为什么 LLM 可观测性如此重要你正在用大模型做点有意思的东西——但让它稳定工作才是真正的难点。有时它给出你想要的答案有时输出却毫无逻辑。当它出错时你要怎么搞清楚为什么LLM 可观测性就是用来回答这些问题的。传统软件出问题时你有日志logs、指标metrics、链路追踪traces——一整套工具让你能看见发生了什么。而大模型应用往往像一个完全的黑盒你输入 prompt它做了些神奇且常常神秘莫测的内部处理然后吐出一个答案。中间到底发生了什么LLM 可观测性要解决的核心问题归根结底是四件事为什么Why你的 LLM 为什么说了它说的那些话怎么样How它到底表现得好不好或有多不好哪里Where事情是在哪里开始跑偏的多少钱How much这一切魔法到底花了你多少钱。为什么说可观测性不是「锦上添花」而是「必备品」看清 LLM 内部意味着什么对你的 AI 项目来说这不是可有可无而是必须告别为 Bug 抓狂LLM 给出了奇怪的回答——「这玩意儿哪来的」可观测性工具能帮你定位问题是 prompt 写得不好、是它使用的数据有问题还是模型今天单纯状态不佳。构建用户真正信任的 AI用户想要可靠、讲得通的 AI。通过密切观察 LLM 行为你能保证输出的质量、安全性与公平性——这正是信任的来源。看紧钱包和手表LLM 极其消耗资源。良好的可观测性让你追踪 token 用量直接命中预算和响应速度延迟 latency。没人喜欢又慢又贵得惊人的应用。尽早发现问题模型不是静态的它们会随时间「漂移」drift性能可能以意想不到的方式退化。扎实的可观测性帮你及早发现这些变化在它变成大问题之前进行调整。用户更满意你也更省心归根结底更懂你的 LLM就意味着更好的产品和更顺畅的用户体验。应该盯住哪些核心指标七块拼图可观测性看起来内容很多但主要就下面几大块1. Prompt 与输入追踪知道你的起点用户或系统实际发送的是什么样的 prompt结果往往会让你吃惊是否存在模式什么样的 prompt 成功、什么样的严重失败更重要的是有没有人试图用「提示注入」prompt injection耍花招你只有先记录它们才能理解它们。2. 输出与响应监控它到底在说什么一定要记录 LLM 生成的文本但还要评估质量相关性、连贯性coherence以及是否输出了有害语言或错误信息即「幻觉」hallucination。3. 顺着面包屑追踪尤其对 Agent / 多步骤链路如果 LLM 不是单打独斗——而是作为 Agent 的一部分使用工具或按思维链执行——你需要看到中间步骤它决定调用哪些工具为什么它的内部「推理」过程能看到的范围内是怎样的4. 性能体检生命体征延迟Latency用户等多久才拿到响应太久用户就流失了吞吐Throughput你的架构能扛多少并发请求规划扩容的关键Token 用量输入输出了多少 token这直接关系成本。5. 算账成本追踪每次请求、每个用户、每个功能到底花了多少钱能不能发现某些功能贵得离谱6. 倾听用户反馈闭环用户是最好的真相来源。让他们方便地表达看法简单的大拇指上/下即可非常有价值他们对 AI 的整体有用性评价如何是否得到了想要的东西7. 给模型打分它是否称职追踪准确率分数或其他相关指标用专门的评估数据集和 benchmark 看它的对比表现时刻警惕模型「漂移」。听上去很多对吧好消息是你不必一次全做完。先从对你自己的应用最关键的部分开始再逐步扩展。难点所在为什么 LLM 可观测性并不容易如果全面观测 LLM 很容易那大家早都搞定了。事实上有一些独特难题让它比普通软件观测更棘手「好」是非常主观的什么是 LLM 的「正确」或「高质量」答案有时显而易见但更多时候相当模糊、高度依赖上下文。这让自动化质量检查充满挑战信息海洋LLM 处理海量文本。记录、存储并真正分析所有这些数据是项大工程实时性需求如果 LLM 在与用户实时交互你往往需要实时监控。问题发生当下就抓住它至关重要标准仍在发展坦白说LLM 可观测性的标准仍在演进。不同模型和平台各有各的做法并不总是即插即用隐私是头等大事prompt 和响应极易包含敏感的个人信息。你必须在如何记录、存储和保护这些数据上格外小心、负责。工具箱到底怎么做 LLM 可观测性更聪明的日志别丢掉现有日志实践去改造它。标准日志框架是你的第一道防线但务必捕获 LLM 特有的内容prompt、完整响应、token 用量甚至可获取的中间思考过程。追踪整段旅程OpenTelemetry对于比单次 LLM 调用更复杂的场景微服务、LLM 调用链分布式追踪是你最好的朋友。像 OpenTelemetry 这样的工具能让你看到请求在系统各部分之间弹跳的完整生命周期。向量数据库来救场它们正变得非常实用。你可以存储 prompt 和响应的 embedding然后搜索相似内容。这非常适合发现常见问题、查找异常甚至支撑一些巧妙的自动化质量检查。仪表盘平台Prometheus、Grafana、Datadog 等如果这些平台已经在服务你的其他应用往往也能接入 LLM 数据。它们擅长可视化指标、创建仪表盘、在异常时告警。那到底怎么给 LLM 打分评估技术人工评审常常是王道有时就需要一个人看看输出说「没错挺好」或「不行差远了」模型评估AI 评 AI用另一个 LLM或更小更专注的模型给你的主 LLM 输出打分。不完美但能规模化你的检查跑 benchmark用标准数据集和基准测试你的 LLM看它与其他模型或自身历史表现相比如何。实战案例VoltAgent 与 VoltOps 的可视化可观测性说回平台本身。看看可观测性如何成为一项基础设计原则是很有启发性的。VoltAgent 在构建时就撞上了无数 AI Agent 开发者遇到的同一个「黑盒」问题。最大的挫败感在于太难理解 Agent 为什么做出某些决策了。它们走了哪些步骤选了哪些工具、什么时候选的当错误不可避免地出现时弄清楚到底哪一步出了问题就像在证据不足的情况下做侦探工作。标准日志有点帮助但随着交互越来越复杂它们越来越不够用。VoltAgent 从 n8n 这类工具的可视化调试能力中获得了大量灵感「为什么 AI Agent 不能拥有同样清晰的东西」于是VoltAgent 决定把可观测性直接内建为核心体验。其关键差异化就是VoltOps LLM 可观测性平台。这个控制台不是又一个仪表盘它让你可视化 Agent 的整个生命周期——LLM 交互、工具调用、状态变更甚至内部推理——全部铺展在 **n8n 风格的画布canvas**上。这种可视化方案让你能清楚看到 Agent 实际执行的逐步流程——不再靠猜在画布上精确定位出错位置大大降低调试错误难度追踪 Agent 的性能以及关键的、与流程中特定步骤绑定的 LLM 成本在试验不同 LLM 或调整 prompt 时轻松对比结果与执行路径。VoltAgent 做整个可视化、画布式可观测性的目标就是让 Agent 的「黑盒」变得透明可理解。VoltOps 平台概览把执行变成可视化 Trace从 VoltAgent 官方文档看VoltOps 通过「把执行变成可视化 trace」来帮助你监控和调试 VoltAgent 应用你可以在一个地方检查模型调用、工具使用、多 Agent 跳转、日志和延迟参见 VoltOps 平台总览。为什么这对 AI Agent 开发者如此重要文档总结了四个理由AI Agent 是非确定性的相同的 prompt 可能产生不同的路径VoltOps 帮你看到每次运行实际发生了什么多步骤流程常常在隐蔽处出问题模型选择、工具输入、重试、子 Agent 委派VoltOps 直接展示失败的精确步骤而不是逼你猜随着 Agent 复杂度上升纯日志调试会变慢可视化 trace 让根因分析在生产环境中更快、更安全可观测性还能提升迭代速度你可以对比运行、追踪行为变化、在大规模发布前验证改进。心智模型一次请求 一条 Trace一个步骤 一个 Span在用 VoltOps 之前先建立最小心智模型详见 Mental Model。AI Agent 只看最终输出是很难调试的VoltOps 的解法是把每次运行呈现为一条带步骤级 span 的 trace在 VoltOps 中trace是一次端到端执行span是这次执行中的一次操作span 通过父子关系连接并被渲染为画布上的节点。五分钟接入环境变量零代码开启接入 VoltOps 非常简单。首先从 VoltOps 控制台的项目设置中获取两个密钥参见 Setup 指南Public Keypk_xxxxSecret Keysk_live_xxxxVoltAgent 会自动检测以下环境变量并连接 VoltOps基础路径无需任何额外观测代码VOLTAGENT_PUBLIC_KEYpk_xxxx VOLTAGENT_SECRET_KEYsk_live_xxxx显式配置VoltOpsClient需要更多控制时可以显式配置VoltOpsClientimport { VoltAgent, VoltOpsClient } from voltagent/core; import { Agent } from voltagent/core; import { openai } from ai-sdk/openai; const supportAgent new Agent({ name: Support Agent, model: openai(gpt-4), instructions: Help users with their questions, }); new VoltAgent({ agents: { supportAgent, }, voltOpsClient: new VoltOpsClient({ publicKey: process.env.VOLTAGENT_PUBLIC_KEY!, secretKey: process.env.VOLTAGENT_SECRET_KEY!, }), });跑一次请求然后打开 VoltOps 控制台。如果 trace 没有出现先确认密钥属于同一个项目、修改环境变量后重启并检查运行日志中的鉴权/导出错误。给 Trace 附加元数据与上下文附加 ID 能让过滤和调试更容易const agent new Agent({ name: Support Agent, model: openai(gpt-4), instructions: Help users with their questions, }); await agent.run(Hello, { userId: user-123, conversationId: conv-456, });字段说明userId将 trace 关联到特定用户conversationId按会话分组 trace高级配置服务命名与采样控制使用createVoltAgentObservability可以控制服务命名与采样import { VoltAgent, createVoltAgentObservability } from voltagent/core; new VoltAgent({ agents: { // your agents }, observability: createVoltAgentObservability({ serviceName: my-app, serviceVersion: 1.0.0, voltOpsSync: { sampling: { strategy: ratio, ratio: 0.5, // Sample 50% of traces }, maxQueueSize: 2048, maxExportBatchSize: 512, scheduledDelayMillis: 5000, exportTimeoutMillis: 30000, }, }), });推荐的起点本地开发用strategy: always高流量生产环境用strategy: ratio。完整配置项如下表选项类型默认值说明serviceNamestringvoltagent显示在 VoltOps 仪表盘中的服务名serviceVersionstring-用于过滤 trace 的版本标签voltOpsSync.sampling.strategyalways|never|ratio|parentalways采样策略voltOpsSync.sampling.rationumber-当策略为ratio时的采样率0-1voltOpsSync.maxQueueSizenumber2048导出前排队的最多 span 数voltOpsSync.maxExportBatchSizenumber512每次导出批次的最大 span 数voltOpsSync.scheduledDelayMillisnumber5000两次导出之间的延迟毫秒voltOpsSync.exportTimeoutMillisnumber30000导出超时毫秒源码透视基于 OpenTelemetry 的观测内核「零配置默认值」背后是 VoltAgent 对 OpenTelemetry 的系统性封装。在 observability/index.ts 的模块注释中明确写着该模块基于 OpenTelemetry 提供通过自定义SpanProcessor提供WebSocket 实时事件通过自定义SpanProcessor提供本地存储OTLP 导出支持零配置默认值。从源码结构看Node 运行时通过 node/volt-agent-observability.ts 包装NodeTracerProvider并组装 VoltAgent 特有的处理器/导出器链包括LocalStorageSpanProcessor本地存储默认InMemoryStorageAdapter最多保留 10000 个 span、每分钟清理一次WebSocketSpanProcessor实时推送SamplingWrapperProcessor实现always/never/ratio/parent等采样策略SpanFilterProcessor按 instrumentation scope 与服务名过滤 spanLazyRemoteExportProcessorOTLP 远程导出。同时会为每个服务构建包含service.name、service.version等语义约定的 OpenTelemetry resource 属性这正是 VoltOps 仪表盘上服务维度的数据来源。createVoltAgentObservability还会自动检测 Serverless 运行时Cloudflare Workers、Vercel Edge、Deno Deploy 等并从全局VoltOpsClient自动推导 traces/logs 的 OTLP 上报端点与鉴权头。看懂 TraceWaterfall 视图、Node-Based 视图与过滤器选中一条 trace 后可以打开Waterfall 视图或Node-Based 视图参见 Tracing 总览。Waterfall 视图waterfall.md以层级展示 span用于理解时间与执行顺序错误徽标 子 span 帮助你找到第一个断点和成因时长条与计时定位最慢的步骤延迟热点还可以核对模型上下文输入/输出、UI 消息与模型消息、LLM 配置、记忆配置与知识库使用情况。Node-Based 视图node-based.md把同一条 trace 呈现为可视化流程适合先看大局再钻入某个节点看细节。在 trace 列表页你还可以使用过滤器快速定位目标Trace FiltersStatus隔离失败或重试频繁的运行Agent ID / Entity type缩小到具体 agent 或步骤Token usage / Cost找出昂贵或异常的运行Duration发现慢 trace 与延迟离群值Feedback source / key按来源回顾反馈User ID / Conversation ID深入单个用户的旅程。比如用 Status Duration 看故障从哪开始用 Token usage Cost 抓昂贵运行用 User ID Conversation ID 检查特定用户流程。成本追踪provider 报价优先模型计价兜底VoltOps 会自动记录 prompt tokens、completion tokens 与总成本详见 LLM Usage Costs成本计算分两条路径provider 返回计费成本时VoltOps 直接使用该精确值provider 未返回成本数据时VoltOps 回退到基于模型名与 token 用量的模型计价。这样既能即时看到成本、无需手动配置又在路由与 BYOK 场景下尽量保持账单准确。对 OpenRouterVoltOps 优先使用其真实成本字段顺序为usage.cost_details.upstream_inference_cost→usage.cost→ 内部计价回退并通过模型上的usage: { include: true }让 VoltAgent 自动把 OpenRouter 用量元数据带入观测 span。如果你的 provider 不返回计费成本也可以用 VoltAgent 的 hook 自行写入usage.input_cost/usage.output_cost/usage.total_cost等 span 属性。反馈闭环用户评价与自动化打分用户反馈是上文提到的「倾听用户」环节在 VoltAgent 中的具体实现详见 Feedback反馈始终绑定一个trace_id启用后VoltAgent 向 VoltOps API 请求一个短时效 token并把元数据附加到最后一条 assistant 消息上方便 UI 展示控件、稍后提交元数据包含traceId、key、url、tokenId、expiresAt、feedbackConfig支持categorical/continuous/freeform等类型。你可以在 Agent 层面开启feedback: true也可以在单次调用时传入feedback选项指定 key 与 config。更进一步可以用buildScorer构建 LLM 评判器在onResult回调里通过feedback.save(...)自动把打分结果持久化为反馈feedbackSourceType: model实现「AI 评 AI」的规模化质量检查。同时支持通过/agents/:id/chatAI SDKuseChat兼容在消息元数据里渲染点赞/点踩 UI并通过agent.markFeedbackProvided(...)持久化「已提交」状态避免会话重载后反馈控件重现。用 Public Trace API 复现与对比运行如果你想在 VoltOps 仪表盘之外加载历史运行比如工作流测试器预载历史运行、内部调试工具、prompt 迭代 UI 对比新旧运行可以使用Public Trace APIpublic-trace-api.mdimport { VoltOpsClient } from voltagent/core; const voltops new VoltOpsClient({ publicKey: process.env.VOLTAGENT_PUBLIC_KEY!, secretKey: process.env.VOLTAGENT_SECRET_KEY!, }); const traces await voltops.observability.traces.list({ search: checkout, environments: [dev, prod], status: [success, error], limit: 20, offset: 0, sortBy: start_time, sortOrder: desc, }); console.log(traces.data);查询参数覆盖了 UI 上的核心过滤能力limit/offset分页、sortBy/sortOrder排序、traceId/agentId/entityType/conversationId/userId/model/status/tags/environments过滤、minTokens/maxTokens/minCost/maxCost/minDuration/maxDuration数值区间以及feedbackKey/feedbackScore等反馈过滤。一个典型的工作流测试器模式是按工作流 ID/环境/用户搜索历史 trace → 用户选择一条 → 用其input、metadata、conversation_id预填测试器 → 用修改后的 prompt 或配置重跑 → 在 VoltOps 里对比新旧 trace。注意x-secret-key属于敏感信息务必只在后端调用切勿暴露到浏览器代码。保持清醒的实践建议最后几条让可观测性之旅更顺畅的建议先弄清楚你的「为什么」不要为了记录而记录。问自己你到底想回答什么问题想解决什么难题先有清晰目标再让目标引导行动从小处开始聪明地扩展不必第一天就实现所有观测模块。先记录对你应用最关键的数据点之后随着感觉再逐步加层搞清楚什么是「正常」建立基线不了解你的 LLM 配置下「好」或「正常」长什么样就无法发现问题。长期追踪关键指标掌握基线性能与成本内建而非事后硬塞尽可能从项目一开始就想可观测性。尽早织入开发生命周期比全部构建完再强行加进去容易得多也有效得多人机组合 黄金搭档自动化监控很棒一定要用。但别忘记人的因素把自动化检查与人工监督、人工评估结合尤其是输出质量和公平性这类微妙内容谨慎处理数据尤其敏感数据如果你在记录 prompt 和响应你很可能应该记录务必对任何个人或敏感信息做匿名化、脱敏或保护处理。结语所以LLM 可观测性到底是不是又一件压到你那本就庞大的待办清单上的事是的某种程度上确实如此。但关键是它是那种能真正帮你省下大量麻烦、可观金钱和无数用户挫败感的事情。当你真正理解 LLM 在做什么、为什么这么做你就从一个只靠祈祷的乐观操作者转变为一个自信的智能系统架构师。你获得了构建更可靠、更高效、更重要的是更值得信赖的 AI 应用的能力。赞分享人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆【免费下载链接】voltagentAI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework项目地址https://gitcode.com/gh_mirrors/vo/voltagent点击查看免费下载相关推荐Goose Langfuse 集成实战为开源 AI Agent 接入 LLM 可观测性Goose Langfuse 集成实战为开源 AI Agent 接入 LLM 可观测性 本教程以 goose一个开源、可扩展、支持任意 LLM 的 AI人工智能大模型AI AgentAI 应用本地部署MCP ClientsMCP 服务工具调用桌面应用CLIQwen3.5-27B API调用指南多模态请求与文本生成的实用示例Qwen3.5 27B API调用指南多模态请求与文本生成的实用示例 Qwen3.5 27B是一款基于MoE架构的高性能多模态大模型支持图文融合的原生多模态Scientific Agent Skills 实战指南把 AI Agent 变成可执行科研工作流的 AI ScientistScientific Agent Skills 实战指南把 AI Agent 变成可执行科研工作流的 AI Scientist Scientific AgenAI 技能科研生物信息学数据科学上一篇ComfyUI-Manager离线节点安装终极指南本地ZIP包完整解决方案下一篇Windows Cleaner3分钟快速清理C盘垃圾的免费神器创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
