上一篇《FastAPI 快速入门》从创建路由开始,介绍了如何读取和校验请求,以及如何用依赖、异常处理和响应模型把一个接口写完整。这一篇继续往路由函数内部看,讨论接入大语言模型后,程序需要怎样组织一次问答。
以技术问答接口为例,收到问题后,程序可能需要先检索文档,把相关资料和对话历史放进提示词,再将模型回复转成接口需要的数据。问题字符串、文档列表和模型消息会在这些步骤之间传递,任何一处接错,都可能让后面的代码无法执行,或让模型拿到错误的上下文。
LangChain 是用于构建大语言模型应用的开发框架。它提供模型调用、提示词模板、检索器和工具等组件,让开发者可以用统一的接口组合这些步骤。在这个问答服务里,FastAPI 负责接收请求和返回响应,LangChain 组织中间的处理流程,具体的大语言模型负责生成回答。
LCEL 的全称是 LangChain Expression Language,是 LangChain 中组合组件的一套写法。它让开发者用 Python 描述步骤的先后顺序、分支和数据传递,例如把“填充模板 → 调用模型 → 解析回答”组成一个可以整体调用的流程。后面代码中的 | 就用来连接相邻步骤。
本文按职责介绍 Models、Prompts、Chains、Indexes、Memory 和 Agents 六类核心功能。学习时重点看两件事:每个对象负责什么,以及前一步的结果怎样交给下一步。最后用一个简单的问答函数把检索、历史和生成连起来。
源码解读和 LangGraph 等扩展放在“选读”折叠区,第一次阅读可以跳过;理解正文示例不需要先掌握它们。代码旁的 Python 语法说明用于帮助读懂例子,不需要当成新的 LangChain 概念记忆。
1. 六类模块与 LangChain、LCEL 的关系
LangChain 是整个开发框架,下面的六类模块按职责划分了它的核心功能。LCEL 用来连接提示词模板、聊天模型、输出解析器等处理对象,让前一步的输出成为后一步的输入。其中,Chains 关注如何把多个步骤组织成处理流程,LCEL 则是构建这类链的一种具体写法。
| 功能分类 | 要解决的问题 | 典型输入 → 输出 |
|---|---|---|
| Models | 调用聊天模型生成回答 | 输入消息 → 模型回复消息 |
| Prompts | 把变量和历史组装成模型输入 | 本次填写的数据 → 填好的消息 |
| Chains | 规定步骤如何串联、分叉 | 上游输出 → 下游输入 |
| Indexes / Retrieval | 把外部资料整理成可检索内容,并按问题取回 | 问题 str → list[Document] |
| Memory | 保存旧对话,在下一轮取出来继续使用 | 旧消息 + 当前问题 → 本轮模型输入 |
| Agents / Tools | 让模型请求工具,由程序执行并交回结果 | 问题 → 工具调用 → 结果 → 回答 |
以 chain = prompt | model | parser 为例,prompt 属于 Prompts,model 属于 Models,parser 负责整理输出。用 LCEL 的 | 连接这些组件,得到的 chain 就是一条可以整体调用的链。组件承担各自的工作,LCEL 描述它们的连接关系。
这条链还可以接入 Retrieval 获取资料,或让程序加载 Memory 中的历史消息。涉及 Agents 时,则需要管理“模型请求工具 → 执行工具 → 把结果交回模型”的循环。历史如何读写、工具能否执行,都要有对应的处理逻辑,仅写下 | 不会自动完成这些工作。
Output Parser(输出解析器)是处理模型回复的辅助组件,例如取出回答文本,或把 JSON 文本变成字典。第 8 节会展示两者的区别。
一次性的简单问答可以直接调用模型。需要固定的处理步骤时再写链;外部资料、对话历史和工具分别在任务需要时接入。
2. Prompts 与 Models:从模板到回答
先写一个“按主题解释术语”的例子。prompt 保存提问模板,本次输入决定要解释的主题。只组装模板和使用后面的模拟模型时,安装 langchain-core 即可。
1 | python -m pip install langchain-core |
下面的模板包含 system、human 两种角色,topic 是要填的变量。
1 | from langchain_core.prompts import ChatPromptTemplate |
这段代码会打印以下两行。type(message).__name__ 取消息对象的类型名,message.content 取消息正文。
1 | SystemMessage 你是一名耐心的技术编辑 |
value 保存的是 prompt.invoke({"topic": "LCEL"}) 返回的 ChatPromptValue。这一步只把变量填入模板,生成待发送的消息,还没有调用模型。system 设定模型的任务,human 写本轮请求;角色和内容都属于模型输入。
from_messages(...)是一次方法调用。传进去的[...]是 Python 列表,里面每个("角色", "模板内容")是一个包含两个元素的元组。LangChain 按这个约定读取角色和模板字符串。
{"topic": "LCEL"}是 Python 字典,"topic"是键,"LCEL"是值。字符串"请用一句话解释 {topic}"中的{topic}是 LangChain 会替换的模板占位符。两处花括号的作用不同。
prompt 可以反复使用。下次换成 {"topic": "FastAPI"},human 消息随之改变,固定的 system 消息和模板保持不变。
调用字典的键必须对应模板变量。模板要的是 topic,如果只传 {"text": "LCEL"},就会报缺少 topic 的错误。
上面的 value 已经装好了 system 和 human 两条消息。假设 chat_model 已经配置好,可以把它交给模型。
1 | reply = chat_model.invoke(value) |
value 是一个 ChatPromptValue,可以把它看作装着本次消息的容器。value.to_messages() 会取出里面的消息,得到一个 Python 列表,内容相当于下面两条消息。
1 | from langchain_core.messages import SystemMessage, HumanMessage |
to_messages() 只取出消息,不会调用模型。因此 chat_model.invoke(value) 和 chat_model.invoke(value.to_messages()) 交给模型的是同样的两条消息。
reply 是模型发回的一整条消息,reply.content 是消息正文。例如模型回答“LCEL 用来连接多个处理步骤”,这句话就在 reply.content 中。本文先用这种文本回复学习;第 7 节再看模型请求工具时返回什么。
选读:模型为什么既接受 value,又接受消息列表(源码,非核心)
使用时知道两种写法都能传入消息即可。下面的内部转换解释原因,无需自己实现或记住这个方法。
chat_model.invoke() 内部会先调用 _convert_input(),根据传入对象的类型处理输入。BaseChatModel 源码中的这段代码说明了它如何接受不同形式的参数。
1 | def _convert_input(self, model_input: LanguageModelInput) -> PromptValue: |
isinstance(对象, 类型) 用来判断对象是否属于某个类型,也会识别该类型的子类。value 是 ChatPromptValue,它继承自 PromptValue,所以第一个 if 就会返回这个对象。value.to_messages() 返回的是列表,属于 Sequence(序列),因此会进入第三个 if,被包装成一个 ChatPromptValue。两种输入由此进入相同的后续流程,再转成消息列表交给底层模型。
3. Chains 与 LCEL:把三个步骤连起来
在 LangChain 中,Runnable 可以理解为支持统一调用接口的处理对象。前面用到的 ChatPromptTemplate、聊天模型对象,以及接下来使用的 StrOutputParser 都实现了这套接口,能够通过 .invoke(输入) 执行各自的工作。
invoke 是方法名,对象.invoke(输入) 是普通的 Python 方法调用。它把一份输入交给当前对象,执行相应步骤,再返回结果。例如 prompt.invoke(...) 填充模板,model.invoke(...) 调用模型,parser.invoke(...) 解析输出。虽然方法名相同,各个对象要求的输入、产生的输出仍由它们自己的职责决定。
| 用来连接这些步骤,让前一步的输出成为后一步的输入。写下 chain = prompt | model | parser 时,只是创建了一条链;调用 chain.invoke(...) 时,才会按顺序执行里面的步骤。整条链本身也是 Runnable,所以可以像单个步骤一样调用。
LCEL 中的各个步骤最终都以 Runnable 的形式参与执行。提示词模板、聊天模型和输出解析器已经支持这套接口;普通 Python 函数也能接入,LangChain 可以将它包装成 Runnable。下面的
RunnableLambda就用来做这件事。
先用一个普通函数模拟模型回复。它只把输入文字放进一条 AIMessage,没有调用大语言模型,也不会解释术语。这样可以先专注于数据怎样传递。
1 | from langchain_core.messages import AIMessage |
这段代码里,RunnableLambda(fake_model) 是一次创建对象的调用。RunnableLambda 是类,fake_model 是传给它的函数对象。Python 允许把函数作为参数传递;写 fake_model 表示取这个函数,写 fake_model(value) 才会执行函数。
包装和执行可以拆开来看。下面沿用示例中的 prompt 与 fake_model。
1 | step = RunnableLambda(fake_model) # 创建包装对象,尚未执行 fake_model |
在这个例子里,普通函数 fake_model 通过 fake_model(value) 调用,包装后的 step 则支持 .invoke(value)。类名中的 Lambda 不限制函数的定义方式:用 def 写出的函数也能传给它。
[-1]是 Python 的索引写法,表示最后一个元素,[0]表示第一个元素。本例的from_template(...)生成一条 human 消息,所以这里取到的request是字符串"请用一句话解释 LCEL"。这段函数只读取最后一条消息,用它来构造固定格式的演示回答。
fake_model 收到 ChatPromptValue,返回一个 AIMessage。整条链的数据类型依次变化。
1 | {"topic": "LCEL"} --prompt--> ChatPromptValue |
对照 chain.invoke({"topic": "LCEL"}),手动执行同样的流程是下面三步。
1 | value = prompt.invoke({"topic": "LCEL"}) # 填模板 |
链替程序完成了这三次调用和中间结果的传递。下次传入 {"topic": "FastAPI"},只会改变填进模板的主题,处理步骤保持不变。
使用真实聊天模型时,把 RunnableLambda(fake_model) 换成已配置好的 model,就得到 prompt | model | StrOutputParser()。前后步骤要求的输入输出仍然一样。
运行准备:如何换成真实模型(服务配置,不是 LCEL 学习重点)
下面需要安装 langchain 和所选模型提供商的集成包,并配置该服务要求的凭据。MODEL_ID 是程序读取的环境变量,填写所选服务支持的模型标识。这些配置随服务而异,本文不展开;真实服务示例未实测。
1 | import os |
后面需要真实模型的例子都以已经配置好的 model 为前提。模型初始化说明
选读:batch 一次处理多个问题,stream 逐段接收回答
这两个也是 Runnable 的调用方式。先会用 invoke 串通流程,再按需要使用它们。
batch 接收一组输入,返回对应的一组结果。下面仍用前面的模拟模型,可以直接对照输入和输出。
1 | results = chain.batch([{"topic": "LCEL"}, {"topic": "FastAPI"}]) |
stream 适合在模型生成过程中逐段显示文字。下面沿用上方配置好的 real_chain,需要模型支持流式输出;链尾的 StrOutputParser 让循环每次拿到的是一段字符串。
1 | for piece in real_chain.stream({"topic": "LCEL"}): |
这些片段拼起来才是一条完整回答,每次返回的长度不固定。想让它们在同一行逐渐显示,可把循环中的打印改成 print(piece, end="", flush=True)。本文的 fake_model 一次返回整条消息,用它观察不到这种逐段生成的效果。Runnable 调用接口与组合说明
4. LCEL 分支:生成回答,同时保留原始输入
上一节的链最终只返回回答字符串。如果还想知道“这条回答对应哪个输入”,可以把同一份输入交给两路处理:一路生成回答,另一路保留原始数据。
下面继续使用上一节含 fake_model 的 chain,不调用真实模型。RunnableParallel 创建并行分支,RunnablePassthrough 让输入原样通过。
1 | from langchain_core.runnables import RunnableParallel, RunnablePassthrough |
answer 和 original 是结果字典的键。两路收到的输入完全相同,都是 {"topic": "LCEL"},各自处理后才把结果放到对应的键下。
| 分支 | 收到的输入 | 做什么 | 返回的值 |
|---|---|---|---|
answer |
{"topic": "LCEL"} |
执行模板、模拟模型和解析器 | 回答字符串 |
original |
{"topic": "LCEL"} |
原样返回 | 原始字典 |
因此 result["answer"] 取到回答,result["original"]["topic"] 取到最初的主题。RunnablePassthrough() 保留的是整个输入,不会自动从字典里选一个字段。
下一个步骤只需要回答怎么办
branch 的输出是字典。如果后面只需要回答文本,就先取出 answer。
1 | from langchain_core.runnables import RunnableLambda |
这次数据变化是“原始输入 → 分支结果字典 → 取出回答字符串”。它解释了为什么不能把 branch 直接交给 StrOutputParser:解析器接收消息或文本,不接收包含 answer、original 的整个字典。这里 answer 已经是字符串,取出来就可以直接使用。
Python 写法补充:
lambda x: x["answer"]是一个没有单独命名的小函数,与上面的take_answer做同样的取值。因此也能写成RunnableLambda(lambda x: x["answer"])。会用def的写法就能完成本文示例,无需刻意缩写。
选读:字典和函数什么时候能自动转换成 Runnable
前面已经用 RunnableParallel(...) 创建了 branch,因此可以省略右边的 RunnableLambda,直接连接函数。
1 | text_chain = branch | take_answer |
这里由左边的 branch 处理 LCEL 连接,LangChain 会把普通函数 take_answer 自动包装成 RunnableLambda。写函数名时不加括号,表示把函数交给链;执行 text_chain.invoke(...) 时,才把分支结果传给它。
也可以反过来:左边用字典简写,右边保留 RunnableLambda。
1 | text_chain = { |
这个字典的值是“生成字段的处理步骤”。与右边的 Runnable 通过 | 连接时,LangChain 会把它转成 RunnableParallel。执行后才得到包含回答和原始输入的结果字典,再交给 take_answer。
但不能把两边的包装都省掉。下面这段会在创建链时直接报错,还没到 .invoke()。
1 | # 错误示范:普通字典不能直接用 | 连接普通函数 |
这时 | 左边的整个对象是普通字典,右边是普通函数,没有 Runnable 对象来处理 LCEL 连接。字典里面即使放着 chain 和 RunnablePassthrough(),也不会让外层字典自动获得这种能力。
因此,如果想直接写 | take_answer,左边就用前面显式创建的 branch。先掌握这种写法即可,不必同时省略所有包装。
单独的普通 Python 字典没有 .invoke()。要单独执行两路并查看结果,就用正文中的 branch = RunnableParallel(...) 写法。RunnableParallel 的组合说明
5. Indexes 与 Retrieval:找到资料,再交给模型
如果要让模型根据一份 FastAPI 笔记回答问题,先从笔记中找到相关内容,再把内容和问题一起交给模型。这种做法叫 RAG,全称 Retrieval-Augmented Generation,中文是“检索增强生成”。RAG 描述回答问题的方法,LCEL 可以用来连接其中的步骤。
资料要先准备好才能查询。本节用向量检索解释这个过程;先理解各对象做什么,不需要在这里学习向量的数学计算或数据库选型。
假设笔记同时介绍路径参数、请求体和依赖注入。读取笔记后,程序先用 Document 保存文本和来源信息,再把长文本切成较小的片段。每个片段叫一个 chunk,通常也用 Document 保存。下面按主题示意切分结果,实际片段中可以包含完整说明和代码。
| 片段 | 包含的资料 | 适合回答的问题 |
|---|---|---|
| chunk A | 路径参数如何声明和读取 | 怎样读取 URL 中的用户 ID? |
| chunk B | 请求体与 Pydantic 模型 | 请求体如何校验? |
| chunk C | 依赖项的执行与结果注入 | 依赖项何时执行? |
例如,chunk B 可以用下面这个对象表示。为方便观察,正文只保留一句话。
1 | from langchain_core.documents import Document |
page_content 保存正文,metadata 保存附加信息。这里的 source_id 是程序为片段设置的编号,source 记录它来自哪份笔记。
接下来,让 Embedding 模型(嵌入模型)把每个片段的正文转成一串数字,称为向量。例如 [0.12, -0.34, 0.56],这里只示意形式,没有实际计算这些数值。语义相近的文字,其向量通常也更相近,因此可以用来查找相关片段。向量由嵌入模型计算;后面生成文字回答的是聊天模型,两者做的工作不同。Embeddings 接口说明
VectorStore 是保存和搜索这些向量的存储。可以把其中一条记录理解成“向量 B + chunk B 的正文 + 来源信息”。搜索时用向量比较相似度,找到后取回对应的文字和来源。因此,向量检索需要保留向量与原文之间的对应关系。
1 | 准备资料 |
这部分就是 Indexes 在本文中承担的工作。它把资料准备好,供后面的检索使用。
假设资料已经入库,并创建好了检索器 retriever。用户提问时,把问题字符串传给它。
1 | question = "请求体如何校验?" |
对于这里的向量检索器,内部会把问题也转换成向量,再到 VectorStore 中比较已保存的片段向量。建库和提问时要使用配套的嵌入模型,让两边的向量可以比较。理想情况下,这个问题会找到介绍请求体校验的 chunk B,随后返回包含它的 list[Document]。
1 | "请求体如何校验?" |
调用方给 retriever 的是问题字符串,拿到的是文档列表;问题转向量和搜索由内部完成。本文只用这一种检索方式理解数据流。更多方式参考:LangChain 检索组件说明
为什么返回列表,数量由谁决定
一个问题可能需要几段资料才能回答完整。例如“怎样校验请求体,并要求年龄至少 18?”包含两个要求,介绍请求体校验的片段和介绍年龄限制的片段都可能有用。因此,Retriever 返回一组候选资料,供后面的程序组织和使用。
这里每个 Document 通常代表一个片段。列表里的两项可以来自同一份笔记,也可以来自不同文件。统一使用 list[Document],还能表示只有一项的 [doc_b],以及没有结果的 [];后面的代码始终可以按列表处理。
返回多少项取决于检索配置。对于本文使用的向量检索,假设 vector_store 已配置好嵌入模型并存入资料,可以这样创建检索器。下面仅展示配置方式。
1 | retriever = vector_store.as_retriever(search_kwargs={"k": 2}) |
as_retriever(...) 从向量存储创建检索器,k=2 表示希望取两条候选结果,实际可能更少。即使设为 k=1,结果仍是列表。本节只需理解“查询字符串 → 文档列表”;创建知识库时的其他搜索参数可以暂时跳过。VectorStore 检索器配置说明
多个片段怎样一起参与回答
先写一个 format_docs 函数,把列表中每个片段的编号和正文拼成一段文本。这里的文档都带有前面定义的 source_id。
1 | def format_docs(docs): |
Python 语法补充:
f"...{表达式}..."会把花括号中表达式的值填进字符串。这里每次生成类似[doc-b] 资料正文的文字;"\n\n".join(parts)用一个空行连接这些文字。它只整理已经拿到的资料,不执行检索。
下面沿用 doc_b,再构造一段字段约束说明,模拟检索到了两项资料。这只是展示数据如何传递,没有实际运行向量搜索。
1 | doc_d = Document( |
准备一个同时接收 context 和 question 的模板,试着把这两段资料放进去。search_prompt 是本节新建的模板名称。
1 | from langchain_core.prompts import ChatPromptTemplate |
最后一条 human 消息的正文如下。这就是模型会看到的资料和问题。
1 | 资料: |
一条有依据的回答可以是“用 Pydantic 模型校验请求体,并为 age 设置至少 18 的数值下限”。前半句的依据来自 doc-b,后半句来自 doc-d。
这里会把列表中的两段资料都交给模型,供它综合回答。模型不会自己读取 VectorStore;只有程序检索后填进 Prompt 的内容,才会成为本轮参考资料。
用 LCEL 接起检索和模板
先前用手写的 docs 演示数据。本节接下来假设 retriever 已按上面的方式配置好,并能返回带有 source_id 的文档。用第 4 节学过的分支,让同一个问题一路查资料、一路原样保留。
1 | from langchain_core.runnables import ( |
如果检索返回刚才的两段资料,data 就是下面这样的字典。模板收到的是执行结果,不是 retriever 等处理对象。
1 | { |
search_prompt.invoke(data) 能填好模板。因此把它们连接起来,就能自动传递这个字典;再接上已配置好的模型和解析器,就得到一条 RAG 链。
1 | from langchain_core.output_parsers import StrOutputParser |
整个过程是“问题字符串 → 检索并保留问题 → 资料与问题的字典 → 填好的消息 → 模型回复 → 回答文本”。
如果业务传入的是 {"question": "请求体如何校验?"},先把问题取出来,再交给上面的链。
1 | def take_question(data): |
这里增加的步骤只负责 dict → str。后面的检索器仍然收到字符串,RunnablePassthrough 保留的也仍然是问题字符串。这种“先看下游要什么,再提取字段”的判断,是使用 LCEL 时需要掌握的重点。
切分和检索还需要检查什么
切分时,要兼顾“容易找到相关片段”和“片段自己能把事情说清楚”。如果把路径参数、请求体和依赖注入全部放在一个很大的 chunk 里,查询请求体校验时可能会带回很多无关内容。切得太细也会出问题,例如笔记里有下面两句话。
1 | 原文:FastAPI 会先处理路由声明的依赖项。它会在调用路径操作函数前执行。 |
这时仅凭片段很难确定“它”指什么。把这两句放在一起,就能保留完整意思。本节先记住“片段要能独立说明问题”;切分算法和参数属于后续调优,不在这里展开。文本切分说明
最后还要检查,找回来的资料能否回答当前问题。假设用户问“FastAPI 默认要求 age ≥ 18 吗”,而唯一检索结果是“age: int 会进行整数类型校验”。
| 检查项 | 这个例子的结果 |
|---|---|
| 找到文档了吗? | 找到了,docs 非空 |
| 文档与问题有关吗? | 有关,都谈到 age 的校验 |
| 文档说明了年龄下限吗? | 没有,整数类型校验不能推出 age ≥ 18 |
如果要求只根据资料回答,合适的回复应是“资料只说明了整数类型校验,没有说明默认年龄下限,无法据此确认是否要求至少 18 岁”。可以把这个要求写进 Prompt;对重要结论,还应检查答案是否得到原文支持,不能仅凭模型遵循了输出格式就认定回答正确。
如果检索结果直接是空列表,format_docs([]) 会得到空字符串。LCEL 仍会继续把它交给 Prompt 和模型。业务若要求没有资料就不回答,需要在检索之后检查 docs 是否为空,并在调用模型前直接返回“没有找到相关资料,无法确认”。第 9 节会给出这个判断的代码。
6. Memory:把旧对话放进本轮输入
上一节用检索资料帮助模型回答技术问题。聊天时还可能需要前面说过的话,例如用户已经提出“请用初学者能理解的方式讲解 FastAPI”,接着问“FastAPI 的依赖项何时执行?”。如果本轮只发送后一个问题,模型就看不到之前的讲解偏好。
要让模型继续利用这项偏好,程序需要把相关旧消息也放进本轮输入。本文用对话历史实现 Memory,由程序负责保存和读取消息,再交给模板组装。即使旧消息已经存在数据库中,也要把它们读出来并传给模型,才能在这次回答中使用。
在模板中给历史消息留出位置
MessagesPlaceholder("history") 会创建一个消息模板对象,为本次传入的 history 消息列表预留插入位置,因此称为“消息占位符”。定义模板时先放入这个对象,调用模板时再提供具体的历史消息。下面把它放在 system 消息之后、当前问题之前。
1 | from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder |
这里需要提供三个字段,它们的数据类型和用途不同。
| 字段 | 本例传入的内容 | 放进模板后起什么作用 |
|---|---|---|
history |
旧的 HumanMessage、AIMessage 组成的列表 |
让模型看到之前的对话,保留每条消息的角色 |
context |
检索片段整理成的字符串 | 提供回答技术问题所需的资料 |
question |
当前问题字符串 | 告诉模型本轮要回答什么 |
MessagesPlaceholder("history") 中的 "history" 对应调用字典的同名键。这个对象从本次输入中取出历史消息;它在模板列表中的位置,决定了这些消息插入哪里。
看一次模板填充后的完整消息
下面手动构造两条旧消息,模拟程序已经读取了当前会话的历史;资料也用一段文本模拟。这个例子只组装 Prompt,不调用真实模型。
1 | from langchain_core.messages import AIMessage, HumanMessage |
value 是 ChatPromptValue,value.to_messages() 取出其中的消息列表。按上面的模板和数据,预期会看到四条消息,顺序如下。
1 | SystemMessage 请根据资料回答;资料不足时说明无法确认。 |
模板里虽然只写了一行 MessagesPlaceholder("history"),但本次插入了两条消息,各自仍保留 human 和 ai 角色。最后一条 HumanMessage 则包含本轮资料和问题。把这个 value 交给模型,模型才能同时看到讲解偏好、技术资料和当前问题;上面的打印结果展示的是准备发送的输入。
新会话没有旧消息时,传入 "history": [] 即可。MessagesPlaceholder("history") 对应的位置不会插入任何消息,最终只剩 system 和当前 human 两条。
MessagesPlaceholder 只把已经提供的消息列表插入模板,不负责查询数据库。这里应传入 history 列表,不能传入 "Human: 请用简单语言讲解\nAI: 好的" 这样的整段字符串,期待它自动拆成两条消息。
本轮问题只放一次,回答完成后再保存
上面的 history 只有旧消息,当前问题由模板中的 {question} 填入。如果调用前又执行下面这行代码,就会把当前问题放进历史。
1 | # 错误示范:不要在调用上述模板前,把本轮问题也放入 history |
再用这个 history 和相同的 question 调用模板,结果就变成五条消息。第 4 条来自历史中的当前问题,第 5 条来自模板末尾的“资料 + 当前问题”,同一个问题出现了两遍。因此,在这个模板中,应让 history 保持为本轮之前的对话。
等到本轮得到回答,再把当前问题和这次回答保存起来。下一轮读取时,它们才属于旧历史。每轮按下面的顺序处理;第 9 节会用消息列表演示如何记录本轮对话。
1 | 读取该会话的旧历史 |
如果某条旧消息没有被取出来,模型本轮就看不到它。多人使用时,要按会话分别读写历史,避免把 A 的消息放进 B 的输入。
选读:MessagesPlaceholder 的源码与可选参数(非核心,可跳过)
这部分用于回查“历史消息怎样被取出并插入”。使用前面的模板时,不需要记住这些内部方法。
创建 MessagesPlaceholder("history") 时,对象会把 "history" 保存到 variable_name。下面是它的 format_messages 方法的简化片段,省略了可选参数分支和类型标注,无需复制到业务代码中。
1 | def format_messages(self, **kwargs): |
self 指这个 MessagesPlaceholder 对象,所以 kwargs[self.variable_name] 在本例中就是 kwargs["history"]。函数定义中的 **kwargs 收集关键字参数:调用 format_messages(history=history) 时,收到的参数会组成 {"history": history} 这个字典。
convert_to_messages 把列表各项统一成消息对象。例如 ("human", "你好") 会转换为 HumanMessage(content="你好");已经是消息对象的项可以直接使用。整段字符串过不了前面的列表检查。
取出历史后,外层 ChatPromptTemplate 还要把它与 system、当前 human 消息拼到一起。针对本例的三个模板对象,可以把外层流程简化为:
1 | result = [] |
这里的 self 已经是外层的 rag_prompt,self.messages 保存它的模板列表。message_template 是 for 循环的变量,每轮指向当前一项,并非固定指向历史占位符。
| 循环轮次 | message_template 当前指向什么 |
返回的消息 |
|---|---|---|
| 第一次 | system 元组转换成的消息模板 | 一条 system 消息 |
| 第二次 | MessagesPlaceholder("history") |
本次传入的两条历史消息 |
| 第三次 | human 元组转换成的消息模板 | 填好资料和问题的一条 human 消息 |
extend 将每次返回的列表逐条加入 result,所以最终有四条消息。MessagesPlaceholder.format_messages(...) 返回消息列表;整个 rag_prompt.invoke(...) 则把组装完成的列表放入 ChatPromptValue 返回。源码参考
还可以在创建 MessagesPlaceholder 时设置两个参数。下面单独调用它,观察参数效果:
1 | placeholder = MessagesPlaceholder("history", optional=True, n_messages=2) |
optional 默认是 False,需要提供 history;设为 True 才能省略。n_messages=2 只保留传入列表的最后两条消息,不是最后两轮对话,也不会自动生成摘要。不设置它,就保留传入的全部消息。把这个 placeholder 放入 ChatPromptTemplate.from_messages([...]) 中,也会按相同规则处理历史。
选读:用 checkpointer 保存历史,再交给 LCEL(非核心,可跳过)
前面的示例由程序读取和保存历史。如果以后使用 LangGraph,可以把这部分交给 checkpointer。LangGraph 是执行工作流程的框架;它引入的流程节点和状态管理不属于本文的学习重点,下面只保留一个配合 LCEL 的例子。
这里的“状态”指流程保留的数据,本例只关心 messages 消息列表。checkpointer 保存这份列表,让下一轮取回;MessagesPlaceholder 则把取回的消息插入模板。两者分别负责存取和组装。
下面是独立的纯文本对话示例,需要安装 langgraph,并事先配置好没有绑定工具的聊天模型 model。示例未实测真实模型调用。每轮只提交一条新消息,不手动重复提交旧历史。
1 | from langchain_core.messages import HumanMessage |
StateGraph(MessagesState) 创建一个流程构建对象,并规定流程保存的数据包含 messages。add_node("reply", call_model) 注册一个名为 reply 的步骤,轮到它时执行 call_model;两行 add_edge 把执行顺序连成“开始 → reply → 结束”。compile(...) 最后生成可以调用的流程,并为它配置 checkpointer。官方配置示例
call_model 接收当前状态,返回要添加的新消息。函数名可以更换;state: MessagesState 是类型标注。这里的消息合并规则来自 MessagesState,因此函数只返回新增的 [reply],不用把全部历史再返回一遍。MessagesState 说明
第二轮沿用 thread_id="name-demo",LangGraph 先取回上一轮消息,再加入新问题。假设第一轮回复“你好,Lin”,call_model 收到的 state["messages"] 就是:
1 | HumanMessage:我叫 Lin。 |
messages[:-1] 取最后一条之前的所有消息,本例得到前两条旧历史;messages[-1].content 取最后一条正文,得到当前问题。随后 LCEL 链用 MessagesPlaceholder 插入历史、填入问题,再调用模型。新回复交回 LangGraph 保存,供下一轮继续使用。
调用入口必须是 dialog_graph.invoke(...),这样流程才会读取之前的状态。单独调用内部的 dialog_chain.invoke(...) 时,仍需自己提供 history。
InMemorySaver 只保存在当前进程的内存里,两轮调用要复用同一个实例;程序重启后不能靠它恢复历史。这个限制和第 9 节使用内存列表相同。存储方式说明
7. Agents 与 Tools:模型请求,程序执行
用户问“17 × 23 等于多少”,程序可以提供一个乘法函数,让模型请求它来计算。下面的 multiply 就是普通 Python 函数,直接执行 multiply(17, 23) 会得到整数 391。
1 | def multiply(a: int, b: int) -> int: |
要让模型知道这个工具,需要绑定工具的名称、用途和参数。下面假设 model 已配置好,并且支持工具调用。bind_tools 会根据函数的说明和类型标注生成工具描述;这一步完成后,还需要调用模型,模型才会根据问题决定是否请求工具。工具调用说明
1 | from langchain_core.messages import HumanMessage, ToolMessage |
假设这次模型决定调用 multiply。返回的 ai 是一条 AIMessage,其中 ai.content 可能是空字符串,ai.tool_calls 可能包含下面这条请求。这里的调用 ID 用 c1 示意,实际值由模型服务返回。
1 | [ |
这段数据表达的是“请执行 multiply(a=17, b=23)”。到这里,Python 函数还没有运行。应用程序需要读取请求,调用函数,再把执行结果加进消息列表。下面接着处理刚才的 ai,演示一轮工具执行。
1 | messages.append(ai) # 保留模型提出的工具调用 |
**是 Python 在调用函数时展开字典的语法。这里call["args"]是{"a": 17, "b": 23},所以multiply(**call["args"])等同于multiply(a=17, b=23)。如果变量名是args,就写成multiply(**args);args只是变量名。
乘法执行后,result 是整数 391,str(result) 把它转成消息正文 "391"。第二次调用模型时,消息列表包含下面三条内容。
| 消息 | 内容 | 作用 |
|---|---|---|
HumanMessage |
请使用乘法工具计算 17 × 23 | 用户问题 |
AIMessage |
请求 multiply,参数为 17 和 23,ID 为 c1 |
模型提出工具调用 |
ToolMessage |
正文为 "391",tool_call_id 为 c1 |
程序返回执行结果 |
tool_call_id 用来把结果和请求配对。若模型同时请求了乘法和加法,两条工具结果必须各自带上正确的调用 ID,不能交换。模型读到乘法结果后,才可能生成“17 × 23 = 391”这样的回答。
bind_tools()让模型能够提出工具调用。执行函数和回传结果仍需要程序完成。StrOutputParser()只提取文本,如果模型这时的正文为空,解析结果也是空字符串,解析器不会代替程序计算乘法。
上面的代码只演示了一轮工具执行。第二次返回的 reply 仍可能带有 tool_calls,这时还要执行新的请求,再把结果交回模型。直到模型不再请求工具、给出最终回答,这次问答才完成。
Agent 就负责组织这个循环:调用模型,查看它要用哪个工具,执行工具,带着结果再次调用模型。模型决定下一步需要什么工具,程序负责实际执行。LangChain 的 create_agent 可以管理这一过程,本节先理解它做的事情,不展开新的 API。
实现循环时要设置最大轮数;工具执行失败也应如实返回失败信息,不能写成已经成功。相比之下,前面的 prompt | model | parser 按预先写好的步骤执行,| 本身不会增加这个工具调用循环。
选读:普通函数和 LangChain Tool 对象怎样调用
这部分解释另一种工具写法,不是理解上面调用流程的前提。通过 def 定义的 multiply 是普通 Python 函数,直接用括号调用,没有 LangChain 提供的 .invoke() 方法。
1 | args = {"a": 17, "b": 23} |
如果把已有函数包装成 LangChain 工具对象,就可以通过 .invoke(...) 执行。下面用新变量 multiply_tool 保存这个对象。
1 | from langchain_core.tools import tool |
tool(multiply) 根据函数名称、说明文字和类型标注生成工具描述与参数结构;调用 .invoke(...) 时,再处理参数并执行内部函数。LangChain 工具说明
| 变量 | 指向什么对象 | 本例的执行方式 |
|---|---|---|
multiply |
普通 Python 函数 | multiply(**args) |
multiply_tool |
LangChain 工具对象 | multiply_tool.invoke(args) |
前面的 model.bind_tools([multiply]) 只是把工具描述提供给模型,不会把变量 multiply 改成工具对象。因此,前面的执行代码仍然使用 multiply(**call["args"])。
8. 把模型回复转成文本或字典
假设要从“商品 A7,库存 0”这条记录中提取商品编号和库存。程序后面要根据库存做判断,因此需要一个可以读取字段、比较数值的结果。
先用手动构造的 AIMessage 模拟模型回复,观察两个解析器分别做了什么。这段代码不调用真实模型。
1 | from langchain_core.messages import AIMessage |
两次打印都能看见 sku 和 stock,但类型不同。text 是一整段字符串,不能用 text["stock"] 取库存。data 是字典,可以用 data["stock"] 取字段;只是这里的库存仍是字符串 "0",因为模型回复中的数字带着引号。
如果模型回复的是 '{"sku":"A7","stock":0}',数字不带引号,JSON 解析后才会得到整数 0。JsonOutputParser 按 JSON 内容解析,不会因为字段叫 stock 就自动修改它的类型。
接到 LCEL 链尾
普通文字回答可以接 StrOutputParser();需要读取 JSON 字段时,就接 JsonOutputParser()。下面使用已经配置好的 model,从记录中提取商品编号和库存。
1 | from langchain_core.prompts import ChatPromptTemplate |
这条链依次完成“填模板 → 生成 JSON 文本 → 解析成字典”。如果模型回复 not json,解析器会抛出异常,本次调用就失败了。Prompt 中写“只输出 JSON”是对模型的要求;| 负责连接步骤,不会在解析失败后自动重新调用模型。
选读:需要检查字段时,再接入 Pydantic
Pydantic 是一个检查 Python 数据的库,不是使用 LCEL 的前提。如果后面的程序要求“必须有商品编号,库存必须是非负整数”,就需要在 JSON 解析后检查这些要求。
下面定义 StockReport,写清允许接收的字段和数值范围。这组规则也常被称为 Schema,可以理解成数据应该符合的格式。
1 | from pydantic import BaseModel, Field, StrictInt |
StockReport 是保存并校验数据的类。sku: str 要求提供字符串字段;StrictInt 要求库存值本身就是整数;Field(ge=0) 再要求这个整数大于或等于 0。Pydantic 严格模式说明
model_validate 是 Pydantic 通过 BaseModel 提供的方法,StockReport.model_validate(...) 是普通的方法调用语法。它接收数据,按这个类的规则检查;通过时返回 StockReport 实例,不符合规则时抛出校验异常。
1 | report = StockReport.model_validate({"sku": "A7", "stock": 0}) |
如果把上面字典中的库存换成 "0",会被 StrictInt 拒绝;换成 -1,会被 Field(ge=0) 拒绝。只有字段满足要求,程序才能拿到 report。
如果只声明 stock: int,Pydantic 默认会接受可以转换的 "0" 并转成整数。这里选择 StrictInt,是为了让“拒绝字符串库存”这个要求由代码明确检查。
接入 LCEL 时,直接在前面的 stock_chain 后再接一步校验。
1 | from langchain_core.runnables import RunnableLambda |
这里传给 RunnableLambda 的是 StockReport.model_validate 这个方法;调用整条链时,它才会收到 JSON 解析后的字典并执行检查。最后一步成功返回的是 StockReport,因此整条链的返回值也变成了 StockReport。
还要对照原始记录看数字是否提取正确。例如记录明明写着“库存 10”,模型却返回 {"sku":"A7","stock":0}:JSON 可以解析,0 也满足非负整数的要求,但库存数字仍然错了。解析器和字段检查只能解决数据形式的问题,不能替代这一步核对。
9. 把检索、历史和生成接起来
最后做一个小例子。用户问“FastAPI 的依赖项何时执行?”,也就是想知道依赖函数和接口处理函数谁先运行。程序把找到的资料和之前的对话交给模型,得到一段文字回答。
本节的代码按顺序阅读和执行。先手动准备一段资料,观察它怎样进入模型;最后再换成真正的检索调用。聊天模型 model 需要提前配置好,使用普通文本回复、不调用工具。
第一步,准备资料、旧对话和当前问题
下面的 docs 模拟已经检索到的文档列表。history 是这一段对话中已经说过的话,question 是本轮新问题。
1 | from langchain_core.documents import Document |
docs 是文档列表,模板里的 {context} 要填一段文字。因此,先用一个小函数把每段正文取出来,再用空行连接。这里为本节单独定义 join_docs。
1 | def join_docs(docs): |
现在要交给模板的三项数据都已经有了。context 提供技术资料,history 保留用户之前的讲解要求,question 指定本轮要回答的问题。
第二步,用一条 LCEL 链生成回答
本节新建 qa_prompt,让模型直接用文字回答。模板中先放规则,再插入旧消息,最后放资料和当前问题。
1 | from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder |
qa_chain 是这条链的变量名。定义它只是连接步骤,接下来调用 .invoke(...) 才会执行。把第一步准备好的三个变量放进字典,作为本次输入。
1 | input_data = { |
这一次调用里,每一步只做下面这件事。
| 步骤 | 收到什么 | 交出什么 |
|---|---|---|
qa_prompt |
包含资料、历史和问题的字典 | ChatPromptValue,里面是填好的消息 |
model |
填好的 Prompt | AIMessage,里面是模型的回答 |
StrOutputParser() |
模型的回复消息 | 回答字符串,保存到 answer |
这里已经完成一次“带着资料和旧对话回答问题”。StrOutputParser 取出回复文本,回答是否准确仍要对照资料判断。
第三步,把固定资料换成检索结果
前面手写 docs = [...] 是为了看清数据。实际使用时,这一行可以换成 docs = retriever.invoke(question),由已经配置好的检索器返回文档列表。
把准备输入和调用链的步骤放进一个函数,就可以重复提问。下面沿用刚才的 join_docs 和 qa_chain;retriever 要提前连接好可检索的资料。
1 | def ask(question, history): |
读这个函数时,从上往下看即可。先用问题查资料;if not docs 表示结果为空,此时直接返回,模型不会被调用。找到资料后,把正文、旧历史和问题交给已经定义好的链。
最后两次 append 将本轮问题和回答加到传进来的 history 列表中。假设原来有两条消息,调用成功后就变成四条。下次把同一个列表传给 ask,模型就能看到这一轮对话。当前问题是在生成回答之后才加入历史,因此本轮模型输入里不会重复出现它。
如果检索或模型调用抛出异常,程序不会执行后面的 append;本例在空检索时也会提前返回,不记录这一轮。这里的历史只保存在内存中,程序重启后不会保留。
这个例子只是处理了一段对话。将来做成多人使用的服务时,需要为每个会话分别读取和保存历史。