从零搭建 Python 版 RAG 智能问答知识库｜本地离线文档检索大模型实战

目录前言一、RAG 核心原理与整体架构1.1 RAG 工作流程1.2 项目技术选型轻量化首选二、项目环境依赖安装2.1 批量安装所需依赖库2.2 前置准备三、通用文档加载工具类开发3.1 多格式文档统一读取代码四、文本切片 向量化 向量库持久化入库4.1 完整知识库入库脚本4.2 入库使用方法五、核心 RAG 检索问答逻辑实现5.1 完整 RAG 智能问答主程序5.2 运行问答系统六、核心功能拓展6.1 切换不同本地大模型6.2 调整检索精度与分片参数6.3 清空重建向量知识库七、常见问题与报错解决方案问题 1加载 PDF 文档乱码 / 读取为空问题 2嵌入模型下载缓慢问题 3Ollama 连接超时无法调用大模型问题 4问答结果依旧出现幻觉问题 5内存占用过高八、项目商用优化方向九、总结前言在日常工作与开发场景中大量 PDF、Word、TXT、Markdown、业务手册、技术文档、规章制度等非结构化文档堆积传统关键词搜索效率极低无法实现语义理解、精准问答、内容总结、文档推理。RAG检索增强生成技术完美解决该痛点先对私有文档进行文本拆分、向量化存入向量数据库用户提问后先检索文档相关片段再将检索内容拼接上下文送入大模型让大模型只基于私有知识库回答杜绝幻觉、精准贴合内部资料同时实现离线本地部署、数据不外泄、私有化部署零接口费用。本文从零开始手把手教大家使用纯 Python搭建完整商用级 RAG 智能问答知识库包含文档加载、文本分割、向量化嵌入、向量库存储、相似度检索、大模型对话拼接、流式问答、完整项目封装全流程全程附可直接运行源码零基础也能搭建属于自己的私有 AI 知识库。一、RAG 核心原理与整体架构1.1 RAG 工作流程文档解析阶段读取本地 PDF/TXT/MD/Word 等各类格式文档文本切片阶段长文档按照固定长度 重叠分片拆分避免上下文断裂文本向量化使用嵌入模型将文本转为多维向量向量入库向量与原文片段存入轻量级向量数据库持久化用户提问用户输入问题问题同样转为向量语义检索向量库匹配相似度最高的知识库文本片段提示词拼接将检索内容 用户问题组合成限定 Prompt大模型推理送入本地 / 在线大模型生成精准答案结果输出返回基于私有文档的专属问答结果1.2 项目技术选型轻量化首选框架核心LangChain一站式 RAG 开发框架文档解析PyPDF2、python-docx主流文档读取文本分割RecursiveCharacterTextSplitter通用递归分词器嵌入模型all-MiniLM-L6-v2轻量开源本地嵌入模型向量数据库ChromaDB纯 Python 轻量向量库无需额外部署服务大模型调用对接本地 Ollama 部署 Llama3/Qwen/DeepSeek交互方式控制台问答 简易 Web 问答二、项目环境依赖安装2.1 批量安装所需依赖库打开 CMD 或终端执行以下一键安装命令bash运行# 核心RAG框架 pip install langchain langchain-community langchain-ollama # 向量数据库 pip install chromadb # 文档解析依赖 pip install pypdf python-docx markdown # 嵌入模型依赖 pip install sentence-transformers # 网络请求与工具 pip install tqdm numpy2.2 前置准备本地提前部署 Ollama 大模型参考上一篇 Windows 一键部署教程确保ollama服务正常运行默认端口11434新建项目文件夹结构如下plaintextrag_knowledge_base/ ├── docs/ # 存放所有知识库文档 ├── vector_db/ # 向量数据库持久化存储目录 ├── load_docs.py # 文档入库脚本 ├── rag_chat.py # RAG智能问答主程序三、通用文档加载工具类开发支持TXT、PDF、Word、Markdown四种常用文档格式批量加载3.1 多格式文档统一读取代码python运行# utils_doc_loader.py import os from langchain_community.document_loaders import ( TextLoader, PyPDFLoader, Docx2txtLoader, UnstructuredMarkdownLoader ) # 定义文档格式映射 LOADER_MAP { .txt: TextLoader, .pdf: PyPDFLoader, .docx: Docx2txtLoader, .md: UnstructuredMarkdownLoader } def load_all_documents(folder_path: str): 批量读取文件夹内所有支持格式文档 :param folder_path: 知识库文档文件夹路径 :return: 文档对象列表 all_docs [] if not os.path.exists(folder_path): os.makedirs(folder_path) return all_docs for file_name in os.listdir(folder_path): file_suffix os.path.splitext(file_name)[-1].lower() file_full_path os.path.join(folder_path, file_name) if file_suffix in LOADER_MAP: try: loader LOADER_MAP[file_suffix](file_full_path) docs loader.load() all_docs.extend(docs) print(f✅ 成功加载文档{file_name}) except Exception as e: print(f❌ 加载失败 {file_name}{str(e)}) return all_docs四、文本切片 向量化 向量库持久化入库4.1 完整知识库入库脚本python运行# load_docs.py from langchain.text_splitter import RecursiveCharacterTextSplitter from langchain_community.embeddings import SentenceTransformerEmbeddings from langchain_community.vectorstores import Chroma from utils_doc_loader import load_all_documents # 全局配置 # 知识库文档目录 DOC_FOLDER ./docs # 向量数据库持久化路径 VECTOR_DB_PATH ./vector_db # 文本分片大小 CHUNK_SIZE 800 # 分片重叠长度保证上下文连贯 CHUNK_OVERLAP 150 # 本地嵌入模型名称 EMBED_MODEL_NAME all-MiniLM-L6-v2 def build_knowledge_base(): # 1.加载所有文档 documents load_all_documents(DOC_FOLDER) if not documents: print(未读取到任何知识库文档请放入文件至docs目录) return # 2.初始化文本分割器 text_splitter RecursiveCharacterTextSplitter( chunk_sizeCHUNK_SIZE, chunk_overlapCHUNK_OVERLAP, separators[\n\n, \n, 。, , , ] ) split_docs text_splitter.split_documents(documents) print(f 文档拆分完成总分片数量{len(split_docs)}) # 3.初始化本地嵌入模型 embedding SentenceTransformerEmbeddings(model_nameEMBED_MODEL_NAME) # 4.构建并持久化向量数据库 chroma_db Chroma.from_documents( documentssplit_docs, embeddingembedding, persist_directoryVECTOR_DB_PATH ) # 持久化保存 chroma_db.persist() print( 知识库向量化入库完成向量库已本地持久化) if __name__ __main__: build_knowledge_base()4.2 入库使用方法将 PDF/TXT/MD/DOCX 文档全部放入项目docs文件夹直接运行python load_docs.py自动完成加载、拆分、向量化、存入本地向量库首次入库较慢后续新增文档重新运行即可增量更新五、核心 RAG 检索问答逻辑实现5.1 完整 RAG 智能问答主程序python运行# rag_chat.py from langchain_community.embeddings import SentenceTransformerEmbeddings from langchain_community.vectorstores import Chroma from langchain_ollama import OllamaLLM from langchain.chains import RetrievalQA from langchain.prompts import PromptTemplate # 全局配置 VECTOR_DB_PATH ./vector_db EMBED_MODEL_NAME all-MiniLM-L6-v2 # 选择本地Ollama模型llama3 / qwen / deepseek-coder LOCAL_LLM_MODEL llama3 # 检索匹配文档数量 RETRIEVE_TOP_K 3 # 自定义RAG专属提示词严控模型只参考知识库回答 RAG_PROMPT_TEMPLATE 你是专业知识库智能问答助手请严格依据下方提供的【知识库参考内容】回答用户问题。 1. 仅使用参考内容作答禁止编造、禁止知识库外内容联想 2. 如果参考内容无法解答问题直接回复暂无相关知识库内容 3. 回答简洁清晰条理分明使用中文回复 知识库参考内容{context} 用户提问{question} 请给出精准回答 def init_rag_chain(): # 1.加载本地嵌入模型 embedding SentenceTransformerEmbeddings(model_nameEMBED_MODEL_NAME) # 2.读取本地持久化向量库 vector_db Chroma( persist_directoryVECTOR_DB_PATH, embedding_functionembedding ) # 3.构建相似度检索器 retriever vector_db.as_retriever(search_kwargs{k: RETRIEVE_TOP_K}) # 4.初始化本地大模型 llm OllamaLLM(modelLOCAL_LLM_MODEL, temperature0.1) # 5.封装自定义提示词 prompt PromptTemplate( templateRAG_PROMPT_TEMPLATE, input_variables[context, question] ) # 6.组装RAG问答链 rag_chain RetrievalQA.from_chain_type( llmllm, chain_typestuff, retrieverretriever, chain_type_kwargs{prompt: prompt}, return_source_documentsTrue # 返回引用知识库原文 ) return rag_chain def start_rag_chat(): print( Python私有RAG知识库智能问答系统 ) print(输入问题即可问答输入 exit 退出程序\n) rag_chain init_rag_chain() while True: user_question input(请输入你的问题) if user_question.lower() in [exit, quit, 退出]: print(已退出RAG问答系统) break result rag_chain.invoke(user_question) print(\n AI知识库回答) print(result[result]) print(- * 60) if __name__ __main__: start_rag_chat()5.2 运行问答系统bash运行python rag_chat.py启动后直接输入文档内相关问题模型会精准调取知识库内容作答无知识库内容直接拒绝回答彻底解决大模型幻觉问题。六、核心功能拓展6.1 切换不同本地大模型只需修改LOCAL_LLM_MODEL参数即可一键切换python运行LOCAL_LLM_MODEL qwen:7b # 中文最优通义千问 LOCAL_LLM_MODEL deepseek-coder # 代码知识库专用 LOCAL_LLM_MODEL llama3:8b # 通用英文通用问答6.2 调整检索精度与分片参数CHUNK_SIZE越大单片段内容越多适合长上下文文档CHUNK_OVERLAP越大分片连贯性越强适合剧情、流程类文档RETRIEVE_TOP_K数值越大调取参考文档越多答案越全面6.3 清空重建向量知识库直接删除项目内vector_db整个文件夹重新执行入库脚本即可全新构建知识库。七、常见问题与报错解决方案问题 1加载 PDF 文档乱码 / 读取为空解决更换pdfplumber加载器替换原有 PyPDFLoader适配加密、扫描版 PDF问题 2嵌入模型下载缓慢解决手动下载all-MiniLM-L6-v2模型放置本地路径指定本地模型路径加载问题 3Ollama 连接超时无法调用大模型解决确认 Ollama 服务正常启动关闭防火墙本地测试ollama run 模型名是否可用问题 4问答结果依旧出现幻觉解决收紧 Prompt 约束调低 temperature 温度值至 0.05 以内增加检索片段数量问题 5内存占用过高解决减小分片大小、使用轻量化嵌入模型、选用 3B 轻量级本地大模型八、项目商用优化方向搭建 Web 界面结合 Gradio/Flask 搭建网页版知识库问答系统接入 RAG 流式输出实现打字机实时回复效果添加文档管理后台实现网页上传文档自动入库多轮对话记忆整合 LangChain 对话记忆组件实现连续上下文问答部署内网服务将 RAG 项目部署至服务器公司局域网全员共用知识库PDF 图片 OCR 解析集成 PaddleOCR 实现图片类文档文字提取入库九、总结本文基于纯 PythonLangChainChromaDB 本地开源大模型搭建了一套轻量化、低成本、可私有化部署的完整 RAG 智能问答知识库系统摆脱第三方 AI 接口依赖所有数据全部本地存储完全满足企业内网文档问答、个人学习知识库、业务手册智能检索、技术资料答疑等场景。整套项目代码无冗余、结构清晰、开箱即用新手可直接运行部署开发者可在此基础上快速迭代成商用级 AI 知识库平台。RAG 作为目前落地最快的 AI 应用方案掌握该架构可快速切入企业 AI 私有化项目开发。