Stuff Document Chain 完整深度解读

Stuff Document Chain 完整深度解读定位LangChain 最早、最简单的文档拼接链也是RetrievalQA.from_chain_type(chain_typestuff)背后真正实现同时是 LCEL RAG 默认采用的文档组装思路。 中文常称塞满模式 / 直塞模式一、底层原理概述1. 核心逻辑接收一组List[Document] 用户问题 → 把全部文档 page_content 拼接成一段上下文一次性塞进 Prompt只调用1 次 LLM。数据流plaintext[Document1, Document2, Document3...] ↓ 字符串拼接换行/分隔符 ↓ 填充进 Prompt {context} ↓ 用户问题 {question} ↓ 单次 LLM 请求 → 输出答案2. 类源码层级langchain 0.1包路径python运行from langchain.chains.combine_documents import create_stuff_documents_chaincreate_stuff_documents_chain(llm, prompt)返回值一个Runnable新版不再是老式 Chain兼容 LCEL历史说明 早期RetrievalQA的chain_typestuff内部就是调用这个链 现在官方推荐直接用create_stuff_documents_chain搭配检索器或者手写 LCEL 替代。二、标准 API 使用方式方式 1官方封装 create_stuff_documents_chain推荐过渡写法python运行from langchain_openai import ChatOpenAI from langchain_core.prompts import ChatPromptTemplate from langchain.chains.combine_documents import create_stuff_documents_chain from langchain_core.documents import Document llm ChatOpenAI(modelgpt-3.5-turbo) prompt ChatPromptTemplate.from_template( 基于下面上下文回答问题。 上下文 {context} 问题{question} ) # 构建 stuff 文档链 stuff_chain create_stuff_documents_chain(llm, prompt) # 输入格式必须是 dict: {context: [Document...], question: xxx} docs [ Document(page_contentLangChain 支持多种文档链), Document(page_contentstuff 模式一次性塞入全部文档) ] res stuff_chain.invoke({ context: docs, question: stuff chain 是什么 }) print(res)方式 2原生 LCEL 手写等价实现彻底理解本质create_stuff_documents_chain本质 ≈ 下面这段逻辑python运行from langchain_core.runnables import RunnablePassthrough def format_docs(docs: list[Document]) - str: return \n\n.join(doc.page_content for doc in docs) stuff_lcel ( RunnablePassthrough.assign( contextlambda x: format_docs(x[context]) ) | prompt | llm ) res stuff_lcel.invoke({context: docs, question: stuff chain 是什么})看懂这点stuff 没有任何黑魔法仅仅是文档列表转字符串 prompt 填充。三、关键入参详解create_stuff_documents_chainpython运行create_stuff_documents_chain( llm: BaseChatModel, prompt: BasePromptTemplate, document_variable_name: str context, # prompt里存放文档上下文的变量名 )document_variable_name非常容易踩坑 如果你的 prompt 模板里上下文变量不叫{context}必须显式修改否则报错。示例prompt 使用{documents}python运行prompt ChatPromptTemplate.from_template( 文档{documents} 问题{question} ) stuff_chain create_stuff_documents_chain(llm, prompt, document_variable_namedocuments)四、Stuff Chain 完整执行约束✅ 优点只发起一次 LLM 请求速度最快、成本最低文档之间可以相互参考LLM 具备全局视野多文档交叉推理实现最简单、调试直观链路短出错概率低完美支持流式输出.stream()❌ 致命缺陷严格受限于模型上下文窗口context window所有检索文档拼接后的总 Token Prompt 问题 不能超过模型最大长度一旦超长OpenAI直接报错context_length_exceeded部分开源模型自动截断尾部文档 → 丢失信息、产生幻觉检索返回文档较多时k6、8、10基本不能直接使用 stuff适用边界总结Stuff 适合少量召回文档k ≤ 35、单轮短上下文场景不适合大量长文档、长知识库问答五、和另外三种文档链横向对比map_reduce /map_rerank/refine这四种就是 RetrievalQA 支持的四大 chain_type表格Chain Type核心思路LLM 调用次数适合场景stuff全部文档一次性塞进 Prompt1 次文档少、总长度短首选map_reducemap: 每篇单独摘要 → reduce 汇总N1 次大量文档支持超长文本refine依次迭代逐步更新答案N 次需要保留上下文递进关系速度慢map_rerank每篇文档打分选出最优文档作答N 次答案大概率仅存在单篇文档内六、在完整 RAG 链路中组合使用RetrievalChain 标准结构新版推荐create_retrieval_chaincreate_stuff_documents_chainLangChain 0.1.x 官方标准写法替代老旧 RetrievalQApython运行from langchain.chains import create_retrieval_chain from langchain.chains.combine_documents import create_stuff_documents_chain # 1. 构建文档组装链 combine_docs_chain create_stuff_documents_chain(llm, prompt) # 2. 绑定检索器形成完整RAG retrieval_chain create_retrieval_chain(retriever, combine_docs_chain) # 调用 result retrieval_chain.invoke({input: 你的问题}) # result.keys() → input, context(List[Document]), answer print(result[answer]) print(result[context]) # 原始召回文档链路拆解plaintext用户input ↓ retriever → List[Document] ↓ stuff文档链拼接文档promptLLM ↓ answer输出七、高频踩坑清单坑 1Prompt 变量名不匹配报错Input variables missing: {context}原因prompt 没有{context}忘记修改document_variable_name坑 2传入字符串而不是 List [Document]stuff chain 的context输入必须是list[Document]不能直接传字符串。 如果你已经手动拼接好文本不需要用 stuff chain直接手写 LCEL 即可。坑 3检索 k 设太大频繁触发上下文超限解决方案三条任选降低 retriever k控制召回数量使用重排序器 Reranker过滤低相关文档更换文档链map_reduce坑 4分不清 create_stuff_documents_chain 和 RetrievalQARetrievalQA Retriever 文档组合链stuff/map_reduce...的老式封装create_retrieval_chain create_stuff_documents_chain 现代化 Runnable 实现支持流式、异步官方主推。八、延伸思考什么时候放弃 Stuff简单判定公式预估所有文档 token prompt 固定 token 问题 token ≥ 模型窗口 × 0.85 → 不要再使用 Stuff切换 map_reduce 或者做文档压缩ContextCompressionRetriever九、最简知识结构图plaintextStuff Document Chain ├─ 本质List[Document] → 拼接字符串 → 填入Prompt → 单次LLM调用 ├─ API入口create_stuff_documents_chain() ├─ 输入规范{context: [Document], question: str} ├─ 优势最快、最少LLM调用、跨文档推理 ├─ 局限受上下文窗口限制 └─ 上层应用作为 create_retrieval_chain 的文档合并组件