docs: 修正 Win7 模型加载失败的原因(中文路径 + GBK 编码)

原文档写「中文路径本身不是问题」,这个结论是错的:本机 Win11 开启了
UTF-8 系统编码(ACP=65001),中文路径能跑;Win7 默认 ACP=936(GBK),
Paddle 的 C++ 层用 ANSI 接口做文件存在性检查,会把中文路径判成「不存在」。

判断依据:程序只会在四个模型文件齐全时才去加载本地模型(_is_complete_model
用 Python 的 is_file(),它通过了),而 Paddle 的 IsFileExists 返回 0 ——
Python 看得到、C++ 看不到,是编码不一致,不是文件缺失。

更正后的排查顺序:首要原因是安装路径含中文,把包放到纯英文路径
(如 D:\ocr-server-win7)即可;确实无法避免时,把模型复制到英文目录并
在 config.yaml 里把 model_dir 指过去。

Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
zimoyin
2026-10-19 01:08:23 +08:00
parent 94b2432f09
commit f4b7e250a8
+18 -9
View File
@@ -596,18 +596,27 @@ Remove-Item dist/ocr-server-win7/_internal/ucrtbase.dll
**`Cannot open file ...\models\official_models\PP-OCRv5_server_det\inference.json`**
能报出这个说明程序已经启动、并跑到推理阶段了,只是模型文件没找到。按顺序排查:
⚠️ **首要原因是安装路径里有中文**,不是模型缺失。Win7 的 ANSI 代码页是 GBK(936),
而 Paddle 的 C++ 层用 ANSI 接口做文件存在性检查:`IsFileExists()` 返回 0,
于是报「打不开」。
1. 确认 `models` 目录拷完整了。`official_models/PP-OCRv5_server_det/` 下必须有四个文件:
`config.json`、`inference.yml`、`inference.json`、`inference.pdiparams`。
判断依据:程序只会在这四个文件都齐全时才去加载本地模型(`_is_complete_model()` 用的是
Python 的 `is_file()`),也就是说 **Python 认为文件存在、Paddle 的 C++ 层却认为不存在**——
这是路径编码不一致,不是文件没拷全。
```bat
dir "D:\ocr-server-win7\models\official_models\PP-OCRv5_server_det"
```
**解决:把整个包放到纯英文路径下再运行**,例如:
2. 不要直接在浏览器的下载目录里运行(例如 `C:\...浏览器下载\`),先解压/复制到普通目录。
3. **中文路径本身不是问题**——同版本包放在中文目录下实测可正常识别(34 框)。
优先怀疑文件没拷全。
```text
D:\ocr-server-win7\ocr-server-win7.exe
```
不要放在 `C:\360极速浏览器X下载\`、`C:\Users\张三\Desktop\` 这类含中文的目录。
> 为什么开发和测试时没发现:本机 Win11 开启了「Beta: 使用 Unicode UTF-8 提供全球语言支持」
> (系统 ACP = 65001),中文路径在那种环境下能正常工作;Win7 默认 ACP = 936,行为不同。
>
> 如果确实无法避免中文路径,可以先把模型复制到纯英文目录,再把 `config.yaml` 的
> `model_dir` 指过去,例如 `model_dir: D:\ocr-models`。
#### 备份与回退