RAG Pipeline 预处理 — 能力边界说明
本文档定义 RAG Pipeline 预处理系统的能力范围、已知限制和风险阈值，供参考。
1. 文件类型支持矩阵
1.1 直接支持的文件类型
| 文件类型 | 扩展名 | 解析步骤 | 备注 |
|---|
| PDF | .pdf | PDF_CONTENT_EXTRACTION / TEXTIN / AZURE_DI / ALI_OCR / LLM_CONTENT_EXTRACTION | 基础解析仅适用于文本型 PDF，扫描件需 OCR 步骤 |
| Word 文档 | .docx | DOCX_CONTENT_EXTRACTION | 通过 pypandoc 转 Markdown，支持段落/表格/嵌入图片 |
| 旧版 Word | .doc | 需先经 FILE_CONVERT_WITH_SPIRE 或 FILE_CONVERT_WITH_LIBREOFFICE 转换 | 无法直接解析，必须先转为 .docx 或 .pdf |
| Markdown | .md | MD_CONTENT_EXTRACTION | 原生支持 |
| 纯文本 | .txt | TXT_CONTENT_EXTRACTION | 原生支持 |
| Excel | .xlsx .xls | TABULAR_CONTENT_EXTRACTION | 有行列限制，见 §2 |
| CSV / TSV | .csv .tsv | TABULAR_CONTENT_EXTRACTION | — |
| PowerPoint | .pptx .ppt | 需先经 FILE_CONVERT_WITH_SPIRE 或 FILE_CONVERT_WITH_LIBREOFFICE 转换 | 无法直接内容提取，须先转 PDF |
| 图片 | .png .jpg .jpeg .gif .webp .svg | IMAGE_CONTENT_EXTRACTION | 使用 Vision LLM（如 GPT-4o）描述图像内容，上限 300 词 |
| 视频 | .mp4 .avi .mkv .mov | VIDEO_CONTENT_EXTRACTION | 提取音轨 → 转录文本 |
| 音频 | .mp3 .wav .flac .aac | AUDIO_CONTENT_EXTRACTION | 切分为 60 秒片段后逐段转录 |
1.2 不支持 / 明确禁止的文件类型
| 类型 | 说明 |
|---|
.exe | 硬编码黑名单（_UNSUPPORTED_EXTENSIONS） |
.zip / .rar 等压缩包 | 无解压步骤，Pipeline 不处理 |
.html / .xml | 无专用解析步骤 |
.json / .yaml | 无专用解析步骤 |
.eml / .msg 邮件 | 不支持 |
.dwg / .dxf CAD 文件 | 不支持 |
.rtf | 无专用步骤（可尝试经 LibreOffice 转换，但无保证） |
| 加密 / 密码保护文件 | 所有格式均无法处理加密文件 |
2. 文件大小与资源限制
2.1 预检限制（file_limit_checker）
上传时会进行轻量级预检，超限文件将被拒绝上传或标记警告：
| 维度 | 默认阈值 | 可配置 | 说明 |
|---|
| 字符数 | 15,000 字符 | ✅ 通过 FILE_LIMIT_CHECK_CONFIG 环境变量 | 适用于 PDF/DOCX/TXT/MD/CSV/XLSX 等文本类文件 |
| 页数 | 25 页 | ✅ 同上 | PDF 按物理页，Excel 按 Sheet 数，PPT 按幻灯片数 |
⚠️ 知识库文件源批量导入不受此预检限制，但文件过大仍有 OOM 风险。
2.2 Pipeline 处理内的资源阈值
| 资源维度 | 阈值 / 配置 | 风险 |
|---|
| PDF 并行页转换 | 每批 50 页（PDFConversionDefaultOptions.CHUNK_SIZE） | 超大 PDF（500+ 页）在 pdf2image 转换时内存占用高，可能导致 OOM |
| 表格行数 | 单 Sheet ≤ 20,000 行 | 超限直接报错拒绝解析 |
| 表格列数 | 单 Sheet ≤ 200 列 | 超限直接报错拒绝解析 |
| 表格图片 | 单文件 ≤ 150 张图片（_MAX_IMAGES） | 超限忽略多余图片 |
| 向量化批次 | 每批 100 段（batch_size） | — |
| 分段图片密度 | 单段 ≤ 5~8 张图片 | 超限触发提前切分，避免 token 溢出 |
| 音频切片 | 60 秒 / 段 | 长音频/视频会产生大量转录 API 调用 |
| TextIn OCR | API 级配置最大 1,000 页 | 额度耗尽会报错 |
2.3 OOM / 资源过载风险场景
| 场景 | 风险等级 | 原因 | 建议 |
|---|
PDF > 200 页 + pdf2image | 🔴 高 | pdf2image 以 300 DPI 将每页渲染为内存 bitmap，200 页 ≈ 数 GB 内存 | 使用 OCR 步骤（TextIn/Azure DI）替代基础解析 |
| Excel 单 Sheet > 10,000 行 | 🟡 中 | 全量加载到内存，生成大量段落 | 预拆分文件或增大 worker 内存 |
| 视频 > 2 小时 | 🟡 中 | ffmpeg 音频提取 + 120 个 60s 转录请求 | 限制视频时长或预切割 |
| 单文件含 100+ 张嵌入图片 | 🟡 中 | 每张图需 Vision LLM 调用，耗时 & 费用高 | 仅提取关键图片 |
| 批量导入 1,000+ 文件 | 🟡 中 | Celery worker 队列积压，gevent 并发上限 100 | 分批导入，监控队列深度 |
3. 文件解析能力分级
3.1 解析引擎对比
| 引擎 | 解析方式 | 适用场景 | 不适用场景 | 依赖 |
|---|
| Basic（pypdf / pdfplumber） | 文本层直接提取 | 原生文本 PDF（Word 导出、LaTeX 生成等） | 扫描件、图片 PDF、复杂排版 | 无外部依赖 |
| TextIn OCR | 云端 OCR + 版面分析 | 扫描件、票据、混合排版 PDF | — | TEXTIN_APP_ID / TEXTIN_APP_SECRET |
| Azure Document Intelligence | 云端 Layout/Read 模型 | 表格结构保持、多栏排版 | — | azure_ocr_endpoint / azure_ocr_key |
| Ali OCR | 阿里云 OCR | 中文场景扫描件 | — | 阿里云 API 凭证 |
| LLM 解析（PDF LLM） | 页面截图 → Vision LLM 识别 | 极复杂版面、图文混排 | 大文件（成本高、速度慢） | Vision LLM（GPT-4o 等） |
| pypandoc | Pandoc 格式转换 | DOCX → Markdown | 复杂宏、ActiveX 控件 | Pandoc 二进制 |
| LibreOffice / Spire | 格式转换引擎 | .doc→.docx、.ppt→.pdf | — | LibreOffice 或 Spire 运行时 |
3.2 各文件类型解析能力详述
PDF
| 特性 | Basic | TextIn | Azure DI | LLM |
|---|
| 纯文本提取 | ✅ | ✅ | ✅ | ✅ |
| 扫描件 / 图片 PDF | ❌ 返回空 | ✅ | ✅ | ✅ |
| 表格结构保持 | ❌ 丢失格式 | ✅ | ✅（Layout 模式） | ✅ |
| 多栏排版 | ❌ 文本错乱 | ✅ | ✅ | ✅ |
| 超链接提取 | ✅（pdfplumber） | ❌ | ❌ | ❌ |
| 嵌入图片提取 | ✅（转 PNG） | ✅ | ✅ | ✅ |
| 处理速度 | ⚡ 快 | 🐢 中 | 🐢 中 | 🐌 慢 |
| 费用 | 免费 | 💰 按页计费 | 💰 按页计费 | 💰💰 按 token |
DOCX
| 特性 | 支持情况 |
|---|
| 段落文本 | ✅ |
| 表格 | ✅（转 Markdown 表格） |
| 嵌入图片 | ✅（提取为独立文件 + Markdown 标记） |
| 目录 / 书签 | ⚠️ 部分（Pandoc 转换时可能丢失） |
| 宏 / VBA | ❌ 忽略 |
| 修订标记 / 批注 | ❌ 丢失 |
| 复杂嵌套表格 | ⚠️ Pandoc 表现不稳定 |
表格文件（Excel / CSV）
| 特性 | 支持情况 |
|---|
| 多 Sheet | ✅ 逐 Sheet 处理 |
| 公式 | ⚠️ 仅读取计算后的值（data_only=True） |
| 图表 / 数据透视表 | ❌ 忽略 |
| 嵌入图片 | ✅（上限 150 张 / 文件） |
| 合并单元格 | ⚠️ 可能导致数据错位 |
| 超过 20,000 行 | ❌ 拒绝解析 |
| 超过 200 列 | ❌ 拒绝解析 |
音视频
| 特性 | 支持情况 |
|---|
| 语音转文字 | ✅（60s 分段转录） |
| 多语言识别 | 取决于转录服务模型 |
| 说话人分离 | ❌ |
| 背景音乐 / 噪声 | ⚠️ 影响转录质量 |
| 视频画面内容识别 | ❌ 仅提取音轨 |
| 字幕 / CC 提取 | ❌ |
| 特性 | 支持情况 |
|---|
| 图像内容描述 | ✅ Vision LLM 描述（≤ 300 词） |
| OCR 文字识别 | ⚠️ 依赖 Vision LLM 能力，非专业 OCR |
| 图表 / 流程图理解 | ⚠️ 有限（LLM 理解力决定） |
| SVG 矢量图 | ⚠️ 取决于 LLM 是否能渲染 |
4. 分段（Segmentation）能力与限制
| 分段方法 | 适用场景 | 参数 | 限制 |
|---|
固定字符数（FIXED_SIZE） | 通用文本 | chunk_size=1024 | 可能在句中截断；单段 ≤ 5~8 张图片 |
按页（PAGE） | PDF 文档 | — | 仅 PDF 有效；单页内容差异大时段落质量不均 |
按标题（TITLE） | Markdown 文档 | chunk_size=1024 | 仅识别 # / ## / ### 标题；无标题时退化为整文档一段 |
表格（TABULAR） | Excel / CSV | — | 专用于表格类文件 |
LLM 智能（LLM） | 需语义连贯的场景 | — | 速度慢、成本高；大文件不经济 |
细分（REFINE） | 对粗分结果二次优化 | — | 需配合上游粗分步骤使用 |
通用限制：
- ��段时保护表格 / 代码块不被切断（
RecursiveCharacterTextSplitter 回退分隔符）
- 超长段（> 65% chunk_size）使用 spaCy 做句级细分
- 单段图片过多（> 5 张）触发强制切分
5. 字段提取能力
| 步骤 | 功能 | 依赖 | 限制 |
|---|
METADATA_EXTRACTION | 文档级元数据（标题/作者/日期等） | LLM | Schema 需预定义 |
SEGMENT_METADATA_EXTRACTION | 段落级元数据 | LLM | 每段一次 LLM 调用，大文件成本高 |
KEYWORDS_EXTRACTION | 关键词抽取 | LLM | — |
SEGMENT_SUMMARY | 段落摘要 | LLM | 每段一次 LLM 调用 |
DOCUMENT_SUMMARY | 全文摘要 | LLM | 长文档需截断或分批聚合 |
TABLE_CAPTIONING | 表格描述生成 | LLM | — |
TABLE_CAPTIONING_ADVANCED | 表级摘要 + 行级叙述分组 | LLM | 复杂表格效果取决于 LLM 理解力 |
IMAGE_CAPTIONING | 图像描述生成 | Vision LLM | 每张图一次 LLM 调用 |
6. 后处理（Postprocessing）能力
| 步骤 | 功能 | 配置 | 限制 |
|---|
EMBEDDING | 文本向量化 | batch_size=100 | 依赖 Embedding 模型；图片占位符自动剥离 |
TOKENIZER | 全文索引分词 | spaCy 语言模型 | PostgreSQL tsvector 长度限制 |
EMBEDDING_STORE | 向量写入 VectorDB | — | 批次写入，取决于 VectorDB 性能 |
TOKENIZER_STORE | 分词写入 PostgreSQL | — | — |
7. 格式转换能力
| 输入格式 | 输出格式 | 转换引擎 | 限制 |
|---|
.doc | .docx / .pdf | LibreOffice / Spire | 需服务端安装对应运行时 |
.ppt | .pdf | LibreOffice / Spire | 动画/过渡效果丢失 |
.pptx | .pdf | LibreOffice / Spire | 同上 |
8. 外部服务依赖
| 服务 | 环境变量 | 用途 | 不配置的影响 |
|---|
| TextIn OCR | TEXTIN_APP_ID / TEXTIN_APP_SECRET / TEXTIN_APP_ENDPOINT | PDF/图片 OCR | 对应 OCR 步骤不可用 |
| Azure Document Intelligence | azure_ocr_endpoint / azure_ocr_key | PDF Layout 分析 | 对应步骤不可用 |
| Ali OCR | 阿里云凭证 | 中文 OCR | 对应步骤不可用 |
| Embedding 模型 | LLM Gateway 配置 | 文本向量化 | EMBEDDING 步骤不可用 |
| Vision LLM | LLM Gateway 配置 | 图片描述 / LLM PDF 解析 | IMAGE/LLM 步骤不可用 |
| 通用 LLM | LLM Gateway 配置 | 摘要/关键词/元数据提取 | 字段提取步骤不可用 |
| LibreOffice | 服务端二进制 | 格式转换 | .doc/.ppt 无法处理 |
| Pandoc | 服务端二进制 | DOCX → Markdown | DOCX 解析不可用 |
| ffmpeg | 服务端二进制 | 视频音轨提取 | 视频处理不可用 |
| spaCy | Python 包 + 语言模型 | 分词/句分割 | TOKENIZER 步骤和细分功能不可用 |
9. 已知边界案例汇总
| # | 场景 | 表现 | 推荐处理方式 |
|---|
| 1 | 扫描件 PDF + Basic 解析 | 提取内容为空 | 切换至 TextIn / Azure DI / LLM 步骤 |
| 2 | 多栏 PDF + Basic 解析 | 文本顺序错乱，段落交叉 | 使用 Azure DI Layout 模式 |
| 3 | PDF 内复杂表格 + Basic 解析 | 表格结构丢失，数据变为散文 | 使用 TextIn / Azure DI |
| 4 | 加密 / 密码保护 PDF | pypdf 抛异常 | 预处理去除密码保护 |
| 5 | .doc（旧版 Word）直接上传 | 无原生解析器 | 确保 Pipeline 包含文件转换步骤 |
| 6 | Excel 超 20,000 行 | 拒绝解析，抛出错误 | 拆分为多个文件 |
| 7 | Excel 合并单元格 | 数据可能错位 | 上传前取消合并 |
| 8 | Excel 公式 | 仅读取结果值，非公式本身 | 预期行为 |
| 9 | 视频仅提取音轨 | 画面内容无法识别 | 如需画面信息，截取关键帧另行处理 |
| 10 | 图片 OCR 精度 | Vision LLM 非专业 OCR，准确率有限 | 对 OCR 要求高的场景用 TextIn |
| 11 | 大文件 + LLM 解析 | 成本极高（按页/token 计费） | 仅对关键文档使用 LLM 解析 |
| 12 | Markdown 无标题结构 + TITLE 分段 | 整篇文档成为一个段落 | 改用 FIXED_SIZE 分段 |
| 13 | PPT 动画/视频嵌入 | 转 PDF 后丢失 | 无解决方案 |
| 14 | DOCX 含宏/VBA/ActiveX | 忽略所有宏内容 | 预期行为 |
| 15 | DOCX 修订标记/批注 | 丢失 | 上传前接受所有修订 |
10. 容量规划建议
| 文件类型 | 建议上限（单文件） | 理由 |
|---|
| PDF（Basic 解析） | ≤ 50 页 | pdf2image 内存消耗；超 50 页有 OOM 风险 |
| PDF（OCR 解析） | ≤ 100 页 | 受 OCR 服务 API 限制和成本 |
| DOCX | ≤ 20,000 字符 | Pandoc 转换内存 |
| Excel | ≤ 20,000 行 × 200 列 / Sheet | 硬限制 |
| CSV | ≤ 20 MB | 全量加载到内存 |
| 音频 | ≤ 60 分钟 | 60 次转录 API 调用 |
| 视频 | ≤ 30 分钟 | ffmpeg 提取 + 转录；时长越长失败概率越高 |
| 图片 | ≤ 10 MB / 张 | Vision LLM 输入限制 |
本文档基于代码分析生成，实际运行表现可能因部署环境（内存 / CPU / 网络）和外部服务状态而异。建议在生产环境使用前进行针对性压测。