1. 为什么你的大模型缺少“私域知识”最近很多开发者朋友问我同一个问题直接用 ChatGPT、Deepseek 这类大模型做问答效果挺好的但一问到公司内部文档、个人笔记、私有资料里的内容它就“一问三不知”。要么胡编乱造要么干脆告诉你“没有相关信息”。这个问题的本质不是大模型不够聪明而是大模型的知识边界只停留在训练时刻的数据集上。只要你的资料不在它的训练集里它就不可能知道。解决这个问题有两种主流思路一种是微调Fine-tuning让大模型把新知识“记进”参数里另一种就是本文要讲的 RAGRetrieval-Augmented Generation检索增强生成通过“先检索、再生成”的方式把外部知识库的内容动态接入问答链路。两种方案各有适用场景但对大多数开发者来说RAG 是更轻、更快、更可控的选择。这篇文章会围绕一个核心主题展开用 Deepseek 作为大模型底座搭建一套完整的 RAG 私有知识库问答系统。我会从 RAG 的原理讲起然后给出可运行的源码示例、核心模块拆解、运行验证方式和常见问题排查清单。无论你是刚开始接触大模型应用开发还是已经在做 Agent、知识库类产品都能通过这篇文章跑通一套最小可用系统并理解 RAG 每个环节背后的设计逻辑。2. RAG 核心原理与概念拆解2.1 什么是 RAGRAG 的全称是 Retrieval-Augmented Generation中文通常翻译为“检索增强生成”。它的核心思想非常朴素别让大模型凭空回答先让它去你的知识库里“查资料”查完再回答。传统的大模型问答流程是用户提问 → 直接送入大模型 → 大模型根据参数记忆生成回答RAG 的问答流程变成了用户提问 → 从知识库检索相关内容 → 把用户问题和检索到的内容一起送入大模型 → 大模型基于证据生成回答这一步变化看似简单实际上解决了几个很关键的问题解决知识陈旧问题模型训练数据有截止日期但知识库可以实时更新。解决私有知识问题公司内部文档、个人笔记、产品手册不需要进入模型参数只需要进入向量数据库。解决幻觉问题大模型生成时有了检索到的片段作为上下文依据回答会更有边界感也能给出出处。降低更新成本加一份新文档只需要重新做切片和向量化不需要重新训练模型。2.2 RAG 的三个核心阶段一套完整的 RAG 系统可以分成三个子模块这也是后续代码实现的主线1. 索引阶段Indexing把原始文档切分成合理的片段Chunk然后通过 Embedding 模型把每个片段转换成向量最后写入向量数据库。这个阶段解决的是“知识怎么存”的问题。2. 检索阶段Retrieval用户提问时先把问题通过同一个 Embedding 模型转换成向量然后在向量数据库中做相似度检索找到最相关的 Top K 个文档片段。这个阶段解决的是“知识怎么找”的问题。3. 生成阶段Generation把用户问题、检索到的文档片段、系统提示词一起组装成 Prompt送入大模型本文使用 Deepseek让模型基于这些材料生成最终回答。这个阶段解决的是“答案怎么组织”的问题。三个阶段的流程可以用下面的表格做一个直观对比阶段输入处理方式输出索引原始文档切分 Embedding 写入向量库文档向量检索用户问题问题向量化 相似度搜索Top K 相关片段生成问题 相关片段组装 Prompt LLM 生成最终答案2.3 为什么选择 Deepseek 作为底座模型RAG 架构中的“生成”环节需要一个底座大模型。为什么这篇文章选择 Deepseek主要有几个原因接口兼容成熟。Deepseek 提供了兼容 OpenAI 接口风格的 API开发者不需要额外学习一套新的 SDK直接使用常见的 HTTP 请求方式就能接入。中文效果有优势。Deepseek 在中文理解和生成上的表现处于第一梯队而 RAG 知识库问答最常见的场景恰恰是中文文档。成本可控。相比一些大型闭源模型Deepseek 的 API 价格更适合个人开发者和中小团队跑通原型、做产品验证。本地化部署路径清晰。如果你有私有化部署需求Deepseek 的开源模型权重和量化为本地部署提供了比较成熟的社区方案。需要说明的是RAG 架构本身并不绑定任何特定模型。你今天用的是 Deepseek明天换成其他 LLM替换的只是“生成”模块的 API 调用索引和检索模块完全不需要改动。这也是 RAG 架构能够广泛流行的原因之一——它足够模块化。3. 系统架构设计与技术选型3.1 系统整体架构本文要搭建的 RAG 知识库问答系统整体架构如下---------------- ------------------ ------------------ | 原始文档 | | Embedding 向量 | | 向量数据库 | | Markdown/PDF | --- | 模型 | --- | (Chroma) | ---------------- ------------------ ------------------ | 用户提问 ------------------------------------------------- | v ------------------ ------------------ ------------------ | 问题向量化 | --- | 相似度检索 TopK | --- | Prompt 组装 | ------------------ ------------------ ------------------ | v ------------------ | Deepseek API | | 生成回答 | ------------------3.2 技术选型说明模块技术选型选择理由底座大模型Deepseek API中文效果好接口兼容 OpenAI 风格Embedding 模型text2vec 或 OpenAI 兼容接口中文向量化效果好本地可运行向量数据库Chroma轻量、纯 Python、适合学习和原型开发文档加载LangChain / 自研解析支持 Markdown、PDF、TXT 等常见格式开发语言Python 3.9AI 生态系统最完善如果你的项目是大型生产系统可以把 Chroma 替换为 Milvus、Qdrant 或 Elasticsearch如果数据量很小甚至可以直接把向量保存在内存里。本文保持“最小可用系统”优先后续在最佳实践部分再讲生产化改造方案。4. 环境准备与依赖安装4.1 环境要求在开始写代码之前需要准备以下环境Python 3.9 或更高版本建议用 3.10 或 3.11兼容性更好。一个 Deepseek 开放平台账号并在控制台创建 API Key。能够访问外网的环境Deepseek API 调用需要联网。推荐使用虚拟环境避免依赖冲突。4.2 创建 Python 虚拟环境建议每个项目使用独立的虚拟环境。打开终端执行mkdir rag-knowledge-base cd rag-knowledge-base python3 -m venv venv source venv/bin/activateWindows 系统激活命令略有不同venv\Scripts\activate激活提示符出现(venv)前缀后说明虚拟环境已经生效。4.3 安装依赖本项目需要的核心依赖有chromadb向量数据库存储文档向量。sentence-transformers加载本地 Embedding 模型。openaiDeepseek API 兼容 OpenAI 协议直接用 openai SDK 调用。python-dotenv读取 .env 配置文件。langchain-text-splitters仅使用 LangChain 中的文档切分器避免引入整个框架。pypdf解析 PDF 文件。执行安装命令pip install chromadb sentence-transformers openai python-dotenv pypdf pip install langchain-text-splitters如果你在安装sentence-transformers或chromadb时遇到依赖冲突建议先升级 pip 再重试pip install --upgrade pip4.4 配置 Deepseek API Key在项目根目录创建.env文件DEEPSEEK_API_KEY你的_api_key DEEPSEEK_BASE_URLhttps://api.deepseek.com DEEPSEEK_MODELdeepseek-chat再创建config.py用于读取环境变量# 文件路径config.py import os from dotenv import load_dotenv load_dotenv() DEEPSEEK_API_KEY os.getenv(DEEPSEEK_API_KEY) DEEPSEEK_BASE_URL os.getenv(DEEPSEEK_BASE_URL, https://api.deepseek.com) DEEPSEEK_MODEL os.getenv(DEEPSEEK_MODEL, deepseek-chat)注意不要把.env文件提交到 Git 仓库建议在.gitignore中加上.env和venv/。5. 核心流程拆解从文档到问答在编写完整代码之前先理清我们要实现哪些功能模块。整个系统由四个 Python 文件组成职责划分如下文件职责对应阶段config.py加载环境变量通用data_processing.py文档加载、切分索引阶段knowledge_base.py向量化、写入向量库索引阶段rag_query.py检索 生成回答检索与生成阶段这个划分是典型的“高内聚、低耦合”设计文档处理不关心后面用什么向量库问答模块也不关心前期文档是怎么切分的。替换任何一个模块都不需要大规模改动其他代码。5.1 文档加载与切分文档加载要解决的问题是把不同格式的资料统一成纯文本。切片要解决的问题是让文本的长度适合 Embedding 和检索。切片为什么重要如果切片太长检索回来的内容可能包含大量无关信息浪费上下文窗口如果切片太短一个完整概念可能被切成两半语义不完整。所以切片长度和重叠是 RAG 中需要反复调参的关键参数。切分逻辑使用RecursiveCharacterTextSplitter它会以层级方式递归切分文本优先保证段落和句子的完整性。实现如下# 文件路径data_processing.py from langchain_text_splitters import RecursiveCharacterTextSplitter from pypdf import PdfReader def load_markdown(file_path: str) - str: with open(file_path, r, encodingutf-8) as f: return f.read() def load_pdf(file_path: str) - str: reader PdfReader(file_path) text [] for page in reader.pages: page_text page.extract_text() if page_text: text.append(page_text) return \n.join(text) def split_text(text: str, chunk_size: int 500, chunk_overlap: int 100) - list: splitter RecursiveCharacterTextSplitter( chunk_sizechunk_size, chunk_overlapchunk_overlap, separators[\n\n, \n, 。, , , , , ] ) chunks splitter.split_text(text) return [chunk.strip() for chunk in chunks if chunk.strip()]这里的关键逻辑在separators参数。它定义了文本切分的优先顺序先按空行切再按换行切再按中文句号、感叹号、问号切。这样能够最大程度避免把一个完整句子拦腰截断。注意PyPDF对扫描版 PDF 无能为力。如果你的文档是图片型 PDF需要先做 OCR 再进入 RAG 流程。这是很多新手容易踩的坑。5.2 向量化与向量库写入Embedding 阶段需要完成两件事第一用文本向量模型将每个切片转成向量第二把向量和原始文本一起写入向量数据库。本项目的 Embedding 模型采用本地加载的sentence-transformers模型好处是数据不需要传到第三方适合有隐私要求的场景。当然也可以换成 Deepseek 或 OpenAI 的 Embedding API这里展示本地方案# 文件路径knowledge_base.py import chromadb from sentence_transformers import SentenceTransformer from data_processing import load_markdown, load_pdf, split_text CHROMA_DIR ./chroma_data COLLECTION_NAME knowledge_base EMBEDDING_MODEL shibing624/text2vec-base-chinese class VectorStore: def __init__(self): self.embedding_model SentenceTransformer(EMBEDDING_MODEL) self.client chromadb.PersistentClient(pathCHROMA_DIR) self.collection self.client.get_or_create_collection( nameCOLLECTION_NAME, metadata{hnsw:space: cosine} ) def add_documents(self, texts: list, source_file: str): if not texts: return embeddings self.embedding_model.encode(texts).tolist() ids [ f{source_file}_{idx} for idx in range(len(texts)) ] metadatas [ {source: source_file, chunk_index: idx} for idx in range(len(texts)) ] self.collection.add( idsids, embeddingsembeddings, documentstexts, metadatasmetadatas ) def query(self, question: str, top_k: int 4): question_embedding self.embedding_model.encode(question).tolist() results self.collection.query( query_embeddings[question_embedding], n_resultstop_k ) return results def build_index(file_paths: list): store VectorStore() for file_path in file_paths: if file_path.endswith(.md): text load_markdown(file_path) elif file_path.endswith(.pdf): text load_pdf(file_path) else: print(f不支持的文件格式: {file_path}) continue chunks split_text(text) print(f文件 {file_path} 被切成 {len(chunks)} 个片段) store.add_documents(chunks, source_filefile_path) if __name__ __main__: build_index([./docs/员工手册.md])这段代码里有几个值得留意的设计点持久化存储。用PersistentClient而不是临时内存客户端这样向量数据会落盘到./chroma_data目录。下次启动程序时不需要重新索引。余弦相似度。向量检索的相似度度量选择cosine这是文本向量场景最常用的度量方式。还有l2欧式距离和ip内积两种选择但 cosine 对向量长度不敏感更适合语义相似度计算。元数据Metadata。每一条向量都记录了来源文件和 chunk 索引。这样在后续问答时我们可以追溯答案出自哪份文档做“引用溯源”。5.3 检索与生成检索阶段把用户问题转化为向量然后在向量库里搜索最接近的 Top K 个片段。生成阶段则把问题与检索片段组成 Prompt 发送给 Deepseek。这里是最核心的代码因为 Prompt 的组装方式直接决定了回答质量。一个高质量的 RAG Prompt 需要明确告诉模型哪些信息是检索到的证据回答时只能基于证据证据不足时要说不知道而不是编造。# 文件路径rag_query.py from openai import OpenAI from knowledge_base import VectorStore from config import DEEPSEEK_API_KEY, DEEPSEEK_BASE_URL, DEEPSEEK_MODEL SYSTEM_PROMPT 你是一个严谨的知识库问答助手。请基于以下检索到的文档片段回答用户问题。 规则 1. 只能使用提供的文档片段中的信息来回答问题。 2. 如果文档片段中没有相关信息请明确回复“知识库中没有找到相关信息”不要编造。 3. 在回答末尾列出引用的文档来源片段编号。 检索到的文档片段 {context} def search_knowledge(question: str, top_k: int 4): store VectorStore() results store.query(question, top_ktop_k) documents results[documents][0] metadatas results[metadatas][0] context_lines [] for idx, (doc, meta) in enumerate(zip(documents, metadatas)): source meta.get(source, 未知来源) chunk_index meta.get(chunk_index, 0) context_lines.append(f[{idx 1}] 来源: {source} 片段: {chunk_index}\n{doc}) return \n\n.join(context_lines) def ask_question(question: str, top_k: int 4): context search_knowledge(question, top_ktop_k) client OpenAI( api_keyDEEPSEEK_API_KEY, base_urlDEEPSEEK_BASE_URL ) response client.chat.completions.create( modelDEEPSEEK_MODEL, messages[ {role: system, content: SYSTEM_PROMPT.format(contextcontext)}, {role: user, content: question} ], streamFalse, temperature0.3 ) return response.choices[0].message.content if __name__ __main__: question input(请输入问题: ) answer ask_question(question) print(\n 回答 ) print(answer)代码中temperature0.3是一个刻意设置的值。RAG 场景的核心诉求是“忠实于知识库”而不是“发挥创造力”。温度越低生成的随机性越小回答越稳定。如果你做的是创意写作类应用可以调高到 0.7 以上但知识库问答建议固定在一个偏低的范围。5.4 批量导入脚本为了让知识库便于维护我们再写一个批量导入脚本。后续新增文档时只需要把文件放入docs/目录运行脚本即可# 文件路径import_docs.py import os from knowledge_base import build_index def get_all_docs(docs_dir: str ./docs): file_paths [] for root, dirs, files in os.walk(docs_dir): for file in files: if file.endswith((.md, .txt, .pdf)): full_path os.path.join(root, file) file_paths.append(full_path) return file_paths if __name__ __main__: files get_all_docs() print(f共发现 {len(files)} 个文档) build_index(files)这个脚本的价值在于知识库的维护不再依赖手动编写 Python 代码而是变成“把文件放进去跑一次脚本”的简单操作。6. 运行结果与效果验证6.1 运行步骤假设你的docs/目录下已经有一份名为员工手册.md的文档内容包含公司考勤制度、请假流程、加班规则等信息。第一步导入文档建立索引python import_docs.py预期输出共发现 1 个文档 文件 ./docs/员工手册.md 被切成 6 个片段第二步运行问答程序python rag_query.py输入问题请简单介绍一下这里的考勤制度预期输出效果大模型生成的内容具体文字会有差异但结构和引用格式应当一致根据知识库中的《员工手册》信息考勤制度的主要内容包括 1. 工作时间为每个工作日的 9:00 至 18:00午休一小时。 2. 每日上下班需要在考勤系统打卡公差外出需要提前提交申请。 3. 每月可享有两次迟到豁免机会超过部分计入月度考勤统计。 引用来源 [1] 来源: ./docs/员工手册.md 片段: 0 [2] 来源: ./docs/员工手册.md 片段: 36.2 如何判断系统效果是否正常从三个维度验证检索相关性。如果回答中的信息确实来自知识库文档且能对应到正确的文档片段说明检索链路正常。如果回答内容与文档无关需要检查切分结果和 Embedding 模型是否合适。回答忠实度。将回答与原始文档逐条对照确认没有出现文档中不存在的信息。Deepseek 的能力很强但一旦 Prompt 里给了上下文它有时会把上下文当作“参考资料”加上自己训练知识中的内容混合输出。所以 Prompt 规则里的“不要编造”需要反复强调必要时可以添加更严格的约束。引用可追溯性。回答末尾应该列出引用来源。如果引用的片段编号与实际内容对不上说明元数据或检索结果映射出了问题。6.3 一个失败案例的排查演示假设你输入了“公司年假是多少天”回答却是“知识库中没有找到相关信息”。这时候不要急着改 Prompt按下面的顺序排查确认文档中确实包含年假条款。打印检索到的 Top 4 片段看是否含有关键词“年假”。如果片段中有年假内容但回答仍说“找不到”说明是 Prompt 或模型生成链路的问题。如果片段中没有年假内容说明是切分或检索的问题可能需要调整chunk_size或top_k。很多 RAG 项目效果不好问题不在大模型而在检索阶段。优先排查检索结果是 RAG 排错的第一原则。7. 常见问题与排查思路下面这张表汇总了 RAG 知识库开发中最常遇到的问题和对应的排查方向。问题现象可能原因排查方式解决方案答案总说“找不到信息”检索 Top K 太小或切分太细导致语义不完整打印检索结果查看相关性增大 Top K调整 chunk_size回答中出现知识库没有的内容Prompt 约束不够严格检查是否开启了高 temperature降低 temperature在 Prompt 中加入强制约束向量化速度极慢本地 CPU 运行 Embedding 模型查看 CPU 占用率换更大的机器或改用 API 版 Embedding导入文档时报编码错误文档不是 UTF-8 编码查看文件编码格式统一转成 UTF-8 编码Chroma 目录越来越大反复导入导致数据重复检查 collection 中记录数导入前根据 sourcecontent 做去重扫描版 PDF 提取不到文字PDF 是图片型没有文本层用 PdfReader 打印提取结果先 OCR 再导入答案过渡依赖某一段切分粒度太大跨主题文本混在一个 chunk检查 chunk 内容主题纯度减小 chunk_size增加 overlapAPI 调用报 401API Key 配置错误或已过期打印 config 中 Key 的前几位重新生成 Key检查 .env 文件排查 RAG 问题有一个简单原则从数据流的方向查先查输入数据再查检索结果最后查生成结果。不要一上来就怀疑大模型不行。大多数情况下问题出在数据清洗和检索参数上。8. 工程化最佳实践与优化方向跑通最小可用系统之后如果你想把这个项目推向生产环境有几件事是绕不开的。8.1 切分策略优化切片是 RAG 中影响最大的变量之一。500 字固定切分只是起点生产环境要根据文档类型做差异化处理。策略型文档制度、规范按标题层级切分优先保持章节完整。问答型文档FAQ每个问答对作为一个 chunk。技术文档按代码块和方法定义边界切分。更进阶的做法是使用“父子切分”Parent-Child Chunking检索时用较短的子片段提高召回精度送入大模型时把子片段所属的父段落一起送上保证上下文完整。有相关热词也在讨论类似的做法核心解决的就是检索精度和上下文完整性的矛盾。8.2 混合检索与重排序向量检索擅长语义相似度但有时会忽略精确关键词匹配。比如文档里写的是“五险一金”用户问的是“社保”向量检索能关联上但精确的条款数字可能需要 BM25 关键词召回。实际项目中推荐“向量检索 关键词检索”的混合模式。在两种模式的结果合并之后需要加一个重排序Re-ranking环节。重排序模型会以更精细的方式评估每个候选片段与用户问题的匹配度把最相关的结果排到前面。这个环节对回答质量的提升往往非常明显。8.3 引用溯源与安全边界RAG 系统的优势之一是答案可溯源。在生产环境中回答的每一个关键论点都应该能对应到文档原文。实现方式是不仅返回大模型生成的文本还要同时返回检索到的文档 ID、片段索引、原文内容。安全方面需要注意知识库文档可能存在敏感信息需要在上传前做权限分级。对用户输入做基本的注入防护。知识库 Prompt 中如果嵌入了类似“忽略之前的指令”的内容模型可能被诱导。不要把系统 Prompt 设计得过于复杂避免被反向套出。关于权限边界从系统设计一开始就应该考虑谁可以上传文档、谁可以查询哪部分知识这比上线后再补要省很多成本。8.4 从原型到生产的架构演进原型的目录结构适合学习但生产环境建议按团队和模块拆分更多依托 Dify、LangChain、LlamaIndex 等成熟框架来承载工程复杂度。具体演进建议将向量数据库替换为 Milvus 或 Qdrant支持分布式部署和千亿级向量规模。Embedding 模型从本地转 API 或部署成独立服务避免与主服务抢占资源。增加缓存层对高频相同问题直接返回缓存结果降低 API 调用成本。增加评测体系建立“问题-预期答案-检索结果”的评测集每次修改参数后回归测试。接入可观测性工具记录每一次问答的检索片段、模型输出、耗时和 token 消耗。8.5 多轮对话与 Agent 化演进目前实现的 RAG 问答是“单轮检索 单轮回答”。实际使用中用户可能会追问细节也可能一句话里包含两个不同维度的问题。这时候有两种优化方向一是多轮对话改写。在检索之前利用大模型把“它呢”“那年假怎么算”这类追问改写为包含上下文的完整问题再进入检索流程。二是 Agent 化。把 RAG 能力封装成 Agent 的一个工具配合意图识别、工具调用、流程编排形成 Agentic RAG。例如“帮我把季度销售数据做成图表”这类任务单靠知识库问答解决不了但 Agent 可以决定先去知识库找数据定义再调用数据分析工具。这也是当前 RAG 技术演进比较快的一个方向。9. 总结这篇文章从零搭建了一套基于 Deepseek 的 RAG 知识库问答系统核心代码分成了四个模块配置管理、文档处理、向量存储、检索问答。整套流程可以概括为“文档切分 → 向量化 → 向量库检索 → Prompt 组装 → 大模型生成”每一步都有对应的代码实现。几个容易忽略但影响很大的细节值得再强调一次第一RAG 的核心瓶颈通常在检索不在生成。回答质量不高时先检查检索回来的片段是否真的相关、是否完整。第二Prompt 设计直接决定 RAG 的底线。温度调低、来源标注、拒绝编造规则这些虽然看起来简单但对抗幻觉的效果非常明显。第三切分是持续调优的过程。不同文档用同一套切分参数是不合理的生产环境需要针对文档类型设计切分策略并用评测集持续验证效果。如果你是从零学习 RAG建议拿到代码后先跑通最小示例然后用自己手头真实的文档替换测试数据观察切分、检索和生成三个阶段分别发生了什么。对 RAG 的理解是从“看别人讲解”到“自己调整参数观察变化”之后才真正开始的。下一步可以继续研究混合检索、重排序、多轮对话改写和 Agentic RAG这些都是基于本文这套基础架构的自然延伸。