20250913-03: Langchain概念：回调

任务

• 阅读 LCEL 官方文档
• 理解 | 操作符的底层是 RunnableSequence​

‍

🎯 学习目标

理解 LangChain 的“运行时引擎”——所有组件如何被统一调度和编排。

🔗 核心概念

• ​可运行接口（Runnable）
• ​LangChain 表达式语言（LCEL）
• ​回调（Callbacks）
• ​追踪（Tracing）
• ​流式传输（Streaming）
• ​异步编程（Async）

‍

回调（Callbacks）

回调 | 🦜️🔗 LangChain 框架

LangChain 提供了一个回调系统，允许您介入 LLM 应用程序的各个阶段。这对于日志记录、监控、流式传输及其他任务非常有用。

您可以通过使用 API 中随处可见的 callbacks 参数来订阅这些事件。此参数是一个处理程序对象列表，这些对象需要实现下面更详细描述的一个或多个方法。

回调事件

事件	事件触发	关联方法
聊天模型开始	当聊天模型开始时	​on_chat_model_start​
LLM 开始	当 LLM 开始时	​on_llm_start​
LLM 新令牌	当 LLM 或聊天模型发出新令牌时	​on_llm_new_token​
LLM 结束	当 LLM 或聊天模型结束时	​on_llm_end​
LLM 错误	当 LLM 或聊天模型出错时	​on_llm_error​
链开始	当链开始运行时	​on_chain_start​
链结束	当链结束时	​on_chain_end​
链错误	当链出错时	​on_chain_error​
工具开始	当工具开始运行时	​on_tool_start​
工具结束	当工具结束时	​on_tool_end​
工具错误	当工具出错时	​on_tool_error​
代理动作	当代理执行动作时	​on_agent_action​
代理完成	当代理结束时	​on_agent_finish​
检索器开始	当检索器开始时	​on_retriever_start​
检索器结束	当检索器结束时	​on_retriever_end​
检索器错误	当检索器出错时	​on_retriever_error​
文本	当任意文本运行时	​on_text​
重试	当重试事件运行时	​on_retry​

回调处理程序

回调处理程序可以是同步的或异步的

• 同步回调处理程序实现 BaseCallbackHandler 接口。
• 异步回调处理程序实现 AsyncCallbackHandler 接口。

在运行时，LangChain 会配置适当的回调管理器（例如，CallbackManager 或 AsyncCallbackManager），它将负责在事件触发时调用每个“注册”回调处理程序上的相应方法。

传递回调

​callbacks 属性在 API 中的大多数对象（模型、工具、代理等）的两个不同位置可用。

• ** 请求时 ​回调**：在请求时除了输入数据之外传递。在所有标准 Runnable 对象上可用。这些回调会被定义它们的对象的所有子对象继承。例如，chain.invoke({"number": 25}, {"callbacks": [handler]})。
• ​** 构造函数 ​回调**：chain = TheNameOfSomeChain(callbacks=[handler])。这些回调作为参数传递给对象的构造函数。回调仅限于定义它们的对象，并且​不会​被对象的任何子对象继承。

‍

注意

构造函数回调仅限于定义它们的对象。它们不会被对象的子对象继承。

如果您正在创建自定义链或可运行对象，您需要记住将请求时回调传播到任何子对象。

‍

注意

Python <=3.10 中的异步

任何调用其他可运行对象并在 Python <=3.10 中以异步方式运行的 RunnableLambda、RunnableGenerator 或 Tool 都必须手动将回调传播到子对象。这是因为在这种情况下 LangChain 无法自动将回调传播到子对象。

这是您可能无法看到自定义可运行对象或工具发出事件的常见原因。

---

复习知识点

1. 一句话定义：回调是 LangChain 提供的一个事件钩子系统，允许您在 LLM 应用程序执行的不同阶段（如开始、结束、出错时）注入自定义逻辑。
2. 核心用途：用于日志记录、监控、流式传输及其他需要在运行时观测和干预的任务。
3. 启用方式：通过 API 中普遍存在的 callbacks 参数来订阅事件，该参数是一个回调处理程序对象列表。
4. 关键机制：不同的事件会触发处理程序上对应的特定方法（如 on_llm_start, on_chain_end）。

重要说明与概念

5. 回调事件表：核心事件包括 LLM/Chain/Tool/Retriever 的 开始、结束、错误，以及 LLM生成新token 和 代理动作 等。

6. 处理程序类型：回调处理程序可以是同步的（实现 BaseCallbackHandler 接口）或异步的（实现 AsyncCallbackHandler 接口）。

7. 运行时管理：LangChain 使用回调管理器（CallbackManager/AsyncCallbackManager）在事件触发时自动调用所有已注册处理程序上的对应方法。

8. 两种传递方式：

   • 请求时回调 (Invoke-time callbacks) ：通过 callbacks 参数在调用时（如 .invoke()）传入。重要：这些回调会被当前对象及其所有子对象继承。
   • 构造函数回调 (Constructor callbacks) ：通过 callbacks 参数在对象初始化时传入。关键限制：这些回调仅作用于定义它们的对象本身，不会被其子对象继承。

9. 最重要的警告：构造函数回调不会被对象的子对象继承。这意味着如果您在链的构造函数中传递了回调，链内部的LLM或工具不会触发这些回调。

10. 自定义开发须知：如果您在创建自定义链或可运行对象，必须手动将请求时回调传播到任何子对象，否则子对象的事件不会被捕获。

11. Python 版本兼容性警告：在 Python <= 3.10 中，异步运行的 RunnableLambda、RunnableGenerator 或 Tool 必须手动传播回调到子对象，这是此类对象不触发事件的常见原因。

---

‍