尧图网站建设 
LlamaIndex × Literal AI 集成指南为 RAG 管道一键开启 LLM 可观测性与评估【免费下载链接】llama_indexLlamaIndex is the document processing platform for AI项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index本指南围绕 LlamaIndex 官方回调集成包llama-index-callbacks-literalai展开讲解如何将 LlamaIndex 构建的 RAG 应用无缝接入 Literal AI实现对话线程、Agent 运行过程的自动日志记录、LLM 可观测性与评估。读完本文你将掌握该集成的安装方式、一行代码接入方法、全部配置参数及其底层实现原理并能基于仓库源码理解其事件分发与缓存刷新的工作机制。集成概览什么是 Literal AI Callbacks 集成Literal AI 是一个面向 LLM 应用的评估Evaluation与可观测性Observability平台面向工程与产品团队帮助他们在构建 LLM 应用时打通提示词工程Prompt Engineering、LLM 可观测性、LLM 评估与 LLM 监控的协作开发闭环。其核心能力包括自动记录对话线程Conversation Threads与 Agent 运行过程Agent Runs。本项目提供的llama-index-callbacks-literalai集成包正是为了让 LlamaIndex 用户以最小成本获得上述能力它通过 LlamaIndex 的全局回调Callback机制为 RAG 管道提供 Literal AI 的“一键可观测性”one-click observability。该包声明于 pyproject.toml版本为 1.4.0要求 Python 3.10 且依赖llama-index-core0.13.0,0.15。从源码结构看该集成包非常精简仅包含三个核心文件base.py集成核心定义literalai_callback_handler工厂函数init.py导出literalai_callback_handlerliteralai_example.py可直接运行的接入示例。快速开始三步接入 Literal AI1. 注册账号并获取 API Key最简单的方式是注册 Literal AI 的云端实例cloud.getliteral.ai。注册完成后进入项目的Settings页面获取你的 API Key即可开始记录日志。若你使用自托管的 Literal AI 实例还需要记下其 Base URL。2. 安装依赖该集成本身通过llama-index-callbacks-literalai包安装LlamaIndex 全局处理器机制会自动导入它同时其底层依赖 Literal AI 官方 Python SDK。安装命令如下pip install llama-index-callbacks-literalai literalai需要注意literalaiSDK 是运行时的硬性前置依赖。在 base.py 中工厂函数内部通过try块导入literalai.LiteralClient与literalai.my_types.Environment若导入失败会抛出ImportError提示信息明确要求执行pip install -U literalai。也就是说即使llama-index-callbacks-literalai已安装缺少literalaiSDK 时集成仍无法工作。3. 一行代码开启全局处理在你的应用代码入口处调用set_global_handler并传入模式名literalaifrom llama_index.core import set_global_handler # API Key 与 Base URL 通过环境变量提供 # LITERAL_API_KEY, LITERAL_API_URL set_global_handler(literalai)这段代码来自 observability 文档。set_global_handler定义于 global_handlers.py它会把创建的处理器赋值给llama_index.core.global_handler从而在整个应用生命周期内生效。当eval_mode literalai时create_global_handler 会从llama_index.callbacks.literalai导入literalai_callback_handler并传入所有**eval_params——如果包未安装则抛出ImportError并提示执行pip install llama-index-callbacks-literalai。配置参数详解literalai_callback_handler工厂函数base.py接受以下参数全部可省略参数类型默认值说明batch_sizeint5LiteralClient 批量上报日志的批次大小。api_keyOptional[str]NoneLiteral AI API Key。为None时从环境变量LITERAL_API_KEY读取。urlOptional[str]NoneLiteral AI 实例 Base URL。为None时从环境变量LITERAL_API_URL读取云端默认https://cloud.getliteral.ai。environmentOptional[str]None环境标识如production、development会被转换为literalai.my_types.Environment类型。disabledboolFalse是否禁用上报能力。这些参数会被直接透传给LiteralClient(batch_size..., api_key..., url..., environment..., disabled...)用于构造底层客户端。也就是说参数的取值与语义以 Literal AI Python SDK 为准LlamaIndex 侧仅做透传与类型转换。在调用set_global_handler(literalai)时不传任何参数是最省事的用法——此时所有配置都依赖环境变量LITERAL_API_KEY与LITERAL_API_URL这也是官方推荐的做法。若需显式覆盖也可像 literalai_example.py 中注释展示的那样逐一传入set_global_handler( literalai, api_keylsk_xxx, urlhttps://cloud.getliteral.ai, batch_size5, environmentNone, disabledFalse, )完整可运行示例仓库在 examples/literalai_example.py 中提供了一个端到端示例先注册全局处理器再构建一个基于向量索引的查询引擎最后连续发起三个问题所有查询过程都会被自动记录到 Literal AIfrom llama_index.core import Document, VectorStoreIndex, set_global_handler # 所有配置参数均可省略。若未提供 api_key 和 url # 请通过环境变量 LITERAL_API_KEY、LITERAL_API_URL 提供 set_global_handler( literalai, # api_keylsk_xxx, # urlhttps://cloud.getliteral.ai, # batch_size5, # environmentNone, # disabledFalse ) # 该示例默认使用 OpenAI请设置 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)运行此脚本注意预先配置OPENAI_API_KEY与LITERAL_API_KEY后你可以在 Literal AI 控制台中逐条查看每次查询对应的对话线程、使用的提示词、模型调用与响应内容。底层原理从事件分发到缓存刷新理解这个集成如何工作关键在于看 base.py 的完整实现流程它分为三层第一层构造并插桩 Literal Clientfrom literalai import LiteralClient from literalai.my_types import Environment literalai_client LiteralClient( batch_sizebatch_size, api_keyapi_key, urlurl, environmentcast(Environment, environment), disableddisabled, ) literalai_client.instrument_llamaindex()调用instrument_llamaindex()后LiteralClient 会自动监听 LlamaIndex 内部的 LLM 调用与 Agent 执行过程这正是“对话线程与 Agent 运行自动记录”能力的来源。第二层注册 QueryEnd 事件处理器集成通过 LlamaIndex 的 Instrumentation 事件系统llama_index.core.instrumentation来感知查询生命周期from llama_index.core.instrumentation import get_dispatcher from llama_index.core.instrumentation.event_handlers import BaseEventHandler from llama_index.core.instrumentation.events.query import QueryEndEvent class QueryEndEventHandler(BaseEventHandler): 该处理器会在每次查询结束时刷新 Literal Client 缓存到 Literal AI。 classmethod def class_name(cls) - str: return QueryEndEventHandler def handle(self, event: BaseEvent, **kwargs) - None: try: if isinstance(event, QueryEndEvent): literalai_client.flush() except Exception as e: logging.error( Error in Literal AI global handler : %s, str(e), exc_infoTrue, ) dispatcher get_dispatcher() event_handler QueryEndEventHandler() dispatcher.add_event_handler(event_handler)这段代码表明QueryEndEventHandler订阅了全局 dispatcher 的QueryEndEvent一旦某次query_engine.query()结束就调用literalai_client.flush()把缓存的日志批量推送到 Literal AI 服务端。第三层容错与异常处理若literalaiSDK 未安装立即抛出带安装指引的ImportError若flush()过程中出现异常例如网络错误处理器不会让整个查询崩溃而是通过logging.error记录错误信息后继续执行。从源码结构看这种“缓存 查询结束统一刷新 异常隔离”的设计兼顾了性能批量上报、默认batch_size5与稳定性刷新失败不影响业务查询。在 LlamaIndex 可观测性体系中的位置该集成隶属于 LlamaIndex 的回调与可观测性Observability模块。在 observability 文档 中Literal AI 与 Langfuse、Comet Opik、Arize Phoenix 等并列共同构成 LlamaIndex 的第三方可观测性生态。官方将其定位为 LLM 评估与可观测性方案特别强调对话线程与 Agent 运行的自动日志能力。从 global_handlers.py 可以看到set_global_handler支持wandb、openinference、arize_phoenix、honeyhive、promptlayer、deepeval、simple、argilla、langfuse、agentops、literalai、opik等多种模式。这种统一入口设计意味着切换可观测性后端只需修改set_global_handler的入参业务代码无需任何改动literalai是其中一键接入成本最低的方案之一。使用前提与限制说明版本要求本集成要求 Python 3.10且llama-index-core版本在0.13.0,0.15之间见 pyproject.toml若你的项目使用更老或更新的 core 版本需先确认兼容性。环境变量约定未显式传参时需设置LITERAL_API_KEY与LITERAL_API_URL该约定同时出现在官方 observability 文档与示例代码中。前提服务需要可访问的 Literal AI 云端实例或自托管实例示例代码默认依赖 OpenAI需OPENAI_API_KEY实际接入时可替换为任意 LlamaIndex 支持的 LLM。只读接入集成仅负责向 Literal AI 上报观测数据不会修改你的索引、文档或查询逻辑属于纯观测性质的旁路组件。总结llama-index-callbacks-literalai以极简的代码量一个工厂函数 一个事件处理器为 LlamaIndex RAG 管道补齐了 Literal AI 的可观测性与评估能力。核心要点可归纳为接入成本低pip install两个包后一行set_global_handler(literalai)即可生效配置灵活api_key、url、batch_size、environment、disabled五个参数全部可选默认走环境变量机制清晰依赖 LiteralClient 的instrument_llamaindex()插桩配合QueryEndEvent触发缓存 flush实现查询粒度的自动上报定位明确它是 LlamaIndex 可观测性生态中的评估与监控选项适合需要对话线程级追溯与 Agent 运行分析的团队。【免费下载链接】llama_indexLlamaIndex is the document processing platform for AI项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 LlamaIndex × Literal AI 集成指南：为 RAG 管道一键开启 LLM 可观测性与评估
LlamaIndex × Literal AI 集成指南为 RAG 管道一键开启 LLM 可观测性与评估【免费下载链接】llama_indexLlamaIndex is the document processing platform for AI项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index本指南围绕 LlamaIndex 官方回调集成包llama-index-callbacks-literalai展开讲解如何将 LlamaIndex 构建的 RAG 应用无缝接入 Literal AI实现对话线程、Agent 运行过程的自动日志记录、LLM 可观测性与评估。读完本文你将掌握该集成的安装方式、一行代码接入方法、全部配置参数及其底层实现原理并能基于仓库源码理解其事件分发与缓存刷新的工作机制。集成概览什么是 Literal AI Callbacks 集成Literal AI 是一个面向 LLM 应用的评估Evaluation与可观测性Observability平台面向工程与产品团队帮助他们在构建 LLM 应用时打通提示词工程Prompt Engineering、LLM 可观测性、LLM 评估与 LLM 监控的协作开发闭环。其核心能力包括自动记录对话线程Conversation Threads与 Agent 运行过程Agent Runs。本项目提供的llama-index-callbacks-literalai集成包正是为了让 LlamaIndex 用户以最小成本获得上述能力它通过 LlamaIndex 的全局回调Callback机制为 RAG 管道提供 Literal AI 的“一键可观测性”one-click observability。该包声明于 pyproject.toml版本为 1.4.0要求 Python 3.10 且依赖llama-index-core0.13.0,0.15。从源码结构看该集成包非常精简仅包含三个核心文件base.py集成核心定义literalai_callback_handler工厂函数init.py导出literalai_callback_handlerliteralai_example.py可直接运行的接入示例。快速开始三步接入 Literal AI1. 注册账号并获取 API Key最简单的方式是注册 Literal AI 的云端实例cloud.getliteral.ai。注册完成后进入项目的Settings页面获取你的 API Key即可开始记录日志。若你使用自托管的 Literal AI 实例还需要记下其 Base URL。2. 安装依赖该集成本身通过llama-index-callbacks-literalai包安装LlamaIndex 全局处理器机制会自动导入它同时其底层依赖 Literal AI 官方 Python SDK。安装命令如下pip install llama-index-callbacks-literalai literalai需要注意literalaiSDK 是运行时的硬性前置依赖。在 base.py 中工厂函数内部通过try块导入literalai.LiteralClient与literalai.my_types.Environment若导入失败会抛出ImportError提示信息明确要求执行pip install -U literalai。也就是说即使llama-index-callbacks-literalai已安装缺少literalaiSDK 时集成仍无法工作。3. 一行代码开启全局处理在你的应用代码入口处调用set_global_handler并传入模式名literalaifrom llama_index.core import set_global_handler # API Key 与 Base URL 通过环境变量提供 # LITERAL_API_KEY, LITERAL_API_URL set_global_handler(literalai)这段代码来自 observability 文档。set_global_handler定义于 global_handlers.py它会把创建的处理器赋值给llama_index.core.global_handler从而在整个应用生命周期内生效。当eval_mode literalai时create_global_handler 会从llama_index.callbacks.literalai导入literalai_callback_handler并传入所有**eval_params——如果包未安装则抛出ImportError并提示执行pip install llama-index-callbacks-literalai。配置参数详解literalai_callback_handler工厂函数base.py接受以下参数全部可省略参数类型默认值说明batch_sizeint5LiteralClient 批量上报日志的批次大小。api_keyOptional[str]NoneLiteral AI API Key。为None时从环境变量LITERAL_API_KEY读取。urlOptional[str]NoneLiteral AI 实例 Base URL。为None时从环境变量LITERAL_API_URL读取云端默认https://cloud.getliteral.ai。environmentOptional[str]None环境标识如production、development会被转换为literalai.my_types.Environment类型。disabledboolFalse是否禁用上报能力。这些参数会被直接透传给LiteralClient(batch_size..., api_key..., url..., environment..., disabled...)用于构造底层客户端。也就是说参数的取值与语义以 Literal AI Python SDK 为准LlamaIndex 侧仅做透传与类型转换。在调用set_global_handler(literalai)时不传任何参数是最省事的用法——此时所有配置都依赖环境变量LITERAL_API_KEY与LITERAL_API_URL这也是官方推荐的做法。若需显式覆盖也可像 literalai_example.py 中注释展示的那样逐一传入set_global_handler( literalai, api_keylsk_xxx, urlhttps://cloud.getliteral.ai, batch_size5, environmentNone, disabledFalse, )完整可运行示例仓库在 examples/literalai_example.py 中提供了一个端到端示例先注册全局处理器再构建一个基于向量索引的查询引擎最后连续发起三个问题所有查询过程都会被自动记录到 Literal AIfrom llama_index.core import Document, VectorStoreIndex, set_global_handler # 所有配置参数均可省略。若未提供 api_key 和 url # 请通过环境变量 LITERAL_API_KEY、LITERAL_API_URL 提供 set_global_handler( literalai, # api_keylsk_xxx, # urlhttps://cloud.getliteral.ai, # batch_size5, # environmentNone, # disabledFalse ) # 该示例默认使用 OpenAI请设置 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)运行此脚本注意预先配置OPENAI_API_KEY与LITERAL_API_KEY后你可以在 Literal AI 控制台中逐条查看每次查询对应的对话线程、使用的提示词、模型调用与响应内容。底层原理从事件分发到缓存刷新理解这个集成如何工作关键在于看 base.py 的完整实现流程它分为三层第一层构造并插桩 Literal Clientfrom literalai import LiteralClient from literalai.my_types import Environment literalai_client LiteralClient( batch_sizebatch_size, api_keyapi_key, urlurl, environmentcast(Environment, environment), disableddisabled, ) literalai_client.instrument_llamaindex()调用instrument_llamaindex()后LiteralClient 会自动监听 LlamaIndex 内部的 LLM 调用与 Agent 执行过程这正是“对话线程与 Agent 运行自动记录”能力的来源。第二层注册 QueryEnd 事件处理器集成通过 LlamaIndex 的 Instrumentation 事件系统llama_index.core.instrumentation来感知查询生命周期from llama_index.core.instrumentation import get_dispatcher from llama_index.core.instrumentation.event_handlers import BaseEventHandler from llama_index.core.instrumentation.events.query import QueryEndEvent class QueryEndEventHandler(BaseEventHandler): 该处理器会在每次查询结束时刷新 Literal Client 缓存到 Literal AI。 classmethod def class_name(cls) - str: return QueryEndEventHandler def handle(self, event: BaseEvent, **kwargs) - None: try: if isinstance(event, QueryEndEvent): literalai_client.flush() except Exception as e: logging.error( Error in Literal AI global handler : %s, str(e), exc_infoTrue, ) dispatcher get_dispatcher() event_handler QueryEndEventHandler() dispatcher.add_event_handler(event_handler)这段代码表明QueryEndEventHandler订阅了全局 dispatcher 的QueryEndEvent一旦某次query_engine.query()结束就调用literalai_client.flush()把缓存的日志批量推送到 Literal AI 服务端。第三层容错与异常处理若literalaiSDK 未安装立即抛出带安装指引的ImportError若flush()过程中出现异常例如网络错误处理器不会让整个查询崩溃而是通过logging.error记录错误信息后继续执行。从源码结构看这种“缓存 查询结束统一刷新 异常隔离”的设计兼顾了性能批量上报、默认batch_size5与稳定性刷新失败不影响业务查询。在 LlamaIndex 可观测性体系中的位置该集成隶属于 LlamaIndex 的回调与可观测性Observability模块。在 observability 文档 中Literal AI 与 Langfuse、Comet Opik、Arize Phoenix 等并列共同构成 LlamaIndex 的第三方可观测性生态。官方将其定位为 LLM 评估与可观测性方案特别强调对话线程与 Agent 运行的自动日志能力。从 global_handlers.py 可以看到set_global_handler支持wandb、openinference、arize_phoenix、honeyhive、promptlayer、deepeval、simple、argilla、langfuse、agentops、literalai、opik等多种模式。这种统一入口设计意味着切换可观测性后端只需修改set_global_handler的入参业务代码无需任何改动literalai是其中一键接入成本最低的方案之一。使用前提与限制说明版本要求本集成要求 Python 3.10且llama-index-core版本在0.13.0,0.15之间见 pyproject.toml若你的项目使用更老或更新的 core 版本需先确认兼容性。环境变量约定未显式传参时需设置LITERAL_API_KEY与LITERAL_API_URL该约定同时出现在官方 observability 文档与示例代码中。前提服务需要可访问的 Literal AI 云端实例或自托管实例示例代码默认依赖 OpenAI需OPENAI_API_KEY实际接入时可替换为任意 LlamaIndex 支持的 LLM。只读接入集成仅负责向 Literal AI 上报观测数据不会修改你的索引、文档或查询逻辑属于纯观测性质的旁路组件。总结llama-index-callbacks-literalai以极简的代码量一个工厂函数 一个事件处理器为 LlamaIndex RAG 管道补齐了 Literal AI 的可观测性与评估能力。核心要点可归纳为接入成本低pip install两个包后一行set_global_handler(literalai)即可生效配置灵活api_key、url、batch_size、environment、disabled五个参数全部可选默认走环境变量机制清晰依赖 LiteralClient 的instrument_llamaindex()插桩配合QueryEndEvent触发缓存 flush实现查询粒度的自动上报定位明确它是 LlamaIndex 可观测性生态中的评估与监控选项适合需要对话线程级追溯与 Agent 运行分析的团队。【免费下载链接】llama_indexLlamaIndex is the document processing platform for AI项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考