← 文章 / AI技术
signoz 12天前 · 2026-11-10 10:04:34 · 15 阅读

LlamaIndex 的可观测性与监控(基于 OpenTelemetry)

本指南将带你完成基于 Python 的 LlamaIndex 应用的观测性与监控配置,并通过 OpenTelemetry 将遥测数据流式传输至 SigNoz Cloud。完成设置后,你将能够监控 LlamaIndex 中特定的 AI 操作,例如文档摄取、文档检索、用户查询、文本生成和用户反馈,同时通过详细的 span 捕获请求时长、节点与查询输入、模型输出、检索评分、元数据以及管道中的中间步骤。

通过为 RAG 工作流添加遥测探针,你可以实现检索和生成管道的全链路可观测性。这在构建生产级、面向开发者的工具时尤为关键,因为洞察模型行为、延迟瓶颈和检索准确率至关重要。借助 SigNoz,你可以端到端地追踪每个用户问题,从提示词到响应,并持续优化性能和可靠性。

如需快速上手,请参考我们示例 LlamaIndex RAG 问答机器人,该示例集成了基于 OpenInference 的 OpenTelemetry 监控。你可以在这里查看完整代码仓库 here。

先决条件

  • 一个使用 Python 3.8+ 的应用程序
  • 已在应用中集成 LlamaIndex,并配置好文档摄取和查询接口
  • 对 RAG(检索增强生成)工作流有基本了解
  • SigNoz 环境配置(二选一):
  • 已安装 pip 以管理 Python 包
  • 具备互联网连接,以便向 SigNoz Cloud 发送遥测数据
  • (可选但推荐) 创建一个 Python 虚拟环境以隔离依赖关系

为 LlamaIndex 应用添加探针

为了在不修改核心应用逻辑的情况下从 LlamaIndex 捕获详细遥测数据,我们采用 OpenInference。这是一个由社区驱动的标准,基于 OpenTelemetry 构建,为 LlamaIndex 等流行 AI 框架提供预构建的探针功能。这允许你以最少配置即可追踪 LlamaIndex 应用。

如何在你这里设置 OpenInference 埋点 LlamaIndex 应用的详细说明,请查看这里。

无需代码(推荐)代码

无代码自动埋点适合快速上手,只需极少代码改动。如果你不想修改应用代码、并且使用的是标准 instrumentor 库,这是获取可观测性能力的理想方式。

步骤 1:在 Python 环境中安装必要的包。

复制
pip install \
  opentelemetry-distro \
  opentelemetry-exporter-otlp \
  opentelemetry-instrumentation-httpx \
  opentelemetry-instrumentation-system-metrics \
  llama-index \
  openinference-instrumentation-llama-index

步骤 2:添加自动埋点

复制
opentelemetry-bootstrap --action=install

步骤 3:配置日志级别

为确保日志能被正确采集和导出,需将 root logger 配置为输出 INFO 及以上级别的日志:

复制
import logging
 
logging.getLogger().setLevel(logging.INFO)

这会把 root logger 的最低日志级别设为 INFO,确保 logger.info() 调用以及更高级别的日志(WARNING、ERROR、CRITICAL)能被 OpenTelemetry 日志自动埋点捕获并发送到 SigNoz。

步骤 4:运行示例

复制
from llama_index.llms.openai import OpenAI
 
llm = OpenAI(model="gpt-4o")
 
response = llm.complete("Hello, world!")
print(response)

📌 注意:运行代码前,请确保已正确设置 OPENAI_API_KEY 环境变量,填入你的 API key。

步骤 5:以自动埋点方式运行应用

复制
OTEL_RESOURCE_ATTRIBUTES="service.name=<service_name>" \
OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.<region>.signoz.cloud:443" \
OTEL_EXPORTER_OTLP_HEADERS="signoz-ingestion-key=<your-ingestion-key>" \
OTEL_EXPORTER_OTLP_PROTOCOL=grpc \
OTEL_TRACES_EXPORTER=otlp \
OTEL_METRICS_EXPORTER=otlp \
OTEL_LOGS_EXPORTER=otlp \
OTEL_PYTHON_LOG_CORRELATION=true \
OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true \
opentelemetry-instrument <your_run_command>
  • <service_name>:你的服务名称
  • <region>:你的 SigNoz Cloud 区域
  • <your-ingestion-key>:你的 SigNoz 采集密钥
  • 将 <your_run_command> 替换为实际运行应用程序的命令。例如:python main.py
Info

使用自托管 SigNoz?大多数步骤相同。若要适配本指南,请按照云端到自托管所述,更新端点并移除采集密钥头部。

基于代码的埋点为你提供对遥测配置的细粒度控制。当你需要自定义资源属性、采样策略,或与现有的可观测性基础设施集成时,请使用此方法。

步骤 1:安装 OpenInference 和 OpenTelemetry 相关包

Copy
pip install openinference-instrumentation-llama-index \
opentelemetry-exporter-otlp \
opentelemetry-sdk \
llama-index

步骤 2:在 Python 应用程序中导入必要的模块

Copy
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.sdk.resources import Resource
from openinference.instrumentation.llama_index import LlamaIndexInstrumentor

步骤 3:配置 OpenTelemetry Tracer Provider,以将 trace 直接发送到 SigNoz Cloud

Copy
resource = Resource.create({"service.name": "<service_name>"})
provider = TracerProvider(resource=resource)
span_exporter = OTLPSpanExporter(
    endpoint="https://ingest.<region>.signoz.cloud:443/v1/traces",
    headers={"signoz-ingestion-key": "<your-ingestion-key>"},
)
provider.add_span_processor(BatchSpanProcessor(span_exporter))
  • <service_name>:你的服务名称
  • <region>:你的 SigNoz Cloud 区域
  • <your-ingestion-key>:你的 SigNoz ingestion key
Info

使用自托管 SigNoz?大部分步骤完全相同。只需参考 Cloud → Self-Hosted 文档,修改 endpoint 并移除 ingestion key 请求头即可。

第 4 步:使用 OpenInference 和配置好的 Tracer Provider 对 LlamaIndex 进行插桩

使用 OpenInference 提供的 LlamaIndexInstrumentor,即可在你的 OpenTelemetry 配置下自动追踪 LlamaIndex 的各项操作:

Copy
LlamaIndexInstrumentor().instrument(tracer_provider=provider)

📌 注意:请把这段代码放在应用逻辑的最前面——在任何 LlamaIndex 函数被调用之前——以确保遥测数据能被正确采集。

第 5 步:运行示例

Copy
from llama_index.llms.openai import OpenAI
 
llm = OpenAI(model="gpt-4o")
 
response = llm.complete("Hello, world!")
print(response)

📌 提示:运行代码前,请确保已正确设置 OPENAI_API_KEY 环境变量,填入你的 API key。

现在,你的 LlamaIndex 命令会自动生成 traces、spans 和 attributes。

最后,你可以在 SigNoz Cloud 的 traces 标签页中查看这些数据:

Traces View
LlamaIndex 应用的 Traces

点击 SigNoz 中的某个 trace ID,就能看到该 trace 的详细视图,包括所有关联的 spans 及其 events 和 attributes。

Detailed Traces View
LlamaIndex 应用的详细 trace 视图

在 AI Observability 中查看

AI 可观测性展示了 LlamaIndex 应用中 LLM 调用的成本、Token 用量、延迟和错误。在 SigNoz 中,打开 AI 可观测性,并在 service_name 过滤器中选择你的服务。

AI 可观测性概览仪表盘,包含 LLM 调用的成本、Token 和延迟面板
AI 可观测性概览仪表盘

查询单个 Trace 时,打开 Explorer 选项卡。Trace 视图为每个 Trace 显示一行,包含 Token、成本和调用次数等总计值。你可以按这些总计值进行过滤、聚合和排序,例如 trace.total_tokens > 1000。详情参见AI 可观测性 Explorer。

如果面板保持空白,请确保你的 Spans 携带了遥测要求中指定的属性。要映射其他属性名称,请使用属性映射。

相关集成

追踪你的 LLM 应用和检索堆栈的其余部分:

延伸阅读:

  • Re
原始来源: signoz

评论 (0)