diff --git a/README.md b/README.md index f1c2346..899c0ab 100644 --- a/README.md +++ b/README.md @@ -509,25 +509,123 @@ D:\code\work\ocr-server\.venv\Scripts\python.exe 在 Ubuntu 上,建议使用系统 Python 3.10–3.12 或 uv 创建项目虚拟环境,不会影响系统其他 Python 项目。 -### Windows 7 不支持 +### Windows 7:需要单独的 Python 3.8 构建 -**本服务不能运行在 Windows 7 上**,也不建议为了 Win7 做降级。实测确认的阻断点: +主包(Python 3.12)**无法在 Win7 上运行**:Win7 最高只支持 Python 3.8,exe 启动阶段会报缺 +`api-ms-win-core-path-l1-1-0.dll`(Win8+ 才有)。 -| 层面 | 情况 | +Win7 需要单独构建一版:**纯 CPU**、Python 3.8 + paddlepaddle 3.0.0。项目已经产出过一版: + +```text +dist/ocr-server-win7/ocr-server-win7.exe 约 993 MB(含 398 MB 模型) +``` + +源码改动在分支 **`win7-python38`**(主分支保持 3.12,两者互不影响)。 + +#### 构建步骤 + +**1. 切到 Win7 分支。** 该分支已做 3.8 兼容:所有模块加 `from __future__ import annotations`, +pydantic 模型(`config.py` / `schemas.py`)的注解改成 `Optional/List/Union`——pydantic 会 +运行时求值注解,只加 future import 不够。 + +```bash +git checkout win7-python38 +``` + +**2. 建 Python 3.8 环境并装依赖。** + +```powershell +uv venv --python 3.8 .venv-win7 +uv pip install --python .venv-win7\Scripts\python.exe ^ + "crc32c==2.8" "paddleocr==3.7.0" "paddlepaddle==3.0.0" ^ + "fastapi" "uvicorn[standard]" "pillow" "python-multipart" "pyyaml" "pyinstaller" +``` + +三个版本限制,不要随手升级: + +| 包 | 限制 | 原因 | +| --- | --- | --- | +| `crc32c` | 必须 `2.8` | 更新的 2.9.post0 在 cp38 没有 Windows 轮子,会触发源码编译并失败 | +| `paddlepaddle` | 只能 `3.0.0` | 3.2.x 没有 cp38 轮子 | +| `uvicorn` | 会解析到 `0.33` | `>=0.34` 要求 Python >=3.9 | + +**3. 打包(必须排除 `bidi` 和 `watchfiles`)。** + +```powershell +.venv-win7\Scripts\python.exe -m PyInstaller --noconfirm --clean --onedir ^ + --name ocr-server-win7 --distpath dist --paths src ^ + --exclude-module bidi --exclude-module watchfiles ^ + --collect-all paddleocr --collect-all paddlex --collect-all paddle ^ + --collect-all cv2 --collect-all PIL --collect-all pyclipper ^ + --collect-all pypdfium2 --collect-all shapely ^ + --hidden-import paddlex.inference.models.text_detection.processors ^ + --copy-metadata paddlex --copy-metadata paddleocr ^ + --copy-metadata paddlepaddle --copy-metadata imagesize ^ + --add-data "config.yaml;." --add-data "http;http" ^ + --additional-hooks-dir scripts ^ + --hidden-import imagesize --hidden-import imagesize.imagesize ^ + --hidden-import ocr_server.app --hidden-import ocr_server.config ^ + scripts/packaged_entry.py +``` + +> 为什么排除这两个:它们的原生扩展依赖 `api-ms-win-core-synch-l1-2-0.dll`(Win8+), +> 在 Win7 上加载会失败。`watchfiles` 只在 `uvicorn --reload` 用;`bidi` 只用于阿拉伯语等 +> RTL 模型的显示,中文识别用不到(源码里已去掉对它的强制可用性检查)。 + +**4. 后处理(三步都不能漏)。** + +```powershell +# 纯 CPU + 模型随包自带 +python scripts/prepare_release_config.py config.yaml dist/ocr-server-win7/config.yaml "device=cpu" "model_dir=models" +# 复制模型 +cp -r models dist/ocr-server-win7/models +# 删掉包内的 ucrtbase.dll,改用系统版 +Remove-Item dist/ocr-server-win7/_internal/ucrtbase.dll +``` + +> 包内那份 `ucrtbase.dll` 来自较新的 Windows SDK,依赖 `api-ms-win-core-*-l1-2-0`(Win8+)。 +> 删掉后由系统的 UCRT 接管(前提是目标机装了 KB2999226,见下)。 + +#### 目标机要求 + +- **Win7 SP1 + KB2999226**(Universal C Runtime),或直接安装 **VC++ 2015-2022 运行库**。 +- **纯 CPU**:Win7 的 NVIDIA 驱动最高只到 472,而 CUDA 11.8 需要 520+,GPU 版不可用。 +- 解压到普通目录再运行,例如 `D:\ocr-server-win7`。 + +#### 常见问题 + +**`Cannot open file ...\models\official_models\PP-OCRv5_server_det\inference.json`** + +能报出这个说明程序已经启动、并跑到推理阶段了,只是模型文件没找到。按顺序排查: + +1. 确认 `models` 目录拷完整了。`official_models/PP-OCRv5_server_det/` 下必须有四个文件: + `config.json`、`inference.yml`、`inference.json`、`inference.pdiparams`。 + + ```bat + dir "D:\ocr-server-win7\models\official_models\PP-OCRv5_server_det" + ``` + +2. 不要直接在浏览器的下载目录里运行(例如 `C:\...浏览器下载\`),先解压/复制到普通目录。 +3. **中文路径本身不是问题**——同版本包放在中文目录下实测可正常识别(34 框)。 + 优先怀疑文件没拷全。 + +#### 备份与回退 + +Win7 构建只用独立的 `.venv-win7`,不影响 `.venv` / `.venv-gpu`。回退只需删除 `.venv-win7`。 + +完整构建环境记录在 `backups/env-win7-2026-10-19/`: + +| 文件 | 内容 | | --- | --- | -| Python | Win7 最高只支持 Python **3.8**(3.9 起官方不再支持 Win7),本项目要求 `>=3.10` | -| 打包产物 | exe 内嵌 CPython 3.12,在 Win7 上启动即失败(缺 `api-ms-win-core-path-l1-1-0.dll`) | -| `paddlepaddle` | 3.2.x **没有 cp38 轮子**,3.8 上最高只能用 3.0.0 | -| Web 栈 | `uvicorn>=0.34` 要求 Python >=3.9,整条栈都要降版本 | -| 本项目的代码 | 有 120+ 处 3.9/3.10+ 注解语法,其中 pydantic 模型必须真正改写(不能只加 `from __future__ import annotations`) | -| GPU | **不可行**:CUDA 11.8 需要 520+ 驱动,Win7 最后只支持到 472 | +| `BUILD-NOTES.md` | 构建配方、兼容性检查结果、已知坑 | +| `freeze-win7.txt` | 85 个包的精确版本 | +| `versions.txt` | 关键版本一览 | -**推荐架构**:把服务跑在 Win10+ 或 Linux 机器上,Win7 只当客户端——用浏览器打开 -`scripts/GUI.html`,或调用 HTTP 接口。Win7 上需要 Chrome 109(最后一个支持 Win7 的 -版本)或 Firefox 115 ESR;**IE11 不行**(不支持 `fetch`、可选链、`async/await`)。 +#### 更省事的替代方案 -如果必须在 Win7 本机跑,那是一次完整移植(降 Python、降 Paddle、降 Web 栈、改注解), -且最终兼容性只能在 Win7 实机上验证。 +如果 Win7 那台机器只是**使用方**,不必本机跑 OCR:把服务放在 Win10+ / Linux 机器上, +Win7 用浏览器打开 `scripts/GUI.html` 即可(需要 Chrome 109 或 Firefox 115 ESR; +**IE11 不行**,不支持 `fetch`、可选链、`async/await`)。 ## Windows 安装和启动