LlamaIndex 接入 Graphsignal零代码改动实现 LLM 应用的自动 Tracing、检索观测与成本监控【免费下载链接】llama_indexLlamaIndex is the document processing platform for AI项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index本文围绕 LlamaIndex 官方社区集成文档 Graphsignal 集成指南 展开讲清楚三件事Graphsignal 能自动捕获 LlamaIndex 应用中的哪些执行细节提示词、补全、嵌入统计、检索节点、延迟、异常以及 OpenAI 的 token 用量与成本如何用两行代码完成接入与配置以及 LlamaIndex 底层的instrumentation模块Dispatcher / Span / Event 体系是如何让这种自动追踪成为可能的。读完本文你可以把 Graphsignal 接入自己的 LlamaIndex 项目并理解其背后 LlamaIndex 原生的可观测性机制为后续对接其他观测平台打下基础。一、Graphsignal 能追踪 LlamaIndex 中的什么Graphsignal 是一个面向 AI Agent 与 LLM 应用的观测observability平台其目标是帮助开发者确认 AI 应用按预期运行。接入 LlamaIndex 后它会自动追踪并监控 LlamaIndex 的执行围绕查询query、检索retrieval、索引index三类操作产出 Traces 与 Metrics。根据官方集成文档自动采集到的执行细节包括观测维度说明Prompts提示词发送给 LLM 的完整提示内容Completions补全LLM 的返回结果Embedding statistics嵌入统计向量化环节的相关统计信息Retrieved nodes检索节点检索命中的具体文档节点Parameters参数各环节使用的调用参数Latency延迟各操作的耗时表现Exceptions异常执行过程中捕获的异常此外当应用使用 OpenAI API 时Graphsignal 会额外提供token 用量与成本洞察并可按部署deployment、模型model或任意上下文维度聚合分析。这使得团队不仅能排查某次回答为什么不对还能回答这次调用花了多少钱、哪个模型最贵这类运营问题。需要说明的是Graphsignal 本体是外部 SDKgraphsignal包并不位于 LlamaIndex 仓库内仓库内提供的是让这种第三方观测得以实现的instrumentation 基础设施。两者的分工在下文展开。二、安装与配置两行代码完成接入接入流程非常简单——安装 SDK 并调用一次configurepip install graphsignalimport graphsignal # API key 可以直接传入也可以通过 GRAPHSIGNAL_API_KEY 环境变量提供 graphsignal.configure( api_keymy-api-key, deploymentmy-llama-index-app-prod )关键点说明api_key在 Graphsignal 平台创建账号后获取用于向平台上报 trace 数据。文档同时支持通过环境变量GRAPHSIGNAL_API_KEY提供密钥生产环境中推荐用环境变量而非硬编码deployment部署名称如my-llama-index-app-prod用于在平台侧区分不同环境/版本的应用是后续按部署维度做成本与延迟分析的基础配置完成后无需修改任何 LlamaIndex 业务代码——LlamaIndex 内部各组件产生的事件与 span 会经由 instrumentation 机制自动流向 Graphsignal。三、追踪任意函数start_trace上下文管理器LlamaIndex 的自动追踪覆盖了 LLM 调用、检索、合成等内部环节但应用自身的外部代码如自定义数据加载、外部 API 调用默认不在覆盖范围内。Graphsignal 提供了start_trace上下文管理器或装饰器来补充这部分with graphsignal.start_trace(load-external-data): reader.load_data()这样reader.load_data()的执行会被作为一个具名 traceload-external-data上报与 LlamaIndex 内部产生的 trace 串在同一条执行链路中便于在平台里查看完整的时间线。四、自动追踪的底层支撑LlamaIndex 的 instrumentation 模块自动二字的实现位于 LlamaIndex 仓库内。自 v0.10.20 起LlamaIndex 用新的instrumentation模块取代了早期的callbacks模块在过渡期内两者并存详见 Instrumentation 模块指南。该模块由五类核心构件组成Event表示应用代码执行过程中某一时刻发生的单次事件EventHandler监听事件并在事件发生时执行自定义逻辑Span表示一段有起止时间的执行流程内部包含若干事件SpanHandler负责 span 的进入enter、退出exit与丢弃drop即因异常提前结束Dispatcher向所有已注册的 handler 分发事件与 span 信号。这些构件在仓库中的实现位于独立的 llama-index-instrumentation 包核心实现在 dispatcher.py。4.1 事件从哪里来内建的观测事件类型LlamaIndex 核心库在 instrumentation/events 目录下定义了一组覆盖 RAG 全链路的事件类型与 Graphsignal 文档中列举的观测维度一一对应llm.py—— LLM 调用的开始/流式/结束事件retrieval.py—— 检索事件对应retrieved nodesembedding.py—— 向量化事件对应embedding statisticsquery.py/synthesis.py—— 查询与响应合成事件agent.py/chat_engine.py—— Agent 与对话引擎事件rerank.py—— 重排事件。当 LlamaIndex 内部的查询引擎执行一次query时这些事件与 span 会由所在模块的 dispatcher 自动发出。4.2 Span 的生命周期enter / exit / dropBaseSpanHandler 定义了 span 的三种状态迁移span_enter创建并登记一个打开的 spanspan_exit将其移入completed_spansspan_drop处理执行异常时的提前结束。仓库自带的 SimpleSpanHandler 是这一机制的参考实现它在 span 退出时记录结束时间并计算duration即各操作的延迟来源在 drop 时把异常信息写入 span 的metadata即exceptions维度的来源并可以通过print_trace_trees()把完成的 span 按父子关系组装成 trace 树打印出来。4.3 Dispatcher 的层级与传播全局观测如何生效Dispatcher 通过name/parent_name构成一棵树默认propagateTrue事件与 span 信号会沿父链向上传播——这与 Pythonlogging模块的层级模型类似。其含义是挂在 root dispatcher 上的 handler 能收到整个应用中所有子模块发出的事件而挂在某个子模块 dispatcher 上的 handler 只订阅该模块内部的事件。这就是 Graphsignal以及所有基于 instrumentation 的观测集成配置一次、全局生效的原理SDK 在配置时把自己的 span/event handler 注册到 dispatcher 树上此后 LlamaIndex 核心库与扩展包中任何位置发出的事件与 span 都会自动流经该 handler被序列化上报到 Graphsignal 平台。Dispatcher 还内置了同步/异步兼容的dispatcher.span装饰器见 dispatcher.py它为被装饰函数自动生成带 UUID 的 span id、通过active_span_idContextVar 维护父子关系、在函数返回时触发span_exit、在异常时触发span_drop并发出SpanDropEvent对async函数与返回Future的结果也分别做了处理保证并发场景下 trace 树的层级依然正确。4.4 跨进程传播上下文对于需要将 trace 延续到子进程或多进程边界的场景Dispatcher 还提供了capture_propagation_context()/restore_propagation_context()方法前者在所有已注册 span handler 上采集可序列化的传播上下文并附带当前instrument_tags后者在另一个进程中恢复它使新产生的 span 能正确挂接回原 trace。这为分布式部署下的链路连续性提供了基础。五、完整接入示例结合上文一个最小可运行的接入形态如下基于 Graphsignal 集成文档的官方用法# 1. 配置 Graphsignal应用入口先于任何 LlamaIndex 调用 import graphsignal graphsignal.configure( api_keymy-api-key, # 或设置环境变量 GRAPHSIGNAL_API_KEY deploymentmy-llama-index-app-prod, ) # 2. 正常构建 LlamaIndex 应用无需额外埋点 from llama_index.core import SimpleDirectoryReader, VectorStoreIndex documents SimpleDirectoryReader(input_dir./data/paul_graham).load_data() index VectorStoreIndex.from_documents(documents) query_engine index.as_query_engine() # 3. 外部代码可手动补 trace with graphsignal.start_trace(load-external-data): extra fetch_external_data() # 4. 查询会自动产出完整 traceprompts、completions、 # retrieved nodes、latency、exceptions # 以及 OpenAI token counts 与 costs response query_engine.query(What did Paul do?)运行后在 Graphsignal 平台中即可按部署/模型/上下文维度查看每条查询的执行树、延迟分布与成本消耗。六、在 LlamaIndex 观测体系中的定位与注意事项LlamaIndex 的 Observability 总览 页面列出了官方支持的一整套观测集成OpenTelemetry、Arize Phoenix、Langfuse、Weave、MLflow、SigNoz、Opik 等。Graphsignal 属于社区集成文档community/integrations中的一员特点是接入方式最轻不需要通过set_global_handler注册也不依赖 OpenInference/OTel 标准链路仅靠graphsignal.configure()一步完成观测覆盖面查询、检索、索引操作全链路外加 OpenAI 场景下的 token 与成本维度前提条件LlamaIndex 需使用 v0.10.20 及以上版本instrumentation 模块自该版本起提供Graphsignal SDK 为外部依赖其 APIconfigure、start_trace等以graphsignal包自身文档为准。如果后续需要把同一套 trace 同时导出给多个平台例如既上报 Graphsignal 又走 OpenTelemetry 链路可以基于 Instrumentation 模块指南 中自定义 EventHandler / SpanHandler的扩展点将多个 handler 挂到同一个 dispatcher 上——这正是 instrumentation 模块化设计的意图。参考Graphsignal 集成文档本文主体Instrumentation 模块指南Observability 集成总览llama-index-instrumentation 包说明Dispatcher 核心实现SimpleSpanHandler 参考实现内建事件类型目录【免费下载链接】llama_indexLlamaIndex is the document processing platform for AI项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考