简介这份资源是一套基于大语言模型API支持本地部署或商用接口的外挂知识库问答系统Python源码包面向计算机、人工智能、通信工程等专业的在校学生、教师及企业开发者可用于毕业设计、课程大作业、项目立项演示或技术进阶学习。压缩包约10.26MB内含项目源码、文档说明与报告等文件源码部分实现知识库检索与大模型问答的对接逻辑文档与报告则梳理了系统设计思路与实现过程便于理解整体架构。目前已有93人学习关注说明该方向具备一定实用价值。读者可借此掌握外挂知识库问答系统的完整实现路径包括文档加载、向量检索、API调用与答案生成等关键环节并可在源码基础上修改扩展适配自身课题或业务场景。下载后建议先阅读README.md了解运行方式资源仅供学习参考请勿用于商业用途。1. 外挂知识库问答系统为什么大模型 API 加检索才是企业落地的正解直接调大模型 API 做问答最常翻车的场景是用户问「我们公司报销标准是多少」模型一本正经编出一个数字。这不是模型不行是它压根没见过你的内部文档。外挂知识库问答系统要解决的就是这件事——把企业私有文档切片、向量化、存进检索库用户提问时先检索出相关片段再连同问题一起塞给大语言模型 API让它基于真实材料回答。整套东西用 Python 就能串起来本地模型或商用 API 都能接。这套方案适合三类人手里有一堆 PDF、Word、Markdown 文档想变成问答入口的开发者想用 DeepSeek、智谱这类 API 快速搭原型的团队以及已经在用 Dify 知识库流水线、但想搞懂底层检索逻辑的工程师。核心链路只有四步文档加载 → 切片 → 向量化入库 → 检索增强生成。下面按落地顺序拆开讲每一步都给能跑的代码和参数。2. 文档加载与切片把 PDF、Word、Markdown 变成可检索的文本块2.1 加载器选型与编码坑文档加载看着简单实际是整条链路里最容易埋雷的地方。PDF 分两种文字型 PDF 用pypdf直接抽文本就行扫描件 PDF 必须走 OCR常见做法是pdf2image转图片再上paddleocr或tesseract。Word 用python-docxMarkdown 直接读文件。我一般会写一个统一入口按扩展名分发避免后面切片逻辑到处判断类型。import os from pypdf import PdfReader from docx import Document def load_document(file_path: str) - str: 按扩展名分发加载器返回纯文本 ext os.path.splitext(file_path)[1].lower() if ext .pdf: reader PdfReader(file_path) # 逐页抽取join 时补换行避免段落粘连 return \n.join(page.extract_text() or for page in reader.pages) elif ext .docx: doc Document(file_path) return \n.join(p.text for p in doc.paragraphs) elif ext in (.md, .txt): with open(file_path, r, encodingutf-8) as f: return f.read() else: raise ValueError(f不支持的格式: {ext})逻辑说明extract_text()对某些 PDF 会返回None所以用or 兜底。参数上PdfReader默认不做布局还原表格和双栏 PDF 抽出来会串行这是后面检索不准的常见根因。如果文档里表格多建议换pdfplumber它能按坐标还原表格结构。2.2 切片策略chunk_size 和 overlap 怎么定切片决定了检索的粒度。切太大一个块里混了好几个主题检索出来噪声多切太小一句话被拦腰截断模型拿到的上下文不完整。常见做法是按字符数切chunk_size取 500 到 800overlap取chunk_size的 10% 到 20%。中文场景下 500 字符大约对应 300 到 400 个 token塞进大多数模型的上下文窗口毫无压力。def split_text(text: str, chunk_size: int 500, overlap: int 80): 按字符滑窗切片overlap 保证跨块语义连续 chunks [] start 0 while start len(text): end start chunk_size chunk text[start:end].strip() if chunk: chunks.append(chunk) # 下一块回退 overlap 个字符避免句子被切断 start end - overlap return chunks参数说明chunk_size500适合问答类文档如果是技术手册这种长段落可以放到 800。overlap80是经验值太小跨块问题接不上太大入库量翻倍。注意这个切法不认标点更讲究的做法是按句号、换行符递归切分LangChain 的RecursiveCharacterTextSplitter就是干这个的分隔符优先级设成[\n\n, \n, 。, , , ]中文标点一定要加进去否则它按英文句号切中文文档会切出一大块。提示切片前先做一次文本清洗把连续空行、页眉页脚、乱码字符去掉。页眉页脚不清理每个块都会带上「第 X 页」这种噪声检索时容易被误命中。3. 向量化与检索embedding 模型选型和相似度检索实现3.1 embedding 模型本地还是 API向量化这一步决定了检索质量的上限。两条路本地跑sentence-transformers或BGE系列优点是免费、数据不出内网商用 API 如智谱的embedding-3、OpenAI 的text-embedding-3-small优点是省事、维度高、效果稳。我一般原型阶段用 API 快速验证确认链路通了再换本地模型压成本。import numpy as np from sentence_transformers import SentenceTransformer # 本地模型首次运行会自动下载权重 model SentenceTransformer(BAAI/bge-small-zh-v1.5) def embed_texts(texts: list[str]) - np.ndarray: 批量向量化normalize 后内积等价余弦相似度 embeddings model.encode(texts, normalize_embeddingsTrue) return np.array(embeddings)参数说明bge-small-zh-v1.5输出 512 维模型体积小、推理快适合几千到几万条 chunk 的场景。如果文档量上十万换bge-base或bge-large维度更高但检索更准。normalize_embeddingsTrue是关键归一化之后用内积算相似度省去每次除模长的开销。3.2 向量库选型与相似度检索向量库从轻到重有几种numpy暴力检索适合几千条以内faiss适合十万级支持 IVF 索引加速chromadb、milvus适合生产环境带持久化和元数据过滤。原型阶段我直接用 numpy代码最少调试最直观。def search(query: str, chunks: list[str], embeddings: np.ndarray, top_k: int 3): 检索与 query 最相似的 top_k 个 chunk query_vec model.encode([query], normalize_embeddingsTrue)[0] # 归一化后内积即余弦相似度 scores embeddings query_vec top_idx np.argsort(scores)[::-1][:top_k] return [(chunks[i], float(scores[i])) for i in top_idx]逻辑说明embeddings query_vec是矩阵乘向量一次算出所有 chunk 的相似度。argsort升序后反转取前top_k。参数top_k3是问答场景的常用值检索太多会稀释上下文太少可能漏掉关键信息。如果发现检索结果总是不相关先检查 embedding 模型和文档语言是否匹配——用英文模型跑中文文档相似度会集体失真。注意向量检索对「同义不同词」友好但对精确匹配比如产品型号、订单号很弱。生产级系统一般会做混合检索向量召回加 BM25 关键词召回再融合排序。原型阶段可以先只做向量但心里要清楚这个边界。4. 对接大语言模型 APIprompt 组装、流式输出与多轮对话4.1 prompt 模板与上下文注入检索出相关片段后要把它们和用户问题拼成一个 prompt 发给大模型。模板设计直接决定回答质量。核心原则有三条明确告诉模型「只根据提供的资料回答」资料里没有就说不知道禁止编造把检索片段放在问题前面用分隔符隔开要求模型引用来源片段编号方便溯源。PROMPT_TEMPLATE 你是一个严谨的问答助手只能根据下面提供的资料回答问题。 如果资料中没有相关信息直接回答「根据现有资料无法回答」不要编造。 资料 {context} 问题{question} 回答 def build_prompt(question: str, retrieved: list[tuple[str, float]]) - str: 把检索片段拼成 context注入模板 context \n---\n.join(chunk for chunk, _ in retrieved) return PROMPT_TEMPLATE.format(contextcontext, questionquestion)参数说明分隔符用\n---\n而不是空行是为了让模型清楚区分不同片段。如果检索片段很长注意总 token 数别超过模型上下文窗口——DeepSeek 系列支持 64K 以上但有些模型只有 8Ktop_k和chunk_size要相应调小。4.2 调用商用 API 与流式输出以 DeepSeek API 为例它兼容 OpenAI 的 SDK 格式改base_url和model就行。流式输出对问答体验很重要用户不用等整段生成完才看到字。from openai import OpenAI client OpenAI( api_key你的API_KEY, base_urlhttps://api.deepseek.com # 换成实际服务地址 ) def ask_llm(prompt: str, stream: bool True): 调用大模型 API支持流式返回 response client.chat.completions.create( modeldeepseek-chat, messages[{role: user, content: prompt}], temperature0.1, # 问答场景压低随机性 streamstream ) if stream: for chunk in response: delta chunk.choices[0].delta.content if delta: yield delta else: return response.choices[0].message.content参数说明temperature0.1是问答场景的关键设置值越高回答越发散知识库问答要的是忠实于资料所以压低。streamTrue时返回的是生成器逐块 yield。注意 API 报错里常见的400多半是模型名写错或上下文超长429是触发限流生产环境要加退避重试。4.3 多轮对话与历史管理单轮问答跑通后多轮对话要维护历史消息。做法是把历史轮次拼进messages数组但要注意两点历史太长会挤占上下文需要做滑动窗口截断历史里的检索片段不必重复带入只保留问题和回答即可。def chat_with_history(question: str, history: list, chunks, embeddings): 带历史的多轮问答history 为 [(q, a), ...] retrieved search(question, chunks, embeddings) prompt build_prompt(question, retrieved) messages [] # 只保留最近 3 轮历史避免上下文爆炸 for q, a in history[-3:]: messages.append({role: user, content: q}) messages.append({role: assistant, content: a}) messages.append({role: user, content: prompt}) response client.chat.completions.create( modeldeepseek-chat, messagesmessages, temperature0.1 ) return response.choices[0].message.content逻辑说明历史只保留最近 3 轮是经验值再多会明显拖慢响应并增加费用。检索始终基于当前问题不基于历史这样每轮都能召回最新相关的片段。5. 避坑与排查知识库问答系统上线前必须过的五道坎5.1 检索结果不相关答非所问现象用户问报销标准检索出来的却是考勤制度。原因通常是切片粒度过大一个块里混了多个主题或者 embedding 模型与文档语言不匹配。解决先把chunk_size从 500 降到 300 试观察检索命中率再确认 embedding 模型是否支持中文英文模型跑中文文档必然翻车。如果还不行加一层关键词过滤把明显不相关的块在检索后剔除。5.2 API 报 400 或 429现象调用时报400 the supported api model names are...或429 exceeded quota。原因前者是模型名拼错或该 API 平台不支持这个模型后者是触发限流或额度用尽。解决核对平台文档里的模型名别照搬别处的配置429 加指数退避重试代码里用tenacity库三行搞定同时监控调用量别等线上挂了才发现额度没了。5.3 上下文超长导致截断现象报maximum context length is 1048576 tokens之类的错误或回答到一半突然断掉。原因检索片段加历史消息总 token 超过模型窗口。解决估算 token 数中文约 1 字 1 token控制top_k * chunk_size不超过窗口的 60%给生成留足空间。历史轮次做滑动窗口别无限累积。5.4 文档更新后知识库不同步现象文档改了问答还是旧答案。原因向量库是静态快照文档更新后没有重新切片入库。解决给每个 chunk 存来源文件路径和修改时间文档变更时按路径删除旧向量再重新入库。生产环境建议用支持 upsert 的向量库比如 Chroma 或 Milvus别用纯 numpy 数组硬扛。5.5 本地模型和 API 效果差异大现象本地小模型答得驴唇不对马嘴换 API 立刻正常。原因本地模型参数量小指令遵循能力弱prompt 里的约束它理解不了。解决本地部署至少选 7B 以上且做过指令微调的模型prompt 写得更直白把「只能根据资料回答」拆成更细的步骤。如果效果还是不行问答场景优先用 API本地模型留给对延迟和隐私要求极高的场景。6. 进阶技巧用重排序和引用溯源把问答质量再拉一档检索召回top_k10之后直接全塞给模型并不是最优解。更好的做法是加一个重排序rerank环节先用向量召回 10 条再用交叉编码器对这 10 条精排取前 3 条。交叉编码器把问题和片段拼在一起过模型精度比向量内积高不少代价是慢。常见做法是用bge-reranker系列本地就能跑。from sentence_transformers import CrossEncoder reranker CrossEncoder(BAAI/bge-reranker-base) def rerank(query: str, candidates: list[tuple[str, float]], top_n: int 3): 对向量召回结果精排返回 top_n pairs [(query, chunk) for chunk, _ in candidates] scores reranker.predict(pairs) ranked sorted(zip(candidates, scores), keylambda x: x[1], reverseTrue) return [chunk for (chunk, _), _ in ranked[:top_n]]参数说明bge-reranker-base比 large 快精度略低原型够用。top_n3是最终喂给模型的片段数。加了重排序之后检索准确率通常能提升一截尤其是文档主题相近、向量区分度不高的时候。引用溯源是另一个提升可信度的技巧。让模型在回答里标注来源片段编号前端把编号映射回原文位置用户点一下就能看到出处。实现上在 prompt 里给每个片段加编号要求模型回答时带上[1][2]这样的标记解析回答时提取编号即可。优化手段成本效果提升适用阶段重排序中需额外模型检索准确率明显提升原型验证后混合检索中需维护 BM25 索引精确匹配场景提升大有型号/编号类查询引用溯源低改 prompt 即可可信度提升便于排查上线前必做查询改写低多一次 API 调用口语化提问召回率提升用户提问随意时查询改写值得单独说一句用户问「报销咋弄」直接检索可能召回不到「费用报销流程」这个块。做法是先让大模型把口语化问题改写成规范查询再拿去检索。多一次 API 调用但召回率提升明显尤其是面向普通用户的系统。我自己踩得最狠的一次坑是切片时没清页眉页脚结果每个块都带着「XX 公司内部资料 第 3 页」检索时这些噪声词反而成了高频匹配项把真正相关的内容挤下去了。后来养成习惯入库前先跑一遍清洗把重复出现的短行统计出来批量删掉。这个方案值不值得做我的判断是——只要你有超过 50 篇内部文档、且团队里有人反复问同样的问题外挂知识库问答系统的投入产出比就很高。先从 numpy 加本地 embedding 跑通最小闭环再逐步换向量库、加重排序别一上来就上重型架构。希望帮到你。本文还有配套的精品资源点击获取