xerrors--yuxi/docs/advanced/document-processing.md

文档处理与 OCR

Yuxi 支持多种文档格式的智能解析，从简单的文本文件到复杂的 PDF 文档，都能自动提取内容并转换为可检索的格式。

支持的文件类型

常规文档

类型	格式	说明
文本	.txt, .md, .html, .htm	直接提取内容
Word	.docx	保留格式和结构
PowerPoint	.pptx	保留主要文本结构
PDF	.pdf	支持文本和图片 PDF
表格	.csv, .xls, .xlsx	识别表格结构
JSON	.json	结构化数据

图片文件

对于图片文件，需要启用 OCR 才能提取文字：

• .jpg, .jpeg, .png, .bmp, .tiff, .tif

压缩包

支持上传 ZIP 压缩包，系统会：

• 自动提取并处理其中的 Markdown 文件
• 处理图片并上传到对象存储
• 智能识别 full.md 或第一个 .md 文件

网页内容

支持通过 URL 直接抓取网页内容：

1. 配置 YUXI_URL_WHITELIST 环境变量启用白名单机制
2. 系统自动将 HTML 转换为 Markdown
3. 内置去重机制，避免重复抓取

::: tip URL 白名单配置 示例：YUXI_URL_WHITELIST=github.com,*.wikipedia.org,docs.python.org :::

OCR 方案选择

系统提供多种 OCR 方案，适用于不同场景：

方案对比

方案	适用场景	硬件要求	特点
RapidOCR	基础文字识别	CPU	免费开源，速度快
MinerU	复杂 PDF、表格	GPU	精度高，版面分析好
MinerU Official	复杂文档	无	官方云服务，开箱即用
PP-Structure-V3	表格、票据	GPU	专业版面解析
DeepSeek OCR	智能理解	无	云端服务，Markdown 输出
PaddleOCR-VL-1.6	复杂文档、表格、图片 PDF	无	百度 AI Studio 云端服务，输出 Markdown
PP-OCRv6	基础文字识别	无	百度 AI Studio 云端 OCR，输出纯文本

选择建议

• 个人使用或 CPU 环境：选择 RapidOCR，免费且资源占用低
• 高精度需求：选择 MinerU（需要 GPU）或 MinerU Official
• 表格密集型文档：选择 PP-Structure-V3
• 云端版面解析：选择 PaddleOCR-VL-1.6，适合希望输出 Markdown 的 PDF 或图片文档
• 云端纯文字识别：选择 PP-OCRv6，适合只需要提取图片文字的场景
• 简单云服务：选择 DeepSeek OCR 或 PaddleOCR API

快速配置

RapidOCR

启动后会默认下载，无需配置

MinerU（高精度）

项目已内置 mineru-api 服务（位于 docker-compose.yml，属于 all profile），无需额外下载官方 compose 文件。首次构建镜像时会基于 docker/mineru.Dockerfile 下载模型，该过程耗时较长。

启动服务（需要 GPU）：

docker compose --profile all up -d --build mineru-api

该服务在 30001 端口提供 /file_parse 接口，后端 api / worker 默认通过 MINERU_API_URI=http://mineru-api:30001 连接，通常无需额外配置。

::: tip 显存不足 若显存有限导致启动失败，可在 docker-compose.yml 的 mineru-api 服务下放开 --gpu-memory-utilization 参数（如 0.5，必要时进一步降低）。 :::

MinerU Official（云服务）

从 MinerU 官网 获取 API 密钥，在 .env 配置环境变量

MINERU_API_KEY=your-api-key-here

PP-Structure-V3（结构化）

启动服务（需要 GPU）

docker compose up paddlex -d

DeepSeek OCR（简单云服务）

在 .env 配置（使用已有的 SiliconFlow 密钥）

SILICONFLOW_API_KEY=your-api-key-here

PaddleOCR API（百度 AI Studio 云服务）

PaddleOCR API 使用百度 AI Studio 的 Access Token。获取方式：

1. 登录 百度 AI Studio Access Token 页面
2. 在页面中复制 Access Token
3. 在 .env 中配置为 PADDLEOCR_API_TOKEN

PADDLEOCR_API_TOKEN=your-access-token-here

如需使用自定义 PaddleOCR API 地址，可额外配置：

PADDLEOCR_API_URL=https://paddleocr.aistudio-app.com/api/v2/ocr/jobs

配置完成后，重启后端服务，在上传文件或解析临时附件时可以选择：

• PaddleOCR-VL-1.6：对应 paddleocr_vl_1_6，用于文档版面解析，返回 Markdown
• PP-OCRv6：对应 paddleocr_pp_ocrv6，用于基础 OCR，返回按行拼接的纯文本

图片显示配置

上传文档中的图片需要正确配置才能在外部显示：

在 .env 中设置服务器 IP：

HOST_IP=your_server_ip

注意事项

1. 图片文件必须启用 OCR：否则无法提取内容
2. GPU 要求：MinerU 和 PP-Structure-V3 需要 GPU 支持
3. API 密钥：MinerU Official、DeepSeek OCR、PaddleOCR API 等云服务需要额外的 API 密钥或 Access Token 配置
4. 超时处理：复杂文档解析可能耗时较长，可通过 MINERU_TIMEOUT 环境变量调整超时时间
5. 文件大小限制：单个上传文件大小不超过 100 MB