简介这份资源是面向计算机相关专业学生与项目实战学习者的校园LLM完整项目包以RAG检索增强生成技术为核心可用于毕业设计、期末大作业或课程实践。项目经导师指导并通过评审获得98分高分源码均经过本地编译与严格调试确保可直接运行难度适中适合需要完整案例参考的学习者。压缩包共21个文件约1.06MB以Python源码为主涵盖检索模块、模型调用与工具脚本另含XML配置、Markdown说明、JSON数据及依赖清单等目录结构清晰便于按模块阅读与二次开发。资源围绕校园场景构建问答链路包含向量检索、关键词检索与链路回调等实现可帮助读者理解RAG系统的数据组织、检索策略与工程落地方式。目前已有135人学习适合希望快速掌握检索增强生成项目结构、积累实战经验的学生下载使用。1. 从一份校园 RAG 项目源码说起它到底解决了什么校园场景里最不缺的就是文档培养方案、选课手册、奖学金评定办法、实验室安全规范、历年答辩模板。这些内容散落在教务处网站、学院群文件、辅导员发的压缩包里学生想问一句「转专业后学分怎么认定」往往要在五个 PDF 之间来回翻。基于 RAG 的校园 LLM 项目本质就是把这些非结构化文档灌进一个可检索的知识库再让大模型基于检索到的片段回答问题而不是靠它自己「回忆」。这份源码加资料的价值不在于模型多强而在于它把「文档解析 → 切块 → 向量化 → 检索 → 拼 prompt → 生成」这条链路完整跑通了并且针对校园问答做了适配。适合谁适合想拿 RAG 项目练手的学生、需要给院系做内部问答的开发者以及已经看过 rag 详解但没动手写过 rag 项目实战的人。它不解决模型训练也不解决多模态核心就是文本检索增强生成这一件事。2. 拆开这份源码RAG 链路里每个模块在干什么2.1 文档加载与清洗为什么 PDF 解析是第一个翻车点校园文档的格式比想象中脏。教务处导出的 PDF 经常是扫描件套文字层或者表格跨页断裂直接丢给PyPDF2抽出来的文本会混入页眉页脚、页码、甚至乱码。我一般会先做格式分流纯文本 PDF 走pdfplumber扫描件走 OCRWord 文档走python-docx网页存档走BeautifulSoup。清洗阶段要干掉连续空行、孤立页码、重复的页眉字符串。这一步不做干净后面切块再漂亮也是垃圾进垃圾出。import pdfplumber import re def clean_text(raw: str) - str: # 去掉纯数字页码行 raw re.sub(r^\s*\d\s*$, , raw, flagsre.MULTILINE) # 合并被硬换行拆断的句子 raw re.sub(r([^\n。])\n([^\n]), r\1\2, raw) # 压缩连续空行 raw re.sub(r\n{3,}, \n\n, raw) return raw.strip() def load_pdf(path: str) - str: text [] with pdfplumber.open(path) as pdf: for page in pdf.pages: t page.extract_text() or text.append(t) return clean_text(\n.join(text))逻辑说明clean_text先按行处理页码再用正则把被换行拆开的句子接回去最后压缩空行。参数上pdfplumber的extract_text默认按阅读顺序输出如果表格多可以加layoutTrue但会牺牲速度。失败时先看抽出来的文本前 500 字如果全是空白或乱码说明是扫描件得换 OCR 路线。2.2 切块策略rag 切块不是越小越好切块直接决定检索命中率。校园文档里一条奖学金评定办法可能横跨三页如果按固定 500 字切很可能把「申请条件」和「发放标准」切到两个块里检索时只召回一半。常见做法是递归字符切分优先按段落切段落太长再按句子切最后才按字符硬切。块大小我一般设 300500 字重叠 5080 字保证跨块语义不断裂。对于表格类内容最好单独抽成结构化文本再切别和正文混在一起。from langchain.text_splitter import RecursiveCharacterTextSplitter splitter RecursiveCharacterTextSplitter( chunk_size400, chunk_overlap60, separators[\n\n, \n, 。, , , ], length_functionlen, ) chunks splitter.split_text(clean_text)逻辑说明separators的顺序就是切分优先级先按空行段落切再按单换行再按中文句号、分号、逗号最后才按字符。chunk_overlap让相邻块有重叠避免边界信息丢失。参数怎么改如果文档句子特别长把「。」提前如果检索结果太碎把chunk_size调到 600 以上。注意别把chunk_overlap设得超过chunk_size的一半否则块数量爆炸。2.3 向量化与检索embedding 模型选型与 top-k 怎么定向量化就是把每个块映射成一个稠密向量检索时算 query 向量和块向量的余弦相似度。校园场景中文为主embedding 模型优先选中文或多语言模型比如bge-small-zh这类轻量级模型本地跑得动效果也够用。如果源码里用的是 OpenAI 的 embedding注意网络和费用问题校园内网部署建议换本地模型。检索 top-k 一般设 35太少容易漏太多会把无关片段塞进 prompt 导致模型跑偏。可以加一个相似度阈值低于阈值的块直接丢掉。from sentence_transformers import SentenceTransformer import numpy as np model SentenceTransformer(BAAI/bge-small-zh-v1.5) chunk_vecs model.encode(chunks, normalize_embeddingsTrue) def retrieve(query: str, top_k: int 4, threshold: float 0.35): q_vec model.encode([query], normalize_embeddingsTrue)[0] scores chunk_vecs q_vec idx np.argsort(scores)[::-1][:top_k] return [(chunks[i], float(scores[i])) for i in idx if scores[i] threshold]逻辑说明normalize_embeddingsTrue让向量归一化点积等价于余弦相似度。top_k4是经验值threshold0.35过滤掉明显不相关的块。参数怎么改如果召回太少降阈值到 0.25如果噪声多升到 0.45。失败时打印每个块的分数看是不是 query 和文档用词差异太大必要时加同义词扩展。2.4 Prompt 拼装与生成怎么让 LLM 只答文档里有的内容检索回来的片段要拼进 prompt同时必须约束模型「只根据以下资料回答资料没有就说不知道」。这是防止幻觉的关键。校园问答里学生问「补考成绩怎么算」如果资料里没有模型编一个算法出来后果很严重。prompt 模板里把资料放在明确的分隔符之间指令写清楚。生成模型可以用本地部署的开源 LLM也可以用 API但要注意鉴权信息别硬编码在源码里用环境变量或配置文件读取。PROMPT_TEMPLATE 你是一个校园问答助手。请严格根据以下资料回答问题。 如果资料中没有相关信息直接回答「资料中未找到相关内容」不要编造。 资料 {context} 问题{question} 回答 def build_prompt(query: str, retrieved: list) - str: context \n\n.join([f[片段{i1}] {c} for i, (c, _) in enumerate(retrieved)]) return PROMPT_TEMPLATE.format(contextcontext, questionquery)逻辑说明context里给每个片段编号方便排查时定位。指令里明确「不要编造」这是血泪经验不加这句模型十有八九会自由发挥。参数上temperature设 0.10.3越低越稳定。如果模型还是编把「不知道」的指令再加强或者加 few-shot 示例。3. 把源码跑起来本地部署的最小步骤与参数3.1 环境准备与依赖安装别在 Python 版本上踩坑拿到源码先看requirements.txt或pyproject.toml确认 Python 版本。RAG 项目常见的依赖冲突集中在langchain、transformers、torch三者版本上。我一般用 conda 建独立环境Python 3.10 比较稳。安装顺序是先装torch按 CUDA 版本选再装transformers最后装langchain及其周边。如果源码里用了faiss做向量库Linux 下直接pip install faiss-cpuWindows 下可能要装faiss-cpu的预编译包。conda create -n campus-rag python3.10 -y conda activate campus-rag pip install torch --index-url https://download.pytorch.org/whl/cpu pip install transformers sentence-transformers langchain pdfplumber faiss-cpu逻辑说明CPU 版 torch 够跑小模型有 GPU 就把 index-url 换成对应 CUDA 版本。faiss-cpu用于向量检索数据量小的时候也可以用 numpy 暴力算。失败时先看报错是不是版本不兼容pip check能列出冲突。3.2 知识库构建文档放哪、索引存哪、怎么增量更新源码里一般有个data/目录放原始文档index/目录存向量索引。构建流程是遍历data/下所有文件逐个加载、清洗、切块、向量化最后把向量和块文本一起持久化。增量更新是个容易被忽略的点校园文档每学期都会变不能每次全量重建。常见做法是给每个块存一个文档 ID 和哈希新文档进来先比对哈希只重新处理变化的文件。import os, json, hashlib def file_hash(path): with open(path, rb) as f: return hashlib.md5(f.read()).hexdigest() def build_index(data_dir: str, index_dir: str): os.makedirs(index_dir, exist_okTrue) meta_path os.path.join(index_dir, meta.json) meta json.load(open(meta_path)) if os.path.exists(meta_path) else {} all_chunks, all_vecs [], [] for fname in os.listdir(data_dir): fpath os.path.join(data_dir, fname) h file_hash(fpath) if meta.get(fname) h: continue # 未变化跳过 text load_pdf(fpath) if fname.endswith(.pdf) else open(fpath, encodingutf-8).read() chunks splitter.split_text(clean_text(text)) vecs model.encode(chunks, normalize_embeddingsTrue) all_chunks.extend(chunks) all_vecs.append(vecs) meta[fname] h # 持久化向量和文本 np.save(os.path.join(index_dir, vecs.npy), np.vstack(all_vecs)) json.dump(all_chunks, open(os.path.join(index_dir, chunks.json), w, encodingutf-8), ensure_asciiFalse) json.dump(meta, open(meta_path, w), ensure_asciiFalse)逻辑说明file_hash用 MD5 判断文件是否变化meta.json记录每个文件的哈希。参数上index_dir要和检索时读取的路径一致。注意np.vstack要求每个文件的向量维度一致换 embedding 模型时必须全量重建。3.3 检索与生成联调query 进来之后发生了什么联调阶段把检索和生成串起来输入一个问题输出答案和引用片段。这一步要打印中间结果召回了哪些块、分数多少、拼出来的 prompt 长什么样。很多问题不是模型不行而是检索没召回对的块。我一般会写一个debug开关打开后把每个环节的中间数据都打出来。def ask(query: str, debug: bool False): retrieved retrieve(query, top_k4) if debug: for c, s in retrieved: print(f[score{s:.3f}] {c[:80]}...) prompt build_prompt(query, retrieved) if debug: print( * 40) print(prompt[:500]) answer llm_generate(prompt) # 替换成实际生成函数 return answer, retrieved逻辑说明debug模式打印召回片段和分数方便判断是检索问题还是生成问题。llm_generate根据源码里用的模型替换本地模型用transformers的pipelineAPI 模型用对应 SDK。参数上如果答案不完整先看召回片段是否覆盖了答案没覆盖就调检索覆盖了但答错就调 prompt。4. 校园 RAG 项目避坑5 个真实翻车记录4.1 现象PDF 抽出来全是乱码检索完全失效原因文档是扫描件没有文字层pdfplumber只能抽出空白或乱码。解决先用pdf2image把页面转成图片再走 OCR如paddleocr把 OCR 结果当作文本源。注意 OCR 有错字检索时可以用模糊匹配或同义词兜底。4.2 现象模型回答「资料中未找到」但资料里明明有原因切块把关键信息切碎了或者 query 和文档用词差异大向量相似度低。解决先调大chunk_size和chunk_overlap再看召回分数如果分数普遍低于阈值降阈值或换更强的 embedding 模型。还可以加关键词检索做混合召回。4.3 现象同一个问题每次回答不一样甚至自相矛盾原因temperature设太高或者 prompt 里资料顺序随机。解决temperature降到 0.1资料按相似度排序后拼入 prompt固定顺序。如果还飘把「只根据资料回答」的指令再强化加一句「不要使用你的先验知识」。4.4 现象源码里 API key 硬编码提交后泄露原因开发时图方便直接把 key 写在代码里。解决改成从环境变量读取os.environ.get(LLM_API_KEY)本地用.env文件.env加进.gitignore。如果已经提交立刻去平台吊销旧 key重新生成。4.5 现象知识库更新后旧答案还在原因增量更新只加了新块没删旧块或者索引没重新加载。解决更新时按文档 ID 先删旧块再插新块检索前重新加载索引文件。如果用的是内存索引更新后要重启服务或热加载。5. 进阶用混合检索和重排序把校园问答命中率再提一档纯向量检索在校园场景有个短板学生问「缓考申请流程」文档里写的是「缓考办理手续」用词对不上向量相似度就不高。混合检索的思路是向量召回和关键词召回各跑一遍再合并去重。关键词召回可以用 BM25对中文先分词。合并后用一个重排序模型如bge-reranker对候选块重新打分取 top-k 送进 prompt。这套组合拳在文档量大、用词不规范的场景下提升明显。from rank_bm25 import BM25Okapi import jieba tokenized [list(jieba.cut(c)) for c in chunks] bm25 BM25Okapi(tokenized) def hybrid_retrieve(query: str, top_k: int 4): # 向量召回 vec_hits retrieve(query, top_ktop_k * 2) # 关键词召回 q_tokens list(jieba.cut(query)) bm25_scores bm25.get_scores(q_tokens) bm25_idx np.argsort(bm25_scores)[::-1][:top_k * 2] # 合并去重 candidates {c: s for c, s in vec_hits} for i in bm25_idx: candidates.setdefault(chunks[i], float(bm25_scores[i])) # 重排序 pairs [[query, c] for c in candidates] rerank_scores reranker.predict(pairs) ranked sorted(zip(candidates.keys(), rerank_scores), keylambda x: -x[1]) return ranked[:top_k]逻辑说明jieba.cut做中文分词BM25Okapi算关键词分数。合并时用字典去重保留已有分数。reranker.predict对 query-块对打分取最高几个。参数上top_k * 2是扩大候选集给重排序留空间。注意reranker模型也要本地加载显存不够就用小号模型。验证方法很简单准备 20 个校园高频问题人工标注正确答案所在的文档块然后对比纯向量检索和混合检索的命中率。我一般会跑一个脚本输出每个问题的 top-4 块里有没有包含标注块算一个 recall4。如果混合检索比纯向量高 10 个点以上就值得切过去。最后说个习惯每次改完检索策略别只看一两个例子就下结论跑一遍完整测试集不然很容易被个别 case 带偏。希望帮到你。本文还有配套的精品资源点击获取 校园RAG项目实战：从源码解析到混合检索优化
简介这份资源是面向计算机相关专业学生与项目实战学习者的校园LLM完整项目包以RAG检索增强生成技术为核心可用于毕业设计、期末大作业或课程实践。项目经导师指导并通过评审获得98分高分源码均经过本地编译与严格调试确保可直接运行难度适中适合需要完整案例参考的学习者。压缩包共21个文件约1.06MB以Python源码为主涵盖检索模块、模型调用与工具脚本另含XML配置、Markdown说明、JSON数据及依赖清单等目录结构清晰便于按模块阅读与二次开发。资源围绕校园场景构建问答链路包含向量检索、关键词检索与链路回调等实现可帮助读者理解RAG系统的数据组织、检索策略与工程落地方式。目前已有135人学习适合希望快速掌握检索增强生成项目结构、积累实战经验的学生下载使用。1. 从一份校园 RAG 项目源码说起它到底解决了什么校园场景里最不缺的就是文档培养方案、选课手册、奖学金评定办法、实验室安全规范、历年答辩模板。这些内容散落在教务处网站、学院群文件、辅导员发的压缩包里学生想问一句「转专业后学分怎么认定」往往要在五个 PDF 之间来回翻。基于 RAG 的校园 LLM 项目本质就是把这些非结构化文档灌进一个可检索的知识库再让大模型基于检索到的片段回答问题而不是靠它自己「回忆」。这份源码加资料的价值不在于模型多强而在于它把「文档解析 → 切块 → 向量化 → 检索 → 拼 prompt → 生成」这条链路完整跑通了并且针对校园问答做了适配。适合谁适合想拿 RAG 项目练手的学生、需要给院系做内部问答的开发者以及已经看过 rag 详解但没动手写过 rag 项目实战的人。它不解决模型训练也不解决多模态核心就是文本检索增强生成这一件事。2. 拆开这份源码RAG 链路里每个模块在干什么2.1 文档加载与清洗为什么 PDF 解析是第一个翻车点校园文档的格式比想象中脏。教务处导出的 PDF 经常是扫描件套文字层或者表格跨页断裂直接丢给PyPDF2抽出来的文本会混入页眉页脚、页码、甚至乱码。我一般会先做格式分流纯文本 PDF 走pdfplumber扫描件走 OCRWord 文档走python-docx网页存档走BeautifulSoup。清洗阶段要干掉连续空行、孤立页码、重复的页眉字符串。这一步不做干净后面切块再漂亮也是垃圾进垃圾出。import pdfplumber import re def clean_text(raw: str) - str: # 去掉纯数字页码行 raw re.sub(r^\s*\d\s*$, , raw, flagsre.MULTILINE) # 合并被硬换行拆断的句子 raw re.sub(r([^\n。])\n([^\n]), r\1\2, raw) # 压缩连续空行 raw re.sub(r\n{3,}, \n\n, raw) return raw.strip() def load_pdf(path: str) - str: text [] with pdfplumber.open(path) as pdf: for page in pdf.pages: t page.extract_text() or text.append(t) return clean_text(\n.join(text))逻辑说明clean_text先按行处理页码再用正则把被换行拆开的句子接回去最后压缩空行。参数上pdfplumber的extract_text默认按阅读顺序输出如果表格多可以加layoutTrue但会牺牲速度。失败时先看抽出来的文本前 500 字如果全是空白或乱码说明是扫描件得换 OCR 路线。2.2 切块策略rag 切块不是越小越好切块直接决定检索命中率。校园文档里一条奖学金评定办法可能横跨三页如果按固定 500 字切很可能把「申请条件」和「发放标准」切到两个块里检索时只召回一半。常见做法是递归字符切分优先按段落切段落太长再按句子切最后才按字符硬切。块大小我一般设 300500 字重叠 5080 字保证跨块语义不断裂。对于表格类内容最好单独抽成结构化文本再切别和正文混在一起。from langchain.text_splitter import RecursiveCharacterTextSplitter splitter RecursiveCharacterTextSplitter( chunk_size400, chunk_overlap60, separators[\n\n, \n, 。, , , ], length_functionlen, ) chunks splitter.split_text(clean_text)逻辑说明separators的顺序就是切分优先级先按空行段落切再按单换行再按中文句号、分号、逗号最后才按字符。chunk_overlap让相邻块有重叠避免边界信息丢失。参数怎么改如果文档句子特别长把「。」提前如果检索结果太碎把chunk_size调到 600 以上。注意别把chunk_overlap设得超过chunk_size的一半否则块数量爆炸。2.3 向量化与检索embedding 模型选型与 top-k 怎么定向量化就是把每个块映射成一个稠密向量检索时算 query 向量和块向量的余弦相似度。校园场景中文为主embedding 模型优先选中文或多语言模型比如bge-small-zh这类轻量级模型本地跑得动效果也够用。如果源码里用的是 OpenAI 的 embedding注意网络和费用问题校园内网部署建议换本地模型。检索 top-k 一般设 35太少容易漏太多会把无关片段塞进 prompt 导致模型跑偏。可以加一个相似度阈值低于阈值的块直接丢掉。from sentence_transformers import SentenceTransformer import numpy as np model SentenceTransformer(BAAI/bge-small-zh-v1.5) chunk_vecs model.encode(chunks, normalize_embeddingsTrue) def retrieve(query: str, top_k: int 4, threshold: float 0.35): q_vec model.encode([query], normalize_embeddingsTrue)[0] scores chunk_vecs q_vec idx np.argsort(scores)[::-1][:top_k] return [(chunks[i], float(scores[i])) for i in idx if scores[i] threshold]逻辑说明normalize_embeddingsTrue让向量归一化点积等价于余弦相似度。top_k4是经验值threshold0.35过滤掉明显不相关的块。参数怎么改如果召回太少降阈值到 0.25如果噪声多升到 0.45。失败时打印每个块的分数看是不是 query 和文档用词差异太大必要时加同义词扩展。2.4 Prompt 拼装与生成怎么让 LLM 只答文档里有的内容检索回来的片段要拼进 prompt同时必须约束模型「只根据以下资料回答资料没有就说不知道」。这是防止幻觉的关键。校园问答里学生问「补考成绩怎么算」如果资料里没有模型编一个算法出来后果很严重。prompt 模板里把资料放在明确的分隔符之间指令写清楚。生成模型可以用本地部署的开源 LLM也可以用 API但要注意鉴权信息别硬编码在源码里用环境变量或配置文件读取。PROMPT_TEMPLATE 你是一个校园问答助手。请严格根据以下资料回答问题。 如果资料中没有相关信息直接回答「资料中未找到相关内容」不要编造。 资料 {context} 问题{question} 回答 def build_prompt(query: str, retrieved: list) - str: context \n\n.join([f[片段{i1}] {c} for i, (c, _) in enumerate(retrieved)]) return PROMPT_TEMPLATE.format(contextcontext, questionquery)逻辑说明context里给每个片段编号方便排查时定位。指令里明确「不要编造」这是血泪经验不加这句模型十有八九会自由发挥。参数上temperature设 0.10.3越低越稳定。如果模型还是编把「不知道」的指令再加强或者加 few-shot 示例。3. 把源码跑起来本地部署的最小步骤与参数3.1 环境准备与依赖安装别在 Python 版本上踩坑拿到源码先看requirements.txt或pyproject.toml确认 Python 版本。RAG 项目常见的依赖冲突集中在langchain、transformers、torch三者版本上。我一般用 conda 建独立环境Python 3.10 比较稳。安装顺序是先装torch按 CUDA 版本选再装transformers最后装langchain及其周边。如果源码里用了faiss做向量库Linux 下直接pip install faiss-cpuWindows 下可能要装faiss-cpu的预编译包。conda create -n campus-rag python3.10 -y conda activate campus-rag pip install torch --index-url https://download.pytorch.org/whl/cpu pip install transformers sentence-transformers langchain pdfplumber faiss-cpu逻辑说明CPU 版 torch 够跑小模型有 GPU 就把 index-url 换成对应 CUDA 版本。faiss-cpu用于向量检索数据量小的时候也可以用 numpy 暴力算。失败时先看报错是不是版本不兼容pip check能列出冲突。3.2 知识库构建文档放哪、索引存哪、怎么增量更新源码里一般有个data/目录放原始文档index/目录存向量索引。构建流程是遍历data/下所有文件逐个加载、清洗、切块、向量化最后把向量和块文本一起持久化。增量更新是个容易被忽略的点校园文档每学期都会变不能每次全量重建。常见做法是给每个块存一个文档 ID 和哈希新文档进来先比对哈希只重新处理变化的文件。import os, json, hashlib def file_hash(path): with open(path, rb) as f: return hashlib.md5(f.read()).hexdigest() def build_index(data_dir: str, index_dir: str): os.makedirs(index_dir, exist_okTrue) meta_path os.path.join(index_dir, meta.json) meta json.load(open(meta_path)) if os.path.exists(meta_path) else {} all_chunks, all_vecs [], [] for fname in os.listdir(data_dir): fpath os.path.join(data_dir, fname) h file_hash(fpath) if meta.get(fname) h: continue # 未变化跳过 text load_pdf(fpath) if fname.endswith(.pdf) else open(fpath, encodingutf-8).read() chunks splitter.split_text(clean_text(text)) vecs model.encode(chunks, normalize_embeddingsTrue) all_chunks.extend(chunks) all_vecs.append(vecs) meta[fname] h # 持久化向量和文本 np.save(os.path.join(index_dir, vecs.npy), np.vstack(all_vecs)) json.dump(all_chunks, open(os.path.join(index_dir, chunks.json), w, encodingutf-8), ensure_asciiFalse) json.dump(meta, open(meta_path, w), ensure_asciiFalse)逻辑说明file_hash用 MD5 判断文件是否变化meta.json记录每个文件的哈希。参数上index_dir要和检索时读取的路径一致。注意np.vstack要求每个文件的向量维度一致换 embedding 模型时必须全量重建。3.3 检索与生成联调query 进来之后发生了什么联调阶段把检索和生成串起来输入一个问题输出答案和引用片段。这一步要打印中间结果召回了哪些块、分数多少、拼出来的 prompt 长什么样。很多问题不是模型不行而是检索没召回对的块。我一般会写一个debug开关打开后把每个环节的中间数据都打出来。def ask(query: str, debug: bool False): retrieved retrieve(query, top_k4) if debug: for c, s in retrieved: print(f[score{s:.3f}] {c[:80]}...) prompt build_prompt(query, retrieved) if debug: print( * 40) print(prompt[:500]) answer llm_generate(prompt) # 替换成实际生成函数 return answer, retrieved逻辑说明debug模式打印召回片段和分数方便判断是检索问题还是生成问题。llm_generate根据源码里用的模型替换本地模型用transformers的pipelineAPI 模型用对应 SDK。参数上如果答案不完整先看召回片段是否覆盖了答案没覆盖就调检索覆盖了但答错就调 prompt。4. 校园 RAG 项目避坑5 个真实翻车记录4.1 现象PDF 抽出来全是乱码检索完全失效原因文档是扫描件没有文字层pdfplumber只能抽出空白或乱码。解决先用pdf2image把页面转成图片再走 OCR如paddleocr把 OCR 结果当作文本源。注意 OCR 有错字检索时可以用模糊匹配或同义词兜底。4.2 现象模型回答「资料中未找到」但资料里明明有原因切块把关键信息切碎了或者 query 和文档用词差异大向量相似度低。解决先调大chunk_size和chunk_overlap再看召回分数如果分数普遍低于阈值降阈值或换更强的 embedding 模型。还可以加关键词检索做混合召回。4.3 现象同一个问题每次回答不一样甚至自相矛盾原因temperature设太高或者 prompt 里资料顺序随机。解决temperature降到 0.1资料按相似度排序后拼入 prompt固定顺序。如果还飘把「只根据资料回答」的指令再强化加一句「不要使用你的先验知识」。4.4 现象源码里 API key 硬编码提交后泄露原因开发时图方便直接把 key 写在代码里。解决改成从环境变量读取os.environ.get(LLM_API_KEY)本地用.env文件.env加进.gitignore。如果已经提交立刻去平台吊销旧 key重新生成。4.5 现象知识库更新后旧答案还在原因增量更新只加了新块没删旧块或者索引没重新加载。解决更新时按文档 ID 先删旧块再插新块检索前重新加载索引文件。如果用的是内存索引更新后要重启服务或热加载。5. 进阶用混合检索和重排序把校园问答命中率再提一档纯向量检索在校园场景有个短板学生问「缓考申请流程」文档里写的是「缓考办理手续」用词对不上向量相似度就不高。混合检索的思路是向量召回和关键词召回各跑一遍再合并去重。关键词召回可以用 BM25对中文先分词。合并后用一个重排序模型如bge-reranker对候选块重新打分取 top-k 送进 prompt。这套组合拳在文档量大、用词不规范的场景下提升明显。from rank_bm25 import BM25Okapi import jieba tokenized [list(jieba.cut(c)) for c in chunks] bm25 BM25Okapi(tokenized) def hybrid_retrieve(query: str, top_k: int 4): # 向量召回 vec_hits retrieve(query, top_ktop_k * 2) # 关键词召回 q_tokens list(jieba.cut(query)) bm25_scores bm25.get_scores(q_tokens) bm25_idx np.argsort(bm25_scores)[::-1][:top_k * 2] # 合并去重 candidates {c: s for c, s in vec_hits} for i in bm25_idx: candidates.setdefault(chunks[i], float(bm25_scores[i])) # 重排序 pairs [[query, c] for c in candidates] rerank_scores reranker.predict(pairs) ranked sorted(zip(candidates.keys(), rerank_scores), keylambda x: -x[1]) return ranked[:top_k]逻辑说明jieba.cut做中文分词BM25Okapi算关键词分数。合并时用字典去重保留已有分数。reranker.predict对 query-块对打分取最高几个。参数上top_k * 2是扩大候选集给重排序留空间。注意reranker模型也要本地加载显存不够就用小号模型。验证方法很简单准备 20 个校园高频问题人工标注正确答案所在的文档块然后对比纯向量检索和混合检索的命中率。我一般会跑一个脚本输出每个问题的 top-4 块里有没有包含标注块算一个 recall4。如果混合检索比纯向量高 10 个点以上就值得切过去。最后说个习惯每次改完检索策略别只看一两个例子就下结论跑一遍完整测试集不然很容易被个别 case 带偏。希望帮到你。本文还有配套的精品资源点击获取