安装PaddlePaddle进行本地OCR教程及避坑指南

✅ Anaconda 创建新环境（OCR项目PaddlePaddle）

Windows 下打开 Anaconda Prompt（不要普通cmd），mac/linux直接终端

1. 基础创建命令

复制代码

# -n 就是 --name，后面是环境名字
conda create -n games python=3.10

👉 python版本推荐 3.10 ，这三个OCR库兼容性最好，不容易炸protobuf 回车后会列出要安装的包，输入 y 确认下载

2. 激活环境（必须激活之后再pip装包！）

复制代码

conda activate games

激活成功：命令行前面会出现 (games) 标记

3. 在这个独立环境里面安装OCR（国内阿里云镜像）

复制代码

# PaddleOCR
pip install paddlepaddle -i [https://mirrors.aliyun.com/pypi/simple](https://mirrors.aliyun.com/pypi/simple)
pip install paddleocr -i [https://mirrors.aliyun.com/pypi/simple](https://mirrors.aliyun.com/pypi/simple)

✅ 好处：所有包只装在 ocr_env 里面，完全不污染你原来base或者别的项目环境，解决你之前担心的依赖冲突

📌 配套常用conda命令（日常管理）

复制代码

# 查看全部已有环境
conda env list
# 退出当前环境，回到base
conda deactivate
# 删除整个环境（彻底清空，出问题直接删掉重建）
conda remove -n ocr_env --all
# 克隆一份环境（备份用）
conda create -n ocr_env_bak --clone ocr_env

⚡ 加速建议（国内必配，下载快很多）

清华conda源，在base里面执行一次即可全局生效：

复制代码

conda config --add channels [https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main](https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main)
conda config --add channels [https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/r](https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/r)
conda config --set show_channel_urls yes
conda clean -i

📝 VSCode关联这个conda环境

VSCode打开你的代码文件夹
Ctrl+Shift+P → Python: Select Interpreter
找到 games 下面的python.exe，选中，运行代码就会在这个隔离环境跑OCR

📝 PaddlePaddle（飞桨，当前正式版 3.3）

** 官方文档写明 Windows pip 包最高支持 Python 3.13 ，支持版本：3.9 / 3.10 / 3.11 / 3.12 / 3.13飞桨Pad...

⚠️ 3.13 属于比较新的支持，虽然能装，但社区踩坑案例少；生产脚本不优先选

如果conda 源（清华源）里，python=3.10 对应的 openssl 版本要求，和仓库里能找到的 openssl 包版本对不上、互相冲突，解包器找不到一套兼容的组合，环境创建失败，则重新设置源：

复制代码

# 先查看当前配置
conda config --show channels
# 移除defaults，很多时候冲突来自defaults源
conda config --remove-key channels
# 重新只添加清华main源
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main
conda config --set show_channel_urls yes
# 再创建环境
conda create -n games python=3.10

安装PaddleOCR

复制代码

# PaddleOCR
pip install paddlepaddle -i https://mirrors.aliyun.com/pypi/simple
pip install paddleocr -i https://mirrors.aliyun.com/pypi/simple

后续可能用到的命令备忘：

复制代码

# 退出环境回到base
conda deactivate

# 查看所有conda环境
conda env list

# 如果以后这个环境彻底玩坏了，一键删除重建
conda remove -n games --all

PaddleOCR 3.7.0 本地模型部署：问题复盘 + 正确步骤

一、踩过的坑及解决方案

#	现象	根因	解决
1	三个下载链接全部 `NoSuchKey`	URL 路径是错的	换官方真实地址（见下）
2	det/rec 解压后没有 `.pdmodel`	PP-OCRv6 是 Paddle 3.0 新静态图格式，用 `inference.json` 取代了 `.pdmodel`	正常现象，Paddle 3.x 直接读 `inference.json`，不用管
3	脚本卡住不动	建了两次 `PaddleOCR()`，第二次 `lang="ch",use_angle_cls=True...` 覆盖了带本地路径的实例 → 丢掉本地模型 → 联网去 HuggingFace 下载（国内被墙/极慢）	整个程序只初始化一次，且始终传本地 `*_model_dir`
4	老 API 不工作	`ocr.ocr()`、`use_angle_cls`、`use_gpu`、`cls=True` 是 2.x 接口，3.7.0 已改	用 `ocr.predict()`，方向分类改 `use_textline_orientation=True`
5	`FileNotFoundError: ...\cls\inference.yml`	下载的 v2.0 cls 包（`.pdmodel` 那种）没有 PaddleX 3.x 必需的 `inference.yml`，与 3.7.0 不兼容	换成 3.x 版 `PP-LCNet_x1_0_textline_ori`（自带 inference.yml）
6	推理即崩 `NotImplementedError ... onednn_shturl.cc/TBGp`	Paddle 3.x 在 CPU 上 oneDNN(MKL-DNN) + PIR 新执行器的已知 bug	初始化加 `enable_mkldnn=False`
7	打印"识别到 0 行"	取错字段层级，结果在 `res.json["res"]` 里	从 `res.json["res"]["rec_texts"/"rec_scores"/"dt_polys"]` 取
8	ccache 警告 + `Creating model:` 日志刷屏	paddle 导入/加载时的提示性日志，非错误	顶部四行静音代码（见下）
9	tar 里有 `._inference.pdmodel` 垃圾文件	macOS AppleDouble 文件	解压后剔除 `._*` 文件

二、正确的安装步骤

1. 建目录

复制代码

F:\paddle_models\
├─ det\
├─ rec\
└─ cls\

2. 下载这 3 个正确地址（你原来的链接全是错的）

复制代码

det : [https://paddle-model-ecology.bj.bcebos.com/paddlex/official_inference_model/paddle3.0.0/PP-OCRv6_medium_det_infer.tar](https://paddle-model-ecology.bj.bcebos.com/paddlex/official_inference_model/paddle3.0.0/PP-OCRv6_medium_det_infer.tar)
rec : [https://paddle-model-ecology.bj.bcebos.com/paddlex/official_inference_model/paddle3.0.0/PP-OCRv6_medium_rec_infer.tar](https://paddle-model-ecology.bj.bcebos.com/paddlex/official_inference_model/paddle3.0.0/PP-OCRv6_medium_rec_infer.tar)
cls : [https://paddle-model-ecology.bj.bcebos.com/paddlex/official_inference_model/paddle3.0.0/PP-LCNet_x1_0_textline_ori_infer.tar](https://paddle-model-ecology.bj.bcebos.com/paddlex/official_inference_model/paddle3.0.0/PP-LCNet_x1_0_textline_ori_infer.tar)

注意：cls 用的是 3.x 版 textline_ori ，不是网上那个 ch_ppocr_mobile_v2.0_cls_infer.tar（那个和 3.7.0 不兼容）。

3. 解压并平铺 ：每个 tar 解压后会多套一层文件夹（如 PP-OCRv6_medium_det_infer/），把里面的文件直接移到 det\、rec\、cls\ 里，去掉嵌套层，并删掉 ._* 文件。

最终应为：

复制代码

F:\paddle_models\det\   → inference.json, inference.pdiparams, inference.yml
F:\paddle_models\rec\   → inference.json, inference.pdiparams, inference.yml
F:\paddle_models\cls\   → inference.json, inference.pdiparams, inference.yml

4. 正确的运行脚本（关键：一次初始化、本地路径、3.x API、关 mkldnn）

复制代码

import os, warnings, logging
os.environ["GLOG_minloglevel"] = "2"
os.environ["GLOG_v"] = "0"
warnings.filterwarnings("ignore")
logging.disable(logging.WARNING)

from paddleocr import PaddleOCR

ocr = PaddleOCR(
    text_detection_model_dir=r"F:\paddle_models\det",
    text_recognition_model_dir=r"F:\paddle_models\rec",
    textline_orientation_model_dir=r"F:\paddle_models\cls",
    use_doc_orientation_classify=False,
    use_doc_unwarping=False,
    use_textline_orientation=True,   # 等价老版 use_angle_cls
    enable_mkldnn=False,            # CPU 必加，否则崩
)

for res in ocr.predict(r"F:\诛仙脚本\游戏截图\测试.png"):
    d = res.json["res"]
    for text, score, box in zip(d["rec_texts"], d["rec_scores"], d["dt_polys"]):
        print(text, round(float(score),3), box.tolist())

三、一句话经验

PaddleOCR 3.x 已全面改用 PaddleX 的模型组织方式 ：模型是"一个目录 + inference.json/pdiparams/yml"，API 是 predict()，参数是 *_model_dir + use_textline_orientation；凡是网上 2.x 时代的教程（.pdmodel、use_angle_cls、ocr.ocr()、ch_ppocr_mobile_v2.0_cls）到了 3.7.0 都会踩坑。当前这套方案已经全部实测跑通，可直接沿用。