基于 ddddocr 模型的验证码识别 HTTP 服务，纯 Python 实现，使用 ONNX Runtime 推理。提供 Web 演示页面、HTTP API、Python 库和测试工具。
衍生自 Mieru-OCR (浏览器扩展版) 和 ddddocr，移植为纯 Python 版本。
- 🚀 一键 Docker 部署，开箱即用
- 🌐 内置 Web 演示页面（
/），支持中英文与亮暗主题切换 - 🔒 可选 API 密钥验证（生产环境推荐）
- 🖼️ 支持 PNG / JPEG / GIF / BMP / WEBP，多种输入方式
- ⚡ 平均识别耗时 ~30ms（CPU 推理）
- 🐍 也可作为 Python 库直接调用
# 本地测试（不启用密钥，公开访问）
docker compose up -d
# 测试服务
curl http://localhost:3210/health
# {"status":"ok"}生产环境启用 API 密钥验证：
# 1. 拷贝模板并生成密钥（直接替换原行，避免重复）
cp .env.example .env
sed -i "s|^OCR_API_KEY=.*|OCR_API_KEY=$(openssl rand -hex 32)|" .env
# 2. 启动
docker compose up -d或一次性传入：
OCR_API_KEY=$(openssl rand -hex 32) docker compose up -d替换为自定义模型：
docker run -d -p 3210:3210 \
-v $(pwd)/my_model.onnx:/app/public/common.onnx:ro \
-v $(pwd)/my_charsets.json:/app/public/charsets.json:ro \
captcha-ocr-server# 需要 Python 3.10 ~ 3.12 (onnxruntime 暂不支持 3.14)
pip install -r requirements.txt
# 启动服务
python -m mieru_ocr.server # 公开访问
python -m mieru_ocr.server --api-key "your-secret-key" # 启用密钥
python -m mieru_ocr.server --host 127.0.0.1 --port 8080 # 自定义地址
python -m mieru_ocr.server --log-level DEBUG # 调试日志
python -m mieru_ocr.server --log-file /var/log/ocr.log # 日志写入文件
python -m mieru_ocr.server --no-demo # 禁用演示页面所有接口在 POST /ocr，响应格式：
{ "text": "识别结果", "time_ms": 23 }URL 模式（GET ?url= / POST {"url": "..."}）额外返回服务端实际拉取的图片，避免验证码刷新导致预览与结果错位：
{ "text": "识别结果", "time_ms": 23, "image": "data:image/png;base64,..." }# 0. 浏览器打开演示页面
# 访问 http://localhost:3210/ 即可使用图形界面识别验证码
# 1. 直接传图片二进制（推荐，最简单）
curl -X POST http://localhost:3210/ocr \
-H "Content-Type: image/png" \
--data-binary @captcha.png
# 2. JSON + Base64
curl -X POST http://localhost:3210/ocr \
-H "Content-Type: application/json" \
-d '{"image": "<base64编码>"}'
# 3. JSON + URL（服务端去拉图片）
curl -X POST http://localhost:3210/ocr \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/captcha.png"}'
# 4. GET + URL（最轻量）
curl "http://localhost:3210/ocr?url=https://example.com/captcha.png"
# 健康检查
curl http://localhost:3210/health启用 OCR_API_KEY 后，调用时需带上密钥（三选一）：
# Authorization Bearer
curl -H "Authorization: Bearer your-secret-key" ...
# X-API-Key Header
curl -H "X-API-Key: your-secret-key" ...
# Query 参数
curl "http://localhost:3210/ocr?url=...&api_key=your-secret-key"未带密钥返回 401，密钥错误返回 403。
from mieru_ocr import OCREngine
engine = OCREngine("public/common.onnx", "public/charsets.json")
# 多种输入
text = engine.recognize("captcha.png") # 文件路径
text = engine.recognize("https://example.com/captcha.png") # URL
text = engine.recognize(image_bytes) # bytes
text = engine.recognize(pil_image) # PIL Image
# 带耗时
text, ms = engine.recognize("captcha.png", return_time=True)
# 批量识别
results = engine.recognize_batch(["1.png", "2.png"])随机生成验证码图片，统计完全匹配率和字符准确率：
python benchmark.py --count 200 --warmup 5从指定 HTTP 接口拉验证码图片，识别后生成可视化校验页面：
# 只输出识别结果到终端
python captcha_test.py --count 50 --url http://example.com/captcha/
# 同时保存图片和生成 HTML 人工校验页面
python captcha_test.py --count 50 --url http://example.com/captcha/ --out ./review
# 用浏览器打开 review/review.html
# 快捷键: Enter=正确 X=错误 S=跳过 统计按钮看准确率mieru_ocr/
__init__.py # 导出 OCREngine
engine.py # 核心引擎（加载模型 + 识别 + 批量识别）
image_processor.py # 图片预处理（灰度化/缩放/归一化）
decoder.py # CTC greedy 解码
logger.py # 统一日志（彩色控制台 + 可选文件输出）
server.py # FastAPI HTTP 服务 + 密钥验证 + 演示页面
static/
index.html # Web 演示页面（中英文 + 亮暗主题）
public/
common.onnx # DDDDOCR 模型 (28 MB)
charsets.json # 字符集 (8210 个)
__main__.py # python -m mieru_ocr 入口
benchmark.py # 本地跑分
captcha_test.py # 远程接口测试
Dockerfile # 镜像构建
docker-compose.yml # 一键部署
.env.example # 环境变量模板
requirements.txt # Python 依赖
| 配置项 | 命令行参数 | 环境变量 | 默认值 |
|---|---|---|---|
| 监听地址 | --host |
— | 0.0.0.0 |
| 监听端口 | --port / -p |
PORT（compose） |
3210 |
| 模型路径 | --model / -m |
— | public/common.onnx |
| 字符集路径 | --charsets / -c |
— | public/charsets.json |
| API 密钥 | --api-key |
OCR_API_KEY |
无（公开访问） |
| 日志级别 | --log-level |
LOG_LEVEL |
INFO |
| 日志文件 | --log-file |
LOG_FILE |
无（仅控制台） |
| 禁用演示页面 | --no-demo |
— | 演示页面启用 |
MIT License — 沿用原 ddddocr 项目许可证
- ddddocr — 原始 OCR 模型
- onnxruntime — 模型推理
- Mieru-OCR — 浏览器扩展版本，本项目的源头