LangChain 核心概念

Catalogue
  1. 1. 六类模块与 LangChain、LCEL 的关系
  2. 2. Prompts 与 Models:从模板到回答
  3. 3. Chains 与 LCEL:把三个步骤连起来
  4. 4. LCEL 分支:生成回答,同时保留原始输入
    1. 下一个步骤只需要回答怎么办
  5. 5. Indexes 与 Retrieval:找到资料,再交给模型
    1. 为什么返回列表,数量由谁决定
    2. 多个片段怎样一起参与回答
    3. 用 LCEL 接起检索和模板
    4. 切分和检索还需要检查什么
  6. 6. Memory:把旧对话放进本轮输入
    1. 在模板中给历史消息留出位置
    2. 看一次模板填充后的完整消息
    3. 本轮问题只放一次,回答完成后再保存
  7. 7. Agents 与 Tools:模型请求,程序执行
  8. 8. 把模型回复转成文本或字典
    1. 接到 LCEL 链尾
  9. 9. 把检索、历史和生成接起来
    1. 第一步,准备资料、旧对话和当前问题
    2. 第二步,用一条 LCEL 链生成回答
    3. 第三步,把固定资料换成检索结果
  10. 参考资料

上一篇《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
2
3
4
5
6
7
8
9
10
from langchain_core.prompts import ChatPromptTemplate

prompt = ChatPromptTemplate.from_messages([
("system", "你是一名耐心的技术编辑"),
("human", "请用一句话解释 {topic}"),
])

value = prompt.invoke({"topic": "LCEL"})
for message in value.to_messages():
print(type(message).__name__, message.content)

这段代码会打印以下两行。type(message).__name__ 取消息对象的类型名,message.content 取消息正文。

1
2
SystemMessage 你是一名耐心的技术编辑
HumanMessage 请用一句话解释 LCEL

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
2
3
reply = chat_model.invoke(value)
print(type(reply).__name__) # AIMessage
print(reply.content) # 例如:LCEL 用来连接多个处理步骤。

value 是一个 ChatPromptValue,可以把它看作装着本次消息的容器。value.to_messages() 会取出里面的消息,得到一个 Python 列表,内容相当于下面两条消息。

1
2
3
4
5
6
from langchain_core.messages import SystemMessage, HumanMessage

[
SystemMessage(content="你是一名耐心的技术编辑"),
HumanMessage(content="请用一句话解释 LCEL"),
]

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
2
3
4
5
6
7
8
9
10
11
12
def _convert_input(self, model_input: LanguageModelInput) -> PromptValue:
if isinstance(model_input, PromptValue):
return model_input
if isinstance(model_input, str):
return StringPromptValue(text=model_input)
if isinstance(model_input, Sequence):
return ChatPromptValue(messages=convert_to_messages(model_input))
msg = ( # type: ignore[unreachable]
f"Invalid input type {type(model_input)}. "
"Must be a PromptValue, str, or list of BaseMessages."
)
raise ValueError(msg)

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
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
from langchain_core.messages import AIMessage
from langchain_core.output_parsers import StrOutputParser
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.runnables import RunnableLambda

prompt = ChatPromptTemplate.from_template("请用一句话解释 {topic}")

def fake_model(value):
messages = value.to_messages()
last_message = messages[-1]
request = last_message.content
return AIMessage(content=f"演示回答:{request}")

chain = prompt | RunnableLambda(fake_model) | StrOutputParser() # 定义流程
print(chain.invoke({"topic": "LCEL"})) # 传入数据,执行整条链
# 演示回答:请用一句话解释 LCEL

这段代码里,RunnableLambda(fake_model) 是一次创建对象的调用。RunnableLambda 是类,fake_model 是传给它的函数对象。Python 允许把函数作为参数传递;写 fake_model 表示取这个函数,写 fake_model(value) 才会执行函数。

包装和执行可以拆开来看。下面沿用示例中的 prompt 与 fake_model。

1
2
3
step = RunnableLambda(fake_model)         # 创建包装对象,尚未执行 fake_model
value = prompt.invoke({"topic": "LCEL"}) # 先得到函数需要的输入
reply = step.invoke(value) # 内部调用 fake_model(value)

在这个例子里,普通函数 fake_model 通过 fake_model(value) 调用,包装后的 step 则支持 .invoke(value)。类名中的 Lambda 不限制函数的定义方式:用 def 写出的函数也能传给它。

[-1] 是 Python 的索引写法,表示最后一个元素,[0] 表示第一个元素。本例的 from_template(...) 生成一条 human 消息,所以这里取到的 request 是字符串 "请用一句话解释 LCEL"。这段函数只读取最后一条消息,用它来构造固定格式的演示回答。

fake_model 收到 ChatPromptValue,返回一个 AIMessage。整条链的数据类型依次变化。

1
2
3
{"topic": "LCEL"}  --prompt-->  ChatPromptValue
ChatPromptValue --fake_model--> AIMessage
AIMessage --StrOutputParser--> str

对照 chain.invoke({"topic": "LCEL"}),手动执行同样的流程是下面三步。

1
2
3
value = prompt.invoke({"topic": "LCEL"})          # 填模板
reply = step.invoke(value) # 调用前面包装好的模拟模型
answer = StrOutputParser().invoke(reply) # 取出文本

链替程序完成了这三次调用和中间结果的传递。下次传入 {"topic": "FastAPI"},只会改变填进模板的主题,处理步骤保持不变。

使用真实聊天模型时,把 RunnableLambda(fake_model) 换成已配置好的 model,就得到 prompt | model | StrOutputParser()。前后步骤要求的输入输出仍然一样。

运行准备:如何换成真实模型(服务配置,不是 LCEL 学习重点)

下面需要安装 langchain 和所选模型提供商的集成包,并配置该服务要求的凭据。MODEL_ID 是程序读取的环境变量,填写所选服务支持的模型标识。这些配置随服务而异,本文不展开;真实服务示例未实测。

1
2
3
4
5
6
7
8
9
import os
from langchain.chat_models import init_chat_model
from langchain_core.output_parsers import StrOutputParser
from langchain_core.prompts import ChatPromptTemplate

prompt = ChatPromptTemplate.from_template("请用一句话解释 {topic}")
model = init_chat_model(os.environ["MODEL_ID"])
real_chain = prompt | model | StrOutputParser()
answer = real_chain.invoke({"topic": "LCEL"})

后面需要真实模型的例子都以已经配置好的 model 为前提。模型初始化说明

选读:batch 一次处理多个问题,stream 逐段接收回答

这两个也是 Runnable 的调用方式。先会用 invoke 串通流程,再按需要使用它们。

batch 接收一组输入,返回对应的一组结果。下面仍用前面的模拟模型,可以直接对照输入和输出。

1
2
3
results = chain.batch([{"topic": "LCEL"}, {"topic": "FastAPI"}])
print(results)
# ['演示回答:请用一句话解释 LCEL', '演示回答:请用一句话解释 FastAPI']

stream 适合在模型生成过程中逐段显示文字。下面沿用上方配置好的 real_chain,需要模型支持流式输出;链尾的 StrOutputParser 让循环每次拿到的是一段字符串。

1
2
3
4
5
6
7
for piece in real_chain.stream({"topic": "LCEL"}):
print(repr(piece))

# 可能依次打印,分段只是示意:
# 'LCEL'
# ' 用来连接'
# '多个处理步骤。'

这些片段拼起来才是一条完整回答,每次返回的长度不固定。想让它们在同一行逐渐显示,可把循环中的打印改成 print(piece, end="", flush=True)。本文的 fake_model 一次返回整条消息,用它观察不到这种逐段生成的效果。Runnable 调用接口与组合说明

4. LCEL 分支:生成回答,同时保留原始输入

上一节的链最终只返回回答字符串。如果还想知道“这条回答对应哪个输入”,可以把同一份输入交给两路处理:一路生成回答,另一路保留原始数据。

下面继续使用上一节含 fake_model 的 chain,不调用真实模型。RunnableParallel 创建并行分支,RunnablePassthrough 让输入原样通过。

1
2
3
4
5
6
7
8
9
10
11
12
13
from langchain_core.runnables import RunnableParallel, RunnablePassthrough

branch = RunnableParallel(
answer=chain,
original=RunnablePassthrough(),
)

result = branch.invoke({"topic": "LCEL"})
print(result)
# {
# 'answer': '演示回答:请用一句话解释 LCEL',
# 'original': {'topic': 'LCEL'}
# }

answer 和 original 是结果字典的键。两路收到的输入完全相同,都是 {"topic": "LCEL"},各自处理后才把结果放到对应的键下。

分支 收到的输入 做什么 返回的值
answer {"topic": "LCEL"} 执行模板、模拟模型和解析器 回答字符串
original {"topic": "LCEL"} 原样返回 原始字典

因此 result["answer"] 取到回答,result["original"]["topic"] 取到最初的主题。RunnablePassthrough() 保留的是整个输入,不会自动从字典里选一个字段。

下一个步骤只需要回答怎么办

branch 的输出是字典。如果后面只需要回答文本,就先取出 answer。

1
2
3
4
5
6
7
8
9
from langchain_core.runnables import RunnableLambda

def take_answer(data):
return data["answer"]

text_chain = branch | RunnableLambda(take_answer)
text = text_chain.invoke({"topic": "LCEL"})
print(text)
# 演示回答:请用一句话解释 LCEL

这次数据变化是“原始输入 → 分支结果字典 → 取出回答字符串”。它解释了为什么不能把 branch 直接交给 StrOutputParser:解析器接收消息或文本,不接收包含 answer、original 的整个字典。这里 answer 已经是字符串,取出来就可以直接使用。

Python 写法补充:lambda x: x["answer"] 是一个没有单独命名的小函数,与上面的 take_answer 做同样的取值。因此也能写成 RunnableLambda(lambda x: x["answer"])。会用 def 的写法就能完成本文示例,无需刻意缩写。

选读:字典和函数什么时候能自动转换成 Runnable

前面已经用 RunnableParallel(...) 创建了 branch,因此可以省略右边的 RunnableLambda,直接连接函数。

1
2
text_chain = branch | take_answer
# 等价于 branch | RunnableLambda(take_answer)

这里由左边的 branch 处理 LCEL 连接,LangChain 会把普通函数 take_answer 自动包装成 RunnableLambda。写函数名时不加括号,表示把函数交给链;执行 text_chain.invoke(...) 时,才把分支结果传给它。

也可以反过来:左边用字典简写,右边保留 RunnableLambda。

1
2
3
4
text_chain = {
"answer": chain,
"original": RunnablePassthrough(),
} | RunnableLambda(take_answer)

这个字典的值是“生成字段的处理步骤”。与右边的 Runnable 通过 | 连接时,LangChain 会把它转成 RunnableParallel。执行后才得到包含回答和原始输入的结果字典,再交给 take_answer。

但不能把两边的包装都省掉。下面这段会在创建链时直接报错,还没到 .invoke()。

1
2
3
4
5
6
# 错误示范:普通字典不能直接用 | 连接普通函数
text_chain = {
"answer": chain,
"original": RunnablePassthrough(),
} | take_answer
# TypeError: unsupported operand type(s) for |: 'dict' and 'function'

这时 | 左边的整个对象是普通字典,右边是普通函数,没有 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
2
3
4
5
6
7
8
9
from langchain_core.documents import Document

doc_b = Document(
page_content="FastAPI 请求体可以通过 Pydantic 模型进行校验。",
metadata={
"source_id": "doc-b",
"source": "fastapi-notes.md",
},
)

page_content 保存正文,metadata 保存附加信息。这里的 source_id 是程序为片段设置的编号,source 记录它来自哪份笔记。

接下来,让 Embedding 模型(嵌入模型)把每个片段的正文转成一串数字,称为向量。例如 [0.12, -0.34, 0.56],这里只示意形式,没有实际计算这些数值。语义相近的文字,其向量通常也更相近,因此可以用来查找相关片段。向量由嵌入模型计算;后面生成文字回答的是聊天模型,两者做的工作不同。Embeddings 接口说明

VectorStore 是保存和搜索这些向量的存储。可以把其中一条记录理解成“向量 B + chunk B 的正文 + 来源信息”。搜索时用向量比较相似度,找到后取回对应的文字和来源。因此,向量检索需要保留向量与原文之间的对应关系。

1
2
3
4
5
6
准备资料
原始笔记 → Document → 切成多个 chunk(仍用 Document 保存)
↓
每个 chunk 的正文计算向量
↓
将向量、正文和来源信息存入 VectorStore

这部分就是 Indexes 在本文中承担的工作。它把资料准备好,供后面的检索使用。

假设资料已经入库,并创建好了检索器 retriever。用户提问时,把问题字符串传给它。

1
2
question = "请求体如何校验?"
docs = retriever.invoke(question)

对于这里的向量检索器,内部会把问题也转换成向量,再到 VectorStore 中比较已保存的片段向量。建库和提问时要使用配套的嵌入模型,让两边的向量可以比较。理想情况下,这个问题会找到介绍请求体校验的 chunk B,随后返回包含它的 list[Document]。

1
2
3
4
5
6
7
8
9
"请求体如何校验?"
↓ retriever.invoke(question)
将问题转换成查询向量
↓
VectorStore 搜索相似的片段向量
↓
取回对应的正文和来源信息
↓
list[Document]

调用方给 retriever 的是问题字符串,拿到的是文档列表;问题转向量和搜索由内部完成。本文只用这一种检索方式理解数据流。更多方式参考:LangChain 检索组件说明

为什么返回列表,数量由谁决定

一个问题可能需要几段资料才能回答完整。例如“怎样校验请求体,并要求年龄至少 18?”包含两个要求,介绍请求体校验的片段和介绍年龄限制的片段都可能有用。因此,Retriever 返回一组候选资料,供后面的程序组织和使用。

这里每个 Document 通常代表一个片段。列表里的两项可以来自同一份笔记,也可以来自不同文件。统一使用 list[Document],还能表示只有一项的 [doc_b],以及没有结果的 [];后面的代码始终可以按列表处理。

返回多少项取决于检索配置。对于本文使用的向量检索,假设 vector_store 已配置好嵌入模型并存入资料,可以这样创建检索器。下面仅展示配置方式。

1
2
3
retriever = vector_store.as_retriever(search_kwargs={"k": 2})
question = "怎样校验请求体,并要求年龄至少 18?"
docs = retriever.invoke(question)

as_retriever(...) 从向量存储创建检索器,k=2 表示希望取两条候选结果,实际可能更少。即使设为 k=1,结果仍是列表。本节只需理解“查询字符串 → 文档列表”;创建知识库时的其他搜索参数可以暂时跳过。VectorStore 检索器配置说明

多个片段怎样一起参与回答

先写一个 format_docs 函数,把列表中每个片段的编号和正文拼成一段文本。这里的文档都带有前面定义的 source_id。

1
2
3
4
5
6
def format_docs(docs):
parts = []
for doc in docs:
text = f"[{doc.metadata['source_id']}] {doc.page_content}"
parts.append(text)
return "\n\n".join(parts)

Python 语法补充:f"...{表达式}..." 会把花括号中表达式的值填进字符串。这里每次生成类似 [doc-b] 资料正文 的文字;"\n\n".join(parts) 用一个空行连接这些文字。它只整理已经拿到的资料,不执行检索。

下面沿用 doc_b,再构造一段字段约束说明,模拟检索到了两项资料。这只是展示数据如何传递,没有实际运行向量搜索。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
doc_d = Document(
page_content="可以为 age 字段设置数值下限,要求年龄至少为 18。",
metadata={
"source_id": "doc-d",
"source": "fastapi-notes.md",
},
)

docs = [doc_b, doc_d] # 模拟本次检索结果
context = format_docs(docs)
print(context)
# [doc-b] FastAPI 请求体可以通过 Pydantic 模型进行校验。
#
# [doc-d] 可以为 age 字段设置数值下限,要求年龄至少为 18。

准备一个同时接收 context 和 question 的模板,试着把这两段资料放进去。search_prompt 是本节新建的模板名称。

1
2
3
4
5
6
7
8
9
10
11
12
from langchain_core.prompts import ChatPromptTemplate

search_prompt = ChatPromptTemplate.from_messages([
("system", "请根据资料回答。资料不足时说明无法确认。"),
("human", "资料:\n{context}\n\n问题:{question}"),
])

value = search_prompt.invoke({
"context": context,
"question": "怎样校验请求体,并要求年龄至少 18?",
})
print(value.to_messages()[-1].content)

最后一条 human 消息的正文如下。这就是模型会看到的资料和问题。

1
2
3
4
5
6
资料:
[doc-b] FastAPI 请求体可以通过 Pydantic 模型进行校验。

[doc-d] 可以为 age 字段设置数值下限,要求年龄至少为 18。

问题:怎样校验请求体,并要求年龄至少 18?

一条有依据的回答可以是“用 Pydantic 模型校验请求体,并为 age 设置至少 18 的数值下限”。前半句的依据来自 doc-b,后半句来自 doc-d。

这里会把列表中的两段资料都交给模型,供它综合回答。模型不会自己读取 VectorStore;只有程序检索后填进 Prompt 的内容,才会成为本轮参考资料。

用 LCEL 接起检索和模板

先前用手写的 docs 演示数据。本节接下来假设 retriever 已按上面的方式配置好,并能返回带有 source_id 的文档。用第 4 节学过的分支,让同一个问题一路查资料、一路原样保留。

1
2
3
4
5
6
7
8
9
10
11
from langchain_core.runnables import (
RunnableLambda, RunnableParallel, RunnablePassthrough,
)

search_inputs = RunnableParallel(
context=retriever | RunnableLambda(format_docs),
question=RunnablePassthrough(),
)

question = "怎样校验请求体,并要求年龄至少 18?"
data = search_inputs.invoke(question)

如果检索返回刚才的两段资料,data 就是下面这样的字典。模板收到的是执行结果,不是 retriever 等处理对象。

1
2
3
4
5
{
"context": "[doc-b] FastAPI 请求体可以通过 Pydantic 模型进行校验。\n\n"
"[doc-d] 可以为 age 字段设置数值下限,要求年龄至少为 18。",
"question": "怎样校验请求体,并要求年龄至少 18?",
}

search_prompt.invoke(data) 能填好模板。因此把它们连接起来,就能自动传递这个字典;再接上已配置好的模型和解析器,就得到一条 RAG 链。

1
2
3
4
from langchain_core.output_parsers import StrOutputParser

rag_chain = search_inputs | search_prompt | model | StrOutputParser()
answer = rag_chain.invoke(question)

整个过程是“问题字符串 → 检索并保留问题 → 资料与问题的字典 → 填好的消息 → 模型回复 → 回答文本”。

如果业务传入的是 {"question": "请求体如何校验?"},先把问题取出来,再交给上面的链。

1
2
3
4
5
def take_question(data):
return data["question"]

dict_rag_chain = RunnableLambda(take_question) | rag_chain
answer = dict_rag_chain.invoke({"question": "请求体如何校验?"})

这里增加的步骤只负责 dict → str。后面的检索器仍然收到字符串,RunnablePassthrough 保留的也仍然是问题字符串。这种“先看下游要什么,再提取字段”的判断,是使用 LCEL 时需要掌握的重点。

切分和检索还需要检查什么

切分时,要兼顾“容易找到相关片段”和“片段自己能把事情说清楚”。如果把路径参数、请求体和依赖注入全部放在一个很大的 chunk 里,查询请求体校验时可能会带回很多无关内容。切得太细也会出问题,例如笔记里有下面两句话。

1
2
3
4
原文: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
2
3
4
5
6
7
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder

rag_prompt = ChatPromptTemplate.from_messages([
("system", "请根据资料回答;资料不足时说明无法确认。"),
MessagesPlaceholder("history"),
("human", "资料:\n{context}\n\n问题:{question}"),
])

这里需要提供三个字段,它们的数据类型和用途不同。

字段 本例传入的内容 放进模板后起什么作用
history 旧的 HumanMessage、AIMessage 组成的列表 让模型看到之前的对话,保留每条消息的角色
context 检索片段整理成的字符串 提供回答技术问题所需的资料
question 当前问题字符串 告诉模型本轮要回答什么

MessagesPlaceholder("history") 中的 "history" 对应调用字典的同名键。这个对象从本次输入中取出历史消息;它在模板列表中的位置,决定了这些消息插入哪里。

看一次模板填充后的完整消息

下面手动构造两条旧消息,模拟程序已经读取了当前会话的历史;资料也用一段文本模拟。这个例子只组装 Prompt,不调用真实模型。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
from langchain_core.messages import AIMessage, HumanMessage

history = [
HumanMessage(content="请用初学者能理解的方式讲解 FastAPI。"),
AIMessage(content="好的,我会先解释概念,再举例。"),
]
context = "FastAPI 会在调用接口处理函数前执行依赖函数。"
question = "FastAPI 的依赖项何时执行?"

value = rag_prompt.invoke({
"history": history,
"context": context,
"question": question,
})

messages = value.to_messages()
for message in messages:
print(type(message).__name__, message.content)

value 是 ChatPromptValue,value.to_messages() 取出其中的消息列表。按上面的模板和数据,预期会看到四条消息,顺序如下。

1
2
3
4
5
6
7
SystemMessage 请根据资料回答;资料不足时说明无法确认。
HumanMessage 请用初学者能理解的方式讲解 FastAPI。
AIMessage 好的,我会先解释概念,再举例。
HumanMessage 资料:
FastAPI 会在调用接口处理函数前执行依赖函数。

问题:FastAPI 的依赖项何时执行?

模板里虽然只写了一行 MessagesPlaceholder("history"),但本次插入了两条消息,各自仍保留 human 和 ai 角色。最后一条 HumanMessage 则包含本轮资料和问题。把这个 value 交给模型,模型才能同时看到讲解偏好、技术资料和当前问题;上面的打印结果展示的是准备发送的输入。

新会话没有旧消息时,传入 "history": [] 即可。MessagesPlaceholder("history") 对应的位置不会插入任何消息,最终只剩 system 和当前 human 两条。

MessagesPlaceholder 只把已经提供的消息列表插入模板,不负责查询数据库。这里应传入 history 列表,不能传入 "Human: 请用简单语言讲解\nAI: 好的" 这样的整段字符串,期待它自动拆成两条消息。

本轮问题只放一次,回答完成后再保存

上面的 history 只有旧消息,当前问题由模板中的 {question} 填入。如果调用前又执行下面这行代码,就会把当前问题放进历史。

1
2
# 错误示范:不要在调用上述模板前,把本轮问题也放入 history
history.append(HumanMessage(content=question))

再用这个 history 和相同的 question 调用模板,结果就变成五条消息。第 4 条来自历史中的当前问题,第 5 条来自模板末尾的“资料 + 当前问题”,同一个问题出现了两遍。因此,在这个模板中,应让 history 保持为本轮之前的对话。

等到本轮得到回答,再把当前问题和这次回答保存起来。下一轮读取时,它们才属于旧历史。每轮按下面的顺序处理;第 9 节会用消息列表演示如何记录本轮对话。

1
2
3
4
5
6
7
读取该会话的旧历史
↓
旧历史 + 本轮资料和问题 → Prompt → Model
↓
得到回答
↓
保存本轮 HumanMessage 和回答消息,供下一轮读取

如果某条旧消息没有被取出来,模型本轮就看不到它。多人使用时,要按会话分别读写历史,避免把 A 的消息放进 B 的输入。

选读:MessagesPlaceholder 的源码与可选参数(非核心,可跳过)

这部分用于回查“历史消息怎样被取出并插入”。使用前面的模板时,不需要记住这些内部方法。

创建 MessagesPlaceholder("history") 时,对象会把 "history" 保存到 variable_name。下面是它的 format_messages 方法的简化片段,省略了可选参数分支和类型标注,无需复制到业务代码中。

1
2
3
4
5
def format_messages(self, **kwargs):
value = kwargs[self.variable_name]
if not isinstance(value, list):
raise ValueError("需要消息列表")
return convert_to_messages(value)

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
2
3
4
result = []
for message_template in self.messages:
message = message_template.format_messages(**kwargs)
result.extend(message)

这里的 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
2
3
4
5
6
7
8
9
10
11
12
13
14
15
placeholder = MessagesPlaceholder("history", optional=True, n_messages=2)

print(placeholder.format_messages())
# []:optional=True 允许省略 history

messages = placeholder.format_messages(history=[
HumanMessage(content="我叫 Lin。"),
AIMessage(content="你好,Lin。"),
HumanMessage(content="请用简单的话回答。"),
])
for message in messages:
print(type(message).__name__, message.content)

# AIMessage 你好,Lin。
# HumanMessage 请用简单的话回答。

optional 默认是 False,需要提供 history;设为 True 才能省略。n_messages=2 只保留传入列表的最后两条消息,不是最后两轮对话,也不会自动生成摘要。不设置它,就保留传入的全部消息。把这个 placeholder 放入 ChatPromptTemplate.from_messages([...]) 中,也会按相同规则处理历史。

选读:用 checkpointer 保存历史,再交给 LCEL(非核心,可跳过)

前面的示例由程序读取和保存历史。如果以后使用 LangGraph,可以把这部分交给 checkpointer。LangGraph 是执行工作流程的框架;它引入的流程节点和状态管理不属于本文的学习重点,下面只保留一个配合 LCEL 的例子。

这里的“状态”指流程保留的数据,本例只关心 messages 消息列表。checkpointer 保存这份列表,让下一轮取回;MessagesPlaceholder 则把取回的消息插入模板。两者分别负责存取和组装。

下面是独立的纯文本对话示例,需要安装 langgraph,并事先配置好没有绑定工具的聊天模型 model。示例未实测真实模型调用。每轮只提交一条新消息,不手动重复提交旧历史。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
from langchain_core.messages import HumanMessage
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.graph import StateGraph, MessagesState, START, END

# LCEL 链负责把历史和当前问题交给模型
dialog_prompt = ChatPromptTemplate.from_messages([
("system", "你是一个耐心的助手"),
MessagesPlaceholder("history"),
("human", "{question}"),
])
dialog_chain = dialog_prompt | model

def call_model(state: MessagesState):
messages = state["messages"]
history = messages[:-1] # 除最后一条以外,都是旧消息
question = messages[-1].content # 最后一条是本轮问题

reply = dialog_chain.invoke({
"history": history,
"question": question,
})
return {"messages": [reply]} # 只返回新增的 AIMessage

# LangGraph 负责执行这个步骤,并管理消息状态
builder = StateGraph(MessagesState)
builder.add_node("reply", call_model)
builder.add_edge(START, "reply")
builder.add_edge("reply", END)

checkpointer = InMemorySaver()
dialog_graph = builder.compile(checkpointer=checkpointer)
config = {"configurable": {"thread_id": "name-demo"}}

# 第一轮
dialog_graph.invoke(
{"messages": [HumanMessage(content="我叫 Lin。")]},
config=config,
)

# 第二轮沿用相同的 thread_id,只传本轮的新消息
result = dialog_graph.invoke(
{"messages": [HumanMessage(content="我叫什么?")]},
config=config,
)
print(result["messages"][-1].content)
# 可能的回复:你叫 Lin。

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
2
3
HumanMessage:我叫 Lin。
AIMessage:你好,Lin。
HumanMessage:我叫什么?

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
2
3
def multiply(a: int, b: int) -> int:
"""计算两个整数的乘积。"""
return a * b

要让模型知道这个工具,需要绑定工具的名称、用途和参数。下面假设 model 已配置好,并且支持工具调用。bind_tools 会根据函数的说明和类型标注生成工具描述;这一步完成后,还需要调用模型,模型才会根据问题决定是否请求工具。工具调用说明

1
2
3
4
5
from langchain_core.messages import HumanMessage, ToolMessage

model_with_tools = model.bind_tools([multiply])
messages = [HumanMessage(content="请使用乘法工具计算 17 × 23。")]
ai = model_with_tools.invoke(messages)

假设这次模型决定调用 multiply。返回的 ai 是一条 AIMessage,其中 ai.content 可能是空字符串,ai.tool_calls 可能包含下面这条请求。这里的调用 ID 用 c1 示意,实际值由模型服务返回。

1
2
3
4
5
6
7
8
[
{
"name": "multiply",
"args": {"a": 17, "b": 23},
"id": "c1",
"type": "tool_call",
}
]

这段数据表达的是“请执行 multiply(a=17, b=23)”。到这里,Python 函数还没有运行。应用程序需要读取请求,调用函数,再把执行结果加进消息列表。下面接着处理刚才的 ai,演示一轮工具执行。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
messages.append(ai)  # 保留模型提出的工具调用

if ai.tool_calls:
for call in ai.tool_calls:
if call["name"] != "multiply":
raise ValueError("请求了未提供的工具")

result = multiply(**call["args"]) # 实际执行 multiply(a=17, b=23)
messages.append(ToolMessage(
content=str(result),
tool_call_id=call["id"],
))

reply = model_with_tools.invoke(messages) # 把工具结果交回模型
else:
reply = 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
2
args = {"a": 17, "b": 23}
result = multiply(**args) # 等同于 multiply(a=17, b=23)

如果把已有函数包装成 LangChain 工具对象,就可以通过 .invoke(...) 执行。下面用新变量 multiply_tool 保存这个对象。

1
2
3
4
5
from langchain_core.tools import tool

multiply_tool = tool(multiply) # 包装函数,此时不执行乘法
result = multiply_tool.invoke({"a": 17, "b": 23})
# 结果为整数 391

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
2
3
4
5
6
7
8
9
10
11
12
13
from langchain_core.messages import AIMessage
from langchain_core.output_parsers import StrOutputParser, JsonOutputParser

reply = AIMessage(content='{"sku":"A7","stock":"0"}')

text = StrOutputParser().invoke(reply)
print(text) # {"sku":"A7","stock":"0"}
print(type(text).__name__) # str

data = JsonOutputParser().invoke(reply)
print(data) # {'sku': 'A7', 'stock': '0'}
print(type(data).__name__) # dict
print(type(data["stock"]).__name__) # str

两次打印都能看见 sku 和 stock,但类型不同。text 是一整段字符串,不能用 text["stock"] 取库存。data 是字典,可以用 data["stock"] 取字段;只是这里的库存仍是字符串 "0",因为模型回复中的数字带着引号。

如果模型回复的是 '{"sku":"A7","stock":0}',数字不带引号,JSON 解析后才会得到整数 0。JsonOutputParser 按 JSON 内容解析,不会因为字段叫 stock 就自动修改它的类型。

接到 LCEL 链尾

普通文字回答可以接 StrOutputParser();需要读取 JSON 字段时,就接 JsonOutputParser()。下面使用已经配置好的 model,从记录中提取商品编号和库存。

1
2
3
4
5
6
7
8
9
10
11
from langchain_core.prompts import ChatPromptTemplate

stock_prompt = ChatPromptTemplate.from_template(
"从记录中提取商品编号和库存,只输出 JSON:"
"sku 为字符串,stock 为整数。记录:{record}"
)
stock_chain = stock_prompt | model | JsonOutputParser()

data = stock_chain.invoke({"record": "商品 A7,库存 0"})
# 模型按要求回答时:{"sku": "A7", "stock": 0}
print(data["stock"]) # 0

这条链依次完成“填模板 → 生成 JSON 文本 → 解析成字典”。如果模型回复 not json,解析器会抛出异常,本次调用就失败了。Prompt 中写“只输出 JSON”是对模型的要求;| 负责连接步骤,不会在解析失败后自动重新调用模型。

选读:需要检查字段时,再接入 Pydantic

Pydantic 是一个检查 Python 数据的库,不是使用 LCEL 的前提。如果后面的程序要求“必须有商品编号,库存必须是非负整数”,就需要在 JSON 解析后检查这些要求。

下面定义 StockReport,写清允许接收的字段和数值范围。这组规则也常被称为 Schema,可以理解成数据应该符合的格式。

1
2
3
4
5
from pydantic import BaseModel, Field, StrictInt

class StockReport(BaseModel):
sku: str
stock: StrictInt = Field(ge=0)

StockReport 是保存并校验数据的类。sku: str 要求提供字符串字段;StrictInt 要求库存值本身就是整数;Field(ge=0) 再要求这个整数大于或等于 0。Pydantic 严格模式说明

model_validate 是 Pydantic 通过 BaseModel 提供的方法,StockReport.model_validate(...) 是普通的方法调用语法。它接收数据,按这个类的规则检查;通过时返回 StockReport 实例,不符合规则时抛出校验异常。

1
2
3
report = StockReport.model_validate({"sku": "A7", "stock": 0})
print(report.sku) # A7
print(report.stock) # 0

如果把上面字典中的库存换成 "0",会被 StrictInt 拒绝;换成 -1,会被 Field(ge=0) 拒绝。只有字段满足要求,程序才能拿到 report。

如果只声明 stock: int,Pydantic 默认会接受可以转换的 "0" 并转成整数。这里选择 StrictInt,是为了让“拒绝字符串库存”这个要求由代码明确检查。

接入 LCEL 时,直接在前面的 stock_chain 后再接一步校验。

1
2
3
4
5
from langchain_core.runnables import RunnableLambda

report_chain = stock_chain | RunnableLambda(StockReport.model_validate)
report = report_chain.invoke({"record": "商品 A7,库存 0"})
# 字段检查通过后,report 是 StockReport 实例

这里传给 RunnableLambda 的是 StockReport.model_validate 这个方法;调用整条链时,它才会收到 JSON 解析后的字典并执行检查。最后一步成功返回的是 StockReport,因此整条链的返回值也变成了 StockReport。

还要对照原始记录看数字是否提取正确。例如记录明明写着“库存 10”,模型却返回 {"sku":"A7","stock":0}:JSON 可以解析,0 也满足非负整数的要求,但库存数字仍然错了。解析器和字段检查只能解决数据形式的问题,不能替代这一步核对。

9. 把检索、历史和生成接起来

最后做一个小例子。用户问“FastAPI 的依赖项何时执行?”,也就是想知道依赖函数和接口处理函数谁先运行。程序把找到的资料和之前的对话交给模型,得到一段文字回答。

本节的代码按顺序阅读和执行。先手动准备一段资料,观察它怎样进入模型;最后再换成真正的检索调用。聊天模型 model 需要提前配置好,使用普通文本回复、不调用工具。

第一步,准备资料、旧对话和当前问题

下面的 docs 模拟已经检索到的文档列表。history 是这一段对话中已经说过的话,question 是本轮新问题。

1
2
3
4
5
6
7
8
9
10
11
from langchain_core.documents import Document
from langchain_core.messages import AIMessage, HumanMessage

docs = [
Document(page_content="FastAPI 会在调用接口处理函数前执行依赖函数。"),
]
history = [
HumanMessage(content="请用简单的话解释。"),
AIMessage(content="好的,我会尽量说得直白一些。"),
]
question = "FastAPI 的依赖项何时执行?"

docs 是文档列表,模板里的 {context} 要填一段文字。因此,先用一个小函数把每段正文取出来,再用空行连接。这里为本节单独定义 join_docs。

1
2
3
4
5
6
7
8
9
def join_docs(docs):
parts = []
for doc in docs:
parts.append(doc.page_content)
return "\n\n".join(parts)

context = join_docs(docs)
print(context)
# FastAPI 会在调用接口处理函数前执行依赖函数。

现在要交给模板的三项数据都已经有了。context 提供技术资料,history 保留用户之前的讲解要求,question 指定本轮要回答的问题。

第二步,用一条 LCEL 链生成回答

本节新建 qa_prompt,让模型直接用文字回答。模板中先放规则,再插入旧消息,最后放资料和当前问题。

1
2
3
4
5
6
7
8
9
10
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
from langchain_core.output_parsers import StrOutputParser

qa_prompt = ChatPromptTemplate.from_messages([
("system", "请根据资料回答问题。资料不足时说明无法确认。"),
MessagesPlaceholder("history"),
("human", "资料:\n{context}\n\n问题:{question}"),
])

qa_chain = qa_prompt | model | StrOutputParser()

qa_chain 是这条链的变量名。定义它只是连接步骤,接下来调用 .invoke(...) 才会执行。把第一步准备好的三个变量放进字典,作为本次输入。

1
2
3
4
5
6
7
8
input_data = {
"context": context,
"history": history,
"question": question,
}
answer = qa_chain.invoke(input_data)
print(answer)
# 可能的回答:先执行依赖函数,再执行接口处理函数。

这一次调用里,每一步只做下面这件事。

步骤 收到什么 交出什么
qa_prompt 包含资料、历史和问题的字典 ChatPromptValue,里面是填好的消息
model 填好的 Prompt AIMessage,里面是模型的回答
StrOutputParser() 模型的回复消息 回答字符串,保存到 answer

这里已经完成一次“带着资料和旧对话回答问题”。StrOutputParser 取出回复文本,回答是否准确仍要对照资料判断。

第三步,把固定资料换成检索结果

前面手写 docs = [...] 是为了看清数据。实际使用时,这一行可以换成 docs = retriever.invoke(question),由已经配置好的检索器返回文档列表。

把准备输入和调用链的步骤放进一个函数,就可以重复提问。下面沿用刚才的 join_docs 和 qa_chain;retriever 要提前连接好可检索的资料。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
def ask(question, history):
docs = retriever.invoke(question)
if not docs:
return "没有找到相关资料,无法确认。"

answer = qa_chain.invoke({
"context": join_docs(docs),
"history": history,
"question": question,
})

history.append(HumanMessage(content=question))
history.append(AIMessage(content=answer))
return answer

answer = ask(question, history)
print(answer)

读这个函数时,从上往下看即可。先用问题查资料;if not docs 表示结果为空,此时直接返回,模型不会被调用。找到资料后,把正文、旧历史和问题交给已经定义好的链。

最后两次 append 将本轮问题和回答加到传进来的 history 列表中。假设原来有两条消息,调用成功后就变成四条。下次把同一个列表传给 ask,模型就能看到这一轮对话。当前问题是在生成回答之后才加入历史,因此本轮模型输入里不会重复出现它。

如果检索或模型调用抛出异常,程序不会执行后面的 append;本例在空检索时也会提前返回,不记录这一轮。这里的历史只保存在内存中,程序重启后不会保留。

这个例子只是处理了一段对话。将来做成多人使用的服务时,需要为每个会话分别读取和保存历史。

参考资料