集成框架LlamaIndex

将 Litefuse 与 LlamaIndex 集成

本 notebook 提供一个分步指南，演示如何将 Litefuse 与 LlamaIndex 集成，从而对你的 LLM 应用实现可观测性与调试。

什么是 LlamaIndex？ LlamaIndex (GitHub) 是一个先进的 “data framework”，专为用私有数据增强 LLM 而设计。它通过多样的数据连接器简化对各种数据源与格式（API、PDF、文档、SQL 等）的集成，并将数据结构化为索引和图，以便与 LLM 兼容。平台提供精巧的检索/查询接口，为 LLM 输入增加上下文相关的输出。

什么是 Litefuse？ Litefuse 是一个开源的 AI Agent 可观测性与评估平台。它为 AI 应用提供 tracing 与监控能力。Litefuse 通过提供详细的洞察以及通过原生集成、OpenTelemetry 和专用 SDK 与众多工具和框架对接，帮助开发者调试、分析并优化其 AI 系统。

快速开始

我们通过一个实际示例演示如何使用 LlamaIndex 并将其与 Litefuse 集成，以获得全面的 tracing。

第 1 步：安装依赖

%pip install langfuse openinference-instrumentation-llama-index llama-index-llms-openai llama-index -U

第 2 步：配置 Langfuse SDK

接下来，设置你的 Litefuse API Key。可通过注册免费的 Litefuse Cloud 账号或 自托管 Litefuse 获取这些 Key。这些环境变量是 Langfuse 客户端鉴权并向 Litefuse 项目发送数据所必需的。

import os
 
# Get keys for your project from the project settings page: https://litefuse.cloud
 
os.environ["LANGFUSE_PUBLIC_KEY"] = "pk-lf-..." 
os.environ["LANGFUSE_SECRET_KEY"] = "sk-lf-..." 
os.environ["LANGFUSE_BASE_URL"] = "https://litefuse.cloud"
 
# Your OpenAI key
os.environ["OPENAI_API_KEY"] = "sk-proj-..."

设置好环境变量后，我们就可以初始化 Langfuse 客户端了。get_client() 会使用环境变量中提供的凭证来初始化 Langfuse 客户端。

from langfuse import get_client
 
langfuse = get_client()
 
# Verify connection
if langfuse.auth_check():
    print("Langfuse client is authenticated and ready!")
else:
    print("Authentication failed. Please check your credentials and host.")

第 3 步：初始化 LlamaIndex Instrumentation

现在我们初始化 OpenInference LlamaIndex instrumentation。这个第三方 instrumentation 会自动捕获 LlamaIndex 的操作并将 OpenTelemetry (OTel) span 导出到 Litefuse。

from openinference.instrumentation.llama_index import LlamaIndexInstrumentor
 
# Initialize LlamaIndex instrumentation
LlamaIndexInstrumentor().instrument()

第 4 步：基础 LlamaIndex 应用

让我们创建一个简单的 LlamaIndex 应用。在本示例中，我们创建一个可以回答问题的简单查询引擎。这将作为演示 Litefuse tracing 的基础。

from llama_index.llms.openai import OpenAI
 
llm = OpenAI(model="gpt-4o")
 
with langfuse.start_as_current_observation(as_type="span", name="llama-index-trace"):
    response = llm.complete("Hello, world!")
    print(response)
 
langfuse.flush()

第 5 步：在 Litefuse 中查看 Trace

执行应用后，进入你的 Litefuse Trace 表。你将看到应用执行的详细 trace，包括 LLM 调用、检索操作、输入、输出以及性能指标的洞察。Trace 将完整呈现从查询处理、文档检索到响应生成的全过程。

Litefuse 中的示例 Trace

Litefuse 中的示例 Trace

Interoperability with the Python SDK

You can use this integration together with the Litefuse SDKs to add additional attributes to the observation.

The @observe() decorator provides a convenient way to automatically wrap your instrumented code and add additional attributes to the observation.

from langfuse import observe, propagate_attributes, get_client
 
langfuse = get_client()
 
@observe()
def my_llm_pipeline(input):
    # Add additional attributes (user_id, session_id, metadata, version, tags) to all spans created within this execution scope
    with propagate_attributes(
        user_id="user_123",
        session_id="session_abc",
        tags=["agent", "my-observation"],
        metadata={"email": "user@litefuse.ai"},
        version="1.0.0"
    ):
 
        # YOUR APPLICATION CODE HERE
        result = call_llm(input)
 
        return result
 
# Run the function
my_llm_pipeline("Hi")

Learn more about using the Decorator in the Langfuse SDK instrumentation docs.

Troubleshooting

No observations appearing

First, enable debug mode in the Python SDK:

export LANGFUSE_DEBUG="True"

Then run your application and check the debug logs:

  • OTel observations appear in the logs: Your application is instrumented correctly but observations are not reaching Litefuse. To resolve this:
    1. Call langfuse.flush() at the end of your application to ensure all observations are exported.
    2. Verify that you are using the correct API keys and base URL.
  • No OTel spans in the logs: Your application is not instrumented correctly. Make sure the instrumentation runs before your application code.
Unwanted observations in Litefuse

The Langfuse SDK is based on OpenTelemetry. Other libraries in your application may emit OTel spans that are not relevant to you. These still count toward your billable units, so you should filter them out. See Unwanted spans in Litefuse for details.

Missing attributes

Some attributes may be stored in the metadata object of the observation rather than being mapped to the Litefuse data model. If a mapping or integration does not work as expected, please raise an issue on GitHub.

Next Steps

Once you have instrumented your code, you can manage, evaluate and debug your application:

Manage prompts in LitefuseAdd evaluation scoresRun LLM-as-a-judge EvaluatorsCreate datasetsCreate custom dashboardsTest queries in the Playground
LiveKitLlamaIndex Workflows
这个页面对你有帮助吗？
支持