LangChain
18 · 流式 API 与部署
带记忆的 RAG 与 FastAPI
- LangChain
- Python
本节速览
这一节的每一块内容,分别是干什么的:
| 内容 | 是干什么的 |
|---|---|
| 问题改写链 | 把「他的故事」这类指代追问改写成独立问题再检索 |
| 带记忆的 RAG | 两种历史管理模式:chain 外自管理 / checkpointer |
| FastAPI 流式部署 | StreamingResponse 把生成过程实时推给前端 |
| 观测工具调用 | 流式模式下追踪 agent 内部行为 |
| 延迟掩盖 | 动画与并行请求改善首字等待体验 |
本章解决工程化三件事:多轮追问的问题改写、带记忆的 RAG、FastAPI 流式部署。
问题改写:独立问题链
没有它会怎样——「介绍他的故事」直接送检索:向量库里没有「他」的答案,top-k 召回的全是不相关内容,答案风马牛不相及。
有了它——先结合历史改写成「介绍小明的故事」,检索词信息完整,召回正常。
多轮对话里用户会用代词指代前文:「介绍他的故事」直接拿去检索,向量库里没有「他」的答案。解决方式:先用 LLM 结合聊天记录,把追问重述成信息完整的独立问题,再送去检索:
from langchain_openai import ChatOpenAI # OpenAI 聊天模型
import os # 读取环境变量
from dotenv import load_dotenv # 从 .env 读环境变量
from langchain_core.messages import AIMessage, HumanMessage # 消息对象
from langchain_core.output_parsers import StrOutputParser # 提取纯文本
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder # 消息模板与历史插槽
from langchain_core.runnables import RunnableSequence # 顺序串联 Runnable
load_dotenv()
llm = ChatOpenAI(
base_url=os.environ["GLM_BASE_URL"],
api_key=os.environ["GLM_API_KEY"],
model=os.environ["GLM_MODEL_ID"],
)
rephrase_chain = RunnableSequence(
ChatPromptTemplate.from_messages([
{
"role": "system",
"content": "给定以下对话和一个后续问题,请将后续问题重述为一个独立的问题。"
"重述的问题应包含足够的信息,让没看过对话历史的人也能理解。",
},
MessagesPlaceholder("history"),
{"role": "human", "content": "将以下问题重述为一个独立的问题:\n{question}"},
]),
llm, # 改写要求忠于原文,温度调低
StrOutputParser(),
)
rephrase_chain.invoke({
"history": [HumanMessage("你好,我叫小明"), AIMessage("你好小明")],
"question": "你觉得我的名字怎么样?",
})
# 你认为小明这个名字怎么样?
除代词消解外,改写还能规整口语化表达,统一提高送入 retriever 的问题质量。这条链可与 检索优化 的手段叠加。
带记忆的 RAG:两种模式
没有它会怎样——RAG 不带历史:用户追问「那他呢?」,检索词只有一个「他」字,什么都查不到,上一轮聊过的上下文全丢。
有了它——历史注入改写链、或 checkpointer 持久化,追问自动带上前文语境。
模式一:chain 外自管理历史
沿用完整 RAG 链的结构,prompt 里给历史留 MessagesPlaceholder 插槽,改写链负责把追问变成独立问题再检索:
from langchain_openai import ChatOpenAI # OpenAI 聊天模型
import os # 读取环境变量
from dotenv import load_dotenv # 从 .env 读环境变量
from langchain_core.output_parsers import StrOutputParser # 提取纯文本
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder # 消息模板与历史插槽
from langchain_core.runnables import RunnableLambda, RunnablePassthrough, RunnableSequence # 透传并追加字段
load_dotenv()
llm = ChatOpenAI(
base_url=os.environ["GLM_BASE_URL"],
api_key=os.environ["GLM_API_KEY"],
model=os.environ["GLM_MODEL_ID"],
)
# 改写链:结合历史把追问改写成独立问题(见本章第一节,这里演示占位)
rephrase_chain = RunnableLambda(lambda question: question)
# 检索器:加载建好的向量库;演示占位,真实实现见 19 章(Qdrant 加载后 .as_retriever())
retriever = RunnableLambda(lambda q: [])
convert_docs_to_string = lambda docs: "\n".join(d.page_content for d in docs)
prompt = ChatPromptTemplate.from_messages([
{"role": "system", "content": "仅依据资料回答,资料里没有就回答「资料里没有」。\n资料:{context}"},
MessagesPlaceholder("history"),
{"role": "human", "content": "{standalone_question}"},
])
rag_chain = RunnableSequence(
RunnablePassthrough.assign(standalone_question=rephrase_chain),
RunnablePassthrough.assign(
context=RunnableSequence(
lambda input: input["standalone_question"],
retriever,
convert_docs_to_string,
)
),
prompt, # system 模板带 {context},history 插槽,human 带 {standalone_question}
llm,
StrOutputParser(),
)
历史管理用自管理方案,读写都在 chain 之外。坑:读写必须成对出现在调用侧,忘了写回,下一轮改写链拿到的历史就是空的,表象是「记忆时有时无」。
模式二:RAG 封装为 tool + agent(推荐)
把检索做成一个 tool 交给 agent。agent 通过 checkpointer 持有多轮记忆,指代消解由模型构造工具参数时自动完成,改写链被内化:
from langchain_openai import ChatOpenAI # OpenAI 聊天模型
import os # 读取环境变量
from dotenv import load_dotenv # 从 .env 读环境变量
from langchain.agents import create_agent # 创建 agent
from langchain.tools import tool # 工具定义装饰器
from langchain_core.runnables import RunnableLambda # 函数转 Runnable
from langgraph.checkpoint.memory import InMemorySaver # 内存版记忆持久化
from pydantic import BaseModel, Field # 数据模型与字段描述
load_dotenv()
llm = ChatOpenAI(
base_url=os.environ["GLM_BASE_URL"],
api_key=os.environ["GLM_API_KEY"],
model=os.environ["GLM_MODEL_ID"],
)
# 检索器:演示占位,真实为加载已落盘的向量库(19 章用 Qdrant).as_retriever()
retriever = RunnableLambda(lambda q: [])
class RetrieveInput(BaseModel):
query: str = Field(description="信息完整的独立检索问题")
def _retrieve(query: str) -> str:
docs = retriever.invoke(query)
return "\n".join(doc.page_content for doc in docs)
retrieve_tool = tool(
_retrieve,
name="retrieve_qiu",
description="检索《秋园小记》的原文片段。调用时把用户问题补全为包含完整上下文的独立问题",
args_schema=RetrieveInput,
)
agent = create_agent(
llm,
system_prompt=(
"你是熟读《秋园小记》的助手,回答必须基于 retrieve_qiu 检索到的原文并引用原文;"
'原文中没有相关内容时回答"原文中没有相关内容"。'
),
tools=[retrieve_tool],
checkpointer=InMemorySaver(),
)
config = {"configurable": {"thread_id": "rag-demo"}}
agent.invoke({"messages": [{"role": "user", "content": "秋天的后园里长着什么树?"}]}, config)
# 第二轮带指代的追问:模型结合线程历史构造 query,检索照常命中
agent.invoke({"messages": [{"role": "user", "content": "它的西边种了什么"}]}, config)
指代消解发生在工具调用环节:模型看到完整线程历史,构造 query 时自动把「它」补全为「后园」。不再需要独立的改写链,省掉每轮一次的改写调用。工具的 description 里写明「补全为独立问题」能让这个行为更稳定。生产环境换 PostgresSaver。这套结构的可运行版(真实检索、溯源角标、阈值拒答)见 19 章综合项目,其中「它的西边种了什么」正是实测跑通的例子。
FastAPI 部署流式接口
没有它会怎样——普通接口等模型把 800 字全生成完才返回:用户盯 20 秒白屏,超时了还要重发,长连接还把吞吐占满。
有了它——StreamingResponse 把 token 一边生成一边推,首字 1 秒内出现,边生成边显示。
agent 用 astream(stream_mode="messages") 做 token 级流式输出。构建代码收进 get_agent(),服务启动时执行一次:
# server.py
from fastapi import FastAPI # Web 框架
from fastapi.responses import StreamingResponse # 流式 HTTP 响应
from pydantic import BaseModel # 定义数据模型
import os # 读取环境变量
from dotenv import load_dotenv # 从 .env 读环境变量
from langchain.agents import create_agent # 创建 agent
from langchain.tools import tool # 工具定义装饰器
from langchain_openai import ChatOpenAI # OpenAI 聊天模型
from langgraph.checkpoint.memory import InMemorySaver # 内存版记忆持久化
app = FastAPI()
class ChatRequest(BaseModel):
question: str
session_id: str
load_dotenv()
llm = ChatOpenAI(
base_url=os.environ["GLM_BASE_URL"],
api_key=os.environ["GLM_API_KEY"],
model=os.environ["GLM_MODEL_ID"],
)
@tool
def retrieve_qiu(query: str) -> str:
"""检索《秋园小记》的原文片段。调用时把用户问题补全为独立问题"""
return "……检索到的原文……" # 占位:真实现(加载 Qdrant 向量库、阈值过滤、角标拼装)见 19 章
retrieve_tool = retrieve_qiu
def get_agent():
"""「模式二」一节的构建过程收进来,服务启动时执行一次"""
return create_agent(
llm,
system_prompt="你是助手,基于 retrieve_qiu 检索到的原文回答问题",
tools=[retrieve_tool],
checkpointer=InMemorySaver(),
)
agent = get_agent() # 向量库加载与 embedding 客户端有初始化开销,启动时构建一次复用
@app.post("/chat")
async def chat(req: ChatRequest):
async def token_stream():
try:
# stream_mode="messages":逐 token 产出 (message, metadata)
async for message, metadata in agent.astream(
{"messages": [{"role": "user", "content": req.question}]},
{"configurable": {"thread_id": req.session_id}},
stream_mode="messages",
):
if metadata.get("langgraph_node") != "model":
continue # 跳过 tools 节点的消息,否则检索到的资料原文会流给用户
if message.content:
yield message.content
except Exception as e:
yield f"Error: {e}" # 响应头已发出,异常只能在生成器内部吐出
return StreamingResponse(token_stream(), media_type="text/plain; charset=utf-8")
pip install fastapi uvicorn
uvicorn server:app --port 8080
客户端读取流:
import requests # HTTP 客户端
with requests.post(
"http://localhost:8080/chat",
json={"question": "秋天的后园里长着什么树", "session_id": "test"},
stream=True,
) as response:
response.encoding = "utf-8"
for chunk in response.iter_content(chunk_size=None, decode_unicode=True):
print(chunk, end="", flush=True)
要点:
thread_id从请求体传入,同一session_id共享一份记忆,checkpointer 在流式过程中自动落盘。- 必须按
metadata["langgraph_node"]过滤,只放行model节点。stream_mode="messages"会把所有节点的消息都吐出来,包括 tools 节点返回的ToolMessage——那是检索到的资料原文,不过滤的话用户会先看到一大段资料、再看到回答(实测一次问答 66 个 model 增量 + 1 个 tools 消息)。本章这个工具是占位符所以看不出来,真实检索工具会立刻暴露,详见 19 章综合项目。 - 默认的
stream_mode="values"产出节点执行后的状态快照,适合观测工具调用轨迹,不适合逐 token 输出。 - 异常必须在生成器内部捕获并写出:
StreamingResponse的响应头一旦发出就无法再改状态码,漏掉捕获会导致连接悬挂。
观测工具调用
没有它会怎样——流式模式下你只看得到最终文字,agent 中间调了几次工具、传了什么参数一无所知,出了错无从查起。
有了它——按消息粒度消费流,tool_call 的请求和结果都是流里的一等公民,中间过程全程可见。
流式接口也用于观察 agent 内部行为。stream_mode="values" 每个节点执行后产出完整状态快照:
from langchain_openai import ChatOpenAI # OpenAI 聊天模型
import os # 读取环境变量
from dotenv import load_dotenv # 从 .env 读环境变量
from langchain.tools import tool # 工具定义装饰器
from langgraph.prebuilt import create_agent # 预置 agent 构造器
from langgraph.checkpoint.memory import InMemorySaver # 内存 checkpointer
load_dotenv()
llm = ChatOpenAI(
base_url=os.environ["GLM_BASE_URL"],
api_key=os.environ["GLM_API_KEY"],
model=os.environ["GLM_MODEL_ID"],
)
@tool
def retrieve_qiu(query: str) -> str:
"""Retrieve passages from the prose《秋园小记》."""
return "……相关原文……"
# 与「带记忆的 RAG」一节同款 agent,这里换成 values 模式观测内部行为
agent = create_agent(
llm,
tools=[retrieve_qiu],
checkpointer=InMemorySaver(),
)
config = {"configurable": {"thread_id": "observe-demo"}}
for snapshot in agent.stream(
{"messages": [{"role": "user", "content": "秋天的后园里长着什么树"}]},
config,
stream_mode="values",
):
latest = snapshot["messages"][-1]
if latest.type == "ai" and latest.tool_calls:
print("Tool calls:", ", ".join(tc["name"] for tc in latest.tool_calls))
# Tool calls: retrieve_qiu
延迟掩盖:动画与请求并行
没有它会怎样——点发送到首字出现之间页面毫无反应,用户以为卡死,连点三次发送,后台跑起三个重复请求。
有了它——等待期放动画给确定性反馈,能并行的请求同时发,体感等待时间砍半。
LLM 请求要数秒,期间用户面对空白。把请求提交到后台线程,主线程同时逐条播放系统生成的流程消息(每秒一条),网络延迟被动画时间吸收:
import os # 读取环境变量
from dotenv import load_dotenv # 从 .env 读环境变量
import time # 定时,控制演示节奏
from concurrent.futures import ThreadPoolExecutor # 后台线程池
from langchain_openai import ChatOpenAI # OpenAI 聊天模型
load_dotenv()
model = ChatOpenAI(
base_url=os.environ["GLM_BASE_URL"],
api_key=os.environ["GLM_API_KEY"],
model=os.environ["GLM_MODEL_ID"],
temperature=0,
)
def chat(question: str) -> str:
"""真实的 LLM 请求,耗时数秒。"""
return model.invoke(question).content
# 流程消息由代码生成,播放节奏可控(系统生成消息的思路,见第六章)
message_list = ["正在理解您的问题……", "正在检索知识库……", "正在整理答案……"]
user_input = input("告诉我你的疑问: ")
with ThreadPoolExecutor(max_workers=1) as pool:
future = pool.submit(chat, "用户的问题是:" + user_input) # 先发请求
for message in message_list: # 同时播放流程消息
time.sleep(1)
print(message)
print(future.result()) # 动画播完,结果也就绪
要点:请求先于动画启动;sleep 间隔按消息条数与预计延迟匹配,消息播完时回答恰好到达。
选型建议
- 内部文档 bot 不需要记忆:每次提问独立,检索加回答即可,调用次数最少、token 消耗最低。
- 要多轮对话先算成本:全量 history 持续增加 prompt token 和延迟。标准组合是 checkpointer + SummarizationMiddleware。
- 纯 chain 结构保留 rephrase_chain,每轮多一次便宜 LLM 调用换检索质量;agent 结构里改写被工具调用内化,不必重复建设。
- POC 阶段先用内置组件跑通看效果,再针对薄弱环节优化。提前调参的收益通常低于先验证方向。
- 本章的
server.py是骨架:检索工具是占位符、无溯源、无阈值拒答。把这些焊成一套真能交付的系统,见19 章综合项目。
上一节:Agent · 下一节:综合项目:完整 RAG 系统