可观测性

LlamaIndex 提供一键式可观测性🔭，使您能够在生产环境中构建基于原则的 LLM 应用。

在数据上进行 LLM 应用（RAG 系统、代理）的原则性开发的一个关键要求是能够观察、调试和评估您的系统 - 包括整体和每个组件。

此功能使您能够将 LlamaIndex 库与我们的合作伙伴提供的强大可观测性/评估工具无缝集成。只需配置一次变量，您就能执行以下操作：

• 查看 LLM/prompt 输入/输出
• 确保任何组件（LLM、嵌入）的输出符合预期
• 查看索引和查询的调用跟踪

每个提供商都有相似之处和不同之处。请查看下方以获取每个提供商的完整指南列表！

注意

可观测性现在通过instrumentation 模块处理（在 v0.10.20 及更高版本中可用）。

本页提到的许多工具和集成使用了我们的旧版 CallbackManager 或不使用 set_global_handler。我们已将这些集成标记出来！

使用模式

要切换，您通常只需执行以下操作：

from llama_index.core import set_global_handler

# general usage
set_global_handler("<handler_name>", **kwargs)

请注意，set_global_handler 的所有 kwargs 都将传递给底层的回调处理程序。

就这样！执行将无缝地导流到下游服务，您将能够访问诸如查看应用程序执行跟踪等功能。

合作伙伴一键式集成

LlamaTrace (托管式 Arize Phoenix)

我们与 Arize 合作推出了 LlamaTrace，这是一个托管式跟踪、可观测性和评估平台，与 LlamaIndex 开源用户原生协作，并集成了 LlamaCloud。

这是基于开源的 Arize Phoenix 项目构建的。Phoenix 通过提供以下功能，为监控您的模型和 LLM 应用提供了笔记本优先的体验：

• LLM 跟踪 - 跟踪您的 LLM 应用的执行过程，以了解其内部结构，并排查检索和工具执行等相关问题。
• LLM 评估 - 利用大型语言模型的能力来评估您的生成模型或应用的关联性、毒性等。

使用模式

要安装集成包，请执行 pip install -U llama-index-callbacks-arize-phoenix。

然后在 LlamaTrace 上创建一个帐户：https://llamatrace.com/login。创建一个 API 密钥并将其放入下方的 PHOENIX_API_KEY 变量中。

然后运行以下代码：

# Phoenix can display in real time the traces automatically
# collected from your LlamaIndex application.
# Run all of your LlamaIndex applications as usual and traces
# will be collected and displayed in Phoenix.

# setup Arize Phoenix for logging/observability
import llama_index.core
import os

PHOENIX_API_KEY = "<PHOENIX_API_KEY>"
os.environ["OTEL_EXPORTER_OTLP_HEADERS"] = f"api_key={PHOENIX_API_KEY}"
llama_index.core.set_global_handler(
    "arize_phoenix", endpoint="https://llamatrace.com/v1/traces"
)

...

指南

• 带有 LlamaTrace 的 LlamaCloud Agent

MLflow

MLflow 是一个开源的 MLOps/LLMOps 平台，专注于机器学习项目的完整生命周期，确保每个阶段都可管理、可跟踪和可复现。MLflow Tracing 是一种基于 OpenTelemetry 的跟踪功能，支持 LlamaIndex 应用的一键式 instrumentation。

使用模式

由于 MLflow 是开源的，您可以直接使用，无需创建帐户或设置 API 密钥。安装 MLflow 包后即可直接开始编写代码！

import mlflow

mlflow.llama_index.autolog()  # Enable mlflow tracing

指南

MLflow LlamaIndex 集成还提供了实验跟踪、评估、依赖管理等功能。有关更多详细信息，请查阅 MLflow 文档。

支持表格

MLflow Tracing 支持 LlamaIndex 的所有功能。一些新功能，如 AgentWorkflow，需要 MLflow >= 2.18.0。

聊天引擎的流式传输 - 精简问题模式	异步	引擎	多模态应用	Workflow	AgentWorkflow
✅	✅	✅	✅	✅ (>= 2.18)	✅ (>= 2.18)

OpenLLMetry

OpenLLMetry 是一个基于 OpenTelemetry 的开源项目，用于跟踪和监控 LLM 应用。它可以连接到所有主要的可观测性平台，并在几分钟内完成安装。

使用模式

from traceloop.sdk import Traceloop

Traceloop.init()

指南

• OpenLLMetry

Arize Phoenix (本地)

您也可以选择通过开源项目使用 Phoenix 的本地实例。

在这种情况下，您无需在 LlamaTrace 上创建帐户或为 Phoenix 设置 API 密钥。Phoenix 服务器将在本地启动。

使用模式

要安装集成包，请执行 pip install -U llama-index-callbacks-arize-phoenix。

然后运行以下代码：

# Phoenix can display in real time the traces automatically
# collected from your LlamaIndex application.
# Run all of your LlamaIndex applications as usual and traces
# will be collected and displayed in Phoenix.

import phoenix as px

# Look for a URL in the output to open the App in a browser.
px.launch_app()
# The App is initially empty, but as you proceed with the steps below,
# traces will appear automatically as your LlamaIndex application runs.

import llama_index.core

llama_index.core.set_global_handler("arize_phoenix")
...

示例指南

• 使用 Pinecone 和 Arize Phoenix 的自动检索指南
• Arize Phoenix 跟踪教程

Langfuse 🪢

Langfuse 是一个开源的 LLM 工程平台，帮助团队协作调试、分析和迭代 LLM 应用。通过 Langfuse 集成，您可以跟踪和监控 LlamaIndex 应用的性能、跟踪和指标。上下文增强和 LLM 查询过程的详细跟踪会被捕获，并可以直接在 Langfuse UI 中查看。

使用模式

确保您已安装 llama-index 和 langfuse。

pip install llama-index langfuse

在您的 LlamaIndex 应用的根目录下，注册 Langfuse 的 LlamaIndexInstrumentor。实例化 LlamaIndexInstrumentor 时，请确保通过环境变量或构造函数参数正确配置您的 Langfuse API 密钥和主机 URL。

import os

# Get keys for your project from the project settings page: https://cloud.langfuse.com
os.environ["LANGFUSE_PUBLIC_KEY"] = "pk-lf-..."
os.environ["LANGFUSE_SECRET_KEY"] = "sk-lf-..."
os.environ["LANGFUSE_HOST"] = "https://cloud.langfuse.com"  # 🇪🇺 EU region
# os.environ["LANGFUSE_HOST"] = "https://us.cloud.langfuse.com" # 🇺🇸 US region

from langfuse.llama_index import LlamaIndexInstrumentor

# Get your keys from the Langfuse project settings page and set them as environment variables
# or pass them as arguments when initializing the instrumentor

instrumentor = LlamaIndexInstrumentor()

# Automatically trace all LlamaIndex operations
instrumentor.start()

# ... your LlamaIndex index creation ...
index.as_query_engine().query("What is the capital of France?")

# Flush events to langfuse
instrumentor.flush()

您现在可以在 Langfuse 中查看 LlamaIndex 应用的日志

LlamaIndex 示例跟踪

Langfuse 中的示例跟踪链接

示例指南

• Langfuse 文档
• 端到端示例 notebook
• 跟踪 LlamaIndex Agents
• Llama Debug 处理器

Literal AI

Literal AI 是首选的 LLM 评估和可观测性解决方案，使工程和产品团队能够可靠、更快、大规模地交付 LLM 应用。这通过协作开发周期实现，包括 prompt 工程、LLM 可观测性、LLM 评估和 LLM 监控。会话线程和 Agent 运行可以自动记录在 Literal AI 上。

开始并试用 Literal AI 的最简单方法是在我们的云实例上注册。然后您可以导航到设置，获取您的 API 密钥，并开始日志记录！

使用模式

• 使用 pip install literalai 安装 Literal AI Python SDK
• 在您的 Literal AI 项目中，转到设置并获取您的 API 密钥
• 如果您使用的是自托管的 Literal AI 实例，请同时记下其基本 URL

然后将以下行添加到您的应用代码中：

from llama_index.core import set_global_handler

# You should provide your Literal AI API key and base url using the following environment variables:
# LITERAL_API_KEY, LITERAL_API_URL
set_global_handler("literalai")

示例指南

• Literal AI 与 Llama Index 集成
• 使用 LLamaIndex 构建问答应用并使用 Literal AI 进行监控

Comet Opik

Opik 是一个由 Comet 构建的开源端到端 LLM 评估平台。

要开始使用，只需在 Comet 上注册一个帐户并获取您的 API 密钥。

使用模式

• 使用 pip install opik 安装 Opik Python SDK
• 在 Opik 中，从用户菜单中获取您的 API 密钥。
• 如果您使用的是自托管的 Opik 实例，请同时记下其基本 URL。

如果您正在使用自托管实例，您可以使用环境变量 OPIK_API_KEY、OPIK_WORKSPACE 和 OPIK_URL_OVERRIDE 来配置 Opik。您可以通过调用以下内容来设置这些变量：

export OPIK_API_KEY="<OPIK_API_KEY>"
export OPIK_WORKSPACE="<OPIK_WORKSPACE - Often the same as your API key>"

# Optional
#export OPIK_URL_OVERRIDE="<OPIK_URL_OVERRIDE>"

现在，您可以通过设置全局处理程序来使用 Opik 与 LlamaIndex 的集成

from llama_index.core import Document, VectorStoreIndex, set_global_handler

# You should provide your OPIK API key and Workspace using the following environment variables:
# OPIK_API_KEY, OPIK_WORKSPACE
set_global_handler(
    "opik",
)

# This example uses OpenAI by default so don't forget to set an OPENAI_API_KEY
index = VectorStoreIndex.from_documents([Document.example()])
query_engine = index.as_query_engine()

questions = [
    "Tell me about LLMs",
    "How do you fine-tune a neural network ?",
    "What is RAG ?",
]

for question in questions:
    print(f"> \033[92m{question}\033[0m")
    response = query_engine.query(question)
    print(response)

您将在 Opik 中看到以下跟踪：

示例指南

• LlamaIndex + Opik 文档页面
• LlamaIndex 集成 cookbook

Argilla

Argilla 是一个协作工具，适用于需要为其项目构建高质量数据集的 AI 工程师和领域专家。

要开始使用，您需要部署 Argilla 服务器。如果您尚未部署，可以按照此指南轻松部署。

使用模式

• 使用 pip install argilla-llama-index 安装 Argilla LlamaIndex 集成包
• 初始化 ArgillaHandler。<api_key> 位于您的 Argilla Space 的 My Settings 页面，但请确保您使用创建该 Space 的 owner 帐户登录。<api_url> 是您浏览器中显示的 URL。
• 将 ArgillaHandler 添加到调度程序。

from llama_index.core.instrumentation import get_dispatcher
from argilla_llama_index import ArgillaHandler

argilla_handler = ArgillaHandler(
    dataset_name="query_llama_index",
    api_url="http://localhost:6900",
    api_key="argilla.apikey",
    number_of_retrievals=2,
)
root_dispatcher = get_dispatcher()
root_dispatcher.add_span_handler(argilla_handler)
root_dispatcher.add_event_handler(argilla_handler)

示例指南

• Argilla LlamaIndex 集成入门
• 其他示例教程

其他合作伙伴一键式集成（旧模块）

这些合作伙伴集成使用我们的旧版 CallbackManager 或第三方调用。

Langfuse

此集成已弃用。我们建议使用此处描述的基于新 instrumentation 的 Langfuse 集成。

使用模式

from llama_index.core import set_global_handler

# Make sure you've installed the 'llama-index-callbacks-langfuse' integration package.

# NOTE: Set your environment variables 'LANGFUSE_SECRET_KEY', 'LANGFUSE_PUBLIC_KEY' and 'LANGFUSE_HOST'
# as shown in your langfuse.com project settings.

set_global_handler("langfuse")

指南

• 使用 PostHog 和 Langfuse 分析和调试 LlamaIndex 应用程序
• 使用 PostHog 进行 Langfuse 跟踪

DeepEval

DeepEval (由 Confident AI 提供) 是一个用于 LLM 应用的开源评估框架。当您使用 DeepEval 当前提供的 14+ 个默认指标（摘要、幻觉、答案相关性、忠实度、RAGAS 等）对您的 LLM 应用进行“单元测试”时，您可以通过与 LlamaIndex 的此跟踪集成来调试失败的测试用例，或者通过 DeepEval 的托管评估平台 Confident AI 来调试生产环境中不满意的评估，该平台在生产环境中运行无参考评估。

使用模式

from llama_index.core import set_global_handler

set_global_handler("deepeval")

# NOTE: Run 'deepeval login' in the CLI to log traces on Confident AI, DeepEval's hosted evaluation platform.
# Run all of your LlamaIndex applications as usual and traces
# will be collected and displayed on Confident AI whenever evaluations are ran.
...

Weights and Biases Prompts

Prompts 允许用户在索引构建和查询期间记录/跟踪/检查 LlamaIndex 的执行流程。它还允许用户对他们的索引进行版本控制。

使用模式

from llama_index.core import set_global_handler

set_global_handler("wandb", run_args={"project": "llamaindex"})

# NOTE: No need to do the following
from llama_index.callbacks.wandb import WandbCallbackHandler
from llama_index.core.callbacks import CallbackManager
from llama_index.core import Settings

# wandb_callback = WandbCallbackHandler(run_args={"project": "llamaindex"})
# Settings.callback_manager = CallbackManager([wandb_callback])

# access additional methods on handler to persist index + load index
import llama_index.core

# persist index
llama_index.core.global_handler.persist_index(graph, index_name="my_index")
# load storage context
storage_context = llama_index.core.global_handler.load_storage_context(
    artifact_url="ayut/llamaindex/my_index:v0"
)

指南

• 输出解析器

OpenInference

OpenInference 是一个用于捕获和存储 AI 模型推理的开放标准。它使得使用 Phoenix 等 LLM 可观测性解决方案进行 LLM 应用的实验、可视化和评估成为可能。

使用模式

import llama_index.core

llama_index.core.set_global_handler("openinference")

# NOTE: No need to do the following
from llama_index.callbacks.openinference import OpenInferenceCallbackHandler
from llama_index.core.callbacks import CallbackManager
from llama_index.core import Settings

# callback_handler = OpenInferenceCallbackHandler()
# Settings.callback_manager = CallbackManager([callback_handler])

# Run your LlamaIndex application here...
for query in queries:
    query_engine.query(query)

# View your LLM app data as a dataframe in OpenInference format.
from llama_index.core.callbacks.open_inference_callback import as_dataframe

query_data_buffer = llama_index.core.global_handler.flush_query_data_buffer()
query_dataframe = as_dataframe(query_data_buffer)

注意：要解锁 Phoenix 的功能，您需要定义额外的步骤来馈入查询/上下文数据帧。参见下方！

指南

• OpenInference 回调处理程序
• 使用 Arize Phoenix 评估搜索和检索

TruEra TruLens

TruLens 允许用户通过反馈函数和跟踪等功能来 instrument/评估 LlamaIndex 应用。

使用模式 + 指南

# use trulens
from trulens_eval import TruLlama

tru_query_engine = TruLlama(query_engine)

# query
tru_query_engine.query("What did the author do growing up?")

指南

• Trulens 指南
• LlamaIndex + TruLens 快速入门指南
• Google Colab

HoneyHive

HoneyHive 允许用户跟踪任何 LLM 工作流程的执行流程。用户可以调试和分析其跟踪，或自定义特定跟踪事件的反馈，以便从生产环境中创建评估或微调数据集。

使用模式

from llama_index.core import set_global_handler

set_global_handler(
    "honeyhive",
    project="My HoneyHive Project",
    name="My LLM Workflow Name",
    api_key="MY HONEYHIVE API KEY",
)

# NOTE: No need to do the following
from llama_index.core.callbacks import CallbackManager

# from honeyhive.utils.llamaindex_tracer import HoneyHiveLlamaIndexTracer
from llama_index.core import Settings

# hh_tracer = HoneyHiveLlamaIndexTracer(
#     project="My HoneyHive Project",
#     name="My LLM Workflow Name",
#     api_key="MY HONEYHIVE API KEY",
# )
# Settings.callback_manager = CallbackManager([hh_tracer])

使用 Perfetto 调试和分析您的 HoneyHive 跟踪

指南

• HoneyHive 回调处理程序

PromptLayer

PromptLayer 允许您跨 LLM 调用跟踪分析，标记、分析和评估用于各种用例的 prompt。将其与 LlamaIndex 结合使用，以跟踪您的 RAG prompt 的性能等。

使用模式

import os

os.environ["PROMPTLAYER_API_KEY"] = "pl_7db888a22d8171fb58aab3738aa525a7"

from llama_index.core import set_global_handler

# pl_tags are optional, to help you organize your prompts and apps
set_global_handler("promptlayer", pl_tags=["paul graham", "essay"])

指南

• PromptLayer

Langtrace

Langtrace 是一个强大的开源工具，支持 OpenTelemetry，旨在无缝跟踪、评估和管理 LLM 应用。Langtrace 直接与 LlamaIndex 集成，提供关于准确性、评估和延迟等性能指标的详细实时洞察。

安装

pip install langtrace-python-sdk

使用模式

from langtrace_python_sdk import (
    langtrace,
)  # Must precede any llm module imports

langtrace.init(api_key="<LANGTRACE_API_KEY>")

指南

• Langtrace

OpenLIT

OpenLIT 是一个 OpenTelemetry 原生的 GenAI 和 LLM 应用可观测性工具。它旨在通过一行代码即可轻松将可观测性集成到 GenAI 项目中。OpenLIT 为各种 LLM、VectorDB 和像 LlamaIndex 这样的框架提供 OpenTelemetry 自动 instrumentation。OpenLIT 提供对您的 LLM 应用性能的洞察、请求跟踪以及使用情况的概览指标，如成本、token 等等。

安装

pip install openlit

使用模式

import openlit

openlit.init()

指南

• OpenLIT 官方文档

AgentOps

AgentOps 帮助开发者构建、评估和监控 AI 代理。AgentOps 将帮助构建从原型到生产的代理，支持代理监控、LLM 成本跟踪、基准测试等。

安装

pip install llama-index-instrumentation-agentops

使用模式

from llama_index.core import set_global_handler

# NOTE: Feel free to set your AgentOps environment variables (e.g., 'AGENTOPS_API_KEY')
# as outlined in the AgentOps documentation, or pass the equivalent keyword arguments
# anticipated by AgentOps' AOClient as **eval_params in set_global_handler.

set_global_handler("agentops")

简单（LLM 输入/输出）

这个简单的可观测性工具会将每个 LLM 输入/输出对打印到终端。当您需要快速启用 LLM 应用的调试日志时非常有用。

使用模式

import llama_index.core

llama_index.core.set_global_handler("simple")

指南

• MLflow

更多可观测性

• 回调指南