企业官网建设流程全解析

做RAG项目最让人头疼的不是写检索代码，而是数据根本“进不来”或者“进来就废了”。前两篇聊了文档解析和清洗，这篇聚焦表格与数据库导入：CSV、Excel 以及通过 LlamaHub 直连数据库的完整实战。如果你正在用 LlamaIndex 搭知识库，卡在“数据导入结构不对、检索结果乱码、整表被切成碎片”这些问题上，这篇应该能直接帮你省下两三天排查时间。

1. 表格类数据为什么是 RAG 导入的“重灾区”

1.1 文档切分时表格被“撕碎”是常态

很多人在导入 PDF、Word 时发现表格数据丢失或错乱，第一反应是换解析库，其实更核心的问题在于 RAG 管线的切分策略。经典的文档切分是按字符数或 Token 数硬切，表格被当作普通文本处理，行与列之间的结构关系在切分后荡然无存。比如一个 80 行的 CSV 被切成多个 chunk，某个 chunk 里只剩“销售区域、华东”这样的零散片段，检索时根本拼不出完整语义。

我之前处理一个销售报表项目时，用默认的 splitter 切分 2000 行 Excel 数据，结果知识库的回答里频繁出现“华南区 2024 年 3 月业绩为 1.2 万”这种把列错位拼出来的胡话。后来才意识到：结构化数据需要的是按行、按记录、按有意义的业务单元来组织 chunk，而不是按字符数。

这里要顺带回应一个被问过很多次的问题——RAG 知识库能存储图片吗？严格说，传统向量库存的是文本块的 embedding，图片本身不直接进库。表格截图、扫描件里的表格，只有先走 OCR 提取文字，或走多模态模型转成描述文本，才能进入 RAG 流程。本文讨论的 CSV、Excel、数据库连接都属于文本与结构化数据的范畴，这类数据才是 RAG 最擅长处理的。

1.2 向量检索与精确查询的本质错位

表格数据的核心价值在于精确性和关联性：某一行是一个完整记录，某一列是一个统一维度。但向量检索本质上是一种模糊匹配，它擅长的是“语义相近”，不是“条件精确”。问“2023 年华东区销售额超过 100 万的客户有哪些”，如果把整个表都塞进向量库，检索效果往往不好，因为答案需要的是字段级过滤和计算，不是语义相似度。

这就是为什么圈子里一直在讨论“KG 知识库、RAG 知识库和结构知识库区分以及应用场景”——结构化知识库适合精确查询，RAG 适合语义召回，知识图谱适合关系推理。在实际项目中，表格数据导入 RAG 并不是要把数据库的功能重复实现一遍，而是要让语义检索能够“找到”这些结构化数据，再用工具链或查询接口去获取精确结果。

所以这篇的定位不是“把 CSV 变成向量就完事”，而是基于 LlamaIndex 的导入与检索机制，给出一个可落地的分层方案：常规问答走向量召回，精确计算走 SQL 查询，混合架构才是处理表格数据的正解。

1.3 CSV、Excel、数据库三者的导入定位差异

先明确一个概念：很多人把 CSV 和 Excel 当成同一种数据格式，实际上在 RAG 导入管线上，它们的处理难度完全不是一个级别。

CSV 是标准的、干净的表格交换格式，几乎所有领域都有它的身影。做 GIS 的朋友用 arcgis 导入 csv 数据，做体育数据分析的用 football-data.co.uk 的 csv，做报表的从业务系统导出 csv，它最大的好处是没有 Excel 那些隐藏格式和宏的干扰，是表格数据导入 RAG 的最佳起点。

Excel 则麻烦不少。真实业务场景里的 Excel 往往带着合并单元格、汇总行、图片水印、公式、多级表头等各种“人看的格式”，这些格式对机器学习模型和分词器都不友好。所以 Excel 导入 RAG 之前，先要“整容”。

数据库连库则要考虑的不是格式问题，而是规模问题：一个生产库的表可能有上百万行，全量导成向量不现实，必须靠 SQL 先做筛选和聚合，再导入。

2. CSV 导入：最标准的起点，先把数据“喂”对

2.1 为什么优先用 CSV 而不是 XLSX

我的习惯是：凡是能从业务系统导出 CSV 的场景，绝不直接处理 XLSX。原因有三点。

第一，编码可控。CSV 文件可以选择 UTF-8、GBK 等编码保存，而 XLSX 是二进制压缩格式，编码由 Excel 内部处理，解析时经常出现“读出来是一堆乱码”的情况，尤其是中文场景。

第二，体积与速度。相同的数据量，CSV 比 XLSX 小很多，读取和逐行处理的性能差距明显。我在测试机上调一个 50MB 的 CSV，Pandas 读进来不到三秒；而同样内容的 XLSX 因为要解压 XML 结构，耗时接近两倍。

第三，格式干扰为零。CSV 没有样式、没有公式、没有合并单元格，这反而让数据更“干净”。很多业务系统导出的 Excel，表头上方有标题行、表尾有汇总行，直接导入 RAG 反而会把标题和汇总当成数据，污染索引。CSV 一般只保留纯数据行，省去预处理这一步。

顺便说一句，CSV 在 GIS 等专业软件里的通用性也验证了它的可靠性。arcgis 导入 csv 数据时要求列名清晰、字段类型明确，这和 RAG 导入对数据的要求完全一致——结构化数据导入的本质都是“先让机器看懂表结构”。

2.2 LlamaIndex 的 CSVLoader 参数实战

LlamaIndex 里读取 CSV 最常用的是 CSVReader，它本质上是先读入 Pandas DataFrame，再把每一行转换成一个 Document 节点。核心代码可以这样写：

from llama_index.core import SimpleDirectoryReader from llama_index.readers.file import CSVReader from llama_index.core.node_parser import SimpleNodeParser from llama_index.core.schema import TextNode loader = CSVReader() documents = loader.load_data(file=open("sales_2024.csv", "r", encoding="utf-8")) # 建议：不要直接用默认的 splitter，而是按行构造节点 node_parser = SimpleNodeParser.from_defaults(chunk_size=1024, chunk_overlap=0) nodes = [] for doc in documents: text = doc.get_content() # 每一行作为一条独立记录，保留足够上下文 nodes.append(TextNode(text=text, metadata={"source": "sales_2024.csv"}))

这里有个关键点：CSVReader 默认会把整个文件读成一个 Document，如果文件很大，直接丢给 splitter 又会走回“按字符硬切”的老路。我的做法是先用 Pandas 读取并做简单探查，再逐行构造 TextNode，这样每一行记录在向量化之后语义是完整的。配合 metadata 保存文件名或主键，后续检索时可以利用 metadata filter 缩小范围。

在读入前先做数据探查，代码很简单：

import pandas as pd df = pd.read_csv("sales_2024.csv", encoding="utf-8") print(df.shape) print(df.dtypes) print(df.head(3))

这一步很重要，千万不要跳过。CSV 导入 RAG 出错，十次里有八次是源数据本身有问题：列数不一致、空行残留、日期格式混乱、字符串列里有特殊符号。先用 Pandas 看一眼，能避免后面所有环节的连锁报错。

2.3 三个 CSV 导入必须避开的坑

坑一：中文乱码。业务系统导出的 CSV 经常是 GBK 编码，Python 直接按 UTF-8 读会报错或乱码。处理方式是用encoding="gbk"或更稳妥的encoding="gb18030"。如果文件里混合了不同编码的字段，可以加上errors="replace"避免中断，但要注意替换特殊字符后需要额外清洗。

坑二：分隔符歧义。字段值里含有逗号时，CSV 会通过引号包裹字段，但某些老系统导出的文件不规范，引号残缺或缺失，Pandas 读进来后列数错位。这种情况我建议先检查原始文件的字节内容，确认是不是标准 CSV，实在不行就手动指定delimiter参数，或者在预处理阶段用csv模块逐行解析。

坑三：大文件内存占用。动辄几百 MB 的 CSV，用pd.read_csv()一次性读入非常吃内存，容易导致机器卡死或进程被杀。可以用chunksize分块读取，边读边清洗，边构造节点：

for chunk in pd.read_csv("large_file.csv", chunksize=5000): for _, row in chunk.iterrows(): # 逐行构造成节点 pass

也可以配合python 查找 excel 中字符串的思路，先按业务关键词筛选子集再导入，这样既控制了 token 消耗，也减少噪声数据对检索的干扰。

3. Excel 导入：别把它当 CSV 用，先“整容”

3.1 从 Excel 到 LlamaIndex 的解析链路

Excel 文件（.xlsx）本质上是多个 XML 文件的压缩包，里面包含工作簿结构、单元格样式、共享字符串表等大量元信息。直接用文本解析器读入会产生很多非业务内容，所以标准的操作是用 Pandas 的read_excel读取，再转成 LlamaIndex 可用的节点。

LlamaIndex 提供了 PandasExcelReader，它会把每个 Sheet 读成 DataFrame，然后你可以选择按行还是按列转成 Document：

from llama_index.readers.file import PandasExcelReader loader = PandasExcelReader(pandas_config={"header": 0}) documents = loader.load_data(file=open("report.xlsx", "rb")) for doc in documents: print(doc.metadata) # 查看 sheet 信息

但这里有个大坑：如果一个 Excel 有多个 Sheet，PandasExcelReader 默认会全部读出来，一个 Sheet 变成一个 Document。直接把这个大文本丢进向量库，检索时很难定位到具体 Sheet 里的某一行，反而会因为文档过长而稀释语义。我一般先看df.shape，确认每个 Sheet 的数据量，再按粒度决定怎么拆。

3.2 三步“整容”：表头、空值、公式全部处理干净

Excel 导入之前，强烈建议先做这三步清洗，否则后面检索结果会让你怀疑人生。

第一步，表头规范化。业务 Excel 的表头经常是“销售区域（华东/华南）”“2024年Q1”这种带括号、带单位、甚至合并单元格的写法。Pandas 读进来后把这些列名直接清洗成无空格、无特殊字符的形式，比如销售区域_华东、2024_Q1。不要小看这一步，列名会成为元数据的一部分，脏列名会直接影响检索的召回质量。

第二步，缺失值填充。合并单元格在 Pandas 里会表现为部分单元格为空，比如“华东区”合并了三行，后两行的区域字段是 NaN。如果不处理，每一行记录的上下文就是不完整的。我习惯用ffill()向前填充，把合并单元格的值补到每一行。

第三步，去公式留值。Excel 里的公式列（比如 SUMIFS 算出来的合计值）在数据导入时必须先转成静态值，否则解析出来是一堆函数表达式，不是计算结果。用 Pandas 读取时其实已经拿到了计算后的值，这一层相对安全；但如果是通过 openpyxl 直接读原始单元格，就要注意区分 cell.value 是公式还是结果。最简单的方式是打开 Excel 文件，先另存为“值”格式，再交给 Python 处理。

顺手说两个真实业务里遇到的 Excel 异常。一个是“excel 加载项被禁用”导致文件里明明有数据，程序读出来却是空的，原因就是加载项劫持了文件打开过程，写入了一定数量的额外元数据。另一个是“excel 无法打开文件，因为文件格式或文件扩展名无效”，这类文件往往是从网页端下载的伪 xlsx，本质是 HTML 表格或 XML 格式，需要先另存为真正的 xlsx 再导入。遇到这种情况，不要直接丢给解析器，先用file命令确认文件真实格式。

3.3 复杂版式 Excel 的处理经验

真实业务里，Excel 往往是给人看的大宽表，比如经营分析表，从第一行到第几百行是明细，最后几行是合计；或者像用 eplan 部件汇总表导出 excel 那样，带大量格式和重复表头，直接读取的结果就是“前五行是标题，中间是数据，最后是汇总”，全搅在一起。

我的处理经验是：先人工判断这个文件的结构，写一段预处理脚本把数据区域单独提取出来。通常的做法是设定一个“数据开始行”，比如取第 4 行开始直到某标记列出现“合计”为止。代码示例如下：

import pandas as pd df_excel = pd.read_excel("经营分析.xlsx", sheet_name="明细", header=2) # 去掉全空行 df_excel = df_excel.dropna(how="all") # 去掉汇总行 df_excel = df_excel[~df_excel["区域"].astype(str).str.contains("合计|总计", na=False)] print(df_excel.shape)

这里的实质是把“人看的表格”改造成“机器能理解的数据表”。注意不要直接修改原文件，而是在代码中做视图级清洗，避免把业务原始资料破坏掉。清洗完成后，再按行构造成节点，导入链路就和 CSV 基本一致了。

还有一个与 Excel 相关的小问题“excel 同一列中统计含关键词对应数据求和”，这实际上就是业务需求里的一个典型查询：在导入 RAG 之后，用户会通过自然语言问“某某关键词对应列的总和”。如果你在导入时保留好了 excel 表格生成的元数据，包括列出了列名，后面这类聚合类问题就可以直接转成 Pandas 或 SQL 查询来完成，而不是靠向量检索强行“算”出来。这也是我在第 1 部分讲的分层策略的一个典型体现。

4. LlamaHub 连数据库：让 RAG 直接读“活数据”

4.1 LlamaHub 里值得常备的几个数据库工具

LlamaHub 是 LlamaIndex 生态的加载器仓库，里面有不少数据库相关的 Reader。最常用的是 SQLDatabaseReader 或 DatabaseReader，它们可以借助 SQLAlchemy 连接多种数据库。使用方式比较简单：

from llama_index.readers.database import DatabaseReader reader = DatabaseReader( scheme="postgresql", host="localhost", port="5432", user="postgres", password="****", dbname="sales_db", ) # 通过 SQL 查询取数 documents = reader.load_data(query="SELECT * FROM sales_2024 WHERE region='华东' LIMIT 500")

这一小段代码的意义很大：连库读数的核心不是“连上”，而是“你让它读什么”。很多入门教程教你无脑读整表，但从实际项目看，整表读入几乎必定导致两个问题：token 浪费和数据噪声。正确的连库方式是先通过 SQL 把业务视图变成可用的数据子集，再做向量化。

还有专门针对单库的 reader，比如 ClickhouseReader、MySQLReader 等，原理类似。在企业场景里，数据最终的归宿通常是数据库而不是 Excel，这也是为什么很多团队在做 RAG 之前会先把分散的 Excel 数据清洗后导入数据库——相当于用数据库做一层“数据中台”。

我见过不少团队纠结“excel 导入数据库”用什么工具，或者“开源 excel 数据库软件”选哪个。其实从 RAG 的角度来看，这一步的实质是把格式多样的 Excel 统一成可以用 SQL 查询的结构化数据。推荐路径是：Excel → 清洗 → SQLite/PostgreSQL → LlamaHub 连库。SQLite 的好处是零配置文件，适合原型验证；PostgreSQL 适合生产环境，支持全文检索和向量扩展，后面如果要演进到混合检索也更方便。

4.2 连接与查询参数的关键细节

用 DatabaseReader 连库，最容易踩的坑是连接串格式。以 PostgreSQL 为例，正确的方式需要保证 SQLAlchemy 的 URL 拼接正确。常见报错集中在“密码含特殊字符”“端口没放通”“数据库驱动没装”这几类。

还有一点值得注意：load_data(query=...)接收的 SQL 是直接执行的，所以你在构造节点时最好为每一行附加元数据，比如表名和主键。这样后期做 Recursive Retrieval 或 Metadata Filter 时才能精确回溯。

同时，导入之前先用 SQL 探查一下数据规模，是非常值得养成的习惯：

SELECT count(*) FROM table_name; SELECT * FROM table_name LIMIT 5;

这两条 SQL 我几乎每次都先执行，因为生产库的数据量远超预期，一个不留神就可能把整个表的向量化任务变成一个耗时数小时且费用高昂的离线任务。

4.3 全表导入、SQL 视图导入、动态查询：三种策略怎么选

数据库类数据接入 RAG，圈内常用的策略有三条，适用场景完全不同。

策略一：全表导入。适合小型维度表（几百到几千行），比如产品目录、组织结构、地区代码表。这种表数据量小，语义固定，全量向量化后做语义匹配完全没有压力。注意点：如果字段太多，每行转为文本后长度会很长，需要控制字段选择，只保留业务含义强的列。

策略二：SQL 视图导入。适合事实表或大表。比如订单明细动辄几十万行，全量导入不现实，但可以让业务方基于统计口径先聚合落成视图，再在导入时执行SELECT * FROM view_name LIMIT 1000。效果就是：向量库里查到的不是每一笔订单，而是某个业务视图的摘要描述，直接缓解 token 和检索精度压力。

策略三：动态查询接口。适合问答 Agent 场景。这里不预先导入数据，而是给 Agent 挂一个可以执行 SQL 的工具。用户问“2024 年华东区前三名的客户是谁”，Agent 将自然语言翻译成 SQL 去数据库执行，返回结果直接作为答案。这个方案不经过向量检索，精确实时，但要保证数据库口径正确、Agent 的 NL2SQL 能力可靠。

不少人在讨论“rag 智能体”时，把动态查询与 RAG 对立起来，其实两者合作更好：普通问题走向量检索从文档里找答案，涉及精确数字就调 SQL 工具查询，这正是处理表格类数据最舒服的方式。生产环境落地时，三种策略往往混合使用，先用策略二解决大头数据引导，再用策略三应对实时查询需求。

5. 结构化数据导入的常见问题速查

最后整理一份实战中反复出现的问题列表，基本覆盖了表格和数据库导入管线里能遇到的典型故障。这些内容来自我自己的排查记录和群里高频求助帖，直接按表检索即可。

出现问题时，先定位是“格式层”“读取层”还是“切分层”的锅，能省下大量时间。另一个小建议是按批导入时，先在代码里加上“导入前校验行数变化”的断言，比如：

assert df.shape[0] > 0, "导入结果为空，请检查源文件"

这条断言在长期运维中非常救急，尤其是定时任务自动跑导入时，数据源变更导致源文件为空的情况很常见，有断言才能及时报警。

我在实际项目中还发现一个容易被忽略的小细节：很多 Excel 文件里的“打印区域”或“冻结窗口”设置不影响读取，但包含图片的单元格（比如用 easypoi 导出 excel 模板带图片）会在解析时产生非文本对象。如果用 OCR 工具强行识别图片文字，反而引入了大量无意义内容。我的建议是：业务表格里如果需要保留图片信息，就不要走纯文本 RAG，要么把图片另存为附件由人查，要么用多模态模型单独建索引，不要混在一个管线里。

表格与数据库导入这块，踩过几次坑之后我的体会是：最省事的方案不是找到一个万能解析器，而是建立一条规范的预处理链路——先用 Pandas 打底清洗，再按记录构造节点，最后统一加载到索引。如果能坚持这个流程，CSV、Excel、数据库三类数据源可以共用同一套导入逻辑，后续维护也不会像缝补丁一样越改越乱。另外，第一次接入新数据源时，强烈建议先取 5 行数据跑通全链路，确认 metadata、分块、检索结果都合理，再全量导入。这个习惯连续救了我好几次，希望你也能用上。