前言LangChain 1.0 彻底抛弃了旧版本杂乱的Chain体系统一使用Runnable作为所有功能组件的底层标准。无论是提示词模板、工具函数、大模型、解析器、自定义逻辑、并行分支全部实现了同一套 Runnable 接口。这也是 LCELLangChain Expression Language管道语法|能够无缝串联所有功能的核心底层原理。本文基于官方原生代码 真实运行输出逐行解析每一类 Runnable 的执行行为、输出差异、事件机制是全网最完整的 Runnable 落地原理手册。一、什么是 Runnable核心设计思想Runnable 是 LangChain 定义的可执行单元统一抽象接口。只要实现了 Runnable就天然拥有 5 套标准执行方式invoke单次同步执行batch批量并发执行stream同步流式迭代输出ainvoke / abatch / astream异步执行astream_events全生命周期事件监听可观测、调试、前端流式渲染所有 LangChain 组件均为 RunnableChatPromptTemplate、tool 工具、ChatModel、StrOutputParser、RunnableLambda、RunnableParallel 等。二、两大类基础 Runnable 实战原始输出 逐行详解我们从最基础、最容易混淆的两个组件开始提示模板 Runnable、工具 Runnable。1. ChatPromptTemplate 提示模板 Runnable完整代码fromlangchain_core.promptsimportChatPromptTemplateimportasyncio promptChatPromptTemplate.from_template(你好{name})print(prompt.invoke({name:世界}))print(prompt.batch([{name:世界},{name:小明}]))forchunkinprompt.stream({name:世界}):print(chunk)asyncdefastream():asyncforchunkinprompt.astream_events({name:世界},versionv2):print(chunk)asyncio.run(astream())程序真实输出messages[HumanMessage(content你好世界, additional_kwargs{}, response_metadata{})] [ChatPromptValue(messages[HumanMessage(content你好世界, additional_kwargs{}, response_metadata{})]), ChatPromptValue(messages[HumanMessage(content你好小明, additional_kwargs{}, response_metadata{})])] messages[HumanMessage(content你好世界, additional_kwargs{}, response_metadata{})] {event: on_prompt_start, data: {input: {name: 世界}}, name: ChatPromptTemplate, tags: [], run_id: 019ff4e3-e5d3-7013-81fc-de6d927257af, metadata: {}, parent_ids: []} {event: on_prompt_end, data: {output: ChatPromptValue(messages[HumanMessage(content你好世界, additional_kwargs{}, response_metadata{})])}, run_id: 019ff4e3-e5d3-7013-81fc-de6d927257af, name: ChatPromptTemplate, tags: [], metadata: {}, parent_ids: []}逐行输出详细解读第一行输出invoke 单次调用messages[HumanMessage(content你好世界)]Prompt 不会返回字符串而是返回ChatPromptValue包装对象内部封装标准的人类消息。仅做本地变量渲染不调用大模型专门用于传递给 ChatModel。第二行输出batch 批量调用接收两组输入返回两个独立的 ChatPromptValue 对象组成列表实现批量模板渲染。第三行输出stream 流式迭代Prompt 属于本地计算无网络 IO、无 Token 分片因此 stream只会输出一个完整块不会逐字拆分。第四、五行astream_events 生命周期事件on_prompt_start提示模板开始渲染携带输入参数on_prompt_end模板渲染完成携带输出的 ChatPromptValuerun_id全局唯一追踪 ID用于链路日志排查2. tool 工具函数 Runnable完整代码fromlangchain_core.toolsimporttoolimportasynciotooldefadd(a:int,b:int)-int:a和b做加法returnabprint(add.invoke({a:1,b:2}))print(add.batch([{a:1,b:2},{a:3,b:4}]))forchunkinadd.stream({a:1,b:2}):print(chunk)asyncdefastream():asyncforchunkinadd.astream_events({a:1,b:2},versionv2):print(chunk)asyncio.run(astream())程序真实输出3 [3, 7] 3 {event: on_tool_start, data: {input: {a: 1, b: 2}}, name: add, tags: [], run_id: 019ff4e8-2674-7103-b121-dc91bd942d54, metadata: {}, parent_ids: []} {event: on_tool_end, data: {output: 3}, run_id: 019ff4e8-2674-7103-b121-dc91bd942d54, name: add, tags: [], metadata: {}, parent_ids: []}逐行输出详细解读第一行invoke 结果 3工具 Runnable直接返回原生数据类型int/str/dict不会做任何对象包装与 Prompt 形成明显区别。第二行batch 批量结果 [3,7]两组入参分别执行加法返回原生结果列表批量执行高效简洁。第三行stream 输出 3普通同步工具无分片能力stream 仅返回单个完整结果无流式拆分。最后两行工具生命周期事件on_tool_start工具函数即将执行携带入参on_tool_end工具执行完毕携带函数返回值三、核心对比Prompt vs Tool 关键差异必背维度ChatPromptTemplatetool 工具返回值类型包装对象 ChatPromptValue原生基础数据类型Stream 行为单次完整输出无分片单次完整输出无分片事件前缀on_prompt_xxxon_tool_xxx核心能力模板变量渲染业务逻辑计算四、三大核心进阶 Runnable 完整解析1. ChatModel 大模型 Runnable唯一真正流式的组件Prompt、Tool 都是本地计算只有 ChatModel 具备真实 Token 流式输出能力是聊天界面打字机效果的核心来源。独有事件on_chat_model_stream持续多次触发逐 Token 返回2. RunnableLambda 自定义函数 Runnable作用将任意 Python 函数包装为标准 Runnable可直接放入 LCEL 管道。事件on_runnable_start / on_runnable_end特点本地计算、单次输出、无分片。3. RunnableParallel 并行 Runnable语法糖{key: Runnable}自动识别为并行执行。作用同一输入同时执行多个逻辑并发提速常用于同时摘要、翻译、检索。输出字典结构key 为分支名称value 为各分支结果。五、全类型 Runnable 事件总对照表终极总结Runnable 类型生命周期事件Stream 分片能力返回格式ChatPromptTemplateon_prompt_start / on_prompt_end无ChatPromptValuetool 工具on_tool_start / on_tool_end无原生数据类型ChatModel 大模型on_chat_model_start / on_chat_model_stream / on_chat_model_end有逐 TokenAIMessageRunnableLambdaon_runnable_start / on_runnable_end无函数返回值RunnableParallelon_runnable_start / on_runnable_end含子组件事件无字典StrOutputParseron_parser_start / on_parser_end跟随上游纯文本字符串六、LCEL 管道底层原理Runnable 组合核心LCEL 的|管道语法本质是Runnable 的自动串联上一个Runnable | 下一个Runnable任意 Runnable 串联后生成的新 Chain依然是一个 Runnable天然拥有 invoke、batch、stream、astream_events 全套能力。标准完整链路输入字典 → Prompt渲染消息→ ChatModel生成 Token→ Parser解析文本七、开发高频踩坑总结stream ≠ 打字机效果只有 ChatModel 能分片Prompt/工具/Lambda 均为一次性输出astream_events 必须携带 version“v2”新版强制要求Prompt 返回对象、工具返回原值、模型返回消息对象类型不匹配会导致管道报错RunnableParallel 适合 IO 并发LLM 请求不适合 CPU 密集计算包名切勿拼写错误langchain_core不是 langchian_core八、全文总结1.Runnable 是 LangChain 1.0 的架构基石统一了所有组件的调用规范。2. 本地组件Prompt、Tool、Lambda无流式分片只有大模型具备真实 Token 流式能力。3. 不同 Runnable 拥有独立事件体系通过astream_events可实现全链路可观测彻底解决 AI 应用调试黑盒问题。4. LCEL 管道、并行分支、自定义逻辑全部基于 Runnable 实现掌握 Runnable 才算真正掌握 LangChain 核心。