本指南面向第一次接触本项目的用户。从下载源码到在浏览器里识别图片，一步一步跟着做就行。
全程不需要训练模型，直接用已经训练好的 M5 模型推理。
操作之前确认你有：
- 一台 Linux 服务器（推荐 Ubuntu 20.04+），或 Windows / macOS
- NVIDIA 显卡（≥10 GB 显存）+ CUDA 11.8 或 12.0；没有显卡也行，用 CPU 模式（慢一些）
- 已经装好 Miniconda 或 Anaconda（没装的话先去 https://docs.conda.io/projects/miniconda/en/latest/ 装一下）
- 网络能访问 GitHub 和百度对象存储
打开终端，进入你想要存放项目的目录，运行：
git clone https://github.com/<your-org>/paddleocr_db.git
cd paddleocr_db后面所有命令都假定你已经在
paddleocr_db/目录里。
项目提供了一键部署脚本，根据你的系统选一个跑：
bash deploy/deploy_linux.sh --cuda 11.8如果你装的是 CUDA 12，改成
--cuda 12.0；没显卡用--cpu。
Set-ExecutionPolicy -Scope Process Bypass -Force
.\deploy\deploy_windows.ps1 -Cuda 11.8bash deploy/deploy_macos.sh脚本会自动完成：
- 创建一个名叫
paddleocr_tibetan的 conda 环境 - 安装 PaddlePaddle 和项目依赖
- 下载预训练权重
整个过程大约 5-10 分钟，看到 [OK] 部署完成 就好了。
需要下载两个模型：识别模型（M5） 和 检测模型，放到项目根目录下。
国内用户（ModelScope）：
from modelscope import snapshot_download
snapshot_download(
'a237401/tibetocr-m5',
local_dir='PP-OCRv5_server_rec_infer_openpecha_ch_en'
)国外用户（HuggingFace）：
pip install huggingface_hub
python -c "
from huggingface_hub import snapshot_download
snapshot_download(
'Databaker/tibetocr-m5',
local_dir='PP-OCRv5_server_rec_infer_openpecha_ch_en'
)
"首次运行时 PaddleX 会自动下载检测模型，无需手动操作。
如需在本地评测模型效果，可下载交付测试集：
国内用户（ModelScope）：
from modelscope import snapshot_download
snapshot_download(
'a237401/tibetocr-delivery-testset',
local_dir='交付测试集'
)国外用户（HuggingFace）：
from huggingface_hub import snapshot_download
snapshot_download(
'Databaker/tibetocr-delivery-testset',
repo_type='dataset',
local_dir='交付测试集'
)测试集包含四个子集（zip 格式）：
pure_tibetan、tibetan_chn_mixed、tibetan_chn_eng_mixed、tibetan_dirty，下载后需解压。
下载完成后目录结构如下：
tibetocr/
├── PP-OCRv5_server_det_infer/ # 检测模型（自动下载）
├── PP-OCRv5_server_rec_infer_openpecha_ch_en/ # 识别模型（手动下载）
└── 交付测试集/ # 测试集（可选）
先看一下显卡占用：
nvidia-smi找一张 Memory-Usage 空闲超过 10 GB 的卡，记下它的编号（最左边的数字）。
如果想换 GPU 卡号或端口，编辑 deploy/app.env：
CUDA_VISIBLE_DEVICES=4 # 改成你选的卡号
APP_PORT=7860 # 改成你想用的端口bash deploy/start_app.sh看到下面这样就说明启动成功：
[OK] 已启动，PID=xxxxx
访问: http://<服务器IP>:7860
第一次启动需要 30-60 秒（模型加载）。
bash deploy/stop_app.sh在同一台机器或同一内网的浏览器里访问：
http://<服务器IP>:7860
例如：http://192.168.1.100:7860（替换为你的服务器实际 IP）
弹出登录框输入：
- 账号：
admin - 密码：
admin123
想改密码？编辑
app.py第 26 行的AUTH = ("admin", "admin123")，重启服务即可。
- 点击"上传图片"区域，选一张藏文文档图（PNG 或 JPG）
- 点击"开始识别"按钮
- 等待几秒，右侧会显示：
- 检测结果：原图上画好红色检测框
- 识别文本：每行文本一条
- 统计：行数、平均置信度、耗时
- 想保存结果？点最下面的"下载结果包"，会得到一个 ZIP 包含 PNG / TXT / JSON
- 一次拖多张图片到上传框
- 点击"开始批量识别"
- 处理完后下载 ZIP 包，里面是每张图的结果
- 上传一个 PDF（最多 20 页）
- 滑动"渲染 DPI"调清晰度（默认 200 即可，太高会很慢）
- 点击"开始解析"
- 下载 ZIP 包，里面是每一页的结果
如果你想在自己的 Python 脚本里用这个 OCR：
from inference import TibetanOCRPipeline
# 初始化（只需要一次）
pipeline = TibetanOCRPipeline()
# 识别一张图
result = pipeline.predict_image("我的图.png")
print(result.to_text()) # 拼成大段文字
print(result.texts) # 一行一行的列表
print(result.scores) # 每行的置信度
print(result.boxes) # 每行的检测框坐标
# 保存可视化（原图+红框）
from PIL import Image
Image.fromarray(result.annotated_image).save("带框的图.png")
# 识别 PDF
results = pipeline.predict_pdf("我的文档.pdf")
for i, res in enumerate(results, 1):
print(f"--- 第 {i} 页 ---")
print(res.to_text())如果你在使用 Claude Code，可以用自然语言触发 OCR 操作，无需手动写命令。
在 Claude Code 对话框输入：
/tibetocr-ocr
然后说明你的需求，例如：
- "识别这张图片 /path/to/image.jpg"
- "批量识别 /data/images/ 目录下所有图片，结果保存到 /data/results/"
- "识别这个 PDF /path/to/doc.pdf"
Claude 会自动调用 Skill API 完成识别并输出结果。
在 agent(推荐claude code） 对话框输入：
/tibetocr-deploy
agent 会自动判断你的网络环境（国内/国外），从对应平台（Gitee/GitHub、ModelScope/HuggingFace）拉取代码和模型，完成完整部署。
Skill 文件位置：
/data/zhouziqi/.claude/skills/tibetocr-ocr/SKILL.md/data/zhouziqi/.claude/skills/tibetocr-deploy/SKILL.md
端口被其他程序占了。改 deploy/app.env 里的 APP_PORT（比如改成 8888），重启。
先装 Miniconda：https://docs.conda.io/projects/miniconda/en/latest/
检查三件事：
- 服务进程还活着吗？
ps aux | grep app.py - 端口监听了吗？
ss -tnlp | grep 7860 - 防火墙开了吗？同事的电脑能 ping 通服务器吗？
显存不够。换一张更空闲的 GPU（改 deploy/app.env 里的 CUDA_VISIBLE_DEVICES），重启服务。
- 图片太模糊：截图清晰一些
- 经文极长：本项目专门优化过长条形经文，但太极端的会被截断
- 文字方向不是水平：目前只支持水平排列，旋转过的文字效果会差
tail -f logs/app.log # 实时看日志
cat logs/app.pid # 看进程号跑一次这个脚本就能跑成 systemd 服务：
bash deploy/install_systemd_user.sh之后用 systemctl --user restart tibetan_ocr_app 之类的命令管理。
| 操作 | 命令 |
|---|---|
| 启动 | bash deploy/start_app.sh |
| 停止 | bash deploy/stop_app.sh |
| 重启 | bash deploy/stop_app.sh && bash deploy/start_app.sh |
| 看日志 | tail -f logs/app.log |
| 访问 | 浏览器开 http://<服务器IP>:7860 |
| 账号 | admin / admin123 |
git clone <仓库> ← 第 1 步
cd paddleocr_db_liufan
bash deploy/deploy_linux.sh --cuda 11.8 ← 第 2 步：搭环境
# 把两个 _infer 模型目录放进项目根目录 ← 第 3 步
vim deploy/app.env ← 第 4.2 步：改 GPU（可选）
bash deploy/start_app.sh ← 第 4.3 步：启动
# 浏览器开 http://服务器IP:7860 ← 第 5 步：用起来
# admin / admin123 登录
跑通一次后，以后只需要 bash deploy/start_app.sh 一句就好。