text-extract-api

环境要求

• Docker 与 Docker Compose（用于构建 FastAPI、Celery、Redis、Ollama 服务）
• Python 3（本地源码方式安装时需要，README 使用 python3 -m venv）
• macOS 本地运行需安装 libmagic、poppler、pkg-config、ghostscript、ffmpeg、automake、autoconf
• 磁盘/内存需能容纳 PyTorch 版 EasyOCR 与 Ollama 模型

安装与启动步骤

1. 1获取项目代码

   克隆仓库到本地并进入项目根目录，后续所有命令都在该目录下执行。

   git clone https://github.com/CatchTheTornado/text-extract-api.git
   cd text-extract-api

   复制

2. 2复制环境变量模板

   Docker 部署用 .env.example，本地运行用 .env.example.localhost，默认值一般可直接使用。

   cp .env.example .env

   复制

3. 3修改环境变量

   按需修改 .env 中的 Redis 地址、存储策略路径和 Ollama 视觉提示词等配置。

4. 4Docker 构建并启动

   一条命令启动 FastAPI、Celery Worker、Redis 与 Ollama 四个服务，首次构建耗时较长。

   docker-compose up --build

   复制

5. 5GPU 模式启动

   需要 GPU 加速时改用 gpu 专用 compose 文件，项目前缀设为 text-extract-api-gpu。

   docker-compose -f docker-compose.gpu.yml -p text-extract-api-gpu up --build

   复制

6. 6本地源码安装

   创建虚拟环境、安装依赖并执行 run.sh；run.sh 会通过 Docker 启动 Redis，因此并非完全脱离 Docker。

   python3 -m venv .venv
   source .venv/bin/activate
   pip install -e .
   chmod +x run.sh
   run.sh

   复制

7. 7安装 macOS 依赖

   使用 Homebrew 安装文档解析所需的系统库，仅在 macOS 本地运行时需要。

   brew update && brew install libmagic poppler pkg-config ghostscript ffmpeg automake autoconf

   复制

8. 8启动 Celery Worker

   macOS 本地运行时需另开终端启动 Celery Worker 处理异步 OCR 任务，--pool=solo 适配 Mac。

   source .venv/bin/activate && celery -A text_extract_api.celery_app worker --loglevel=info --pool=solo

   复制

关键配置

如何确认成功

docker-compose 启动后 FastAPI、Celery Worker、Redis、Ollama 四个服务均运行；执行 CLI 的 ocr_upload 命令能返回 OCR 结果即成功。

常见问题

注意事项

• Docker 部署与本地部署使用不同的 env 模板：Docker 用 .env.example，本地运行用 .env.example.localhost。
• 使用 Makefile 可自动创建 .venv 虚拟环境，也可用 DISABLE_VENV=1 关闭该行为。
• 首次 docker-compose 构建会下载 PyTorch 版 EasyOCR 与 Ollama 模型，耗时和体积较大。
• CLI 示例：python client/cli.py ocr_upload --file examples/example-mri.pdf --ocr_cache --prompt_file=examples/example-mri-remove-pii.txt