2026-06-13-pix2text-docker-ocr-markdown

在 Docker 中部署 Pix2Text：本地 OCR 提取图片/PDF 文字并生成 Markdown

在国内网络环境下用 Docker 部署 Pix2Text，实现纯本地 OCR 文字提取和 Markdown 输出，替代昂贵的视觉模型 API。

基本信息

• 来源类型：文章（掘金）
• 原文位置：raw/articles/2026-06-13-131023-tg-91b01e.md
• 原文 URL：https://juejin.cn/post/7649956328409874467
• 消化日期：2026-06-13

核心观点

1. Pix2Text 是视觉模型的低成本替代方案：纯本地运行、不需要 GPU、不需要 API key，支持中英文文字识别（PaddleOCR）、数学公式识别（LaTeX）、表格识别和版面分析，直接输出 Markdown。相比视觉模型 API 按 token 收费且容易”幻觉”，Pix2Text 在纯文字/文档场景下更精准、更快、免费。

2. Docker 隔离是 ML 依赖地狱的最优解：Pix2Text 依赖链极长（ONNX Runtime、PaddleOCR、transformers 等），直接装在系统里容易污染环境。用 Docker 隔离可以做到即开即用、不影响宿主环境。

3. —no-deps + 手动分批装依赖比 pip 自动解析快 10 倍以上：Pix2Text 的依赖树太深，pip 依赖解析器会陷入无限版本回溯（实测等了 20 分钟没解析完）。用 --no-deps 跳过解析，手动分批安装，反而更快更可控。

4. “容器内补装 + commit”是解决依赖地狱的终极技巧：首次构建后在运行中的容器里逐个补装缺失的包，测试通过后 docker commit 为新镜像。这个模式在 ML 项目中非常实用。

5. Pix2Text vs 视觉模型的最佳搭配：纯文字/文档用 Pix2Text 提取，图表/照片用视觉模型理解，混合文档两者配合。Pix2Text 负责”看字”，视觉模型负责”看图”。

实操内容保留

代码/配置

Docker 镜像源配置（Docker Desktop GUI JSON）：

{
  "registry-mirrors": [
    "https://docker.1ms.run",
    "https://docker.xuanyuan.me"
  ]
}

Dockerfile：

FROM python:3.10-slim
 
RUN sed -i 's|deb.debian.org|mirrors.aliyun.com|g' /etc/apt/sources.list.d/debian.sources 2>/dev/null; \
    sed -i 's|deb.debian.org|mirrors.aliyun.com|g' /etc/apt/sources.list 2>/dev/null || true
 
RUN apt-get update && apt-get install -y --no-install-recommends \
    libgl1 libglib2.0-0 libsm6 libxrender1 libxext6 \
    && rm -rf /var/lib/apt/lists/*
 
RUN pip install --no-cache-dir -i https://pypi.tuna.tsinghua.edu.cn/simple \
    pix2text==1.1.6 --no-deps
 
RUN pip install --no-cache-dir -i https://pypi.tuna.tsinghua.edu.cn/simple \
    cnstd cnocr rapidocr opencv-python-headless onnxruntime \
    Pillow numpy scipy pandas matplotlib pymupdf python-docx \
    openpyxl shapely seaborn scikit-image transformers tokenizers \
    safetensors regex huggingface_hub optimum onnx
 
WORKDIR /data
CMD ["python3", "-c", "from pix2text import Pix2Text; print('Pix2Text ready')"]

操作步骤

1. 配置 Docker 镜像源（Docker Desktop GUI → Settings → Docker Engine → 编辑 JSON）
2. 编写 Dockerfile（使用国内 apt/pip 镜像源 + --no-deps 跳过依赖解析）
3. 构建镜像：docker build --network=host -t pix2text:latest .
4. 补装缺失依赖：启动容器 → docker exec 逐个补装 → docker commit 为新镜像
5. 测试 OCR（英文/中文识别）
6. 使用 recognize_page() + to_markdown() 生成 Markdown
7. PDF 多页处理：recognize_pdf() 逐页输出

补装依赖的完整命令：

docker run -d --name p2t pix2text:latest sleep 3600
docker exec p2t pip install -i https://pypi.tuna.tsinghua.edu.cn/simple --no-deps \
    py-cpuinfo pyspellchecker doclayout_yolo tiktoken sentencepiece
docker exec p2t python3 -c "from pix2text import Pix2Text; print('OK')"
docker commit p2t pix2text:latest
docker rm -f p2t

关键概念

• Pix2Text — 开源 Python OCR 工具，基于 PaddleOCR + ONNX Runtime，支持中英文/公式/表格/版面分析
• Docker — 容器化部署工具，用于隔离 Pix2Text 的复杂依赖链
• OCR（光学字符识别）— Pix2Text 的核心能力，从图片/PDF 中提取文字
• PaddleOCR — Pix2Text 底层使用的 OCR 引擎
• ONNX Runtime — Pix2Text 的推理运行时，替代 PyTorch 实现轻量化部署
• 版面分析 — Pix2Text 的高级功能，区分标题/正文/表格/图片区域

与其他素材的关联

• 与 2026-04-29-deepseek-python-local-setup 的关系：两者都涉及本地部署 Python 工具的环境配置，但 Pix2Text 用 Docker 隔离更干净
• 与 AI Agent 生态的关联：Pix2Text 可以为 AI Agent 提供图片文字提取能力，替代昂贵的视觉模型 API，是 Agent 工具链中的实用组件

原文精彩摘录

日常需要处理大量产品图片和 PDF 文档。之前一直用视觉模型来”看”图片，但问题是：贵——每张图都要调 API，按 token 收费；慢——一张图几秒到十几秒；不准——视觉模型经常”幻觉”，把文字认错或遗漏。后来发现了 Pix2Text，最重要的是：纯本地运行，不需要 GPU，不需要 API key。

Pix2Text 的依赖树非常深，pip 的依赖解析器会陷入无限版本回溯（我等了 20 分钟都没解析完）。用 —no-deps 跳过解析，手动分批安装依赖，反而更快。这个”容器内补装 + commit”的技巧在 ML 依赖地狱中非常实用。pip 的依赖解析器在面对复杂的版本约束时经常卡死，但手动安装反而更快。

Pix2Text 的核心 OCR 引擎是 ONNX Runtime（PaddleOCR），不是 PyTorch。只有 LaTeX 公式识别的 LatexOCR 模块需要 PyTorch，但它是可选的。不装 PyTorch 可以省掉 2GB+ 的依赖。

相关页面

• Pix2Text
• Docker
• AI 编程开发