尧图网站建设 
简介这份资源是一套基于大语言模型API支持本地部署或商用接口的外挂知识库问答系统完整项目面向计算机、人工智能、通信工程等专业的在校学生、教师及企业开发者可用于毕业设计、课程大作业、项目立项演示或技术进阶学习。压缩包约10.26MB内含项目源码、文档说明与报告等文件源码部分为Python实现覆盖知识库构建、向量检索与大模型调用等核心环节文档与报告则用于梳理系统设计与实现思路。目前已有93人学习关注说明其具备一定的参考价值。读者可借此了解外挂知识库问答系统的整体架构与关键模块掌握从文档解析、检索增强到答案生成的完整链路并在此基础上修改扩展实现个性化功能。项目代码经过测试运行成功答辩评审平均分达96.5分适合需要快速搭建可运行问答系统原型或撰写技术报告的读者参考学习。1. 从一份能跑通的 RAG 毕设源码说起它到底解决了什么问题大语言模型火到现在很多人第一反应是「直接问 ChatGPT 不就行了」但真到落地场景里问题立刻暴露模型不知道你公司内部的规章制度、不知道你导师课题组的历史文档、不知道你手里那几百页 PDF 讲的是什么。你问它它要么一本正经胡说要么干脆拒答。这就是外挂知识库存在的意义——把私有文档切片、向量化、存进向量库用户提问时先检索出相关片段再拼进 Prompt 交给大模型生成答案。这套流程现在有个更流行的叫法RAG 知识库。这份资源就是一套完整的、基于大语言模型 API 的外挂知识库问答系统 Python 源码附带文档说明和报告。它不绑定某一家模型厂商本地部署的模型或商用 API 都能接核心链路是「文档加载 → 文本切分 → 向量化 → 检索 → 拼 Prompt → 调 LLM 生成」。适合谁计算机相关专业的毕设/课设学生、想快速搭一个企业知识库原型的开发者、以及想搞懂 RAG 到底怎么落地的新手。下面我按「先跑起来 → 再拆原理 → 再避坑 → 最后进阶」的顺序把这份源码拆开讲。2. 把环境跑起来依赖安装、API 配置与首次问答2.1 环境准备与依赖安装拿到源码包后第一件事不是急着看代码而是先把运行环境对齐。这类 RAG 项目通常依赖 Python 3.9 以上核心库包括 langchain、faiss-cpu 或 chromadb、sentence-transformers、openai SDK 等。我一般会先建一个干净的虚拟环境避免和系统里已有的包打架。# 创建虚拟环境Python 版本建议 3.9 - 3.11 python -m venv venv # 激活环境Windows venv\Scripts\activate # 激活环境macOS / Linux source venv/bin/activate # 安装依赖requirements.txt 在源码根目录 pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple这里有几个参数值得说清楚。-i后面跟的是国内镜像源能显著加快下载速度尤其是 sentence-transformers 这种带大模型权重的包。虚拟环境的作用是隔离依赖因为 RAG 项目对 langchain 版本比较敏感不同版本 API 差异很大装到全局环境里很容易和别的项目冲突。如果pip install中途报编译错误八成是某个包需要 C 编译环境Windows 上装个 Visual Studio Build Tools 基本能解决。装完之后建议先跑一下pip list确认关键包都在特别是 langchain、faiss-cpu、openai 这三个。缺哪个补哪个别等到运行主程序才报 ModuleNotFoundError。2.2 API 配置本地模型和商用 API 怎么切换这份源码的核心卖点之一就是「本地或商用 API 都能接」。配置通常集中在一个 config 文件或 .env 文件里。商用 API 需要填 base_url 和 api_key本地模型则填本地服务的地址。# config.py 或 .env 中的典型配置 import os # 方式一商用 API以兼容 OpenAI 接口的服务为例 LLM_CONFIG { api_key: os.getenv(LLM_API_KEY, your-api-key-here), base_url: os.getenv(LLM_BASE_URL, https://api.example.com/v1), model_name: os.getenv(LLM_MODEL, your-model-name), temperature: 0.3, # 问答场景建议低温度减少胡编 max_tokens: 1024, # 单次生成上限按需调整 } # 方式二本地部署模型如通过本地推理服务暴露的 OpenAI 兼容接口 # 只需把 base_url 改成 http://localhost:端口/v1api_key 随便填temperature这个参数在知识库问答里特别关键。它控制生成的随机性值越高越发散值越低越保守。问答系统要的是「照着检索到的内容答」所以 0.1 到 0.3 比较合适。max_tokens控制单次回答长度设太小答案会被截断设太大又浪费额度。base_url是切换模型来源的开关商用 API 填厂商给的地址本地模型填本地服务地址只要接口兼容 OpenAI 格式代码几乎不用改。提示api_key 千万不要硬编码进代码再上传到公开仓库用环境变量或 .env 文件管理.env 记得加进 .gitignore。2.3 首次问答从文档入库到拿到答案配置好之后完整流程分两步先把知识库文档灌进去再提问。多数这类项目会提供一个 ingest 脚本和一个 query 脚本或者一个带界面的主程序。# 第一步把 docs 目录下的文档灌入向量库 python ingest.py --docs_dir ./docs --persist_dir ./vector_store # 第二步启动问答 python app.py # 或命令行提问 python query.py --question 你们的报销流程是什么ingest.py做的事是遍历 docs 目录 → 加载文档 → 切分成 chunk → 调 embedding 模型转向量 → 存进向量库。--persist_dir指定向量库落盘位置下次启动不用重新灌。query.py则是把问题向量化 → 在向量库里检索最相似的 top-k 片段 → 拼成 Prompt → 调 LLM。第一次跑建议先用一两个小文档测试确认链路通了再灌大批量文档否则出问题不好定位是加载、切分还是检索环节。3. 拆开 RAG 链路文档切分、向量化与检索的工程细节3.1 文档切分chunk_size 和 overlap 怎么定RAG 效果好不好切分策略占一半功劳。切太大检索出来的片段包含太多无关信息干扰模型切太小语义被割裂检索到的片段答不全问题。常见做法是按字符数切配合重叠区。from langchain.text_splitter import RecursiveCharacterTextSplitter splitter RecursiveCharacterTextSplitter( chunk_size500, # 每个片段的目标字符数 chunk_overlap50, # 相邻片段的重叠字符数 separators[\n\n, \n, 。, , , , ], # 中文优先按句切 ) chunks splitter.split_text(raw_text)chunk_size500是个经验值中文场景下大约对应两三百字能容纳一个完整段落。chunk_overlap50是为了防止一句话正好被切在边界上导致语义丢失重叠区让相邻片段有上下文衔接。separators的顺序很重要RecursiveCharacterTextSplitter 会优先用靠前的分隔符切中文文档一定要把中文标点加进去否则它会按空格硬切把句子切得稀碎。我见过有人直接用默认分隔符处理中文 PDF检索出来的片段全是断句答非所问这就是血泪经验。3.2 向量化与向量库选型切分完就是向量化。embedding 模型的选择直接决定检索质量。商用 embedding API 效果稳定但按量收费本地开源模型如 bge、m3e 免费但需要算力。from langchain.embeddings import HuggingFaceEmbeddings from langchain.vectorstores import FAISS # 本地 embedding 模型 embeddings HuggingFaceEmbeddings( model_nameBAAI/bge-small-zh-v1.5, # 中文小模型速度快 model_kwargs{device: cpu}, # 有 GPU 改成 cuda encode_kwargs{normalize_embeddings: True}, # 归一化配合余弦相似度 ) # 构建并持久化向量库 vector_store FAISS.from_texts(chunks, embeddings) vector_store.save_local(./vector_store)normalize_embeddingsTrue是为了让向量归一化这样内积就等于余弦相似度检索更准。device参数决定用 CPU 还是 GPU小模型 CPU 也能跑大模型建议上 GPU。向量库选型上FAISS 轻量、单机够用、支持持久化适合毕设和中小规模知识库chromadb 带元数据过滤更方便milvus 适合生产级大规模。这份源码用 FAISS 或 chromadb 的可能性最大因为部署简单不依赖额外服务。注意embedding 模型换了之前灌的向量库必须重建因为不同模型的向量空间不兼容混用会导致检索结果完全错乱。3.3 检索与 Prompt 拼接top-k 和相似度阈值检索环节的核心参数是 top-k即返回最相似的几个片段。k 太小可能漏掉关键信息k 太大则塞进太多噪声还会撑爆模型的上下文窗口。# 检索 top-k 片段 retriever vector_store.as_retriever( search_typesimilarity_score_threshold, search_kwargs{k: 4, score_threshold: 0.5}, ) # 拼 Prompt def build_prompt(question, docs): context \n\n.join([d.page_content for d in docs]) return f基于以下资料回答问题资料中没有的信息不要编造。 资料 {context} 问题{question} 回答k4是常见起点配合score_threshold0.5过滤掉相似度太低的片段。阈值这个参数要按实际语料调设太高会检索不到内容设太低会引入无关片段。Prompt 里那句「资料中没有的信息不要编造」是抑制幻觉的关键不加这句模型很容易自由发挥。这套「检索 拼接 约束」的组合就是 RAG 相比直接问模型的核心差异。4. 避坑与排查跑不通、答不准、报错怎么定位4.1 现象启动就报 ModuleNotFoundError 或版本冲突原因通常是依赖没装全或者 langchain 版本和代码不匹配。RAG 项目对 langchain 版本极其敏感0.0.x 和 0.1.x 的 API 差异巨大from langchain.vectorstores import FAISS在新版本里可能已经换了路径。解决先看 requirements.txt 里有没有锁版本号有就严格按它装。没锁版本的话看报错信息里缺哪个模块补哪个。如果遇到 langchain 导入路径报错八成是版本问题pip install langchain0.0.xxx回退到代码适配的版本。我一般会先pip freeze存一份当前环境快照出问题好回滚。4.2 现象API 调用报 400 或 429400 通常是模型名写错或参数不合法比如模型名不在服务商支持列表里或者 max_tokens 超过了模型上限。429 是请求频率或额度超限说明调用太频繁或额度用完了。解决400 先核对 model_name 是否和服务商文档一致再检查 max_tokens 有没有超过模型上下文限制。429 就降低调用频率加个重试和退避逻辑或者换用额度更充裕的 key。这类报错信息里通常会带具体原因别只看状态码把完整报错读一遍。import time from openai import OpenAI client OpenAI(api_key..., base_url...) def call_llm(prompt, retries3): for i in range(retries): try: return client.chat.completions.create( modelyour-model, messages[{role: user, content: prompt}], temperature0.3, ) except Exception as e: if i retries - 1: raise time.sleep(2 ** i) # 指数退避2s、4s、8s4.3 现象检索出来的内容和问题不相关原因可能是切分太碎、embedding 模型不适合中文、或者相似度阈值设得不对。中文文档用英文 embedding 模型检索质量会明显下降。解决先换中文 embedding 模型bge、m3e 系列再检查切分参数把 chunk_size 调大一点、overlap 保留足够上下文。如果还是不准打印出检索到的片段人工看一眼往往一眼就能看出是切分问题还是模型问题。这个排查动作我每次调 RAG 都会做比盲调参数高效得多。4.4 现象答案里出现资料中没有的内容幻觉原因是 Prompt 约束不够或者检索到的片段本身就不相关模型只能靠自己的知识补。temperature 设太高也会加剧这个问题。解决Prompt 里明确写「只根据资料回答资料没有就说不知道」temperature 降到 0.1 到 0.3检索阈值调高过滤噪声。如果资料里确实没有答案要允许模型说「不知道」而不是硬编一个。这一点在答辩或演示时特别重要评委一问边界情况答不上来比胡编要好。4.5 现象灌大量文档时内存爆掉或速度极慢原因是 embedding 计算是逐条或逐批进行的文档量大时内存和耗时都会飙升。FAISS 建索引本身也吃内存。解决分批灌入每批几百个 chunk灌完一批持久化一次。embedding 用 GPU 加速或者换更小的模型。如果只是演示没必要灌全量文档挑核心的几十页就够。我见过有人把几百兆 PDF 全灌进去结果机器直接卡死其实毕设演示根本用不到那么多。5. 进阶玩法换模型、加元数据过滤与效果验证5.1 换模型从商用 API 切到本地部署这套源码的价值在于模型可替换。想把商用 API 换成本地部署模型只要本地推理服务暴露了 OpenAI 兼容接口改 base_url 和 model_name 就行代码逻辑一行不用动。本地部署的好处是数据不出内网、无调用费用代价是需要算力。常见做法是用本地推理框架起一个服务把地址填进 config然后重新灌一次向量库如果 embedding 也换了的话。# 切换到本地模型只改配置 LLM_CONFIG { api_key: not-needed, # 本地服务通常不校验 base_url: http://localhost:8000/v1, model_name: local-model-name, temperature: 0.2, max_tokens: 2048, }5.2 加元数据过滤让检索更精准纯向量检索有个短板它只看语义相似度不看来源。如果知识库里有多个部门的文档用户问财务问题却检索到人事文档就尴尬了。解决办法是给每个 chunk 打元数据标签检索时按标签过滤。元数据字段作用示例值source文档来源财务制度.pdfdepartment所属部门financedoc_type文档类型policyupdate_time更新时间2024-06灌入时把元数据一起存进向量库检索时用 filter 参数限定范围。这样即使用户问题模糊也能把检索范围收窄到相关文档集准确率提升明显。dify 这类平台的知识库流水线也是类似思路元数据过滤是生产级 RAG 的标配。5.3 效果验证怎么判断这套系统答得准不准搭完不能只看「能跑」得验证效果。我一般会准备一组测试问题每个问题都有标准答案然后人工或半自动比对系统输出。关键看三个指标检索命中率正确片段有没有被检索到、答案准确率回答对不对、拒答率该说不知道的时候有没有说。# 简单的批量测试脚本 test_cases [ {q: 报销流程是什么, expect_keyword: 审批}, {q: 年假有几天, expect_keyword: 天}, ] for case in test_cases: answer ask(case[q]) hit case[expect_keyword] in answer print(f问题{case[q]} | 命中{hit} | 回答{answer[:50]})这个脚本很粗糙但能快速暴露问题。如果检索命中率低回去调切分和 embedding如果检索到了但答案不对调 Prompt 和 temperature。从那以后我每次改完 RAG 参数都强制走一遍这组测试用例不然改了哪里、效果变好变坏全靠感觉纯属玄学。希望这套拆解能帮到你把这份源码真正跑起来、改起来。本文还有配套的精品资源点击获取 RAG知识库毕设源码实战：从环境搭建到检索优化
简介这份资源是一套基于大语言模型API支持本地部署或商用接口的外挂知识库问答系统完整项目面向计算机、人工智能、通信工程等专业的在校学生、教师及企业开发者可用于毕业设计、课程大作业、项目立项演示或技术进阶学习。压缩包约10.26MB内含项目源码、文档说明与报告等文件源码部分为Python实现覆盖知识库构建、向量检索与大模型调用等核心环节文档与报告则用于梳理系统设计与实现思路。目前已有93人学习关注说明其具备一定的参考价值。读者可借此了解外挂知识库问答系统的整体架构与关键模块掌握从文档解析、检索增强到答案生成的完整链路并在此基础上修改扩展实现个性化功能。项目代码经过测试运行成功答辩评审平均分达96.5分适合需要快速搭建可运行问答系统原型或撰写技术报告的读者参考学习。1. 从一份能跑通的 RAG 毕设源码说起它到底解决了什么问题大语言模型火到现在很多人第一反应是「直接问 ChatGPT 不就行了」但真到落地场景里问题立刻暴露模型不知道你公司内部的规章制度、不知道你导师课题组的历史文档、不知道你手里那几百页 PDF 讲的是什么。你问它它要么一本正经胡说要么干脆拒答。这就是外挂知识库存在的意义——把私有文档切片、向量化、存进向量库用户提问时先检索出相关片段再拼进 Prompt 交给大模型生成答案。这套流程现在有个更流行的叫法RAG 知识库。这份资源就是一套完整的、基于大语言模型 API 的外挂知识库问答系统 Python 源码附带文档说明和报告。它不绑定某一家模型厂商本地部署的模型或商用 API 都能接核心链路是「文档加载 → 文本切分 → 向量化 → 检索 → 拼 Prompt → 调 LLM 生成」。适合谁计算机相关专业的毕设/课设学生、想快速搭一个企业知识库原型的开发者、以及想搞懂 RAG 到底怎么落地的新手。下面我按「先跑起来 → 再拆原理 → 再避坑 → 最后进阶」的顺序把这份源码拆开讲。2. 把环境跑起来依赖安装、API 配置与首次问答2.1 环境准备与依赖安装拿到源码包后第一件事不是急着看代码而是先把运行环境对齐。这类 RAG 项目通常依赖 Python 3.9 以上核心库包括 langchain、faiss-cpu 或 chromadb、sentence-transformers、openai SDK 等。我一般会先建一个干净的虚拟环境避免和系统里已有的包打架。# 创建虚拟环境Python 版本建议 3.9 - 3.11 python -m venv venv # 激活环境Windows venv\Scripts\activate # 激活环境macOS / Linux source venv/bin/activate # 安装依赖requirements.txt 在源码根目录 pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple这里有几个参数值得说清楚。-i后面跟的是国内镜像源能显著加快下载速度尤其是 sentence-transformers 这种带大模型权重的包。虚拟环境的作用是隔离依赖因为 RAG 项目对 langchain 版本比较敏感不同版本 API 差异很大装到全局环境里很容易和别的项目冲突。如果pip install中途报编译错误八成是某个包需要 C 编译环境Windows 上装个 Visual Studio Build Tools 基本能解决。装完之后建议先跑一下pip list确认关键包都在特别是 langchain、faiss-cpu、openai 这三个。缺哪个补哪个别等到运行主程序才报 ModuleNotFoundError。2.2 API 配置本地模型和商用 API 怎么切换这份源码的核心卖点之一就是「本地或商用 API 都能接」。配置通常集中在一个 config 文件或 .env 文件里。商用 API 需要填 base_url 和 api_key本地模型则填本地服务的地址。# config.py 或 .env 中的典型配置 import os # 方式一商用 API以兼容 OpenAI 接口的服务为例 LLM_CONFIG { api_key: os.getenv(LLM_API_KEY, your-api-key-here), base_url: os.getenv(LLM_BASE_URL, https://api.example.com/v1), model_name: os.getenv(LLM_MODEL, your-model-name), temperature: 0.3, # 问答场景建议低温度减少胡编 max_tokens: 1024, # 单次生成上限按需调整 } # 方式二本地部署模型如通过本地推理服务暴露的 OpenAI 兼容接口 # 只需把 base_url 改成 http://localhost:端口/v1api_key 随便填temperature这个参数在知识库问答里特别关键。它控制生成的随机性值越高越发散值越低越保守。问答系统要的是「照着检索到的内容答」所以 0.1 到 0.3 比较合适。max_tokens控制单次回答长度设太小答案会被截断设太大又浪费额度。base_url是切换模型来源的开关商用 API 填厂商给的地址本地模型填本地服务地址只要接口兼容 OpenAI 格式代码几乎不用改。提示api_key 千万不要硬编码进代码再上传到公开仓库用环境变量或 .env 文件管理.env 记得加进 .gitignore。2.3 首次问答从文档入库到拿到答案配置好之后完整流程分两步先把知识库文档灌进去再提问。多数这类项目会提供一个 ingest 脚本和一个 query 脚本或者一个带界面的主程序。# 第一步把 docs 目录下的文档灌入向量库 python ingest.py --docs_dir ./docs --persist_dir ./vector_store # 第二步启动问答 python app.py # 或命令行提问 python query.py --question 你们的报销流程是什么ingest.py做的事是遍历 docs 目录 → 加载文档 → 切分成 chunk → 调 embedding 模型转向量 → 存进向量库。--persist_dir指定向量库落盘位置下次启动不用重新灌。query.py则是把问题向量化 → 在向量库里检索最相似的 top-k 片段 → 拼成 Prompt → 调 LLM。第一次跑建议先用一两个小文档测试确认链路通了再灌大批量文档否则出问题不好定位是加载、切分还是检索环节。3. 拆开 RAG 链路文档切分、向量化与检索的工程细节3.1 文档切分chunk_size 和 overlap 怎么定RAG 效果好不好切分策略占一半功劳。切太大检索出来的片段包含太多无关信息干扰模型切太小语义被割裂检索到的片段答不全问题。常见做法是按字符数切配合重叠区。from langchain.text_splitter import RecursiveCharacterTextSplitter splitter RecursiveCharacterTextSplitter( chunk_size500, # 每个片段的目标字符数 chunk_overlap50, # 相邻片段的重叠字符数 separators[\n\n, \n, 。, , , , ], # 中文优先按句切 ) chunks splitter.split_text(raw_text)chunk_size500是个经验值中文场景下大约对应两三百字能容纳一个完整段落。chunk_overlap50是为了防止一句话正好被切在边界上导致语义丢失重叠区让相邻片段有上下文衔接。separators的顺序很重要RecursiveCharacterTextSplitter 会优先用靠前的分隔符切中文文档一定要把中文标点加进去否则它会按空格硬切把句子切得稀碎。我见过有人直接用默认分隔符处理中文 PDF检索出来的片段全是断句答非所问这就是血泪经验。3.2 向量化与向量库选型切分完就是向量化。embedding 模型的选择直接决定检索质量。商用 embedding API 效果稳定但按量收费本地开源模型如 bge、m3e 免费但需要算力。from langchain.embeddings import HuggingFaceEmbeddings from langchain.vectorstores import FAISS # 本地 embedding 模型 embeddings HuggingFaceEmbeddings( model_nameBAAI/bge-small-zh-v1.5, # 中文小模型速度快 model_kwargs{device: cpu}, # 有 GPU 改成 cuda encode_kwargs{normalize_embeddings: True}, # 归一化配合余弦相似度 ) # 构建并持久化向量库 vector_store FAISS.from_texts(chunks, embeddings) vector_store.save_local(./vector_store)normalize_embeddingsTrue是为了让向量归一化这样内积就等于余弦相似度检索更准。device参数决定用 CPU 还是 GPU小模型 CPU 也能跑大模型建议上 GPU。向量库选型上FAISS 轻量、单机够用、支持持久化适合毕设和中小规模知识库chromadb 带元数据过滤更方便milvus 适合生产级大规模。这份源码用 FAISS 或 chromadb 的可能性最大因为部署简单不依赖额外服务。注意embedding 模型换了之前灌的向量库必须重建因为不同模型的向量空间不兼容混用会导致检索结果完全错乱。3.3 检索与 Prompt 拼接top-k 和相似度阈值检索环节的核心参数是 top-k即返回最相似的几个片段。k 太小可能漏掉关键信息k 太大则塞进太多噪声还会撑爆模型的上下文窗口。# 检索 top-k 片段 retriever vector_store.as_retriever( search_typesimilarity_score_threshold, search_kwargs{k: 4, score_threshold: 0.5}, ) # 拼 Prompt def build_prompt(question, docs): context \n\n.join([d.page_content for d in docs]) return f基于以下资料回答问题资料中没有的信息不要编造。 资料 {context} 问题{question} 回答k4是常见起点配合score_threshold0.5过滤掉相似度太低的片段。阈值这个参数要按实际语料调设太高会检索不到内容设太低会引入无关片段。Prompt 里那句「资料中没有的信息不要编造」是抑制幻觉的关键不加这句模型很容易自由发挥。这套「检索 拼接 约束」的组合就是 RAG 相比直接问模型的核心差异。4. 避坑与排查跑不通、答不准、报错怎么定位4.1 现象启动就报 ModuleNotFoundError 或版本冲突原因通常是依赖没装全或者 langchain 版本和代码不匹配。RAG 项目对 langchain 版本极其敏感0.0.x 和 0.1.x 的 API 差异巨大from langchain.vectorstores import FAISS在新版本里可能已经换了路径。解决先看 requirements.txt 里有没有锁版本号有就严格按它装。没锁版本的话看报错信息里缺哪个模块补哪个。如果遇到 langchain 导入路径报错八成是版本问题pip install langchain0.0.xxx回退到代码适配的版本。我一般会先pip freeze存一份当前环境快照出问题好回滚。4.2 现象API 调用报 400 或 429400 通常是模型名写错或参数不合法比如模型名不在服务商支持列表里或者 max_tokens 超过了模型上限。429 是请求频率或额度超限说明调用太频繁或额度用完了。解决400 先核对 model_name 是否和服务商文档一致再检查 max_tokens 有没有超过模型上下文限制。429 就降低调用频率加个重试和退避逻辑或者换用额度更充裕的 key。这类报错信息里通常会带具体原因别只看状态码把完整报错读一遍。import time from openai import OpenAI client OpenAI(api_key..., base_url...) def call_llm(prompt, retries3): for i in range(retries): try: return client.chat.completions.create( modelyour-model, messages[{role: user, content: prompt}], temperature0.3, ) except Exception as e: if i retries - 1: raise time.sleep(2 ** i) # 指数退避2s、4s、8s4.3 现象检索出来的内容和问题不相关原因可能是切分太碎、embedding 模型不适合中文、或者相似度阈值设得不对。中文文档用英文 embedding 模型检索质量会明显下降。解决先换中文 embedding 模型bge、m3e 系列再检查切分参数把 chunk_size 调大一点、overlap 保留足够上下文。如果还是不准打印出检索到的片段人工看一眼往往一眼就能看出是切分问题还是模型问题。这个排查动作我每次调 RAG 都会做比盲调参数高效得多。4.4 现象答案里出现资料中没有的内容幻觉原因是 Prompt 约束不够或者检索到的片段本身就不相关模型只能靠自己的知识补。temperature 设太高也会加剧这个问题。解决Prompt 里明确写「只根据资料回答资料没有就说不知道」temperature 降到 0.1 到 0.3检索阈值调高过滤噪声。如果资料里确实没有答案要允许模型说「不知道」而不是硬编一个。这一点在答辩或演示时特别重要评委一问边界情况答不上来比胡编要好。4.5 现象灌大量文档时内存爆掉或速度极慢原因是 embedding 计算是逐条或逐批进行的文档量大时内存和耗时都会飙升。FAISS 建索引本身也吃内存。解决分批灌入每批几百个 chunk灌完一批持久化一次。embedding 用 GPU 加速或者换更小的模型。如果只是演示没必要灌全量文档挑核心的几十页就够。我见过有人把几百兆 PDF 全灌进去结果机器直接卡死其实毕设演示根本用不到那么多。5. 进阶玩法换模型、加元数据过滤与效果验证5.1 换模型从商用 API 切到本地部署这套源码的价值在于模型可替换。想把商用 API 换成本地部署模型只要本地推理服务暴露了 OpenAI 兼容接口改 base_url 和 model_name 就行代码逻辑一行不用动。本地部署的好处是数据不出内网、无调用费用代价是需要算力。常见做法是用本地推理框架起一个服务把地址填进 config然后重新灌一次向量库如果 embedding 也换了的话。# 切换到本地模型只改配置 LLM_CONFIG { api_key: not-needed, # 本地服务通常不校验 base_url: http://localhost:8000/v1, model_name: local-model-name, temperature: 0.2, max_tokens: 2048, }5.2 加元数据过滤让检索更精准纯向量检索有个短板它只看语义相似度不看来源。如果知识库里有多个部门的文档用户问财务问题却检索到人事文档就尴尬了。解决办法是给每个 chunk 打元数据标签检索时按标签过滤。元数据字段作用示例值source文档来源财务制度.pdfdepartment所属部门financedoc_type文档类型policyupdate_time更新时间2024-06灌入时把元数据一起存进向量库检索时用 filter 参数限定范围。这样即使用户问题模糊也能把检索范围收窄到相关文档集准确率提升明显。dify 这类平台的知识库流水线也是类似思路元数据过滤是生产级 RAG 的标配。5.3 效果验证怎么判断这套系统答得准不准搭完不能只看「能跑」得验证效果。我一般会准备一组测试问题每个问题都有标准答案然后人工或半自动比对系统输出。关键看三个指标检索命中率正确片段有没有被检索到、答案准确率回答对不对、拒答率该说不知道的时候有没有说。# 简单的批量测试脚本 test_cases [ {q: 报销流程是什么, expect_keyword: 审批}, {q: 年假有几天, expect_keyword: 天}, ] for case in test_cases: answer ask(case[q]) hit case[expect_keyword] in answer print(f问题{case[q]} | 命中{hit} | 回答{answer[:50]})这个脚本很粗糙但能快速暴露问题。如果检索命中率低回去调切分和 embedding如果检索到了但答案不对调 Prompt 和 temperature。从那以后我每次改完 RAG 参数都强制走一遍这组测试用例不然改了哪里、效果变好变坏全靠感觉纯属玄学。希望这套拆解能帮到你把这份源码真正跑起来、改起来。本文还有配套的精品资源点击获取