我们做 RAGRetrieval-Augmented Generation检索增强生成项目时最头疼的往往不是模型选型而是数据准备。PDF、Word 这类非结构化文档还能靠解析器硬啃但表格和数据库这种天生带结构的数据进了 RAG 就各种水土不服要么解析出来是一团乱麻要么检索时上下文被截断要么数值被当成普通文本唠嗑。这篇是这个系列第三篇专门讲表格类数据的导入与解析重点围绕 CSV、Excel 和 LlamaHub 连库实战展开。我会把我在实际项目里踩过的坑、验证过的方案、以及调参细节一并交代清楚给正在做 RAG 知识库、特别是想接入结构化数据的朋友一份可以直接照做的参考。CSV 和 Excel 这类文件看着简单但真要塞进 RAG 流程里涉及的问题一点都不少分隔符识别、编码处理、表头规范化、数据清洗、切块策略、以及最关键的——如何让检索器理解“这是一个表格”而不是一串干巴巴的文本。至于 LlamaHub 连数据库则是把 RAG 的触角伸向真正实时更新的结构化数据源让知识库不再是“导入一次就固化”的静态文档集。这篇文章会从设计思路讲起再一步步拆解实操细节最后给出常见问题的排查实录全程没有晦涩的理论堆砌都是能直接用起来的经验。1. 内容整体设计与思路拆解1.1 表格数据在 RAG 里的核心痛点先说一个经常被忽视的事实表格数据是“半结构化”的它既有文本的自由性又有模式Schema的约束性。你在 CSV 里看到的一行记录其实是一个由多个字段组成的逻辑实体你在 Excel 里的一个 Sheet可能同时包含标题、表头、合并单元格、公式、日期格式等多重信息。普通文本切块Chunking方式对表格极不友好因为切块是按字数就近分割的表头和一行数据被切到两个 chunk 里是常有的事检索时拿到的上下文自然支离破碎。另一个痛点是检索质量的严重下滑。RAG 的检索阶段依赖向量相似度或关键词匹配但表格里的数值型字段价格、日期、编号在向量化之后语义几乎完全丢失。比如“2024Q3 营收 12.8 亿”这个字段在向量空间里跟“2024Q3 营收 13.1 亿”的距离远到让人怀疑但这两条记录在业务上其实是相邻的历史版本。如果只做纯文本嵌入查询“去年三季度营收”时模型很可能返回一条语义接近但数值完全错误的行这就是表格类 RAG 最常见的幻觉来源。所以我做这类项目时第一原则是在导入前先想清楚这个表格将来会被怎么查询。如果查询集中在“某某字段等于什么”“某个时间段的汇总”这类精确匹配那应该走 LlamaHub 连数据库 SQL 生成的路子如果查询是“这段描述对应哪条业务记录”这种模糊匹配那 CSV/Excel 解析成带结构的文本更合适。两条路线解决的是不同的问题千万不要混用。1.2 为什么选择 CSV、Excel 与 LlamaHub 这个组合CSV 和 Excel 是数据交换的“最低公约数”几乎所有系统都能导出这两个格式而且它们代表了两种不同的建模思想CSV 是纯数据、无格式适合批量处理和程序化解析Excel 是带格式的工作表适合人工维护和可视化查看。对 RAG 项目来说CSV 通常来自系统导出、日志收集、API 拉取Excel 则多用于业务人员手工维护的配置表、报价单、物料清单。前者的特点是量大、字段规整后者的特点是结构复杂、带有格式信息颜色、合并单元格、注释。两种都要支持否则知识库的覆盖面就缺了一大块。LlamaHub 在这个体系里的定位是“数据连接器中枢”。它的价值不在于本身多复杂而在于把“连接数据库”这件事从手写 SQL 封装 ORM 的重复劳动变成声明式配置。你不需要关心数据库连接池怎么管、分页怎么拉、字段类型怎么映射LlamaHub 把这些都封装好了。结合数据库本身支持 SQL 查询的特性RAG 就能从“拿文档相似度匹配”升级到“理解用户意图后自动生成 SQL 做精确查询”这是表格数据导入的终极形态。1.3 方案选型的取舍分析我对比过几套常见方案这里直接给出结论有特殊需求再另说。纯文本解析 向量检索适合字段少、记录多、查询偏语义的行式表格。优点是实现快缺点是对精确匹配支持差日期区间和数值比较尤其容易出错。表格结构保留 向量检索在切块时保留表头信息、用分隔符标记字段检索时把整行作为一条记录处理。适合中等规模的业务表比纯文本解析好不少但依然没有解决“数值比较”这个硬伤。LlamaHub 连数据库 语义 SQL适合数据实时更新、查询模式清晰的场景比如 CRM 系统里的客户记录、库存表、订单表。优点是精确、实时缺点是依赖数据库本身可用性且生成 SQL 需要额外校验LLM 有时会写出错误语法。混合方案大规模数据全量走向量检索用于语义召回关键字段用数据库做精确过滤。这个方案效果最好但工程复杂度也最高适合对检索质量要求极高的生产环境。我的建议是项目初期先选第一种或第二种跑通流程等确认了核心查询场景再把高频查询切换到 LlamaHub 连库的路线。一上来就建全套混合架构大概率会陷入过度设计的泥潭。2. CSV 导入的完整流程与核心细节2.1 数据准备清洗永远比解析更重要CSV 导入的第一步不是写代码而是先处理数据本身。很多人直接把源文件丢给解析器结果字段错位、乱码、空行一股脑涌进来后续所有环节都在带病运行。我的经验是先做一次轻量级清洗一般在 Python 里用 Pandas 或 csv 模块搞定。最常见的坑是编码和 BOMByte Order Mark。Windows 下 Excel 导出的 CSV 通常是 GBK 或 GB2312 编码而且文件开头会带一个 \ufeff 字符如果不处理第一列的列名就会变成“\ufeff名称”后续所有下游逻辑都会遭殃。我的固定套路是先读二进制内容检测编码可以用 chardet 或 cchardet再统一转为 UTF-8 并去掉 BOMimport chardet with open(raw_data.csv, rb) as f: raw f.read() encoding chardet.detect(raw[:1000])[encoding] # 统一转为 UTF-8 且不带 BOM import codecs text raw.decode(encoding) text text.lstrip(\ufeff) with open(cleaned.csv, w, encodingutf-8) as f: f.write(text)另一个高频问题是分隔符不一致。有些系统导出的 CSV 并不是严格逗号分隔可能是分号也可能是制表符TSV。用 Pandas 读取时可以用sepNoneenginepython让引擎自动嗅探分隔符但更可靠的做法是自己先读第一行判断import csv with open(cleaned.csv, r, encodingutf-8) as f: sample f.readline() delimiter csv.Sniffer().sniff(sample).delimiter这里有个细节Sniffer 会尝试多种分隔符组合但如果表头里本身包含逗号或分号它可能判断错误。我的兜底方案是准备好下拉列表式枚举常见分隔符依次尝试然后检查列数是否一致不一致就换下一个。2.2 字段类型判断与日期规范化CSV 里所有字段最初读进来都是字符串但后续解析时需要知道哪些列是文本、哪些是数字、哪些是日期。用 Pandas 读取时dtype参数可以显式指定但更省心的做法是让 Pandas 先推断再针对日期列单独处理。日期格式化是这里最容易出 bug 的地方。CSV 里的日期格式五花八门2024/1/1、2024-01-01、01/01/2024、20240101甚至带时间戳的完整时间。如果直接按字符串存进向量库检索时“今年 1 月的数据”和“去年 1 月的数据”在文本上完全无法区分如果统一成 ISO 8601 格式2024-01-01则能保证字符串排序等于时间排序。我的做法是import pandas as pd df pd.read_csv(cleaned.csv, encodingutf-8) # 指定可能的日期列做统一格式化 date_cols [publish_date, update_time] # 按实际情况调整 for col in date_cols: df[col] pd.to_datetime(df[col], errorscoerce).dt.strftime(%Y-%m-%d)这里errorscoerce会把无法解析的日期变成 NaT后续统一过滤掉避免脏数据混入知识库。数值列也一样先转成 float 或 int再把格式化后的字符串写回文本保证向量化时数值表达一致。比如金额列统一保留两位小数而不是有的行是 12.8、有的行是 12.80。2.3 行级切块让检索器看到完整的“记录体”CSV 导入过程中最核心的设计决策是切块策略。我强烈建议按“行”作为基本切块单位而不是按字数。因为一行 CSV 本质上是一条完整记录拆开就废了。具体做法是把每一行拼成一个结构化的文本块表头信息作为 metadata 保留。举个例子一个包含“城市、人口、GDP、年份”四列的 CSV一行数据就可以拼成城市上海 | 人口2487 万 | GDP4.72 万亿 | 年份2023这个拼接格式有两个好处一是语义完整检索时能一次性拿到这条记录的所有关键字段二是字段之间有显式分隔符嵌入模型能更好地学习字段与值之间的对应关系。分隔符我建议用“|”或换行符不要用逗号或分号因为字段内容里本身就可能包含逗号会产生歧义。同时把列名表头作为 metadata 保存而不是拼进文本内容。这样一来查询“上海的 GDP 是多少”时即使文本内容里没有出现“GDP”这个词metadata 里的列名也能帮检索器定位到正确的 chunk。from llama_index.core import Document records [] for _, row in df.iterrows(): content | .join([f{col}{row[col]} for col in df.columns]) doc Document( textcontent, metadata{source: city_stats.csv, row_index: row.name} ) records.append(doc)这里要注意一个性能问题df.iterrows()在数据量大时很慢几万行就要几秒。如果 CSV 超过 5 万行建议改用df.itertuples(indexTrue)速度能快 5~10 倍或者直接to_dict(records)转成列表再循环。2.4 大文件分段处理与内存优化CSV 动不动就几个 GB 的情况很常见一次性读进 Pandas DataFrame 会直接把内存打爆。我的经验是分块读取每次处理 10 万行左右处理完就释放内存。chunk_size 100000 for chunk in pd.read_csv(large.csv, chunksizechunk_size): # 对 chunk 做清洗、格式化、构建 Document process_chunk(chunk)分块的好处不只是省内存还能做断点续传——如果第 3 块处理时程序崩了下次可以从第 3 块接着跑不用从头再来。配合 tqdm 输出进度条导入 1 个 G 的 CSV 全程肉眼可见安全感会强很多。我还会额外做一次去重。很多业务系统导出的 CSV 里会混着重复行如果不去重知识库里的条目会重复检索时同名记录返回多条干扰模型判断。去重逻辑很简单df df.drop_duplicates(subset[primary_key_col], keeplast)如果没有唯一键可以选取所有字段做全字段去重但不建议对包含文本的列做全字段去重因为文本列里可能有细微差别比如多了个空格全字段去重容易误伤。3. Excel 导入的进阶处理与实操要点3.1 多 Sheet 与格式信息的处理策略Excel 和 CSV 最大的区别在于它可以包含多个 Sheet每个 Sheet 有独立的表头和数据区有时候还有合并单元格、标题行、备注行。我之前遇到过一份 8 个 Sheet 的报价单每个 Sheet 的表头结构都不一样甚至同一个 Sheet 里分了上下两个表格区域中间隔着几行标题。针对这种数据我建议不要试图“智能识别”所有结构而是建立一个配置化的映射规则。每个 Sheet 手动指定起始行、表头行、数据结束行、需要跳过的列。用 openpyxl 或 pandas 读取时精确控制范围import pandas as pd df pd.read_excel( quotation.xlsx, sheet_nameSheet1, header2, # 第 3 行是表头 skiprows[0, 1], # 前两行是标题和副标题 usecolsA:F # 只取 A 到 F 列 )这个方案虽然需要人工干预但非常可靠。我见过有人试图用大模型自动推断 Excel 结构但在复杂格式面前成功率并不高而且每次运行成本很高。配置化规则是一次投入、长期复用业务部门改一次格式你只需要改配置文件里的一行参数。合并单元格是一个特别容易踩的坑。Pandas 读 Excel 时合并单元格只有左上角的第一个单元格有值其余都是 NaN。比如一个“地区华东”的单元格跨了 5 行那 5 行里只有第一行有“华东”其余 4 行是 NaN。我的处理方案是向前填充ffilldf[region] df[region].ffill()这样可以保证每条记录都有完整的上下文不会出现“这条属于哪个地区都不知道”的情况。注意这里要按列填充而不是全表填充否则会把无关列的缺失值也填上错误内容。3.2 公式、条件格式与数据验证的处理预案Excel 里的公式是另一个麻烦。有些单元格的值不是静态的而是由公式计算出来的比如VLOOKUP(A2, 价格表!A:B, 2, 0)或SUM(D2:F2)。如果直接用 openpyxl 读你会拿到公式字符串而不是计算结果。RAG 知识库要的是最终值不是公式。我的方案是先用 Excel 应用本身把公式计算结果固化或者在脚本里用data_onlyTrue读取缓存值import openpyxl wb openpyxl.load_workbook(with_formula.xlsx, data_onlyTrue) ws wb[Sheet1]注意data_onlyTrue读取的是上次 Excel 打开文件时计算并缓存的结果。如果这个文件自生成后从未被 Excel 打开过缓存可能是空的返回 None。这种情况我的应对是先用 LibreOffice 的命令行做一次批量转换强制重算并另存soffice --headless --convert-to xlsx --outdir converted/ with_formula.xlsx转换后公式会变成值再加载就没有 None 的问题了。条件格式对 RAG 基本没意义直接忽略即可数据验证下拉列表如果只是输入约束也不影响数据读取可以跳过。3.3 Excel 读取的性能优化与类型保真Excel 文件一大读取速度瞬间拉胯。一个 50 MB 的 xlsxPandas 默认引擎 openpyxl 可能要读 30 秒以上。如果只是读取数据而不关心公式可以尝试enginecalamine如果环境里有或者先转成 CSV 再处理。我的经验是纯数据场景下先用 LibreOffice 把 xlsx 转成 csv再用 csv 模块按 2.1 节的流程走速度能快一个数量级。另外要特别留意数字精度问题。Excel 里的浮点数在二进制存储时本身就是不精确的如果你把 12.999999 当成 13 来处理排序还好但做等值匹配就麻烦了。我的做法是读取后统一做舍入import pandas as pd numeric_cols df.select_dtypes(includenumber).columns df[numeric_cols] df[numeric_cols].round(4)这里取 4 位小数是因为大多数业务数据不需要比 4 位更高的精度太长的尾数反而可能干扰检索。对于金额列建议保留 2 位小数和业务口径保持一致。4. LlamaHub 连库实战让 RAG 直连实时数据4.1 LlamaHub 生态与数据库连接器概览LlamaHub 是 LlamaIndex 官方的数据连接器仓库里面集成了几百个数据源的加载器。连数据库时我们一般用DatabaseReader或SQLDatabase封装类它们会把数据库表映射成 Document 或可查询的结构化源。核心思路是不把整张表灌进向量库而是保留 SQL 查询能力让 LLM 在需要时生成 SQL 去数据库里查查到的结果再交给生成模型做回答。这样做的好处很明显数据实时、查询精确、不占向量库空间。缺点是每次查询都要走一次数据库连接和 SQL 执行延迟比纯向量检索高而且 LLM 生成 SQL 有失败概率需要加校验和兜底。我常用的连接器组合是SQLDatabaseNLSQLTableQueryEngine一个负责连库、一个负责把自然语言翻译成 SQL。还有一个老牌工具SQLTableRetrieverQueryEngine适合关联多表查询的场景返回的上下文更丰富但检索链路也更复杂。如果项目刚起步建议从NLSQLTableQueryEngine开始收敛面小出错好排查。4.2 数据库连接配置与表结构映射先说配置。无论用什么连接器第一步都是建立数据库连接。以 PostgreSQL 为例from sqlalchemy import create_engine engine create_engine( postgresqlpsycopg2://user:passwordlocalhost:5432/dbname )这里有几个细节要注意一是连接字符串里的密码如果包含特殊字符必须做 URL 编码否则解析会出错二是 生产环境千万不要把密码硬编码在脚本里建议用环境变量或密钥管理服务读取。从 LlamaHub 这一侧没有额外限制但要确保数据库账号有读权限并且网络连通性没问题。表结构映射方面连接器需要知道你有哪些表、每张表有哪些列。LlamaIndex 的SQLDatabase会自动从数据库 catalog 里读取表信息生成一份 schema 描述。但自动读取的 schema 不一定直观比如列名是c1、c2的隐藏命名模型根本看不懂。我建议先手动补一层列注释COMMENT ON COLUMN orders.order_id IS 订单号唯一标识每笔订单; COMMENT ON COLUMN orders.amount IS 订单金额单位元;有了注释之后LLM 生成 SQL 的准确性会显著提升因为它能明白amount指的是金额而不是数量。这类注释对普通用户不可见但对 LLM 理解 schema 是刚需。4.3 从自然语言到 SQL 的生成与校验LlamaHub 连数据库的核心价值是“自然语言 → SQL”这个过程如果是黑盒风险很大。我强烈建议在生成 SQL 之后加一道独立的校验层至少要做三件事语法校验、表名列名白名单校验、空结果对应逻辑。语法校验最简单的方式是把生成的 SQL 丢给数据库做 EXPLAIN不真正执行也能发现大部分语法错误try: with engine.connect() as conn: result conn.execute(text(fEXPLAIN {sql})) # 语法没问题 except Exception as e: # 语法有问题记录日志并返回兜底提示 fallback_response 我暂时无法从数据库中找到相关信息请尝试换个问法。白名单校验更重要。LLM 可能生成SELECT * FROM users; DROP TABLE users;这种恶意 SQL虽然大多数情况下只是幻觉写出不存在的列名必须在执行前拦截。我的做法是先用正则抽取所有表名和列名再和数据库 schema 做比对import re tables_used re.findall(rfrom\s([a-z_0-9]), sql, re.IGNORECASE) cols_used re.findall(rselect\s(.*?)\sfrom, sql, re.IGNORECASE) allowed_tables {orders, customers, products} if any(t not in allowed_tables for t in tables_used): raise ValueError(检测到非授权表名已终止执行)最后是空结果处理。自然语言问“上个月卖了多少台”但生成的 SQL 查出来是空这时不能直接告诉用户“没数据”而应该回退到更宽松的查询条件再试一次比如去掉时间过滤条件、模糊匹配商品名称等。这个回退逻辑放在连接器外层做不要放在连接器内部方便单独调试。4.4 多表关联查询与上下文增强单表查询只是入门业务系统里真正有价值的是多表关联。比如“近 30 天华东区客户投诉最多的商品排名”涉及订单表、区域表、投诉表三张表。SQLTableRetrieverQueryEngine在这类场景里表现更好因为它会先做一次“表检索”判断哪些表与当前问题相关再生成跨表 SQL。不过我实测下来三张表以上的关联查询LLM 生成正确 SQL 的概率会明显下降尤其遇到同名字段比如多个表都有created_at时容易搞错关联条件。我的对策是给表名和字段名加前缀别名比如orders.created_at让模型不容易混淆。另一个对策是在数据库里建好视图View把高频关联查询固化成一个虚拟表LLM 只需查询视图少一层 JOIN成功率直线上升。上下文增强方面查询结果返回后直接丢给 LLM 也行但我习惯再补一层业务口径说明。比如把“金额单位是元”这种信息拼接进 prompt避免 LLM 把 47200 解释成 4.72 万。这一步不复杂但对回答质量的影响非常明显。5. 实操环境准备与完整项目流程整合5.1 环境依赖与版本选择我建议直接用 Python 3.10 以上版本搭配 venv 或 conda 环境隔离依赖。核心依赖清单如下pip install llama-index pandas openpyxl sqlalchemy psycopg2-binary如果有 Google Sheets 或其他在线表格需求再加装google-auth、gspread等。LlamaIndex 版本迭代很快API 变动频繁我建议锁定主版本号安装比如 llama-index0.10.x避免升一个大版本后代码大面积报错。嵌入模型和 LLM 的配置同样关键。我习惯把 key 放到环境变量里避免硬编码。如果是要私有化部署也可以选择本地模型比如 embedding 用 bge-large-zh生成用 ChatGLM 或 Qwen这样数据不出内网安全性更高。5.2 从 CSV/Excel 到向量库的完整流水线把 CSV 和 Excel 导入向量库完整流水线应该是这样读取 → 清洗 → 字段类型规范化 → 构建 Document → 切块 → 嵌入 → 写入向量库。切块参数用我前面 2.3 节的行级方案但嵌入和写入向量库时有几个参数需要特别注意。chunk_size建议设置得比普通文本大一些因为一行 CSV 拼接后的字符串往往接近 300~500 字符设太小的 chunk_size 会把一条记录截成两半。overlap在表格场景里意义不大甚至可以设为 0因为表格记录之间没有文章那种上下文衔接。写入向量库时建议用批量模式而不是逐条插入比如一次性 insert 1000 条耗时能减少 60% 以上。from llama_index.core import VectorStoreIndex, Settings from llama_index.core.node_parser import SentenceSplitter Settings.embed_model embed_model splitter SentenceSplitter( chunk_size600, chunk_overlap50, paragraph_separator\n ) nodes splitter.get_nodes_from_documents(records) index VectorStoreIndex(nodes)这里我再多提一句SentenceSplitter是按文本块切分的它不会感知 CSV 的行边界。所以如果你把多行 CSV 拼成一个长文本再交给 splitter它依然可能切坏。我的保险做法是自己先把每一行构建成独立 Document每个 Document 的长度控制在 chunk_size 以内再让 splitter 直接返回原样不要二次切分。具体来说给 splitter 设置一个大 chunk_size比如 4096让它变成“不切块”的透传模式splitter SentenceSplitter(chunk_size4096, chunk_overlap0) nodes [Document(textdoc.text, metadatadoc.metadata) for doc in records]这样每条记录作为一个节点进入向量库检索时一条记录就是一个整体不会再被拦腰切断。5.3 LlamaHub 连库的端到端调试步骤连库调试我分成三步每一步都有明确的验证信号。第一步验证数据库连接。执行一句SELECT 1能拿到返回就说明网络、账号、驱动都正常。这一步挂了就什么都别做先排查网络连通和数据库白名单。第二步验证 schema 读取。让SQLDatabase对象打印出所有表和列的摘要人工确认关键表都在没有缺列。如果发现缺失看看是不是账号权限不足或者数据库里有多个 schema默认只读了 public。第三步自然语言转 SQL 测试。用三五条典型查询样本过一遍流程比如“列出所有客户名”“最近一周的订单总量”。不仅要看 SQL 生成是否正确还要看查询结果能否正确格式化给 LLM。我通常会把中间产物打印出来包括生成的 SQL、查询耗时、返回记录数。这一步是排查“回答离谱”的第一现场。5.4 日常运行与增量更新的维护节奏表格数据不会永远是那个表尤其是数据库每天都在变。我的维护策略是分级刷新CSV/Excel 这类静态文件用定时任务或事件触发重新导入即可频率取决于业务更新周期数据库则不需要固定刷新因为它走的是实时 SQL 查询。唯一要注意的是 LlamaIndex 里缓存的 schema 描述可能过期如果数据库表结构变更了一定要刷新 schema 缓存否则 LLM 还在拿旧结构生成 SQL会频繁报错。为了保证知识库可用性我会给每个数据源打标签source_tag向量库里每条记录都能回溯到原始的 CSV 行号或数据库主键。这样一旦发现某条数据有误可以直接定位并删除不用全量重建。6. 常见问题与排查技巧实录6.1 表格切块错乱与检索丢失上下文症状检索结果看起来像“断章取义”或者回答里出现了一半字段。原因多半是切块时把行掐断了。我在 5.2 节给出的透传方式是最简单可靠的解法但如果你必须用小 chunk_size务必将 chunk_overlap 设置成至少一条记录的 1/3 长度让分割器有缓冲。另外要检查嵌入模型的最大输入 token 长度。有的模型只支持 512 token但你的行拼接文本超过 800 token嵌入时会被截断相当于后半段字段全丢了。这种情况要么换大窗口模型要么把字段裁剪到只保留核心列。6.2 Excel 读取乱码与空数据已经处理过 BOM 了还乱码大概率是编码判断错了。chardet 在小样本上经常误判尤其是中文 GBK 和 Big5 混排的场景。我的经验是多采样几段再判断或者在判断结果不确定时回退到 GB18030它是 GBK 的超集兼容面更大。空数据问题则往往来自data_onlyTrue拿不到公式缓存值。前面提过用 LibreOffice 重算。如果公司环境不允许装 LibreOffice另一个办法是用 Excel COM 组件Windows打开文件并保存一次强制刷新缓存但这就依赖桌面环境了不适合服务器跑批。6.3 LlamaHub 连库时 SQL 生成错误SQL 生成错误我统计过80% 是表名或列名拼错了跟大小写和命名规则息息相关。解决方法是把 schema 描述里的表名列名做成全小写规范化并在提示词里强调“严格使用给定的表名和字段名不要随意改名”。剩下 20% 是多表 JOIN 条件写错建议用视图来规避。还有一个隐藏问题有些数据库的连接超时时间很短长查询执行到一半连接断了异常信息又不够直观。我建议把所有数据库操作统一包一层超时控制from sqlalchemy import text from contextlib import contextmanager contextmanager def db_query(engine, sql, timeout10): with engine.connect() as conn: conn.execute(text(fSET statement_timeout {timeout * 1000})) yield conn这个对 PostgreSQL 有效MySQL 可以用MAX_EXECUTION_TIME只是语法略有差异。设置超时既保护数据库也避免 RAG 接口长时间无响应。6.4 常见问题速查表现象可能原因解决思路CSV 首列列名带“\ufeff”文件带 BOM用text.lstrip(\ufeff)去除日期列被识别为字符串未指定 dtype用pd.to_datetime统一格式检索结果全是片段chunk_size 过小切断了行按行构建 Document不二次切分Excel 某列全为空合并单元格使用ffill()向前填充Excel 读取返回 None公式缓存为空用 LibreOffice 重算转格式LLM 生成 SQL 表名错误schema 描述不清晰补列注释 白名单校验数据库查询超时执行计划不佳加数据量限制 超时控制多表关联出现假数据JOIN 条件写错建视图简化查询6.5 我踩过的一些坑与经验总结做表格导入最怕的是“表面成功、实际有毒”CSV 导入后没有报错但向量检索出的内容张冠李戴Excel 读取没有任何异常但公式缓存让数字全部变成 NoneLlamaHub 连库没有报错但 SQL 查出来是同名不同表的数据。每一步都要有验证信号不能只依赖代码跑通。我的经验是导入后先做一轮抽样人工检查比如随机挑 10 条记录打印出来看看格式对不对连库后先用 3~5 个真实问题做集成测试确认回答质量再上线。另外日志真的很重要。每次导入、每个查询我都把 CSV 文件名、行号、构建的文本内容、数据库连接标识、SQL 语句全部记录下来。这样一旦线上出了问题定位到具体批次数据处理起来会快得多。基于我自己的项目经验表格数据导入 RAG 没有银弹核心是两种手段的取舍CSV/Excel 走向量检索适合语义匹配、内容探索LlamaHub 连数据库走 SQL 生成适合精确查询、实时数据。最稳的架构是两者结合向量索引负责召回候选数据库负责精排过滤。你先按这个思路跑一版最小可用系统等对自家数据的查询模式摸清了再决定要不要往混合架构压重注。
