当前位置：首页 > news >正文

LLamaIndex中经常使用的四个模块

news 来源：原创 2025/5/25 6:04:27

from llama_index.core.callbacks.base import BaseCallbackHandler
from llama_index.core.callbacks.schema import CBEventType
from llama_index.core.tools.types import ToolOutput
from typing import AsyncGenerator, Dict, Any, List, Optional

这四个模块每一个都很实用，在实际开发中经常用到，下面我详细介绍。

✅ 1. `from llama_index.core.callbacks.base import BaseCallbackHandler`

这是 LlamaIndex 框架提供的一个回调处理器的基类，你要想监听聊天过程中的各种事件（比如：开始检索了、调用工具了、Agent 步骤开始了），就得继承它。

✅ 举个例子：

class MyHandler(BaseCallbackHandler):def on_event_start(self, event_type, payload, event_id, **kwargs):print(f"事件开始了！类型是 {event_type}，内容是 {payload}")

📦使用场景：

比如你想做一个流式聊天界面，展示“现在在调用哪个工具”、“找到哪些文档”等等 —— 就可以写一个继承自它的类，然后实时捕捉这些事件。

✅ 2. `from llama_index.core.callbacks.schema import CBEventType`

这是一个事件类型的枚举类（Enum），LlamaIndex 定义了它在运行过程中可能发生的各种事件类型，比如：

类型名	含义
`CBEventType.RETRIEVE`	开始文档检索
`CBEventType.FUNCTION_CALL`	调用了某个工具
`CBEventType.AGENT_STEP`	Agent 进入了某个推理步骤
`CBEventType.LLM`	模型开始生成文本
`CBEventType.TEMPLATING`	正在拼 Prompt 模板

✅ 举个例子：

if event_type == CBEventType.RETRIEVE:print("正在检索文档")

📦使用场景：

你在 CallbackHandler 里判断是哪种事件，就靠这个枚举值，比如你只关心 tool 调用，就判断是不是 CBEventType.FUNCTION_CALL

✅ 3. `from llama_index.core.tools.types import ToolOutput`

这是一个 工具调用结果的结构体类，当 Agent 调用了某个工具函数（比如查天气、算数学题），这个类就表示工具调用完后返回的结果。

它里面有什么？

ToolOutput(content="今天天气晴朗",raw_input={"city": "北京"},raw_output={"weather": "sunny"},tool_name="get_weather",is_error=False
)

📦使用场景：

你想展示：“调用了哪个工具，传了什么参数，返回了什么结果”，就从 ToolOutput 里面拿。

✅ 4. `from typing import AsyncGenerator, Dict, Any, List, Optional`

这是 Python 标准库里的类型注解模块，用来给你的函数或变量标明“是什么类型”，可以让编辑器帮你自动补全、检查 bug，更方便写代码。

各个类型意思：

类型	作用	举例
`AsyncGenerator`	表示是个异步生成器	`async def xxx(): yield ...`
`Dict[str, Any]`	字典，键是字符串，值是任意类型	`{"a": 123, "b": "hello"}`
`List[int]`	表示一个整型列表	`[1, 2, 3]`
`Optional[X]`	可能是 X，也可能是 None	`Optional[str]` 表示：要么是字符串，要么是 None

✅ 举个注解例子：

from typing import AsyncGenerator, Dict, Anyasync def my_gen() -> AsyncGenerator[Dict[str, Any], None]:yield {"msg": "hello"}

🔚 总结对比表：

模块	用途	举个场景
`BaseCallbackHandler`	自定义事件监听器	监听聊天过程中的检索、tool调用等
`CBEventType`	定义事件类型	判断当前发生了什么事件
`ToolOutput`	表示工具函数的返回结果	显示 Agent 工具调用后的输出内容
`typing` 模块	写类型注解	用来标注 async generator、字典、列表等类型

from llama_index.core.tools.types import ToolOutput详细用法

我们来把 ToolOutput 拆开一点点讲，讲清楚它到底是干啥的、里面的每个属性代表什么、以及在哪儿用到它。

🧠 背景知识先补一下（30 秒理解）

在 LlamaIndex 的 Agent 机制中，你可以定义工具（tools），比如：

search_stock_info(股票代码)：查股票信息
get_weather(城市名)：查天气
calculate(expression)：算数学题

当用户提了一个问题，例如：“帮我查下北京的天气”，Agent 会选择合适的工具（比如调用 get_weather），然后等工具返回结果，继续生成回复。

👉 那工具返回的这个结果，LlamaIndex 就用 ToolOutput 类型来描述。

✅ `ToolOutput` 是个什么？

它是一个 数据结构（类），里面放着「某次工具调用的完整信息」，比如：

字段名	说明	举个例子
`tool_name`	用了哪个工具	`"get_weather"`
`raw_input`	工具收到的参数	`{"city": "北京"}`
`raw_output`	工具返回的原始结果	`{"weather": "晴"}`
`content`	给用户展示的文本	`"北京今天天气晴"`
`is_error`	工具有没有出错	`False`（正常）

🧩 举个超简单的例子：

比如你写了一个查天气的工具 get_weather(city: str)，用户问了：

“北京今天什么天气？”

Agent 决定调用这个工具，然后：

# 调用过程
tool_name = "get_weather"
raw_input = {"city": "北京"}
raw_output = {"weather": "晴"}
content = "北京今天天气晴"
is_error = False

这时候 LlamaIndex 就会把这些数据包成一个 ToolOutput 对象：

from llama_index.core.tools.types import ToolOutputoutput = ToolOutput(tool_name="get_weather",raw_input={"city": "北京"},raw_output={"weather": "晴"},content="北京今天天气晴",is_error=False
)

🧲 在哪里用到这个 `ToolOutput`？

这段处理 Agent 工具调用响应：

def get_agent_tool_response(self) -> dict | None:response = self.payload.get("response")if response is not None:sources = response.sourcesfor source in sources:if isinstance(source, ToolOutput):...

意思就是：payload 里有工具的执行结果，提取出来，准备展示给用户。

比如你做的是前端流式对话页面，拿到这个结构后可以展示为：

{"toolCall": {"name": "get_weather","input": {"city": "北京"}},"toolOutput": {"output": "北京今天天气晴","isError": false}
}

用户就知道 Agent 调用了哪个工具、传了啥参数、返回了啥结果。

📦 总结一下：

属性	作用	举个例子
`tool_name`	工具的名字	`"get_weather"`
`raw_input`	工具收到的参数	`{"city": "北京"}`
`raw_output`	工具返回的原始结果（可能是 dict、str 等）	`{"weather": "晴"}`
`content`	工具生成的展示内容（面向用户）	`"北京今天天气晴"`
`is_error`	是否出错	`False`（没错）