本系列文章将手把手带你搭建本地知识库保证代码完美跑通系列文章结束将 开源项目代码敬请期待。导读为什么你接入大模型后它总是胡说八道因为“Garbage In, Garbage Out”。这是《从零构建个人知识库》系列的第一篇我们将彻底抛弃昂贵的云端 SaaS在纯 CPU 环境下用新版 LangChain 搭建一条工业级的本地文档加载与清洗流水线。跟着本文敲完代码你的私有化 RAG 项目就迈出了最坚实的第一步。为什么我们必须自建本地知识库在动手之前我们需要明确两个核心痛点大模型幻觉通用大模型不知道你的公司规章、私人笔记或最新论文。把整本书塞进 Prompt 不仅超出上下文限制还会导致模型“注意力分散”产生严重幻觉。隐私与成本焦虑将核心数据上传至第三方 API 存在极大的合规风险而长期调用商业 Embedding 和解析接口费用是个无底洞。我们的解法全程本地化、开源化、CPU 可运行。今天我们先解决“如何把非结构化文档变成干净文本”的问题。第一步配置极简 CPU 开发环境新版 LangChain 已经彻底模块化我们不再需要安装臃肿的单体包。针对纯 CPU 环境请在终端执行以下精简安装命令# 创建并激活虚拟环境 (强烈建议)python-mvenv .venvsource.venv/bin/activate# Windows使用: .venv\Scripts\activate# 安装新版LangChain核心组件、文本分割器及HuggingFace集成包pipinstalllangchain-core langchain-community langchain-text-splitters langchain-huggingface# 安装轻量级文档解析库及其底层依赖pipinstallunstructured pypdf sentence-transformers避坑提示Unstructured功能强大但依赖复杂。对于个人知识库我们仅安装[md]等基础解析器即可。如果后续需要解析复杂的扫描件 PDF再考虑安装unstructured[all-docs]或使用更轻量的PyMuPDF (fitz)作为备选。第二步多格式文档加载器实战在新版 LangChain 中文档加载器被统一归入了langchain_community.document_loaders。我们来编写一个自动识别文件后缀并加载的工厂函数。在项目根目录创建src/loaders.pyimportosfromtypingimportListfromlangchain_core.documentsimportDocument# 采用社区标准的加载器工厂方法兼容性最好fromlangchain_community.document_loadersimportTextLoader,PyPDFLoadertry:fromlangchain_community.document_loadersimportUnstructuredMarkdownLoaderexceptImportError:UnstructuredMarkdownLoaderNoneprint(未找到UnstructuredMarkdownLoader请确保已安装 unstructured)classLocalDocLoader:本地文档加载器支持 TXT, MD, PDFLOADER_MAPPING{.txt:TextLoader,.md:UnstructuredMarkdownLoader,.pdf:PyPDFLoader,}classmethoddefload(cls,file_path:str)-List[Document]:extos.path.splitext(file_path)[-1].lower()ifextnotincls.LOADER_MAPPING:raiseValueError(f暂不支持的文件格式:{ext})loader_classcls.LOADER_MAPPING[ext]ifext.pdf:loaderloader_class(file_path)else:loaderloader_class(file_path,encodingutf-8)print(f正在加载:{os.path.basename(file_path)})returnloader.load()第三步文本清洗——RAG 质量的隐形护城河很多新手做完加载就直接去切片向量化结果检索出来的全是页眉、页脚和乱码。清洗比加载更重要我们使用 Python 原生正则表达式进行轻量级清洗无需额外依赖。在项目根目录创建src/cleaner.pyimportrefromtypingimportListfromlangchain_core.documentsimportDocumentdefclean_documents(docs:List[Document])-List[Document]: 基础文本清洗流水线 1. 去除多余空白符与换行 2. 清除常见PDF页眉页脚特征 3. 过滤无效短文本 cleaned_docs[]fordocindocs:textdoc.page_content# 1. 将连续的换行和空格替换为单个空格textre.sub(r\s, ,text).strip()# 2. 去除类似 第X页、Page X 的页码残留textre.sub(r(第\s*\d\s*页|Page\s*\d),,text)# 3. 去除特殊控制字符和乱码textre.sub(r[\x00-\x08\x0b\x0c\x0e-\x1f],,text)# 4. 过滤掉清洗后过短的无效片段 (如纯目录项)iflen(text)50:doc.page_contenttext cleaned_docs.append(doc)print(f清洗完成: 原始{len(docs)}个片段 - 有效{len(cleaned_docs)}个片段)returncleaned_docs第四步串联流水线跑通第一个测试现在让我们把加载和清洗串联起来验证整个流水线。创建main.py进行测试fromsrc.loadersimportLocalDocLoaderfromsrc.cleanerimportclean_documentsif__name____main__:# 请在此处替换为你本地的真实文件路径test_files[./data/test_doc.md,./data/manual.pdf]all_docs[]forpathintest_files:try:docsLocalDocLoader.load(path)all_docs.extend(docs)exceptExceptionase:print(f加载失败 [{path}]:{e})# 执行清洗final_docsclean_documents(all_docs)# 打印第一个有效片段验证效果iffinal_docs:print(\n--- 清洗后的首个文档片段预览 ---)print(final_docs[0].page_content[:300])print(f\n元数据保留完整:{final_docs[0].metadata})运行python main.py如果你能看到干净的文本输出以及包含source、page等信息的 metadata恭喜你你的本地知识库数据基石已经牢牢打下。预期运行结果当你运行这段代码时控制台会输出类似以下内容取决于你的文档内容✅ 正在加载: test_doc.md ✅ 正在加载: manual.pdf 清洗完成: 原始 4 个片段 - 有效 3 个片段 --- 清洗后的首个文档片段预览 --- 一、 榜单说话56.6分背后的含金量 在Artificial Analysis最新公布的全球大模型综合榜单中Qwen3.7-Max以56.6分的成绩位列全球第五、国产第一。 这个分数意味着什么它标志着国产模型已经跨越了“可用”到“好用”的鸿沟正式进入全球顶级模型的“俱乐部”。不同于以往部分榜单的自说自话Artificial Analysis以其严苛的工程化评测标准著称。Qwen3.7-Max能在该榜单中脱颖而出说明其在实际应用场景中的综合能力而非单纯的刷题能力得到了国际认可。 更令技术圈振奋的是其在垂直领域的突破 Terminal Bench 2.0-Terminus编程智 元数据保留完整: {source: ./data/test_doc.md} 进程已结束退出代码为 0系列预告这是《从零构建个人知识库》系列的第一篇下一篇我将详细讲解如何用新版 LangChain LCEL 语法实现语义切片并在纯 CPU 环境下完成极速向量化。点击关注更新时第一时间收到通知带你一步步把这个项目真正跑在你的电脑上**关注后续系列文章更新**
【手把手RAG搭建】从零手搓本地知识库（第一篇）：数据清洗流水线搭建指南
发布时间：2026/5/26 23:44:47
本系列文章将手把手带你搭建本地知识库保证代码完美跑通系列文章结束将 开源项目代码敬请期待。导读为什么你接入大模型后它总是胡说八道因为“Garbage In, Garbage Out”。这是《从零构建个人知识库》系列的第一篇我们将彻底抛弃昂贵的云端 SaaS在纯 CPU 环境下用新版 LangChain 搭建一条工业级的本地文档加载与清洗流水线。跟着本文敲完代码你的私有化 RAG 项目就迈出了最坚实的第一步。为什么我们必须自建本地知识库在动手之前我们需要明确两个核心痛点大模型幻觉通用大模型不知道你的公司规章、私人笔记或最新论文。把整本书塞进 Prompt 不仅超出上下文限制还会导致模型“注意力分散”产生严重幻觉。隐私与成本焦虑将核心数据上传至第三方 API 存在极大的合规风险而长期调用商业 Embedding 和解析接口费用是个无底洞。我们的解法全程本地化、开源化、CPU 可运行。今天我们先解决“如何把非结构化文档变成干净文本”的问题。第一步配置极简 CPU 开发环境新版 LangChain 已经彻底模块化我们不再需要安装臃肿的单体包。针对纯 CPU 环境请在终端执行以下精简安装命令# 创建并激活虚拟环境 (强烈建议)python-mvenv .venvsource.venv/bin/activate# Windows使用: .venv\Scripts\activate# 安装新版LangChain核心组件、文本分割器及HuggingFace集成包pipinstalllangchain-core langchain-community langchain-text-splitters langchain-huggingface# 安装轻量级文档解析库及其底层依赖pipinstallunstructured pypdf sentence-transformers避坑提示Unstructured功能强大但依赖复杂。对于个人知识库我们仅安装[md]等基础解析器即可。如果后续需要解析复杂的扫描件 PDF再考虑安装unstructured[all-docs]或使用更轻量的PyMuPDF (fitz)作为备选。第二步多格式文档加载器实战在新版 LangChain 中文档加载器被统一归入了langchain_community.document_loaders。我们来编写一个自动识别文件后缀并加载的工厂函数。在项目根目录创建src/loaders.pyimportosfromtypingimportListfromlangchain_core.documentsimportDocument# 采用社区标准的加载器工厂方法兼容性最好fromlangchain_community.document_loadersimportTextLoader,PyPDFLoadertry:fromlangchain_community.document_loadersimportUnstructuredMarkdownLoaderexceptImportError:UnstructuredMarkdownLoaderNoneprint(未找到UnstructuredMarkdownLoader请确保已安装 unstructured)classLocalDocLoader:本地文档加载器支持 TXT, MD, PDFLOADER_MAPPING{.txt:TextLoader,.md:UnstructuredMarkdownLoader,.pdf:PyPDFLoader,}classmethoddefload(cls,file_path:str)-List[Document]:extos.path.splitext(file_path)[-1].lower()ifextnotincls.LOADER_MAPPING:raiseValueError(f暂不支持的文件格式:{ext})loader_classcls.LOADER_MAPPING[ext]ifext.pdf:loaderloader_class(file_path)else:loaderloader_class(file_path,encodingutf-8)print(f正在加载:{os.path.basename(file_path)})returnloader.load()第三步文本清洗——RAG 质量的隐形护城河很多新手做完加载就直接去切片向量化结果检索出来的全是页眉、页脚和乱码。清洗比加载更重要我们使用 Python 原生正则表达式进行轻量级清洗无需额外依赖。在项目根目录创建src/cleaner.pyimportrefromtypingimportListfromlangchain_core.documentsimportDocumentdefclean_documents(docs:List[Document])-List[Document]: 基础文本清洗流水线 1. 去除多余空白符与换行 2. 清除常见PDF页眉页脚特征 3. 过滤无效短文本 cleaned_docs[]fordocindocs:textdoc.page_content# 1. 将连续的换行和空格替换为单个空格textre.sub(r\s, ,text).strip()# 2. 去除类似 第X页、Page X 的页码残留textre.sub(r(第\s*\d\s*页|Page\s*\d),,text)# 3. 去除特殊控制字符和乱码textre.sub(r[\x00-\x08\x0b\x0c\x0e-\x1f],,text)# 4. 过滤掉清洗后过短的无效片段 (如纯目录项)iflen(text)50:doc.page_contenttext cleaned_docs.append(doc)print(f清洗完成: 原始{len(docs)}个片段 - 有效{len(cleaned_docs)}个片段)returncleaned_docs第四步串联流水线跑通第一个测试现在让我们把加载和清洗串联起来验证整个流水线。创建main.py进行测试fromsrc.loadersimportLocalDocLoaderfromsrc.cleanerimportclean_documentsif__name____main__:# 请在此处替换为你本地的真实文件路径test_files[./data/test_doc.md,./data/manual.pdf]all_docs[]forpathintest_files:try:docsLocalDocLoader.load(path)all_docs.extend(docs)exceptExceptionase:print(f加载失败 [{path}]:{e})# 执行清洗final_docsclean_documents(all_docs)# 打印第一个有效片段验证效果iffinal_docs:print(\n--- 清洗后的首个文档片段预览 ---)print(final_docs[0].page_content[:300])print(f\n元数据保留完整:{final_docs[0].metadata})运行python main.py如果你能看到干净的文本输出以及包含source、page等信息的 metadata恭喜你你的本地知识库数据基石已经牢牢打下。预期运行结果当你运行这段代码时控制台会输出类似以下内容取决于你的文档内容✅ 正在加载: test_doc.md ✅ 正在加载: manual.pdf 清洗完成: 原始 4 个片段 - 有效 3 个片段 --- 清洗后的首个文档片段预览 --- 一、 榜单说话56.6分背后的含金量 在Artificial Analysis最新公布的全球大模型综合榜单中Qwen3.7-Max以56.6分的成绩位列全球第五、国产第一。 这个分数意味着什么它标志着国产模型已经跨越了“可用”到“好用”的鸿沟正式进入全球顶级模型的“俱乐部”。不同于以往部分榜单的自说自话Artificial Analysis以其严苛的工程化评测标准著称。Qwen3.7-Max能在该榜单中脱颖而出说明其在实际应用场景中的综合能力而非单纯的刷题能力得到了国际认可。 更令技术圈振奋的是其在垂直领域的突破 Terminal Bench 2.0-Terminus编程智 元数据保留完整: {source: ./data/test_doc.md} 进程已结束退出代码为 0系列预告这是《从零构建个人知识库》系列的第一篇下一篇我将详细讲解如何用新版 LangChain LCEL 语法实现语义切片并在纯 CPU 环境下完成极速向量化。点击关注更新时第一时间收到通知带你一步步把这个项目真正跑在你的电脑上**关注后续系列文章更新**
