本文介绍一个可直接运行的本地RAG知识库问答系统使用Python、Streamlit构建Web页面整合LangChain文本切分、ChromaDB向量库及Ollama本地大模型。系统支持TXT、Markdown、PDF文档切分向量化后存入库用户提问时检索Top-K片段并生成答案同时展示引用来源。项目适合作为AI项目实战无需训练模型或大量数据可扩展性强适合课程设计、企业知识库原型等提供完整源码和运行方式。1.为什么要做本地 RAG 知识库问答系统很多同学第一次接触大模型项目时容易把项目理解为“调用一个聊天接口然后让模型回答问题”。这种方式可以做简单对话但它不适合真实项目。原因很直接大模型并不知道用户电脑里的课程资料、项目文档、企业制度、产品说明书和实验报告。如果直接问模型“这个项目有哪些功能”“这份制度怎么规定”“某个接口怎么调用”模型只能根据已有知识进行泛化回答结果往往不够准确也无法给出引用依据。RAG 的价值就在这里。它不是让大模型凭空回答而是先从用户提供的资料中检索相关内容再让模型基于这些资料回答。这样系统就可以把“本地私有知识”和“大模型语言表达能力”结合起来。一个典型的 RAG 系统包含两个阶段第一个阶段是索引构建也就是把文档解析、切分、向量化并存入向量库第二个阶段是检索生成也就是把用户问题向量化在向量库中找到相关片段再把片段作为上下文交给模型生成答案。LangChain 官方 RAG 教程也把 RAG 应用描述为面向特定来源信息进行问答的应用核心流程正是索引、检索和生成。本项目选择“本地 RAG 知识库问答系统”作为实战选题主要是因为它具备几个优点。第一它是当前大模型应用中非常常见的落地方向技术热度高。第二它可以用少量示例文档完成演示不需要训练模型也不需要标注数据。第三它可以自然扩展出文档上传、知识库管理、引用溯源、问答历史、权限控制等功能适合从入门项目升级为完整系统。第四它适合写成 CSDN 技术博客既能讲技术路线也能展示源码结构和运行截图。真实业务里的知识库往往来自图书馆资料、企业制度、产品手册、项目文档和归档文件。下面这张资料架实景图可以帮助读者把“文档进入知识库、被切分、被检索、再生成答案”的流程和真实资料管理场景联系起来。2.项目最终实现效果本项目最终实现的是一个轻量级本地知识库问答系统。用户启动 Web 页面后可以先构建示例知识库也可以上传自己的 TXT、Markdown 或 PDF 文档。系统会读取文档内容切分为多个文本块生成向量并写入向量库。之后用户在聊天框中输入问题系统会检索相关片段调用本地模型生成答案并展示参考来源。项目提供两种运行方式。第一种是 Web 界面方式使用streamlit run app.py启动适合截图、演示和项目展示。第二种是命令行验证方式使用python run_demo.py --rebuild启动适合快速检查代码是否能跑通并自动生成结果图片。下面是一次运行结果截图。当前截图展示的是系统在离线备用模式下的回答效果。因为当前环境没有启动 Ollama系统没有中断而是基于检索片段生成了结构化答案。这个设计可以保证项目在没有 GPU、没有本地模型、没有网络的情况下也能完成最小演示。检索结果还会保存为得分图便于在博客和项目报告中说明 Top-K 片段的相似度。实际项目中如果发现得分最高的片段与问题无关就应该优先调整文本切分、Embedding 模型和检索参数而不是直接修改大模型提示词。3.技术路线设计本项目的技术路线可以概括为文档进入系统后先通过文档解析模块转换为纯文本然后通过文本切分模块把长文本拆成多个带重叠的小片段接着使用 Embedding 模型或离线 Hashing 方法把文本片段转换为向量之后把向量、原文和元数据写入向量库当用户提问时再把问题转换为向量在向量库中检索相似片段最后将用户问题和检索片段拼接成 Prompt交给 Ollama 本地模型生成回答。项目中的核心流程如下本地文档 ↓文档解析 document_loader.py ↓文本切分 text_splitter.py ↓Embedding 向量化 embedding_service.py ↓向量库存储 vector_store.py ↓用户问题 ↓Top-K 语义检索 ↓Prompt 拼接 ↓Ollama 本地大模型 ↓答案生成 引用来源展示这里需要强调一个工程细节为了保证源码包可以直接运行项目没有把 ChromaDB 和 BGE 模型作为唯一依赖而是设计了自动降级机制。默认配置中vector_store_backend为auto系统会优先尝试 ChromaDB如果当前环境没有安装 ChromaDB就使用本地 JSON 向量库。Embedding 默认使用离线 Hashing 后端不需要下载权重。如果用户安装requirements_full.txt就可以切换到 ChromaDB BGE 中文 Embedding 的完整模式。这种设计并不是降低项目含金量而是为了提升交付稳定性。很多课程设计和项目演示环境无法保证网络稳定也可能没有 GPU。如果一个项目必须先下载几个 GB 的模型才能启动就很容易在演示时失败。本项目把“能跑通”放在第一位同时保留完整 RAG 技术栈的扩展入口。4.项目目录结构源码包目录结构如下图所示。完整目录如下local_rag_knowledge_base/├── blog.md├── README.md├── requirements.txt├── requirements_full.txt├── app.py├── run_demo.py├── run.bat├── run.sh├── configs/│ ├── config.yaml│ └── config_chroma_bge.yaml├── src/│ ├── document_loader.py│ ├── text_splitter.py│ ├── embedding_service.py│ ├── vector_store.py│ ├── ollama_client.py│ ├── rag_pipeline.py│ ├── visualization.py│ └── utils.py├── demo_data/│ ├── project_intro.md│ ├── course_design.txt│ ├── product_manual.md│ └── rag_notes.md├── vector_db/├── weights/│ └── README_WEIGHTS.md├── images/│ ├── figures/│ └── results/├── outputs/├── docs/└── tests/这个目录结构是按照项目交付思路设计的。src中存放核心代码configs存放配置demo_data存放示例文档weights存放模型下载说明images存放博客插图和运行截图outputs存放运行结果docs存放项目设计说明和常见问题。这样发布到 CSDN 或作为课程设计交付时读者可以很快看懂项目内容。5.环境安装与快速启动项目推荐使用 Python 3.10 到 3.12。核心演示脚本只依赖少量库Web 页面需要 Streamlit。进入项目目录后可以执行python -m venv .venvWindows 环境.venv/Scripts/activatepip install -r requirements.txtpython run_demo.py --rebuildstreamlit run app.pyLinux 或 macOS 环境source .venv/bin/activatepip install -r requirements.txtpython run_demo.py --rebuildstreamlit run app.py如果希望启用完整的 ChromaDB、LangChain 和 BGE 中文 Embedding可以安装pip install -r requirements_full.txt然后将configs/config_chroma_bge.yaml中的配置复制到configs/config.yaml或者在二次开发时传入该配置文件。Ollama 模型需要单独安装。建议初次演示使用轻量模型ollama pull qwen2.5:0.5bollama run qwen2.5:0.5b如果没有安装 Ollama运行python run_demo.py --rebuild依然会成功。此时系统会输出used_llm: false表示没有调用本地大模型而是使用离线备用回答。这个结果对于课程设计和博客演示是有价值的因为它证明了项目的文档解析、切分、向量化、检索和引用展示流程已经跑通。6.配置文件说明项目的默认配置文件是configs/config.yamlrag: chunk_size: 420 chunk_overlap: 80 top_k: 4 vector_store_backend: auto collection_name: local_rag_docsembedding: backend: hashing model_name: BAAI/bge-small-zh-v1.5 dimension: 384ollama: enable: true base_url: 你的本地 Ollama 地址 model: qwen2.5:0.5b timeout: 60chunk_size控制文本块长度chunk_overlap控制相邻文本块之间的重叠字符数。对于中文资料初始可以设置在 400 到 800 之间。如果文档段落较长可以适当增大如果检索结果经常混入多个主题可以适当减小。top_k控制每次检索返回多少个片段默认返回 4 个。返回片段太少可能缺少上下文返回片段太多可能把无关内容塞给模型。vector_store_backend支持三个值auto、chroma和simple。auto是默认模式优先使用 ChromaDB失败后使用 JSON 向量库chroma会强制使用 ChromaDBsimple会强制使用 JSON 向量库。对于第一次运行建议使用默认值。embedding.backend默认为hashing这是一个离线向量化方案不需要下载模型文件适合快速演示。如果需要更好的中文语义检索效果可以使用sentence_transformers并设置模型为BAAI/bge-small-zh-v1.5。7.文档解析模块实现文档解析模块位于src/document_loader.py。它主要负责把不同格式的文件读取成统一的LoadedDocument对象。对象中包含文档来源、文本内容和元数据。元数据会在后续写入向量库并在回答时展示为引用来源。项目支持 TXT、Markdown 和 PDF。TXT 与 Markdown 可以直接按编码读取。PDF 使用pypdf解析如果遇到扫描版 PDF 或解析失败系统会给出提示而不是直接崩溃。这样做符合项目交付要求即使某个文档解析失败用户也能知道问题在哪里。核心设计如下dataclassclass LoadedDocument: source: str text: str metadata: Dict[str, Any]实际项目中文档解析模块是 RAG 系统的第一道质量关。如果文档读取出来就是乱码、空文本或大量无意义换行后面的向量检索和模型回答都会受到影响。因此在项目中加入normalize_text函数对多余空格、多余空行和换行符进行清洗是很有必要的。8.文本切分模块实现文本切分模块位于src/text_splitter.py。项目优先尝试使用 LangChain 的RecursiveCharacterTextSplitter如果本机没有安装 LangChain 文本切分包就自动使用纯 Python 的 fallback 切分器。文本切分是 RAG 项目中非常关键的部分。不能把整篇长文档直接存成一个向量因为长文本会混合太多主题检索时很难精确命中。也不能把文本切得太碎因为过短的片段缺少上下文模型很难生成完整回答。因此项目中使用chunk_size和chunk_overlap两个参数来控制切分效果。chunk_overlap的作用是让相邻片段之间保留少量重叠内容。例如一个说明跨越了两个段落如果完全硬切开检索到其中一个片段时可能缺少前后文。加入重叠后片段之间有一定连续性回答质量会更稳定。切分后的文本块会被包装成TextChunkdataclassclass TextChunk: id: str content: str metadata: Dict[str, Any]其中metadata中会保留文件名、原始路径、片段编号和预览文本。这些信息后续会用于引用溯源。9.Embedding 向量化模块实现Embedding 模块位于src/embedding_service.py。项目提供两个后端一个是离线 Hashing Embedding一个是 Sentence-Transformers Embedding。离线 Hashing Embedding 的优点是完全不需要模型文件也不需要联网下载。它会把中文字符、中文双字片段、英文单词和数字映射到固定维度向量中并进行归一化。这个方案不是生产环境中最强的语义向量方案但足以完成小型演示和项目验收尤其适合交付包在当前环境中自测。如果希望获得更好的中文语义检索效果可以启用BAAI/bge-small-zh-v1.5。它是常见的中文 Embedding 模型适合中文知识库问答、相似度检索和文档召回。启用方式是在配置中设置embedding: backend: sentence_transformers model_name: BAAI/bge-small-zh-v1.5然后安装完整依赖pip install -r requirements_full.txt在实际项目中Embedding 模型往往比大模型更直接影响“能不能检索到正确片段”。如果检索片段不对大模型再强也只能基于错误上下文回答。因此调试 RAG 系统时要先看检索结果再看生成结果。10.向量库模块实现向量库模块位于src/vector_store.py。项目支持 ChromaDB 和 JSON 向量库两种模式。ChromaDB 是正式的向量数据库方案适合保存向量、元数据和文本内容也便于后续扩展过滤、增量更新和多集合管理。JSON 向量库是为了保证项目在没有安装 ChromaDB 的环境中也能运行它会把文本块、向量和元数据保存到vector_db/simple_index.json。默认配置为vector_store_backend: auto在 auto 模式下系统会尝试创建 ChromaDB 持久化客户端。如果失败就输出提示并切换为 JSON 向量库。这样读者第一次运行项目时不会因为 ChromaDB 依赖问题卡住。检索时JSON 向量库使用余弦相似度计算问题向量与文本块向量之间的相似程度然后返回得分最高的 Top-K 片段。ChromaDB 模式下则调用 Chroma 的查询接口返回相关片段。两种模式对上层 RAG Pipeline 暴露同样的query方法因此 Web 页面和命令行脚本不需要关心底层使用的是哪种存储。11.Ollama 本地模型调用Ollama 调用模块位于src/ollama_client.py。项目通过 HTTP 请求访问本地 Ollama 服务默认地址是本地模型服务地址请求体中包含模型名称、Prompt、是否流式输出和生成参数。为了让代码更容易运行本项目默认关闭流式输出payload { model: self.model, prompt: prompt, stream: False, options: { temperature: 0.2, num_predict: 800, },}temperature设置得比较低是为了让模型回答更稳定。RAG 问答系统不需要模型发挥太多想象力而是希望它忠实根据资料回答。Prompt 中也明确要求“只依据给定资料回答如果资料不足请说明不足不要编造”。如果 Ollama 没有启动generate方法会返回错误信息而不是抛出异常导致主程序退出。上层 Pipeline 会检测是否生成成功如果失败就调用离线备用回答函数。这个设计让项目在演示时更稳。12.RAG Pipeline 核心逻辑项目核心逻辑位于src/rag_pipeline.py。LocalRAGPipeline负责组织所有模块包括读取配置、创建 Embedding 服务、创建向量库、构建索引、检索片段、拼接 Prompt、调用 Ollama 和保存问答历史。构建索引的主要流程是documents load_documents(resolved)chunks split_documents( documents, chunk_sizeint(self.rag_cfg.get(chunk_size, 420)), overlapint(self.rag_cfg.get(chunk_overlap, 80)), use_langchainTrue,)vectors self.embedding.embed_texts([c.content for c in chunks])self.store.add_chunks(chunks, vectors)回答问题的主要流程是contexts self.search(question, top_ktop_k)prompt self.build_prompt(question, contexts)answer, used_llm, status self.ollama.generate(prompt)if not answer: answer self.fallback_answer(question, contexts)这里最重要的是build_prompt。它会把检索到的资料片段按照[资料1]、[资料2]的格式拼接起来并告诉模型回答必须忠于资料。Prompt 的质量会直接影响模型是否愿意引用资料、是否会胡编、是否会在资料不足时明确说明不足。项目还会把每次问答保存到outputs/chat_history.jsonoutputs/latest_result.json这两个文件既可以用于调试也可以用于项目报告截图和结果分析。13.Streamlit Web 页面实现Web 页面位于app.py。Streamlit 很适合这种项目演示因为它可以用较少代码实现侧边栏、文件上传、按钮、聊天输入框、结果展示和下载按钮。页面左侧是参数配置区用户可以设置 Ollama 模型名称、Top-K 数量上传文档或构建示例知识库。页面主体是聊天区展示用户问题、系统回答和引用片段。核心交互包括uploaded_files st.file_uploader( 上传 TXT / MD / PDF 文件, type[txt, md, markdown, pdf], accept_multiple_filesTrue,)以及聊天输入question st.chat_input(请输入关于文档的问题)当用户点击“构建示例知识库”时系统会调用pipeline.build_index([demo_data], resetTrue)当用户输入问题时系统会调用result pipeline.answer(question, top_ktop_k)然后把result[answer]显示为回答把result[retrieved]展示为引用片段。引用片段中包含文件名、相关度和原文片段方便用户判断答案依据。14.命令行验证脚本为了满足项目交付和自测要求源码包中提供了run_demo.py。这个脚本的作用不是替代 Web 页面而是让用户在任何环境下都能快速验证项目是否可运行。执行命令python run_demo.py --rebuild脚本会自动完成以下步骤1. **读取 demo_data 示例文档2. 构建向量索引3. 提出默认问题4. 检索 Top-K 片段5. 调用 Ollama 或离线备用回答6. 保存 latest_result.json7. 生成流程图、结构图、运行结果图和检索得分图8. 输出 validation_report.json**运行后可以看到[OK] Result images saved to images/results/. Validation report saved to outputs/validation_report.json.这些输出来自项目运行流程便于读者复现知识库导入、检索得分和问答结果。15.运行结果分析本项目内置的默认问题是这个项目适合哪些课程设计场景系统会在示例文档中检索到course_design.txt、project_intro.md和product_manual.md中的相关片段。这些片段说明项目适合人工智能导论、自然语言处理、Python Web 开发、大数据应用实践、软件工程课程设计、毕业设计原型验证等场景也说明项目包含文档上传、文本解析、文本切分、向量化、向量库存储、问题检索、答案生成和引用片段展示等功能。在离线备用模式下回答会比较结构化重点是把检索到的片段列出来并给出综合说明。在 Ollama 模式下回答会更自然可以根据上下文组织成更完整的中文段落。两种模式的共同点是都会展示引用来源。如果你在自己的电脑上启动了 Ollama并下载了qwen2.5:0.5b运行结果中的used_llm会变成true。如果是false说明项目没有调用成功本地模型但检索流程仍然正常。16.常见问题与解决方法第一个常见问题是 Streamlit 未安装。如果运行streamlit run app.py报错执行pip install -r requirements.txt第二个常见问题是 Ollama 未启动。此时系统会显示 Ollama 调用失败但不会影响离线演示。解决方式是先安装 Ollama然后执行ollama pull qwen2.5:0.5bollama run qwen2.5:0.5b第三个常见问题是 ChromaDB 安装失败。默认配置下不需要强制解决因为系统会自动切换为 JSON 向量库。如果你确实需要 ChromaDB可以安装完整依赖pip install -r requirements_full.txt第四个常见问题是 PDF 解析为空。很多扫描版 PDF 不包含可提取文本需要 OCR 才能读取。当前项目没有内置 OCR建议先使用可复制文字的 PDF或者把文档另存为 TXT/Markdown。第五个常见问题是回答看起来不准确。此时不要先怀疑模型而应该先打开outputs/latest_result.json检查retrieved字段。如果检索片段不相关应该调整 chunk 参数或换用 BGE Embedding如果检索片段正确但回答偏离才需要优化 Prompt 或更换更强的 Ollama 模型。17.项目扩展方向这个项目可以继续向多个方向扩展。第一个方向是支持更多文档格式例如 DOCX、PPTX、Excel、HTML 和网页链接。第二个方向是增加多知识库管理让用户可以为不同课程、不同项目或不同企业部门建立独立知识库。第三个方向是加入数据库把用户、文档、知识库、问答历史和权限信息保存起来。第四个方向是加入混合检索把关键词 BM25 检索和向量检索结合起来提高专业术语和编号类问题的命中率。第五个方向是加入 rerank 模型对召回片段二次排序提高最终上下文质量。如果要做成更完整的系统可以把 Streamlit 替换为 FastAPI Vue 或 Flask Bootstrap。后端负责文档解析、索引构建和问答接口前端负责知识库管理、聊天界面和引用展示。这样项目就可以从课程设计升级为企业知识库原型。如果要做论文或算法改进可以围绕 chunk 策略、Embedding 模型对比、Top-K 参数、rerank 模型、Prompt 模板和检索评价指标展开实验。例如比较 Hashing Embedding、BGE-small-zh、BGE-base-zh 在同一批问题上的召回效果统计 Top-1、Top-3、Top-5 命中率并分析回答质量。大模型的知识又多又杂到底怎么学做这行久了被问最多的问题就一个大模型的知识又多又杂我到底先学啥翻了一堆资料看啥都像重点结果啥都没学进去。今天把我自己一路摸出来的顺序捋一遍零基础、应届生、转行的都适用。跟着走至少方向不乱、不瞎忙学完拿得出手。第一阶段10天初阶应用这一阶段就一个目标把大模型真正玩明白不是只会聊天那种而是能调教它、能用代码把大模型和业务接起来。大模型 AI 能干什么大模型是怎样获得「智能」的用好 AI 的核心心法大模型应用业务架构大模型应用技术架构代码示例向 GPT-3.5 灌入新知识提示工程的意义和核心思想Prompt 典型构成指令调优方法论思维链和思维树Prompt 攻击和防范…第二阶段30天高阶应用这阶段正式进实战目标很实在做出两个能拿出手的东西——一个私有知识库一个 agent 对话机器人。为什么要做 RAG搭建一个简单的 ChatPDF检索的基础概念什么是向量表示Embeddings向量数据库与向量检索基于向量检索的 RAG搭建 RAG 系统的扩展知识混合检索与 RAG-Fusion 简介向量模型本地部署…走完这 30 天Python 或 JavaScript 背景的基本能独立做一套 RAG 应用简历上也敢写大模型应用开发了。第三阶段约20天动手微调学到这你已经开始 “造” 模型了 —— 通过微调搞出垂直领域的专用小模型。为什么要做 RAG什么是模型什么是模型训练求解器 损失函数简介小实验2手写一个简单的神经网络并训练它什么是训练/预训练/微调/轻量化微调Transformer结构简介轻量化微调实验数据集的构建…恭喜你如果学到这里你基本可以找到一份大模型 AI相关的工作自己也能训练 GPT 了通过微调训练自己的垂直大模型能独立训练开源多模态大模型掌握更多技术方案。到此为止大概2个月的时间。你从 “只会用” 变成 “能造” 的 AI 小子。那么你还想往下探索吗想要入局AI大模型赛道、抢占行业红利的朋友微信扫描下方CSDN官方认证二维码即可100%免费领取全套学习资料第四阶段20天商业闭环部署落地技术学完落地才算数。这阶段带你搞明白大模型怎么真正跑起来、用起来。硬件选型带你了解全球大模型使用国产大模型服务搭建 OpenAI 代理热身基于阿里云 PAI 部署 Stable Diffusion在本地计算机运行大模型大模型的私有化部署基于 vLLM 部署大模型案例如何优雅地在阿里云私有部署开源大模型部署一套开源 LLM 项目内容安全互联网信息服务算法备案…想要入坑大模型的朋友给大家准备了一份2026 年最新 AI 大模型全套学习资料1、大模型系统化学习路线2、大模型学习视频教程3、大模型学习书籍电子文档4、AI大模型最新行业报告5、大模型项目实战配套源码6、2026大模型大厂面试真题7、为什么要学习大模型我国在A大模型领域面临人才短缺,数量与质量均落后于发达国家。2023年人才缺口已超百万凸显培养不足。随着AI技术飞速发展预计到2025年,这一缺口将急剧扩大至400万,严重制约我国AI产业的创新步伐。加强人才培养,优化教育体系,国际合作并进是破解困局、推动AI发展的关键。8、适合谁学传统后端 / Java / 前端开发想转型 AI 应用大学生、应届生想拿更好的 offer产品经理、运营想武装职业竞争力技术负责人想给团队落地提效学习是反人性的但回报是真金白银。技术会更新赛道会切换但只要你先动手机会就永远站在你这边。9、这些资料真的有用吗这份资料由我和鲁为民博士(北京清华大学学士和美国加州理工学院博士)共同整理现任上海殷泊信息科技CEO其创立的MoPaaS云平台获Forrester全球’强劲表现者’认证服务航天科工、国家电网等1000企业以第一作者在IEEE Transactions发表论文50篇获NASA JPL火星探测系统强化学习专利等35项中美专利。本套AI大模型课程由清华大学-加州理工双料博士、吴文俊人工智能奖得主鲁为民教授领衔研发。资料内容涵盖了从入门到进阶的各类视频教程和实战项目无论你是小白还是有些技术基础的技术人员这份资料都绝对能帮助你提升薪资待遇转行大模型岗位。想要入局AI大模型赛道、抢占行业红利的朋友微信扫描下方CSDN官方认证二维码即可100%免费领取全套学习资料好了就写到这。路线是死的人是活的卡住了随时来问我。觉得有用就点个收藏别让它进收藏夹吃灰——动起来比啥都强。 
长河君 · 2026/11/4 7:16:47 · 阅读 1.2k 本地RAG知识库问答系统实战：小白也能轻松上手大模型，含收藏功能！
本文介绍一个可直接运行的本地RAG知识库问答系统使用Python、Streamlit构建Web页面整合LangChain文本切分、ChromaDB向量库及Ollama本地大模型。系统支持TXT、Markdown、PDF文档切分向量化后存入库用户提问时检索Top-K片段并生成答案同时展示引用来源。项目适合作为AI项目实战无需训练模型或大量数据可扩展性强适合课程设计、企业知识库原型等提供完整源码和运行方式。1.为什么要做本地 RAG 知识库问答系统很多同学第一次接触大模型项目时容易把项目理解为“调用一个聊天接口然后让模型回答问题”。这种方式可以做简单对话但它不适合真实项目。原因很直接大模型并不知道用户电脑里的课程资料、项目文档、企业制度、产品说明书和实验报告。如果直接问模型“这个项目有哪些功能”“这份制度怎么规定”“某个接口怎么调用”模型只能根据已有知识进行泛化回答结果往往不够准确也无法给出引用依据。RAG 的价值就在这里。它不是让大模型凭空回答而是先从用户提供的资料中检索相关内容再让模型基于这些资料回答。这样系统就可以把“本地私有知识”和“大模型语言表达能力”结合起来。一个典型的 RAG 系统包含两个阶段第一个阶段是索引构建也就是把文档解析、切分、向量化并存入向量库第二个阶段是检索生成也就是把用户问题向量化在向量库中找到相关片段再把片段作为上下文交给模型生成答案。LangChain 官方 RAG 教程也把 RAG 应用描述为面向特定来源信息进行问答的应用核心流程正是索引、检索和生成。本项目选择“本地 RAG 知识库问答系统”作为实战选题主要是因为它具备几个优点。第一它是当前大模型应用中非常常见的落地方向技术热度高。第二它可以用少量示例文档完成演示不需要训练模型也不需要标注数据。第三它可以自然扩展出文档上传、知识库管理、引用溯源、问答历史、权限控制等功能适合从入门项目升级为完整系统。第四它适合写成 CSDN 技术博客既能讲技术路线也能展示源码结构和运行截图。真实业务里的知识库往往来自图书馆资料、企业制度、产品手册、项目文档和归档文件。下面这张资料架实景图可以帮助读者把“文档进入知识库、被切分、被检索、再生成答案”的流程和真实资料管理场景联系起来。2.项目最终实现效果本项目最终实现的是一个轻量级本地知识库问答系统。用户启动 Web 页面后可以先构建示例知识库也可以上传自己的 TXT、Markdown 或 PDF 文档。系统会读取文档内容切分为多个文本块生成向量并写入向量库。之后用户在聊天框中输入问题系统会检索相关片段调用本地模型生成答案并展示参考来源。项目提供两种运行方式。第一种是 Web 界面方式使用streamlit run app.py启动适合截图、演示和项目展示。第二种是命令行验证方式使用python run_demo.py --rebuild启动适合快速检查代码是否能跑通并自动生成结果图片。下面是一次运行结果截图。当前截图展示的是系统在离线备用模式下的回答效果。因为当前环境没有启动 Ollama系统没有中断而是基于检索片段生成了结构化答案。这个设计可以保证项目在没有 GPU、没有本地模型、没有网络的情况下也能完成最小演示。检索结果还会保存为得分图便于在博客和项目报告中说明 Top-K 片段的相似度。实际项目中如果发现得分最高的片段与问题无关就应该优先调整文本切分、Embedding 模型和检索参数而不是直接修改大模型提示词。3.技术路线设计本项目的技术路线可以概括为文档进入系统后先通过文档解析模块转换为纯文本然后通过文本切分模块把长文本拆成多个带重叠的小片段接着使用 Embedding 模型或离线 Hashing 方法把文本片段转换为向量之后把向量、原文和元数据写入向量库当用户提问时再把问题转换为向量在向量库中检索相似片段最后将用户问题和检索片段拼接成 Prompt交给 Ollama 本地模型生成回答。项目中的核心流程如下本地文档 ↓文档解析 document_loader.py ↓文本切分 text_splitter.py ↓Embedding 向量化 embedding_service.py ↓向量库存储 vector_store.py ↓用户问题 ↓Top-K 语义检索 ↓Prompt 拼接 ↓Ollama 本地大模型 ↓答案生成 引用来源展示这里需要强调一个工程细节为了保证源码包可以直接运行项目没有把 ChromaDB 和 BGE 模型作为唯一依赖而是设计了自动降级机制。默认配置中vector_store_backend为auto系统会优先尝试 ChromaDB如果当前环境没有安装 ChromaDB就使用本地 JSON 向量库。Embedding 默认使用离线 Hashing 后端不需要下载权重。如果用户安装requirements_full.txt就可以切换到 ChromaDB BGE 中文 Embedding 的完整模式。这种设计并不是降低项目含金量而是为了提升交付稳定性。很多课程设计和项目演示环境无法保证网络稳定也可能没有 GPU。如果一个项目必须先下载几个 GB 的模型才能启动就很容易在演示时失败。本项目把“能跑通”放在第一位同时保留完整 RAG 技术栈的扩展入口。4.项目目录结构源码包目录结构如下图所示。完整目录如下local_rag_knowledge_base/├── blog.md├── README.md├── requirements.txt├── requirements_full.txt├── app.py├── run_demo.py├── run.bat├── run.sh├── configs/│ ├── config.yaml│ └── config_chroma_bge.yaml├── src/│ ├── document_loader.py│ ├── text_splitter.py│ ├── embedding_service.py│ ├── vector_store.py│ ├── ollama_client.py│ ├── rag_pipeline.py│ ├── visualization.py│ └── utils.py├── demo_data/│ ├── project_intro.md│ ├── course_design.txt│ ├── product_manual.md│ └── rag_notes.md├── vector_db/├── weights/│ └── README_WEIGHTS.md├── images/│ ├── figures/│ └── results/├── outputs/├── docs/└── tests/这个目录结构是按照项目交付思路设计的。src中存放核心代码configs存放配置demo_data存放示例文档weights存放模型下载说明images存放博客插图和运行截图outputs存放运行结果docs存放项目设计说明和常见问题。这样发布到 CSDN 或作为课程设计交付时读者可以很快看懂项目内容。5.环境安装与快速启动项目推荐使用 Python 3.10 到 3.12。核心演示脚本只依赖少量库Web 页面需要 Streamlit。进入项目目录后可以执行python -m venv .venvWindows 环境.venv/Scripts/activatepip install -r requirements.txtpython run_demo.py --rebuildstreamlit run app.pyLinux 或 macOS 环境source .venv/bin/activatepip install -r requirements.txtpython run_demo.py --rebuildstreamlit run app.py如果希望启用完整的 ChromaDB、LangChain 和 BGE 中文 Embedding可以安装pip install -r requirements_full.txt然后将configs/config_chroma_bge.yaml中的配置复制到configs/config.yaml或者在二次开发时传入该配置文件。Ollama 模型需要单独安装。建议初次演示使用轻量模型ollama pull qwen2.5:0.5bollama run qwen2.5:0.5b如果没有安装 Ollama运行python run_demo.py --rebuild依然会成功。此时系统会输出used_llm: false表示没有调用本地大模型而是使用离线备用回答。这个结果对于课程设计和博客演示是有价值的因为它证明了项目的文档解析、切分、向量化、检索和引用展示流程已经跑通。6.配置文件说明项目的默认配置文件是configs/config.yamlrag: chunk_size: 420 chunk_overlap: 80 top_k: 4 vector_store_backend: auto collection_name: local_rag_docsembedding: backend: hashing model_name: BAAI/bge-small-zh-v1.5 dimension: 384ollama: enable: true base_url: 你的本地 Ollama 地址 model: qwen2.5:0.5b timeout: 60chunk_size控制文本块长度chunk_overlap控制相邻文本块之间的重叠字符数。对于中文资料初始可以设置在 400 到 800 之间。如果文档段落较长可以适当增大如果检索结果经常混入多个主题可以适当减小。top_k控制每次检索返回多少个片段默认返回 4 个。返回片段太少可能缺少上下文返回片段太多可能把无关内容塞给模型。vector_store_backend支持三个值auto、chroma和simple。auto是默认模式优先使用 ChromaDB失败后使用 JSON 向量库chroma会强制使用 ChromaDBsimple会强制使用 JSON 向量库。对于第一次运行建议使用默认值。embedding.backend默认为hashing这是一个离线向量化方案不需要下载模型文件适合快速演示。如果需要更好的中文语义检索效果可以使用sentence_transformers并设置模型为BAAI/bge-small-zh-v1.5。7.文档解析模块实现文档解析模块位于src/document_loader.py。它主要负责把不同格式的文件读取成统一的LoadedDocument对象。对象中包含文档来源、文本内容和元数据。元数据会在后续写入向量库并在回答时展示为引用来源。项目支持 TXT、Markdown 和 PDF。TXT 与 Markdown 可以直接按编码读取。PDF 使用pypdf解析如果遇到扫描版 PDF 或解析失败系统会给出提示而不是直接崩溃。这样做符合项目交付要求即使某个文档解析失败用户也能知道问题在哪里。核心设计如下dataclassclass LoadedDocument: source: str text: str metadata: Dict[str, Any]实际项目中文档解析模块是 RAG 系统的第一道质量关。如果文档读取出来就是乱码、空文本或大量无意义换行后面的向量检索和模型回答都会受到影响。因此在项目中加入normalize_text函数对多余空格、多余空行和换行符进行清洗是很有必要的。8.文本切分模块实现文本切分模块位于src/text_splitter.py。项目优先尝试使用 LangChain 的RecursiveCharacterTextSplitter如果本机没有安装 LangChain 文本切分包就自动使用纯 Python 的 fallback 切分器。文本切分是 RAG 项目中非常关键的部分。不能把整篇长文档直接存成一个向量因为长文本会混合太多主题检索时很难精确命中。也不能把文本切得太碎因为过短的片段缺少上下文模型很难生成完整回答。因此项目中使用chunk_size和chunk_overlap两个参数来控制切分效果。chunk_overlap的作用是让相邻片段之间保留少量重叠内容。例如一个说明跨越了两个段落如果完全硬切开检索到其中一个片段时可能缺少前后文。加入重叠后片段之间有一定连续性回答质量会更稳定。切分后的文本块会被包装成TextChunkdataclassclass TextChunk: id: str content: str metadata: Dict[str, Any]其中metadata中会保留文件名、原始路径、片段编号和预览文本。这些信息后续会用于引用溯源。9.Embedding 向量化模块实现Embedding 模块位于src/embedding_service.py。项目提供两个后端一个是离线 Hashing Embedding一个是 Sentence-Transformers Embedding。离线 Hashing Embedding 的优点是完全不需要模型文件也不需要联网下载。它会把中文字符、中文双字片段、英文单词和数字映射到固定维度向量中并进行归一化。这个方案不是生产环境中最强的语义向量方案但足以完成小型演示和项目验收尤其适合交付包在当前环境中自测。如果希望获得更好的中文语义检索效果可以启用BAAI/bge-small-zh-v1.5。它是常见的中文 Embedding 模型适合中文知识库问答、相似度检索和文档召回。启用方式是在配置中设置embedding: backend: sentence_transformers model_name: BAAI/bge-small-zh-v1.5然后安装完整依赖pip install -r requirements_full.txt在实际项目中Embedding 模型往往比大模型更直接影响“能不能检索到正确片段”。如果检索片段不对大模型再强也只能基于错误上下文回答。因此调试 RAG 系统时要先看检索结果再看生成结果。10.向量库模块实现向量库模块位于src/vector_store.py。项目支持 ChromaDB 和 JSON 向量库两种模式。ChromaDB 是正式的向量数据库方案适合保存向量、元数据和文本内容也便于后续扩展过滤、增量更新和多集合管理。JSON 向量库是为了保证项目在没有安装 ChromaDB 的环境中也能运行它会把文本块、向量和元数据保存到vector_db/simple_index.json。默认配置为vector_store_backend: auto在 auto 模式下系统会尝试创建 ChromaDB 持久化客户端。如果失败就输出提示并切换为 JSON 向量库。这样读者第一次运行项目时不会因为 ChromaDB 依赖问题卡住。检索时JSON 向量库使用余弦相似度计算问题向量与文本块向量之间的相似程度然后返回得分最高的 Top-K 片段。ChromaDB 模式下则调用 Chroma 的查询接口返回相关片段。两种模式对上层 RAG Pipeline 暴露同样的query方法因此 Web 页面和命令行脚本不需要关心底层使用的是哪种存储。11.Ollama 本地模型调用Ollama 调用模块位于src/ollama_client.py。项目通过 HTTP 请求访问本地 Ollama 服务默认地址是本地模型服务地址请求体中包含模型名称、Prompt、是否流式输出和生成参数。为了让代码更容易运行本项目默认关闭流式输出payload { model: self.model, prompt: prompt, stream: False, options: { temperature: 0.2, num_predict: 800, },}temperature设置得比较低是为了让模型回答更稳定。RAG 问答系统不需要模型发挥太多想象力而是希望它忠实根据资料回答。Prompt 中也明确要求“只依据给定资料回答如果资料不足请说明不足不要编造”。如果 Ollama 没有启动generate方法会返回错误信息而不是抛出异常导致主程序退出。上层 Pipeline 会检测是否生成成功如果失败就调用离线备用回答函数。这个设计让项目在演示时更稳。12.RAG Pipeline 核心逻辑项目核心逻辑位于src/rag_pipeline.py。LocalRAGPipeline负责组织所有模块包括读取配置、创建 Embedding 服务、创建向量库、构建索引、检索片段、拼接 Prompt、调用 Ollama 和保存问答历史。构建索引的主要流程是documents load_documents(resolved)chunks split_documents( documents, chunk_sizeint(self.rag_cfg.get(chunk_size, 420)), overlapint(self.rag_cfg.get(chunk_overlap, 80)), use_langchainTrue,)vectors self.embedding.embed_texts([c.content for c in chunks])self.store.add_chunks(chunks, vectors)回答问题的主要流程是contexts self.search(question, top_ktop_k)prompt self.build_prompt(question, contexts)answer, used_llm, status self.ollama.generate(prompt)if not answer: answer self.fallback_answer(question, contexts)这里最重要的是build_prompt。它会把检索到的资料片段按照[资料1]、[资料2]的格式拼接起来并告诉模型回答必须忠于资料。Prompt 的质量会直接影响模型是否愿意引用资料、是否会胡编、是否会在资料不足时明确说明不足。项目还会把每次问答保存到outputs/chat_history.jsonoutputs/latest_result.json这两个文件既可以用于调试也可以用于项目报告截图和结果分析。13.Streamlit Web 页面实现Web 页面位于app.py。Streamlit 很适合这种项目演示因为它可以用较少代码实现侧边栏、文件上传、按钮、聊天输入框、结果展示和下载按钮。页面左侧是参数配置区用户可以设置 Ollama 模型名称、Top-K 数量上传文档或构建示例知识库。页面主体是聊天区展示用户问题、系统回答和引用片段。核心交互包括uploaded_files st.file_uploader( 上传 TXT / MD / PDF 文件, type[txt, md, markdown, pdf], accept_multiple_filesTrue,)以及聊天输入question st.chat_input(请输入关于文档的问题)当用户点击“构建示例知识库”时系统会调用pipeline.build_index([demo_data], resetTrue)当用户输入问题时系统会调用result pipeline.answer(question, top_ktop_k)然后把result[answer]显示为回答把result[retrieved]展示为引用片段。引用片段中包含文件名、相关度和原文片段方便用户判断答案依据。14.命令行验证脚本为了满足项目交付和自测要求源码包中提供了run_demo.py。这个脚本的作用不是替代 Web 页面而是让用户在任何环境下都能快速验证项目是否可运行。执行命令python run_demo.py --rebuild脚本会自动完成以下步骤1. **读取 demo_data 示例文档2. 构建向量索引3. 提出默认问题4. 检索 Top-K 片段5. 调用 Ollama 或离线备用回答6. 保存 latest_result.json7. 生成流程图、结构图、运行结果图和检索得分图8. 输出 validation_report.json**运行后可以看到[OK] Result images saved to images/results/. Validation report saved to outputs/validation_report.json.这些输出来自项目运行流程便于读者复现知识库导入、检索得分和问答结果。15.运行结果分析本项目内置的默认问题是这个项目适合哪些课程设计场景系统会在示例文档中检索到course_design.txt、project_intro.md和product_manual.md中的相关片段。这些片段说明项目适合人工智能导论、自然语言处理、Python Web 开发、大数据应用实践、软件工程课程设计、毕业设计原型验证等场景也说明项目包含文档上传、文本解析、文本切分、向量化、向量库存储、问题检索、答案生成和引用片段展示等功能。在离线备用模式下回答会比较结构化重点是把检索到的片段列出来并给出综合说明。在 Ollama 模式下回答会更自然可以根据上下文组织成更完整的中文段落。两种模式的共同点是都会展示引用来源。如果你在自己的电脑上启动了 Ollama并下载了qwen2.5:0.5b运行结果中的used_llm会变成true。如果是false说明项目没有调用成功本地模型但检索流程仍然正常。16.常见问题与解决方法第一个常见问题是 Streamlit 未安装。如果运行streamlit run app.py报错执行pip install -r requirements.txt第二个常见问题是 Ollama 未启动。此时系统会显示 Ollama 调用失败但不会影响离线演示。解决方式是先安装 Ollama然后执行ollama pull qwen2.5:0.5bollama run qwen2.5:0.5b第三个常见问题是 ChromaDB 安装失败。默认配置下不需要强制解决因为系统会自动切换为 JSON 向量库。如果你确实需要 ChromaDB可以安装完整依赖pip install -r requirements_full.txt第四个常见问题是 PDF 解析为空。很多扫描版 PDF 不包含可提取文本需要 OCR 才能读取。当前项目没有内置 OCR建议先使用可复制文字的 PDF或者把文档另存为 TXT/Markdown。第五个常见问题是回答看起来不准确。此时不要先怀疑模型而应该先打开outputs/latest_result.json检查retrieved字段。如果检索片段不相关应该调整 chunk 参数或换用 BGE Embedding如果检索片段正确但回答偏离才需要优化 Prompt 或更换更强的 Ollama 模型。17.项目扩展方向这个项目可以继续向多个方向扩展。第一个方向是支持更多文档格式例如 DOCX、PPTX、Excel、HTML 和网页链接。第二个方向是增加多知识库管理让用户可以为不同课程、不同项目或不同企业部门建立独立知识库。第三个方向是加入数据库把用户、文档、知识库、问答历史和权限信息保存起来。第四个方向是加入混合检索把关键词 BM25 检索和向量检索结合起来提高专业术语和编号类问题的命中率。第五个方向是加入 rerank 模型对召回片段二次排序提高最终上下文质量。如果要做成更完整的系统可以把 Streamlit 替换为 FastAPI Vue 或 Flask Bootstrap。后端负责文档解析、索引构建和问答接口前端负责知识库管理、聊天界面和引用展示。这样项目就可以从课程设计升级为企业知识库原型。如果要做论文或算法改进可以围绕 chunk 策略、Embedding 模型对比、Top-K 参数、rerank 模型、Prompt 模板和检索评价指标展开实验。例如比较 Hashing Embedding、BGE-small-zh、BGE-base-zh 在同一批问题上的召回效果统计 Top-1、Top-3、Top-5 命中率并分析回答质量。大模型的知识又多又杂到底怎么学做这行久了被问最多的问题就一个大模型的知识又多又杂我到底先学啥翻了一堆资料看啥都像重点结果啥都没学进去。今天把我自己一路摸出来的顺序捋一遍零基础、应届生、转行的都适用。跟着走至少方向不乱、不瞎忙学完拿得出手。第一阶段10天初阶应用这一阶段就一个目标把大模型真正玩明白不是只会聊天那种而是能调教它、能用代码把大模型和业务接起来。大模型 AI 能干什么大模型是怎样获得「智能」的用好 AI 的核心心法大模型应用业务架构大模型应用技术架构代码示例向 GPT-3.5 灌入新知识提示工程的意义和核心思想Prompt 典型构成指令调优方法论思维链和思维树Prompt 攻击和防范…第二阶段30天高阶应用这阶段正式进实战目标很实在做出两个能拿出手的东西——一个私有知识库一个 agent 对话机器人。为什么要做 RAG搭建一个简单的 ChatPDF检索的基础概念什么是向量表示Embeddings向量数据库与向量检索基于向量检索的 RAG搭建 RAG 系统的扩展知识混合检索与 RAG-Fusion 简介向量模型本地部署…走完这 30 天Python 或 JavaScript 背景的基本能独立做一套 RAG 应用简历上也敢写大模型应用开发了。第三阶段约20天动手微调学到这你已经开始 “造” 模型了 —— 通过微调搞出垂直领域的专用小模型。为什么要做 RAG什么是模型什么是模型训练求解器 损失函数简介小实验2手写一个简单的神经网络并训练它什么是训练/预训练/微调/轻量化微调Transformer结构简介轻量化微调实验数据集的构建…恭喜你如果学到这里你基本可以找到一份大模型 AI相关的工作自己也能训练 GPT 了通过微调训练自己的垂直大模型能独立训练开源多模态大模型掌握更多技术方案。到此为止大概2个月的时间。你从 “只会用” 变成 “能造” 的 AI 小子。那么你还想往下探索吗想要入局AI大模型赛道、抢占行业红利的朋友微信扫描下方CSDN官方认证二维码即可100%免费领取全套学习资料第四阶段20天商业闭环部署落地技术学完落地才算数。这阶段带你搞明白大模型怎么真正跑起来、用起来。硬件选型带你了解全球大模型使用国产大模型服务搭建 OpenAI 代理热身基于阿里云 PAI 部署 Stable Diffusion在本地计算机运行大模型大模型的私有化部署基于 vLLM 部署大模型案例如何优雅地在阿里云私有部署开源大模型部署一套开源 LLM 项目内容安全互联网信息服务算法备案…想要入坑大模型的朋友给大家准备了一份2026 年最新 AI 大模型全套学习资料1、大模型系统化学习路线2、大模型学习视频教程3、大模型学习书籍电子文档4、AI大模型最新行业报告5、大模型项目实战配套源码6、2026大模型大厂面试真题7、为什么要学习大模型我国在A大模型领域面临人才短缺,数量与质量均落后于发达国家。2023年人才缺口已超百万凸显培养不足。随着AI技术飞速发展预计到2025年,这一缺口将急剧扩大至400万,严重制约我国AI产业的创新步伐。加强人才培养,优化教育体系,国际合作并进是破解困局、推动AI发展的关键。8、适合谁学传统后端 / Java / 前端开发想转型 AI 应用大学生、应届生想拿更好的 offer产品经理、运营想武装职业竞争力技术负责人想给团队落地提效学习是反人性的但回报是真金白银。技术会更新赛道会切换但只要你先动手机会就永远站在你这边。9、这些资料真的有用吗这份资料由我和鲁为民博士(北京清华大学学士和美国加州理工学院博士)共同整理现任上海殷泊信息科技CEO其创立的MoPaaS云平台获Forrester全球’强劲表现者’认证服务航天科工、国家电网等1000企业以第一作者在IEEE Transactions发表论文50篇获NASA JPL火星探测系统强化学习专利等35项中美专利。本套AI大模型课程由清华大学-加州理工双料博士、吴文俊人工智能奖得主鲁为民教授领衔研发。资料内容涵盖了从入门到进阶的各类视频教程和实战项目无论你是小白还是有些技术基础的技术人员这份资料都绝对能帮助你提升薪资待遇转行大模型岗位。想要入局AI大模型赛道、抢占行业红利的朋友微信扫描下方CSDN官方认证二维码即可100%免费领取全套学习资料好了就写到这。路线是死的人是活的卡住了随时来问我。觉得有用就点个收藏别让它进收藏夹吃灰——动起来比啥都强。