text-extract-api：给文档装上"全能翻译眼"

一封 MRI 报告引发的技术冲动

想象一个场景：放射科医生收到一份 PDF 格式的 MRI 报告，需要快速提取其中关键指标并录入系统；法务人员收到一批扫描版合同，需要去掉其中的姓名、身份证号再分发给团队审阅；研究员收到数百篇 PDF 论文，需要批量转成可检索的文本用于 RAG 系统。

这些看似简单的"复制粘贴"操作，在真实世界中充满了格式混乱——有的文档是扫描件（纯图片），有的文档混着表格和数学公式，有的语言夹杂特殊字符。传统 OCR 工具要么识别不准，要么输出乱码，更别说在同一个接口里完成"提取 → LLM 修正 → 去隐私化 → 存结构化 JSON"的全链路处理。

text-extract-api 正是为解决这些痛点而生的。它是一个本地化运行的文档解析 API 服务，能将 PDF、Word、图片等任意文档转换为高精度的 Markdown 文本或结构化 JSON，同时支持基于 Ollama 本地大模型的 LLM 增强校正和 PII 脱敏处理。不同于依赖云端 API 的方案，所有数据处理都在本地完成，真正实现了"数据不出门"。

图1：MRI 报告转 Markdown + JSON 效果示例

背景：为什么需要本地化文档解析？

文档解析并非新鲜需求，但随着 RAG（检索增强生成）系统的广泛部署，开发者对"高质量文档转文本"的需求急剧增长。传统的云端 OCR API（如 Google Vision、Azure Computer Vision）存在几个固有问题：

数据隐私风险是首要考量。医疗文档、法律合同、财务报表一旦上传到第三方平台，就面临数据泄露合规风险。欧盟 GDPR、国内《个人信息保护法》对敏感数据跨境处理有严格限制，企业在选型时不得不三思。text-extract-api 的核心设计哲学正是"零外部依赖"——EasyOCR（PyTorch OCR）和 Ollama 本地模型都在 Docker 环境内运行，没有任何数据流向外部服务器。

成本与延迟同样不容忽视。按 API 调用次数计费的云端 OCR 在大批量文档处理场景下成本迅速膨胀，而本地 Ollama 模型调用几乎没有边际成本。对于日处理量达数万份文档的企业用户，本地化方案可以将单页成本降低 95% 以上。

离线场景是另一个真实需求。许多政务系统、制造业内网、医院信息系统运行在物理隔离的内网环境中，根本无法访问外部 API。本地化部署的 text-extract-api 完美契合这类场景。

图2：发票 PDF 提取并自动去除个人身份信息（PII）的效果

核心功能：一条 API，解决四类问题

text-extract-api 的功能设计围绕四个核心场景展开，每个场景都有对应的技术实现：

多格式文档转 Markdown：支持 PDF、Word（.docx）、PPT、图片（JPG/PNG/TIFF）等多种格式。通过 EasyOCR（基于 PyTorch 的深度学习 OCR）、Docling（文档结构化解析）、MiniCPM-V（国产端侧多模态模型）以及 marker-pdf（远程渲染方案）等多种策略，用户可按需选择最优提取方案。其中 marker-pdf 通过无头浏览器渲染 PDF 后再识别，对复杂排版效果尤佳。

结构化 JSON 输出：通过 Ollama 本地大模型（如 llama3.1）将提取的文本进一步结构化。用户只需提供一段 prompt（如"提取发票中的金额、日期、买方、卖方"），模型即可返回格式规整的 JSON，无需编写规则引擎。这对于下游的 ERP 系统、数据仓库导入极为友好。

LLM 纠错增强：原始 OCR 输出常有错字、漏行问题。将 OCR 结果再次送入 Ollama 模型进行"拼写检查 + 语义补全"，可显著提升最终文本质量。这一步是可选项，但开启后对扫描质量较差的文档效果提升明显。

PII 脱敏处理：提供 examples/ 目录下的 prompt 示例，指示模型识别并替换人名、身份证号、手机号、银行账号等敏感信息。脱敏后的文档可用于公开数据集构建、内部培训材料制作等场景，是隐私合规工作流中的关键一环。

图3：text-extract-api 系统架构图，展示了 OCR 策略引擎、Celery 异步队列和 Ollama LLM 增强的处理流程

技术架构：FastAPI + Celery 的异步 OCR 流水线

深入代码层面，text-extract-api 的架构设计体现了良好的工程素养：

API 层基于 FastAPI 构建，提供标准的 REST 接口。核心端点 /ocr 接收文件上传和策略参数（strategy、model、prompt 等），立即返回 task_id，耗时操作在后台异步执行。这避免了长连接超时问题，同时支持高并发场景。

异步任务层使用 Celery + Redis 实现。Celery 是 Python 生态最成熟的分布式任务队列框架，支持水平扩展。docker-compose.yml 中配置了 celery_worker 服务，可以部署多个实例来提升并行处理能力。Redis 既充当 Celery 的消息代理（broker），也作为 OCR 结果缓存层——相同文件的二次提取直接从 Redis 读取，节省重复计算。

OCR 策略引擎采用了经典的策略模式（Strategy Pattern）：在 extract/strategies/ 目录下，每个策略实现一个统一的 Strategy 接口。现有的策略包括：

• easyocr.py：基于 PyTorch 的本地深度学习 OCR，GPU 加速，对印刷体和手写体均有良好识别率
• docling.py：基于 Docling 库的文档结构化解析，擅长保留表格、标题层级结构
• ollama.py：调用 Ollama 视觉模型进行端到端识别，适用于高质量 PDF
• remote.py：代理到 marker-pdf 等远程服务，适合内网无法运行 heavy OCR 的场景
• docling.py：文档深度解析，可提取页面布局信息

文件格式抽象层在 files/file_formats/ 目录下，FileFormat 类负责根据文件魔数和扩展名判断真实文件类型，避免上传重命名绕过安全检查。支持的格式包括 PDF、图片（JPG/PNG/TIFF/WebP）、Office 文档（Word/PPT/Excel）。

存储策略通过 StorageManager 和 storage_profiles/ 配置文件实现，支持本地文件系统、Google Drive 等多种存储后端，便于集成到企业现有的文档管理系统中。

上手体验：docker-compose 一键启动

部署 text-extract-api 的门槛相当低。项目提供了完整的 docker-compose.yml，包含 FastAPI 应用、Celery Worker、Redis 和 Ollama 四个服务，一条命令即可启动：

git clone https://github.com/CatchTheTornado/text-extract-api.git
cd text-extract-api
cp .env.localhost.example .env.localhost
make install && make run

Ollama 首次启动时会自动拉取默认模型（约 4-7GB），需确保网络畅通。Mac 用户由于 Apple GPU 不被 Docker 支持，需要在宿主机单独安装 Ollama，并通过 OLLAMA_HOST 环境变量连接。如果对 OCR 精度要求更高（如处理中文文档），建议替换为支持中文的模型。

API 调用的典型流程：上传 PDF → 获取 task_id → 轮询 /ocr/result/{task_id} 获取结果。整个流程有完整的 CLI 客户端 client/cli.py 可参考：

python client/cli.py ocr_upload --file examples/example-mri.pdf --prompt_file examples/example-mri-2-json-prompt.txt

局限与挑战：本地模型的甜蜜与苦涩

任何技术都有其边界，text-extract-api 的局限主要来自本地化路线本身的取舍：

GPU 是性能关键。EasyOCR 和 Ollama 模型在 CPU 上运行极其缓慢——一个 10 页的 PDF 在 CPU 模式下可能需要数分钟，而配备 NVIDIA GPU 的情况下通常在 30 秒内完成。项目文档虽然提到"CPU 可降级运行"，但实际上没有独显的用户体验会大打折扣。这对于个人开发者和小型团队是一个隐性门槛。

模型质量参差不齐。Ollama 生态中的视觉模型（llama3.2-vision、minicpm-v 等）各有优劣，在不同文档类型上表现差异显著。用户需要根据实际文档特点反复调优 prompt 和模型选择，目前缺乏开箱即用的"最佳实践配置"。对非技术用户而言，配置成本偏高。

中文 OCR 精度有待提升。EasyOCR 对英文印刷体识别率极高，但中文场景下错字率明显上升。虽然理论上可以通过 Ollama 的 LLM 纠错环节补救，但这引入了额外延迟和 token 消耗。

安全扫描覆盖有限。项目虽然有 test_security_fix.py 专项测试文件，47 个 open issues 中也包含若干安全问题（如文件类型检测绕过、路径遍历风险），但整体安全审计覆盖面仍有提升空间。在处理恶意构造的畸形文件时需要额外谨慎。

行业意义：从工具到工作流的跃迁

text-extract-api 不是一个孤立的 OCR 工具，它代表了一个趋势——将 AI 能力本地化、工程化、流水线化。在 RAG 系统井喷的当下，文档解析是整个流水线中最脏、最费时的环节。text-extract-api 通过统一的 API 接口和可插拔的策略引擎，把这个环节从"定制开发"变成了"配置即用"。

同时，项目对 PII 脱敏的关注反映了 AI 应用落地的真实合规需求。随着各国数据保护法规日趋严格，"先脱敏再处理"的工作流将成为标配，而非可选项。本地化 + 脱敏的组合拳，使 text-extract-api 在医疗、法律、金融等高敏感行业具有独特的应用价值。

GitHub 上 3100+ 的 Stars 和持续的版本迭代也印证了社区的认可度。项目采用 MIT 许可证，商业使用无限制，生态正处于活跃增长期。