RAG批量文档导入脚本，文件夹递归解析全部文档入库
RAG 系统要正常工作，前提是知识库里已经放入了可检索的文档。
手动一个个导入显然不现实，尤其是面对几百个文件且分布在多层子目录时。
本文给出一个可落地的批量文档导入脚本方案，用递归方式遍历文件夹，自动解析文本类文档并写入向量数据库。
零基础用户也能照着配置运行，最终实现全量入库。
先想清楚：文档从哪里来，入库到哪里去
动手写脚本前，先确认两件事：
- 源目录结构：文档是否分散在多层子目录？是否包含隐藏文件夹或临时文件？
- 入库目标：你用的向量数据库是 Chroma、Milvus 还是自定义 API？本文示例以兼容 OpenAI 接口的 Embedding 服务和 Chroma 为例，实际替换成你手头的服务即可。
建议提前把需要导入的文档统一整理到一个主目录，例如 /data/docs。
脚本会递归扫描该目录下所有子目录。
编写递归扫描与解析脚本
关键逻辑分三步：递归找文件、读取内容、向量化入库。
下面是一份可直接改用的 Python 脚本骨架：
import os
import glob
from pathlib import Path
# 1. 定义支持的文件后缀
SUPPORTED_EXTS = {".txt", ".md", ".markdown"}
def list_all_docs(root_dir):
"""递归获取所有支持的文件路径"""
doc_paths = []
for dirpath, dirnames, filenames in os.walk(root_dir):
# 跳过隐藏文件夹，避免误读
dirnames[:] = [d for d in dirnames if not d.startswith(".")]
for name in filenames:
if Path(name).suffix.lower() in SUPPORTED_EXTS:
doc_paths.append(os.path.join(dirpath, name))
return doc_paths
# 2. 读取文件内容
def read_doc(file_path):
"""优先用 utf-8，失败时尝试 gbk"""
try:
with open(file_path, "r", encoding="utf-8") as f:
return f.read()
except UnicodeDecodeError:
with open(file_path, "r", encoding="gbk") as f:
return f.read()
if __name__ == "__main__":
docs = list_all_docs("/data/docs")
print(f"共发现 {len(docs)} 个文档")
# 这里继续调用你的 embedding 和向量库写入函数实际入库时，你需要把 content 传给 embedding 接口，再将向量和元数据写入向量库。
不同数据库的写法差异较大，建议先按官方文档写好单条写入函数，再在循环里调用。
设置合理的切分与去重规则
直接整篇文档做向量化，长文档容易被截断，短文档又可能丢失上下文。
建议按固定 chunk 大小切分，例如每 500 个字一段，重叠 50 字。
切分后每个 chunk 单独入库。
去重也不能忽略。
常见做法是计算文件 MD5，记录在元数据中。
重复导入时先检查 MD5，已存在则跳过。
如果你的向量库不支持查重，可以在脚本里维护一个 set 记录已处理文件。
运行脚本并验证入库结果
脚本写完先跑一个小目录测试，不要直接全量。
确认无误后，再指向完整目录。
运行方式：
python import_docs.py运行结束后，检查三件事：
- 控制台是否输出了所有文件路径和处理结果；
- 向量库中的集合（collection）数量是否与文件数（或 chunk 数）吻合；
- 随机挑一个文档，在 RAG 检索接口里搜一句原文，能否召回。
只有搜索能命中，才说明文档真正铺进了知识库，RAG 回答时才有可能参考到这些内容。
避坑：这几种情况最容易白跑一趟
- 编码问题：有的文档是 GBK 编码，直接按 UTF-8 读取会报错。上面代码用了 try-except 降级处理，你也可以在读取前先探测编码。
- 隐藏目录干扰：
node_modules、.git这类目录如果没过滤，会把大量无关文件扫进来。os.walk时直接修改dirnames[:]可以过滤。 - 重复导入导致内容重复：没有去重时，同一份文档重复运行脚本会生成多份向量，检索结果混乱。务必加上 MD5 判断。
- 大文件内存溢出：几百 MB 的日志文件不适合一次性读入。要么限制单文件大小，要么改用流式读取，只保留前 N 行。
- 路径中的特殊字符：Windows 下路径包含中文或空格时，注意用
os.path拼接，不要手动打反斜杠。
如果你在导入过程中遇到其他报错，建议先在小目录里复现，再把异常堆栈贴给 AI 或查询向量数据库官方文档。
如果你正在处理 RAG 批量文档导入脚本，文件夹递归解析全部文档入库，建议先按本文步骤完整执行，再根据自己的环境做微调；
遇到异常时优先回看避坑和高频问题部分。
掌握这套流程后，后续维护知识库就只是定期跑一次脚本的事。
