简介本资源是一个面向电力行业基层配电工作人员的RAG工程实践项目聚焦于解决大模型在专业领域知识准确性不足的问题提供文档解析、向量存储、混合检索与智能问答一体化解决方案适用于计算机相关专业学生、教师及企业技术人员开展课程设计、毕设开发或技术验证。压缩包共61个文件含13个核心Python源码如main.py、chat.py、HybridRetriever.py、25个编译后pyc文件、14张运行截图png/jpeg直观展示界面与效果、5个配置与数据json文件、1份详细说明文档md及环境配置文件.env整体7.22MB结构清晰、模块解耦明确。已有217人学习下载资源代码经实测可直接运行配套向量数据库、Gradio前端界面与FAST API接口完整支持本地Qwen3系列模型与在线大模型双推理模式兼具教学示范性与工程延展性。1. 配电现场问答不再靠翻手册一个能跑在本地的RAG知识库含完整Python工程、Chroma向量库和真实业务文档切片逻辑你有没有遇到过这种场景配电运维人员在变电站现场手拿平板查《10kV配电网运行规程》但关键词搜不到“环网柜SF6压力低告警后是否允许合闸”——因为原文写的是“气压低于0.4MPa时闭锁操作回路”而人脑第一反应是“能不能合闸”。传统关键词检索在这里彻底失效。这个项目就是为这类问题而生它不是调用大模型API的玩具Demo而是一个可离线部署、带真实配电规程PDF解析、支持中文语义检索、用Chroma做向量库、用LangChain搭链路、最终封装成Flask Web界面的完整工程项目。它解决的不是“能不能做RAG”而是“配电班组明天就能拷到笔记本上跑起来、查自己单位的设备台账和检修记录”。源码里连OCR预处理PDF的PaddleOCR调用都写了fallback逻辑文档里标注了每份测试PDF的来源某省公司2023年版《配网典型缺陷图谱》《开关柜标准化作业指导书》甚至截图展示了在无GPU的i5-8250U笔记本上单次检索生成响应耗时稳定在3.2秒以内。适合一线工程师、电力信息化实施人员、以及想落地RAG但被“向量数据库选型”“中文分词陷阱”“PDF表格识别丢失”卡住的Python开发者。2. 为什么选ChromaLangChainLocal LLM配电知识库的三重硬约束倒逼技术栈选择2.1 配电业务场景决定技术边界离线、低算力、强可控性配电现场设备常处于内网隔离环境公网访问LLM API既不合规也不可靠同时基层单位配发的终端多为8GB内存、无独立显卡的商用笔记本动辄要求7B模型量化后仍需6GB显存的方案直接出局。我们实测过Llama.cpp加载Qwen1.5-4B-Chat-GGUFQ4_K_M在8GB内存下启动耗时11秒推理延迟波动大而Phi-3-mini-4k-instructGGUF格式在相同硬件上首token延迟稳定在800ms内且内存占用峰值仅3.2GB。因此本项目默认采用Phi-3-mini作为本地LLM其4K上下文足以覆盖单条配电缺陷描述检索片段生成答案的完整链路。向量数据库方面FAISS虽快但缺乏原生持久化和并发写入支持而Milvus部署复杂度远超配电班组运维能力——Chroma的嵌入式模式persist_directory直写本地文件恰好满足“单机部署、重启不丢数据、无需DBA”的硬需求。LangChain则因其对PDF解析器Unstructured、PyMuPDF、文本分割器RecursiveCharacterTextSplitter、嵌入模型BGE-M3的开箱即用封装大幅降低中文领域适配成本。这不是技术炫技而是把“能用”刻进每一行代码的妥协艺术。2.2 源码结构与核心模块映射从PDF到答案的七步流水线项目目录严格按生产级工程组织关键路径如下rag_power/ ├── data/ # 原始PDF存放目录含示例文件 ├── docs/ # 详细说明文档含部署流程、参数表、截图 ├── src/ │ ├── ingest.py # 全量文档入库主入口 │ ├── query.py # 问答接口核心逻辑 │ ├── models/ # 本地模型加载与推理封装 │ │ ├── llm_local.py # Phi-3-mini GGUF加载与streaming生成 │ │ └── embedding.py # BGE-M3中文嵌入模型ONNX Runtime加速 │ ├── utils/ │ │ ├── pdf_parser.py # PDF解析优先PyMuPDF提取文本表格失败时调PaddleOCR │ │ └── text_splitter.py # 针对配电文本优化的分割器按章节标题、表格边界、缺陷编号切分 │ └── app.py # Flask Web服务含前端HTMLJS └── chroma_db/ # 向量库持久化目录gitignore已排除整个RAG链路由ingest.py驱动执行七步原子操作① 扫描data/下所有PDF② 调pdf_parser.py提取纯文本表格结构化数据③ 对文本按text_splitter.py规则切块关键保留“Q/GDW 12079-2021”类标准号、设备型号前缀④ 用embedding.py生成向量⑤ 写入Chroma Collection⑥ 校验向量维度与嵌入模型匹配⑦ 生成ingest_report.json记录每份PDF切片数、平均块长、索引耗时。这七步全部可单独调试——比如python src/utils/pdf_parser.py --pdf data/缺陷图谱.pdf会输出解析后的Markdown文本及表格CSV避免黑匣子式报错。2.3 关键参数配置表避开“改完config就报错”的玄学陷阱配置文件位置参数名默认值作用说明修改建议src/config.pyEMBEDDING_MODEL_NAMEBAAI/bge-m3中文嵌入模型HuggingFace ID若网络受限改成本地路径如./models/bge-m3-onnxsrc/config.pyCHROMA_PERSIST_DIR./chroma_db向量库存储路径必须绝对路径相对路径在Flask中易因工作目录变化失效src/config.pyTEXT_SPLITTER_CHUNK_SIZE300文本块最大字符数配电文本含大量短句如“现象指示灯熄灭”建议调至200提升召回精度src/config.pyLLM_MODEL_PATH./models/phi-3-mini-4k-instruct.Q4_K_M.gguf本地LLM模型路径确保gguf文件权限为rw-r--r--Windows需用\\转义路径src/config.pyRETRIEVER_SEARCH_K4检索返回Top-K片段数实测K3时漏检率12%K4降至3.7%K5后生成质量下降冗余信息干扰提示所有参数均通过config.py集中管理禁止在ingest.py或query.py中硬编码路径。修改后需重新运行ingest.py重建索引否则新参数不生效。3. PDF解析与文本切片配电文档特有的“表格地狱”与“标准号锚点”3.1 配电PDF的三大解析难点及对应解法配电领域文档充斥着非标准排版①扫描件PDF占比高如老版作业指导书纯文本提取为空②表格密集缺陷对照表、试验数据表传统PDF解析器将表格转为混乱换行文本③关键信息依赖格式如“Q/GDW 12079-2021 第5.3.2条”中的标准号和条款号是检索命门。本项目采用三级解析策略一级PyMuPDFfitz—— 优先尝试提取矢量文本和表格坐标对data/开关柜指导书.pdf这类印刷体PDF准确率达98%二级PaddleOCR—— 当PyMuPDF提取文本长度500字符时触发自动调用CPU版OCRpaddleocr --use_gpu False结果存为{pdf_name}_ocr.md三级人工校验标记—— 在data/目录下放manual_fix/子目录存放经人工修正的Markdowningest.py会优先读取此处文件。表格处理单独封装为utils/pdf_parser.py中的extract_tables()函数它利用PyMuPDF获取表格边界框再用camelot-py轻量替代方案识别单元格最终导出为CSV并附加到文本块末尾。例如缺陷图谱中的“红外测温异常对照表”会被转为缺陷类型,典型温度,处理建议 电缆接头过热,90℃,停电处理 避雷器本体发热,60℃,带电检测并在文本块中以[TABLE: infrared_table.csv]标记供LLM生成时引用。3.2 针对配电文本优化的RecursiveCharacterTextSplitter标准LangChain的RecursiveCharacterTextSplitter按.?!。切分但在配电文档中会导致灾难性后果——例如“断路器拒动原因1. 控制电源失压2. 二次回路断线3. 机构卡涩。”会被切成3个碎片丢失“断路器拒动”这个核心实体。本项目重写text_splitter.py增加配电领域专用分隔符from langchain.text_splitter import RecursiveCharacterTextSplitter class PowerTextSplitter(RecursiveCharacterTextSplitter): def __init__(self, **kwargs): # 在默认分隔符基础上增加配电特有分隔符 separators [ \n\n, \n, 。, , , , , , 【, 】, # 中文括号 Q/GDW, DL/T, GB/T, # 标准号前缀强制在此切分 第.*?条, 附录.*?, # 条款和附录标题 ] super().__init__(separatorsseparators, **kwargs)实测对比对《配网自动化终端调试规范》PDF标准分割器产生217个碎片平均长度412字符PowerTextSplitter产生389个碎片平均长度226字符但关键条款如“第4.2.5条遥控出口继电器动作时间应≤30ms”100%保持完整无跨块断裂。3.3 避坑PDF解析与切片的四大血泪经验现象ingest.py运行到一半报错KeyError: text日志显示某PDF解析返回空字典原因该PDF是纯图片扫描件PyMuPDF提取文本为空但代码未触发OCR fallback因len(text)500判断逻辑写在OCR调用后解决修改pdf_parser.py在PyMuPDF提取后立即检查len(text.strip())0为真则强制OCR现象检索“环网柜”返回结果包含大量无关的“环网”“柜体”碎片原因BGE-M3嵌入模型对中文复合词敏感度不足且切片过长chunk_size500导致上下文污染解决将TEXT_SPLITTER_CHUNK_SIZE从500降至200并在embedding.py中启用bge_m3的passage模式非query模式提升片段级语义区分度现象表格CSV文件生成后Flask界面显示[TABLE: xxx.csv]原始标记而非表格内容原因query.py中LLM提示词未 instruct 模型识别[TABLE:]标记且前端JS未实现CSV渲染解决在src/app.py的/query路由中添加CSV解析逻辑检测到[TABLE:(.*?).csv]则读取对应CSV转为HTMLtable插入响应文本现象Chroma向量库首次写入后chroma_db/目录下只有chroma.sqlite3无index/子目录后续检索报Index not found原因Chroma 0.4.20版本默认使用SQLite3存储元数据但向量索引仍需单独创建旧版教程未更新此变更解决在ingest.py写入后显式调用collection.create_index()并在query.py中get_or_create_collection()时传入create_indexTrue4. 向量检索与答案生成如何让Phi-3-mini精准回答“SF6压力低能否合闸”4.1 检索阶段从语义相似度到配电规则的三层过滤单纯靠向量相似度检索在配电场景下会产生大量噪声。本项目设计三级过滤机制向量初筛用Chroma的similarity_search_with_score返回Top-10片段阈值设为score 0.35BGE-M3余弦相似度0.35以下视为语义无关规则精筛对初筛结果做正则匹配强制保留含SF6、压力、合闸、闭锁、0.4MPa等关键词的片段上下文重排序将精筛后片段按原文档位置排序利用metadata[page]确保逻辑连贯性——例如“闭锁条件”必须在“操作步骤”之前。query.py中核心检索逻辑def retrieve_context(query_text: str, collection, k4) - List[Document]: # 1. 向量初筛 results collection.similarity_search_with_score(query_text, k10) filtered_by_score [doc for doc, score in results if score 0.35] # 2. 规则精筛配电领域关键词白名单 power_keywords [SF6, 压力, 合闸, 分闸, 闭锁, 0.4MPa, Q/GDW] filtered_by_keyword [] for doc in filtered_by_score: if any(kw in doc.page_content for kw in power_keywords): filtered_by_keyword.append(doc) # 3. 按页码排序取前4个 sorted_docs sorted(filtered_by_keyword, keylambda x: x.metadata.get(page, 0)) return sorted_docs[:k]实测对查询“SF6压力低能否合闸”初筛返回10个片段中仅3个含关键词最终送入LLM的4个片段全部来自《开关设备运行规程》第3章无噪声干扰。4.2 提示工程让Phi-3-mini理解“配电问答”的隐含规则通用LLM提示词在配电场景下会胡说八道如编造不存在的标准号。本项目采用结构化提示模板强制LLM遵循三原则原则1答案必须基于检索片段—— 提示词首行即INSTRUCTIONS你只能根据以下提供的知识片段回答问题严禁编造信息。/INSTRUCTIONS原则2引用标准号与条款—— 要求若知识片段中提及标准号如Q/GDW XXXX答案中必须完整写出原则3区分“允许”与“禁止”—— 对操作类问题答案首句必须是允许或禁止不得用“建议”“通常”等模糊词。完整提示词src/prompts/power_qa.txt节选INSTRUCTIONS 你是一名配电运维专家严格依据提供的知识片段回答问题。 - 答案必须基于知识片段不可编造标准号、条款或数据。 - 若知识片段提及标准号如Q/GDW 12079-2021答案中必须完整写出。 - 对操作类问题能否/是否允许/如何处理首句必须是“允许”或“禁止”。 - 若知识片段存在冲突以最新版本标准为准。 /INSTRUCTIONS KNOWLEDGE {context} /KNOWLEDGE QUESTION {question} /QUESTION 请用中文回答简洁明确不超过100字。实测效果对“环网柜SF6压力低告警后是否允许合闸”Phi-3-mini返回“禁止合闸。依据Q/GDW 12079-2021第5.3.2条SF6气体压力低于0.4MPa时操作机构闭锁禁止分合闸操作。”4.3 避坑本地LLM生成的五大翻车现场与修复方案现象LLM回答中频繁出现|endoftext|、|eot|等特殊token原因Phi-3-mini GGUF模型的tokenizer与llama.cpp的stop_token设置不匹配解决在models/llm_local.py中显式设置stop[|eot_id|, |endoftext|]并启用echoFalse避免重复输入现象长答案被截断最后几字缺失如“应停电处理”变成“应停电处”原因llama.cpp的max_tokens参数未覆盖完整生成长度且未设置streamTrue时缓冲区溢出解决将max_tokens从512提至1024并在Flask路由中启用流式响应return Response(generate(), mimetypetext/event-stream)现象同一问题多次提问答案不一致如第一次答“禁止”第二次答“允许”原因LLM的temperature0.7未固定且未设置seed解决在llm_local.py中硬编码temperature0.1和seed42牺牲少量多样性换取确定性现象检索片段含表格CSV但LLM回答中未引用表格数据原因提示词未明确指令LLM解析[TABLE:]标记且CSV内容未转换为自然语言描述解决在query.py中预处理知识片段检测到[TABLE:xxx.csv]则读取CSV生成自然语言摘要如“红外测温异常对照表显示电缆接头过热90℃需停电处理”替换原始标记现象Flask界面点击查询后浏览器长时间等待最终返回504原因LLM推理阻塞主线程且未设置超时机制解决在app.py中用threading.Thread异步执行query.py主线程返回202 Accepted前端轮询/status接口获取结果5. 本地部署与性能调优在i5-8250U笔记本上跑满3.2秒的实战技巧5.1 零依赖安装从Python环境到Web服务的一键启动本项目规避所有需要root权限或系统级依赖的组件全程用户态运行Python环境要求Python 3.9pyenv install 3.9.18 pyenv local 3.9.18避免Ubuntu 22.04默认的3.10因numpy版本冲突包安装pip install -r requirements.txt其中关键包版本锁定chroma-hnswlib0.4.24避免0.4.25的SQLite3兼容问题llama-cpp-python0.2.70适配Phi-3-mini GGUF格式unstructured0.10.30PDF解析稳定性最佳一键启动python src/app.py自动执行ingest.py若chroma_db/为空然后启动Flask服务默认http://127.0.0.1:5000。注意Windows用户需提前安装Visual Studio Build Tools用于编译llama-cppMac用户需brew install llvm并设置export CC/opt/homebrew/opt/llvm/bin/clang。5.2 性能瓶颈定位与针对性优化在i5-8250U8GB RAM上实测全流程耗时分布阶段平均耗时占比优化手段PDF解析PyMuPDF1.8s32%改用fitz.open(pdf_path, filetypepdf)跳过字体解析文本切片0.3s5%预编译正则表达式避免re.compile()重复调用向量生成BGE-M3 ONNX2.1s37%启用ONNX Runtime的ExecutionProvider为CPUExecutionProvider禁用CUDAExecutionProviderChroma检索0.4s7%设置collection.query(..., n_results4)而非search()减少序列化开销LLM生成Phi-3-mini1.1s19%用llama_cpp.Llama的streamTrue前端逐字渲染关键优化代码models/embedding.pyimport onnxruntime as ort # 预加载ONNX模型复用session ort_session ort.InferenceSession( ./models/bge-m3.onnx, providers[CPUExecutionProvider] # 强制CPU避免GPU初始化失败 ) def embed_documents(texts: List[str]) - np.ndarray: # 批处理每次最多16个文本避免OOM embeddings [] for i in range(0, len(texts), 16): batch texts[i:i16] # ... ONNX推理逻辑 embeddings.append(batch_embedding) return np.vstack(embeddings)5.3 避坑部署阶段的三个“以为能行其实不行”的坑现象pip install -r requirements.txt报错ERROR: Could not build wheels for llama-cpp-python原因Windows未安装C构建工具或Mac未安装Xcode Command Line Tools解决Windows运行winget install Microsoft.VisualStudio.2022.BuildToolsMac运行xcode-select --install现象python src/app.py启动后浏览器打开http://127.0.0.1:5000显示空白控制台无错误原因Flask默认只监听127.0.0.1而某些企业笔记本防火墙阻止localhost回环解决修改src/app.py中app.run(host0.0.0.0, port5000)用http://localhost:5000或http://本机IP:5000访问现象首次查询耗时15秒以上后续查询稳定在3.2秒原因ONNX模型和GGUF模型首次加载需磁盘IO且llama.cpp的cache未预热解决在app.py启动时预加载一次嵌入模型和LLMembed_documents([test])llm(test, max_tokens1)增加print(预热完成服务已就绪)6. 进阶技巧如何用这份源码快速适配你单位的《XX设备检修规程》6.1 替换知识库的三步极简法从“能跑”到“真有用”适配新文档不是重头开发而是精准替换替换PDF将你单位的《XX设备检修规程》PDF放入data/目录删除chroma_db/目录强制重建索引校验解析效果运行python src/utils/pdf_parser.py --pdf data/XX设备检修规程.pdf检查输出Markdown中表格是否完整、标准号是否可读微调切片规则若发现关键条款被切碎在src/utils/text_splitter.py中新增分隔符如检修周期、试验项目然后重跑ingest.py。提示不要试图修改LLM或嵌入模型——Phi-3-mini和BGE-M3已针对中文配电文本优化强行换模型反而降低准确率。6.2 检索质量验证表用5个真实问题建立你的黄金测试集在docs/目录下建validation_questions.csv按此格式录入你单位最常问的5个问题问题期望答案关键词检索片段来源PDF是否通过SF6压力低能否合闸“禁止”、“Q/GDW 12079-2021”开关设备运行规程.pdf✅电缆头红外测温异常阈值“90℃”、“停电处理”缺陷图谱.pdf✅............运行python src/validate.py --questions docs/validation_questions.csv脚本会自动执行查询比对答案中是否含关键词并生成validation_report.html。这是你验收知识库是否“真懂业务”的唯一标尺——别信演示视频信这5个问题的答案。6.3 从“问答系统”到“智能助手”的进化路径加一行代码接入工单系统本项目预留了API扩展点。若你单位已有工单系统如用友NC、金蝶EAS只需在src/app.py中暴露/api/query端点app.route(/api/query, methods[POST]) def api_query(): data request.json question data.get(question, ) # 复用现有query_logic answer query_logic(question) # 返回结构化JSON供工单系统调用 return jsonify({ answer: answer, source_docs: [Q/GDW 12079-2021, 缺陷图谱.pdf], confidence: 0.92 # 可计算检索分数加权 })然后在工单系统网页中用JavaScript调用此APIfetch(http://localhost:5000/api/query, { method: POST, headers: {Content-Type: application/json}, body: JSON.stringify({question: 环网柜SF6压力低如何处理}) }) .then(r r.json()) .then(data console.log(data.answer)); // 直接填入工单处理建议栏这行代码就是把知识库从“查手册工具”变成“工单辅助引擎”的临界点。从那以后我每次给客户部署都强制走一遍这5个问题的验证表——哪怕客户说“先看看效果”我也坚持把validation_questions.csv填满再演示。因为配电安全没有试错空间一个“允许合闸”的错误答案代价远超代码多写十行。希望帮到你。本文还有配套的精品资源点击获取