表格数据进 RAG是很多人做到中期才意识到的问题。前面几篇咱们聊了文本类数据的切块、清洗和解析但那套思路遇到 CSV、Excel 甚至数据库时会明显不够用。原因很简单文本是线性的而表格是二维的——你如果把一张报价表整包丢给加载器检索时会出现“客户名字和金额串在一起”“列名跑丢”“同一行的语义被切块器拦腰截断”之类的怪问题。这篇文章我就聚焦表格与数据库导入用 LlamaIndex 和 LlamaHub 的读取器把 CSV、Excel 和 PostgreSQL 连库这三条路线的实战配置、代码和踩坑记录完整过一遍。如果你正在做一个包含产品目录、销售明细、配置清单这类结构化数据的 RAG 项目这篇应该能帮你省掉不少试错时间。1. 表格数据进 RAG 的第一个关卡把“二维表”翻译成“一句话”我最早做 RAG 时也犯过懒觉得 CSV 不就是文本吗直接读进去切块不就完了。结果第一次检索就翻车用户问“上个月金额最高的三张订单”返回的片段里订单号和金额根本没出现在同一个节点里。问题不在于切块参数而在于我从来没想过“二维表”和“文本”在信息组织方式上根本是两回事。1.1 为什么不能把 CSV 当成纯文本整包丢进去CSV 和 Word、PDF 最本质的区别是文本的信息靠句子顺序和语义连接而表格的信息靠行、列、表头之间的关系。一张四列的销售表订单号客户金额日期OR9087华东备件商152002025-03-12如果直接把整个文件读成一个长字符串再按固定字数切块切块器根本不知道“OR9087”和“华东备件商”是一对“15200”和这个订单绑定。它只会机械地在某个位置切开运气不好就把“金额”切到上一个客户名下语义错得离谱。还有个隐藏问题表格里的“单位”和“列名”是语义的一部分。金额到底是元还是万元日期到底是下单日还是发货日文本文件里这些信息往往靠上下文交代但表格里全靠表头。你把表头丢掉只留一堆裸数字检索模型再强也猜不出来。我的结论是表格进 RAG 之前必须先做一次“结构化到线性”的转换。你可以理解为把二维表翻译成一段一段的、每一行都自包含的完整句子。比如上面那条记录可以翻译成订单 OR9087 的客户是华东备件商金额为 15200 元日期为 2025-03-12。这样再去切块和向量化每一段语义都是闭合的检索时召回哪一段都不缺上下文。1.2 三种常见的表格→文档转换思路你要先选一种不同场景有不同的“翻译”策略我总结了三种分别适用于不同的查询需求。方案 A整表作为一个文档把整张表转成一个超长文本或者用 Markdown 表格语法保留结构然后交给普通切块器。优点是实现最简单适合需要“全局对比”的查询比如“所有商品的均价是多少”。缺点是表格一长切块器很容易从中间切开破坏行结构而且整表向量化之后单行细节的召回率会很低因为相似度被全局平均了。方案 B逐行生成独立文档我最推荐用脚本遍历每一行把列名和单元格值拼成自然语言句子每行生成一个节点。这样查询“某客户买过什么”时命中的是精准的一行上下文完整还能把行号、主键放进元数据。缺点是如果单行字段特别长比如“备注”列有 500 字这个节点会很大需要再做一次内部切块。方案 C转成 JSON 或 KV 结构再自定义切分把每行转成 JSON按 key-value 粒度组织文本同时把结构化的字段映射到节点元数据里。这是最精确的方案适合高精度要求的业务系统比如财务数据、配置参数。但代码量最大而且需要你对后续检索逻辑想得很清楚你到底希望用向量检索还是用 SQL 过滤还是两者结合。我的建议是第一版先用方案 B 跑通简单、可控后面再根据检索效果决定要不要升级成 C。方案 A 除非表格很小且查询都是粗粒度否则不要用。2. LlamaIndex 原生加载器盘点CSV、Excel 与 Pandas 路线的取舍LlamaHub 上光是名字里带 CSV 的 Reader 就有好几个我第一次看到时也懵过SimpleCSVReader、PandasCSVReader、CSVReader到底用哪个后来我把它们的源码和输出效果都跑了一遍才算把这条线彻底理清楚。这个部分的价值就是把我的对比结果直接给你。2.1 CSV 路线LlamaHub 上那些名字很像的 Reader 到底怎么选如果你用的是 LlamaIndex最省事的入口是SimpleDirectoryReader。它内部会根据文件后缀自动选择解析器CSV 会被SimpleCSVReader处理。这个 Reader 的行为很有意思它不是把整个 CSV 作为一个文档而是逐行读取把每一行拼成列名: 值形式的文本每行生成一个 Document。这正是我们在第一节说的“方案 B”所以小文件可以直接用from llama_index.core import SimpleDirectoryReader documents SimpleDirectoryReader( input_dir./data/csv, file_extractorNone ).load_data() print(len(documents)) # 输出行数而不是文件数注意一个参数如果 CSV 文件列数很多逐行文档的文本可能把不需要的列也拼进去。SimpleCSVReader默认会读取全部列。如果只想保留关键列就得绕到PandasCSVReader去先做列筛选再转成文档。PandasCSVReader在llama_index的实验性模块里它让你把pd.read_csv的各种参数直接传进去然后拿到 DataFrame再自己控制如何生成文本节点。这是我现在最常用的路线因为read_csv的类型控制、缺省值处理都保留了import pandas as pd from llama_index.core.schema import TextNode df pd.read_csv(./product_price.csv, dtype{sku: str}, encodingutf-8-sig) nodes [] for _, row in df.iterrows(): row_text f商品编号 {row[sku]} 的名称是 {row[name]}价格为 {row[price]} 元库存 {row[stock]} 件。 node TextNode(textrow_text, metadata{table: product_price, row_id: row[sku]}) nodes.append(node)为什么我不直接用SimpleCSVReader因为现实中的 CSV 太脏了ID 列会被 pandas 读成 int前导零消失金额列可能带千分位逗号空值会变成 NaN 字符串。SimpleCSVReader对这些完全没辙。而pd.read_csv可以通过dtype、converters、na_values把数据先洗干净再接 LlamaIndex属于“数据处理在前、文档生成在后”的思路更符合正规项目的流程。2.2 Excel 路线多 Sheet、公式残留和读取失败的应对Excel 比 CSV 复杂的地方在于它天生是“多表”的。一个工作簿里可能有Sheet1、Sheet2还有汇总表、说明页。直接把整个文件交给读取器这些 Sheet 会全部拼在一起切块时连哪一页是哪张表都分不清。我的处理方式是先用pd.ExcelFile把 Sheet 名字全部读出来再逐 Sheet 处理每个 Sheet 生成一组节点并把sheet_name写进节点元数据import pandas as pd from llama_index.core.schema import TextNode xl pd.ExcelFile(./sales_report.xlsx) for sheet_name in xl.sheet_names: df xl.parse(sheet_name, dtypestr, keep_default_naFalse) for idx, row in df.iterrows(): row_text f【{sheet_name}】 .join( f{col}: {row[col]} for col in df.columns if row[col] ! ) node TextNode( textrow_text, metadata{sheet: sheet_name, excel_file: sales_report.xlsx, row: idx} ) nodes.append(node)这里我用dtypestr是关键。Excel 里的订单号、身份证号、SKU 码经常被 Excel 显示成科学计数法比如1.23457E17等 pandas 读进来早就精度尽失。先全按字符串读后续再按列做类型转换是最稳妥的。另外keep_default_naFalse是防止空单元格变成 NaN免得生成“列: nan”这种垃圾节点。公式残留是另一个大坑。用 pandas 读 xlsx默认读到的是公式字符串比如SUM(B2:B10)而不是计算结果。如果这个 Excel 是别人给的、还没来得及打开重算你拿到的可能是一堆公式。解决办法有两个要么在生成前用 Excel 或 LibreOffice 把文件打开另存一遍让公式缓存生效要么在 pandas 侧用openpyxl参数指定data_onlyTruedf pd.read_excel(./calc.xlsx, sheet_name汇总, engineopenpyxl, dtypestr, data_onlyTrue)别小看这条很多“导入明明成功检索结果却是公式原文”的诡异 bug 都源于此。3. LlamaHub 连数据库实战PostgreSQL 落地配置与权限避坑如果说 CSV 和 Excel 是“文件搬运”那连数据库就是真正把 RAG 和业务系统接在一起。数据库的优势是天然有主键、有更新、有权限控制但也有新的麻烦你不能把整张表全量读进向量库就完事得考虑增量同步、敏感字段、查询性能。这一节我以 PostgreSQL 为例说一下 LlamaHub 上 DatabaseReader 的完整落地配置。3.1 连库前你必须想清楚的几件事同步粒度、主键与增量更新很多教程直接给你一段连接数据库、读取全表的代码好像执行完就万事大吉。实际项目里你连库之前至少要回答三个问题。同步粒度是行级文档还是查询后的汇总文档比如订单明细表 10 万行每行都生成一个文本节点向量库压力很大而且大部分行只是历史数据很少被查询。更合理的做法是先想清业务需求是要回答“某个客户的订单”还是回答“这个月销售额是多少”如果是后者你根本不需要向量化每一行而是该通过数据库聚合查询把结果直接给出来。RAG 不是只能靠向量检索数据库本身也可以作为工具调用。主键与去重增量更新时怎么判断哪些行是新的如果只是从头全量删了重新建索引那没问题但很浪费。更好的做法是保留源表主键比如order_id写入节点元数据然后用主键去重或做 upsert。LlamaIndex 的索引更新接口支持按 doc_id 覆盖doc_id就可以直接用order_id。增量更新的策略我经常用“时间窗口 主键去重”的双保险。同步脚本里先查updated_at last_sync_time再把这批行的主键和已有节点主键做一次比对只插入新增。这个方法能避免凌晨跑批任务时因为主键冲突导致的偶发失败。还有一个容易被忽视的权限问题连接数据库的账号尽量用只读角色不要用超级用户。RAG 同步是读多写少的场景给只读权限足够而且能防止误操作。如果你们用的是 PostgreSQL可以这样创建一个最小权限账号CREATE ROLE rag_reader WITH LOGIN PASSWORD strong_password; GRANT CONNECT ON DATABASE sales_db TO rag_reader; GRANT SELECT ON ALL TABLES IN SCHEMA public TO rag_reader;3.2 DatabaseReader 的完整接入步骤和一次真实查询演练LlamaHub 上有个DatabaseReader底层基于 SQLAlchemy你只需要给连接字符串和 SQL 查询语句。我通常这样接from sqlalchemy import create_engine from llama_hub.database import DatabaseReader engine create_engine( postgresqlpsycopg2://rag_reader:strong_passwordlocalhost:5432/sales_db ) reader DatabaseReader(engineengine) query SELECT order_id, customer_name, product_name, amount, status FROM order_detail WHERE created_at NOW() - INTERVAL 30 days ORDER BY created_at documents reader.load_data(queryquery)这条 SQL 查询的结果每一行都会被转成一个 Document。但注意DatabaseReader默认生成的文本格式是列名: 值串在一起比如order_id: OR9087, customer_name: 华东备件商, ...。这种格式对向量检索来说是够用的但如果你希望生成更自然的句子就得自己遍历查询结果构造TextNode而不要偷懒直接依赖 Reader 的默认输出。我实际项目里会写得再细一点比如把表和字段语义整合进文本from sqlalchemy import text from llama_index.core.schema import TextNode with engine.connect() as conn: result conn.execute(text(query)) for row in result.mappings(): row_text ( f订单 {row[order_id]} 的客户是 {row[customer_name]} f购买了 {row[product_name]}金额 {row[amount]} 元 f状态为 {row[status]}。 ) node TextNode( textrow_text, metadata{ source: postgres, table: order_detail, order_id: row[order_id], }, ) nodes.append(node)这种做法的好处是检索时命中的是一句人话而不是一串key: value的机器文本。查询效果上差别非常大你可以两个版本都跑一遍召回对比自然会有体会。还有个实战建议如果库表较多不要每次都查原始业务表。可以先把要喂给 RAG 的字段做成一个宽视图比如v_rag_orders里面把客户名称、商品名称、金额、状态这些可能被问到的字段都铺开再让DatabaseReader去查视图。这样既不用改业务表结构也能保证每次同步拿到的数据口径一致。4. 让表格检索真正好用的三个关键动作行级元数据、切块长度与查询改写连库跑通只是第一步。我见过不少人表格导进去了索引也建了但检索结果就是不对。问题常常不在加载器而在“检索链路”上少了几个关键动作。这里我讲三个我反复验证过有效的动作缺一个都可能翻车。4.1 给每一行都盖上“章”把表名、列名、单位写进元数据向量检索的本质是语义相似度匹配它不看数据库的表结构。但很多查询是有过滤条件的比如用户问“华东备件商 3 月份退货了吗”如果节点里没有“客户名”的独立字段只靠一段拼接文本检索器只能碰运气。解决方案是把结构化的关键字段提取到节点元数据里然后用 LlamaIndex 的元数据过滤器做精确匹配。我通常给每个从表格生成的行节点打上这些“章”数据源类型、表名、主键、关键业务字段还可以加上单位说明。from llama_index.core.schema import TextNode from llama_index.core.indices.vector_store import VectorStoreIndex node TextNode( text订单 OR9087 的客户是华东备件商金额为 15200 元日期为 2025-03-12。, metadata{ source: order_detail.xlsx, table: orders, order_id: OR9087, customer_name: 华东备件商, amount: 15200, date: 2025-03-12, }, ) index VectorStoreIndex([node]) query_engine index.as_query_engine( filtersMetadataFilters( filters[ExactMatchFilter(keycustomer_name, value华东备件商)] ) )为什么这很重要因为 RAG 里常见的错误回忆不是向量相似度算错了而是没有字段边界。把“customer_name”单独拎出来做过滤用户约束客户时准确率会显著提高。另一个附带好处是答案可以被追溯——你知道这条信息来自哪张表、哪个主键这在业务系统里几乎是刚需。4.2 表格片段太长/太短的连锁反应以及我的经验参数表格转文档后节点的文本长度直接决定召回效果。太短比如只把两个单元格拼成一句话语义不足相似度匹配会漂移太长比如把整张 Excel 的 Sheet 塞进一个节点切块器会在任意位置切断破坏行内语义平衡。我测试下来比较稳的经验是以行为单位的节点如果单行文本超过 300~400 token就应该拆成子字段或摘要节点如果单行文本在 100 token 以内宁可多做一次“行 表头”拼接也不要单独保留裸值。比如订单表只有“订单号、金额”两列检索时能提供的信息太少我就会拼上表名上下文“订单表 OR9087金额 15200 元。”虽然啰嗦但召回稳定。对于超长字段的 Excel 或数据库行我的做法是把长文本字段单独拆出来做子节点并在主节点中用一句简短摘要指向子节点。这样既保证行级元数据不被冲散又不会因为一列备注太长而拖垮整行的检索质量。除了元数据和长度查询改写也是提升表格检索的利器。用户习惯用自然语言问“最近一个月销售额是多少”但你的文档里写的是具体订单记录没有“销售额”这个词。常规向量检索很难把这种查询映射到正确的聚合逻辑上。我的临时方案是为指标类问题预置几个模板查询做一个简单的意图路由——命中“销售额/订单数/平均价”这类关键词时直接走数据库聚合而不是向量检索。LlamaIndex 对这类工具调用支持得很好后续我可能会单独写一篇。5. 我在表格导入中踩过的 5 个坑编码、类型、空值和“看起来成功”的假象最后这部分是典型的问题排查篇。前四篇我们都在讲“怎么做”这一篇我想反过来说“哪里容易出错”。表格导入的坑不像网络故障那么明显很多时候界面上一路绿灯检索时才发现结果稀碎。我把最典型的 5 类问题按“现象—根因—解法”列出来。5.1 读不出、乱码、数字变字符串CSV 编码与 dtype 的坑CSV 最坑的是编码。Windows 环境导出的 CSV 常常带 BOM用 pandas 默认 utf-8 读第一列列名会多出看不见的\ufeff。判断标准很经典打印列名时第一个列名前面多了一个空格或奇怪的符号。解法是读文件时用encodingutf-8-sig专门处理 BOMdf pd.read_csv(./data.csv, encodingutf-8-sig, dtypestr)如果换成 GBK 编码的老系统则要写encodinggbk。实在不确定文件是什么编码时建议用chardet或charset-normalizer先检测一遍不要盲目尝试。另一类是数字类型的隐性错误。CSV 里的金额列读进来默认是 float但很多业务需求希望保留原格式比如“000123”这种编号。如果我不加dtypestr编号前导零会直接消失等生成文本节点时“000123”就变成“123.0”后续检索只能碰运气。我现在对 Excel/CSV 的统一入口基本都是dtypestr只在后面做显式类型转换而不是让 pandas 猜。5.2 “导入成功但检索不到”失败但不报错的三类典型案例案例一空行和注释行制造了大批垃圾节点。有些 CSV 文件里有大量空行pandas 默认会跳过空行还好但有些系统会在表头前加几行说明文字比如“导出时间2025-03-12”。如果没做过滤这些说明行也会变成文档污染向量库。你看到导入日志全是成功检索质量却下降得很隐蔽。解法是在生成节点前加一行判断只保留“关键列在该行非空”的行。案例二单元格内的换行符把一行拆成两段。一个备注列里可能有多行文本用 Excel 打开显示为同一单元格但用 pandas 读取时输出的字符串里包含\n。如果后续切块参数不够智能本来属于同一个订单的备注会被切到别的片段去。我的做法是生成 row_text 时把内部的\n替换成空格或分号强行保持单行语义。案例三科学计数法导致数字失真。金额列如果数值很大CSV 里可能显示成1.5234E06。你要是直接拼进文本检索到的可能是“1523400”但用户问的是“152万”词面不匹配召回就会失败。这个问题的解法首先是导入阶段用dtypestr防止转换其次可以额外在元数据里加一个格式化后的长文本数值把“1.5234E06”和“1523400”两个表示都保留下来。提示表格导入的“成功”不能只看加载器有没有 Return 一个列表。我强烈建议在导入后做一个抽样校验随机取 20~30 个节点肉眼检查文本是否语义完整、元数据是否齐全、有没有 NaN 或乱码。节省的调试时间远超花掉的时间。我在实际处理表格型 RAG 时一步都绕不开这些细节。尤其是当你把 LlamaHub 的数据库读取器接好、数据源源不断灌进向量库之后返工成本会比一开始做 CSV 时高得多。如果你正准备搭建这类系统我的第一个建议是用 CSV 先跑通整条链路把行级文本生成、元数据过滤、同步策略都验证好再切换到数据库。表格和数据库看着比文本好处理但正因为它们“看起来确定”反而更容易在检索环节给你温柔的一刀。
