跳转到主要内容

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 系统