# python-ocr

**Repository Path**: a304885433/python-ocr

## Basic Information

- **Project Name**: python-ocr
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-27
- **Last Updated**: 2026-04-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PaddleOCR API Demo

这个项目基于 `PaddleOCR` 和 `FunASR` 提供了两个入口：

- 一个命令行脚本，用于快速本地验证
- 一个 HTTP API 服务，用于文件上传识别、样本回归识别，适合容器部署

接口保持不变，仍然使用：

- `GET /`
- `GET /health`
- `GET /sample-files`
- `POST /sample-files/recognize`
- `POST /ocr`
- `POST /ocr/pdf`
- `POST /asr`
- `GET /docs`

## 文件说明

- `api.py`：FastAPI 服务入口
- `ocr_core.py`：PaddleOCR 加载与识别逻辑
- `asr_core.py`：FunASR 加载与音频转写逻辑
- `sample_service.py`：`static/files` 样本文件扫描、自动识别与结果落盘
- `demo.py`：命令行 demo
- `Dockerfile`：镜像构建脚本
- `docker-compose.yml`：本地容器编排脚本
- `tests/test_sample_files.py`：样本文件自动识别单测
- `API_JAVA.md`：Java 调用接口文档和代码段

## 本地运行

### 1. 创建虚拟环境

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
```

### 2. 安装依赖

```bash
pip install -r requirements.txt
```

### 3. 启动 API

```bash
uvicorn api:app --host 0.0.0.0 --port 8000
```

启动后可访问：

- `GET /`：静态测试页面
- `GET /health`
- `GET /sample-files`
- `POST /sample-files/recognize`
- `POST /ocr`
- `POST /ocr/pdf`
- `POST /asr`
- `GET /docs`
- `GET /service-info`

### 4. 浏览器测试

打开：

```bash
http://127.0.0.1:8000/
```

页面里可以直接上传图片 OCR、PDF 识别、音频 ASR 文件，也可以点击 `static/files/` 样本做回归识别，并查看主要结果与原始 JSON。

### 4.1 样本目录约定

把要测试的素材统一放到：

```bash
static/files/
```

页面会自动列出这个目录下支持的文件类型：

- 图片：`png/jpg/jpeg/bmp/webp/tif/tiff`
- PDF：`pdf`
- 音频：`wav/mp3/m4a/aac/flac/ogg`

点击文件后，服务会自动识别，并把主结果写回同目录同名 `.txt` 文件。

例如：

```text
static/files/租赁合同.pdf
static/files/租赁合同.txt
```

### 5. 调用 API

```bash
curl -X POST "http://127.0.0.1:8000/ocr" \
  -F "file=@test.png" \
  -F "langs=ch_sim,en" \
  -F "detail=1" \
  -F "paragraph=false" \
  -F "gpu=false"
```

返回结果格式保持和之前一致：

```json
{
  "filename": "test.png",
  "langs": ["ch_sim", "en"],
  "detail": 1,
  "paragraph": false,
  "gpu": false,
  "count": 2,
  "texts": ["Hello", "世界"],
  "result": [
    [[[10, 10], [80, 10], [80, 30], [10, 30]], "Hello", 0.99],
    [[[90, 10], [150, 10], [150, 30], [90, 30]], "世界", 0.98]
  ]
}
```

### 6. 调用 PDF 接口

`/ocr/pdf` 会优先直接提取 PDF 文本层；如果某一页提取不到文本，再自动把该页转成图片走 OCR。

```bash
curl -X POST "http://127.0.0.1:8000/ocr/pdf" \
  -F "file=@demo.pdf" \
  -F "langs=ch_sim,en" \
  -F "detail=1" \
  -F "paragraph=false" \
  -F "gpu=false" \
  -F "force_ocr=false"
```

返回示例：

```json
{
  "filename": "demo.pdf",
  "langs": ["ch_sim", "en"],
  "detail": 1,
  "paragraph": false,
  "gpu": false,
  "force_ocr": false,
  "page_count": 2,
  "count": 4,
  "texts": ["第一页内容", "第二页内容"],
  "pages": [
    {
      "page_number": 1,
      "mode": "text",
      "count": 2,
      "texts": ["第一页内容"],
      "result": [[[], "第一页内容", null]]
    }
  ]
}
```

如果你想强制把整份 PDF 每页都走 OCR，而不是读文本层：

```bash
curl -X POST "http://127.0.0.1:8000/ocr/pdf" \
  -F "file=@demo.pdf" \
  -F "force_ocr=true"
```

### 7. 调用语音识别接口

`/asr` 用于上传音频文件做语音识别，底层使用 FunASR。

说明：

- 默认模型是中文通用大模型，首次加载会比 OCR 慢
- 代码会优先从本地 `MODELSCOPE_CACHE` 读取模型缓存，再回退到显式 ModelScope 模型 ID
- 如果镜像构建阶段已经预下载模型，运行时可以在无外网环境下直接启动

```bash
curl -X POST "http://127.0.0.1:8000/asr" \
  -F "file=@demo.wav" \
  -F "language=auto" \
  -F "with_punc=true" \
  -F "with_vad=true" \
  -F "hotwords=费用报销,信创Java" \
  -F "gpu=false"
```

返回示例：

```json
{
  "filename": "demo.wav",
  "language": "auto",
  "with_punc": true,
  "with_vad": true,
  "gpu": false,
  "text": "这是语音识别结果。",
  "segments": [],
  "result": [
    {
      "text": "这是语音识别结果。"
    }
  ]
}
```

## 命令行 demo

```bash
python demo.py test.png
```

只返回文字内容：

```bash
python demo.py test.png --detail 0
```

## 自动化测试

直接跑样本单测：

```bash
python -m unittest tests.test_sample_files
```

这个测试会扫描 `static/files/`，自动识别每个样本，并把结果写入同目录同名 `.txt`。

## Docker 运行

### 构建镜像

```bash
docker build -t paddleocr-api .
```

默认会在构建阶段预下载 `ch_sim,en` 对应的 PaddleOCR 模型，镜像启动后不再依赖外网。
当前 `Dockerfile` 也已经内置了国内加速配置：

- `apt` 默认走 `mirrors.aliyun.com`
- `pip` 默认走 `https://mirrors.aliyun.com/pypi/simple/`
- 默认也会在构建阶段预下载 FunASR 模型

如果你只想预置英文模型，可以改成：

```bash
docker build --build-arg PADDLEOCR_PRELOAD_LANGS=en -t paddleocr-api .
```

如果你不想在构建阶段预下载语音模型：

```bash
docker build --build-arg FUNASR_PRELOAD=false -t paddleocr-api .
```

如果你要切换镜像源，也可以覆盖构建参数：

```bash
docker build \
  --build-arg APT_MIRROR_HOST=mirrors.tuna.tsinghua.edu.cn \
  --build-arg PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple \
  -t paddleocr-api .
```

### 启动容器

```bash
docker run --rm -p 8000:8000 \
  -e PADDLE_HOME=/app/.paddle \
  -e PADDLE_PDX_CACHE_HOME=/app/.paddlex \
  -e PADDLE_PDX_MODEL_SOURCE=BOS \
  -e PADDLE_PDX_DISABLE_MODEL_SOURCE_CHECK=True \
  -e PADDLEOCR_DOWNLOAD_ENABLED=false \
  paddleocr-api
```

注意：如果你再挂载空的 volume 到 `/app/.paddle` 或 `/app/.paddlex`，会把镜像里已经预置的模型覆盖掉。

## Docker Compose 运行

```bash
docker compose up --build
```

服务默认监听 `8000` 端口，启动后直接访问：

```bash
http://127.0.0.1:8000/
```

## 环境变量

- `PADDLE_HOME`：Paddle 模型缓存目录，容器里默认使用 `/app/.paddle`
- `PADDLE_PDX_CACHE_HOME`：PaddleX 缓存目录，容器里默认使用 `/app/.paddlex`
- `PADDLE_PDX_MODEL_SOURCE`：模型下载源，默认设置为 `BOS`
- `PADDLE_PDX_DISABLE_MODEL_SOURCE_CHECK`：跳过模型源连通性预检查，默认 `True`
- `PADDLEOCR_DOWNLOAD_ENABLED`：是否允许自动下载模型，镜像运行时默认 `false`
- `PADDLEOCR_PRELOAD_LANGS`：镜像构建阶段预下载的语言列表，默认 `ch_sim,en`
- `MODELSCOPE_CACHE`：FunASR / ModelScope 模型缓存目录，默认 `/app/.modelscope`
- `HF_HOME`：HuggingFace 缓存目录，默认 `/app/.hf`
- `FUNASR_PRELOAD`：是否在构建阶段预下载 FunASR 模型，默认 `true`
- `FUNASR_MODEL`：ASR 模型，默认 `iic/speech_seaco_paraformer_large_asr_nat-zh-cn-16k-common-vocab8404-pytorch`
- `FUNASR_VAD_MODEL`：VAD 模型，默认 `iic/speech_fsmn_vad_zh-cn-16k-common-pytorch`
- `FUNASR_PUNC_MODEL`：标点恢复模型，默认 `iic/punc_ct-transformer_cn-en-common-vocab471067-large`

## 注意事项

- 当前镜像默认在 `docker build` 阶段预下载模型，所以运行容器时不需要外网。
- 预下载会让镜像构建更慢、镜像体积更大，但更适合内网部署。
- `PyMuPDF` 只负责 PDF 文本提取和页面渲染，不依赖外部服务。
- `ffmpeg` 已经加进容器，便于处理常见音频格式。
- 本地直接跑 Python 服务时，如果宿主机没装 `ffmpeg`，FunASR 仍可通过 `torchaudio` 读取常见 wav 音频。
- 当前 `Dockerfile` 默认走 CPU 推理，没有配置 CUDA。
- `gpu=true` 只有宿主机和镜像里的 Paddle 推理环境支持 GPU 时才应该开启。