build: CPU/GPU 双环境、产物命名与打包修复

交付:
  · 产物按变体命名:CPU -> dist/ocr-server/,GPU -> dist/ocr-server-gpu/。
    变体由构建环境实际装的 paddle 自动判断,不需要人工声明
  · GPU 包额外加 --collect-binaries nvidia。漏收的后果实测是最难查的那种:
    引擎能正常加载、设备也识别成 GPU,但第一次推理才报
    cudnn64_9.dll error 126
  · --copy-metadata 的发行包名随变体变化(paddlepaddle / paddlepaddle-gpu),
    改由 scripts/paddle_env.py 动态取;写死任何一个在另一种环境下都打不出包
  · 新增 scripts/prepare_release_config.py 按变体覆盖发布配置(用 Python 改写
    以保持 UTF-8,PowerShell 的 Set-Content 会把中文注释写坏)

环境:
  · paddle 从 pyproject 依赖里移除,改用 scripts/install_paddle.py 安装。
    它没法写死:CPU/GPU 互斥,GPU 还得按显卡选 CUDA 通道(RTX 50 系必须 cu129)。
    钉死 CPU 版时,uv sync / uv run / PyCharm 自动同步都会把装好的
    paddlepaddle-gpu 静默挤掉、服务悄悄退回 CPU(实测踩过三次)
  · 新增 scripts/switch_env.py:.venv(CPU)与 .venv-gpu(GPU)两套环境共存,
    切换零成本;所有 uv run 补 --no-sync,打包改用 uv sync --inexact
  · 预置模型扩到 8 套(v4/v5 × 服务端/移动端 × 检测/识别,约 398MB)

其它:
  · scripts/start.* 先找发布包再退回源码环境;入口脚本名固定是 ocr-server
  · benchmark_ocr.py 输出 segments 与 chars,换设备/模型时可直接比对召回
  · .gitignore 覆盖 .venv-gpu/ 与 dist*/

Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
zimoyin
2026-10-14 03:53:48 +08:00
parent 09ab14c707
commit 5ab4bef80e
18 changed files with 1366 additions and 306 deletions
+90 -12
View File
@@ -1,39 +1,102 @@
# 打包 Windows 发布包(--onedir 目录形式)。
#
# CPU / GPU 两个变体由**构建环境里装的 paddlepaddle 版本**自动决定,不需要手动指定:
# 装了 paddlepaddle -> CPU 包,dist\ocr-server\
# 装了 paddlepaddle-gpu -> GPU 包,dist\ocr-server-gpu\,且 config.yaml 的 device 预置为 auto
# GPU 包在装了 GPU 版 paddle 的机器上走显卡,拿不到 CUDA 设备时回落 CPU(见 README)。
#
# 关键参数说明,改动前请先读:
# --collect-all paddle/paddlex/paddleocr Paddle 的原生库与配置必须整体收集,缺一个就跑不起来
# --collect-all pyclipper/pypdfium2/shapely/bidi
# 检测后处理与识别的必需依赖,漏了会在推理时报错
# --copy-metadata * PaddleX 通过 importlib.metadata 检查依赖,
# 缺元数据会误判「依赖未安装」
# 缺元数据会误判「依赖未安装」。
# ⚠️ paddle 的发行包名随变体变化(paddlepaddle /
# paddlepaddle-gpu),写死会打不出包,
# 所以由 scripts/paddle_env.py 动态取。
# --additional-hooks-dir scripts 启用 scripts/hook-imagesize.py
# --hidden-import imagesize 源码环境下按需导入,打包时必须显式声明
#
# 发布包为 --onedir:模型与 config.yaml 外置,便于替换;不要只替换 exe,_internal 也要一起更新。
param(
[switch]$Clean,
# 输出目录,默认 dist。若 dist 被其它进程当作工作目录占用(Windows 会锁住该目录),
# 可指定别处构建,再把内容搬回去,例如:
# 断言当前环境必须是 GPU 版 paddle。不传时按实际安装的版本自动判断。
[switch]$Gpu,
# 输出根目录,默认 dist。变体决定其下的应用目录名:ocr-server / ocr-server-gpu。
# 若 dist 被其它进程当作工作目录占用(Windows 会锁住该目录),可指定别处构建:
# .\scripts\package-windows.ps1 -DistPath build\pyi-dist
[string]$DistPath = "dist"
[string]$DistPath
)
$ErrorActionPreference = "Stop"
$ProjectRoot = Split-Path -Parent $PSScriptRoot
Set-Location $ProjectRoot
$ReleaseDir = Join-Path $ProjectRoot "$DistPath\ocr-server"
# --inexact + --no-install-package paddlepaddle:只同步除 paddle 以外的依赖。
# pyproject.toml 里声明的是 CPU 版 paddlepaddle,裸跑 uv sync 会「卸载
# paddlepaddle-gpu 和全部 nvidia-* 运行库、装回 CPU 版」,把 GPU 环境悄悄冲掉;
# 而单独用 --no-install-package 又会把 paddlepaddle-gpu 当多余包删掉。
# 这两个参数合用才能保住当前装的 paddle 变体(实测 dry-run 为 no changes)。
uv sync --dev --inexact --no-install-package paddlepaddle
# ── 判断变体 ──────────────────────────────────────────────────
$Variant = (uv run --no-sync python scripts/paddle_env.py variant).Trim()
$PaddleDist = (uv run --no-sync python scripts/paddle_env.py distribution).Trim()
if ($Variant -eq "missing") {
throw "环境里没有安装 paddlepaddle,请先执行 uv sync。"
}
if ($Gpu -and $Variant -ne "gpu") {
throw @"
要求打 GPU 包,但当前环境装的是 $Variant 版 paddle(发行包 $PaddleDist)。
请先换 GPU 版(版本必须同为 3.2.x):
uv run --no-sync python scripts/install_paddle.py --gpu
# (install_paddle.py 会自动识别显卡并选对 CUDA 通道)
⚠️ RTX 50 系必须用 cu129,cu118 / cu126 不含 sm_120 内核,装了会在推理时报
Mismatched GPU Architecture。40/30 系 cu126 / cu129 均可。
详见 README「CPU / GPU 切换」。
"@
}
# 变体由构建环境里实际装的 paddle 决定,没有「强制」开关——
# 产物里打进的就是当前环境的 paddle,改了名字也不会变,只会误导。
$BuildVariant = $Variant
# GPU 包预置 device: auto 而不是 gpu:客户机有卡就用卡、没卡就回落 CPU,
# 两种情况都不会把服务卡死,日志里也会明确打出实际选了哪个。
if ($BuildVariant -eq "gpu") { $ConfigOverride = "device=auto" } else { $ConfigOverride = $null }
if (-not $PSBoundParameters.ContainsKey("DistPath") -or [string]::IsNullOrWhiteSpace($DistPath)) {
$DistPath = "dist"
}
# 产物命名:CPU 版叫 ocr-server,GPU 版叫 ocr-server-gpu,都放在 dist 下,
# 两个发布包一眼能分辨,也不会互相覆盖。
$AppName = if ($BuildVariant -eq "gpu") { "ocr-server-gpu" } else { "ocr-server" }
$ReleaseDir = Join-Path $ProjectRoot "$DistPath\$AppName"
Write-Host "构建变体:$BuildVariant(paddle 发行包 $PaddleDist)"
Write-Host "输出目录:$ReleaseDir"
if ($Clean) {
Remove-Item -Recurse -Force -ErrorAction SilentlyContinue build, dist
# 只清当前变体的目录,别把另一个变体的产物一起删了
Remove-Item -Recurse -Force -ErrorAction SilentlyContinue build, $ReleaseDir
}
uv sync --dev
uv run pyinstaller --noconfirm --clean --onedir --name ocr-server `
# GPU 版必须额外收 nvidia 命名空间:paddlepaddle-gpu 的 CUDA 运行库(cudnn / cublas /
# cufft 等)装在独立的 nvidia-* 发行包里,`--collect-all paddle` 收不到它们。
# 漏收的后果实测是:引擎能加载、设备识别成 GPU,但第一次推理就报
# `PreconditionNotMetError: cudnn64_9.dll ... error code is 126`。
# 收进来的落点是 _internal/nvidia/<包>/bin,正好是 paddle 在 __init__.py 里
# 用 os.add_dll_directory 寻找的路径(os.path.dirname(paddle.__file__)/../nvidia)。
$ExtraCollect = @()
if ($BuildVariant -eq "gpu") {
$ExtraCollect = @("--collect-binaries", "nvidia")
}
uv run --no-sync pyinstaller --noconfirm --clean --onedir --name $AppName `
--distpath $DistPath `
--paths src `
--collect-all paddleocr `
--collect-all paddlex `
--collect-all paddle `
@ExtraCollect `
--collect-all cv2 `
--collect-all PIL `
--collect-all pyclipper `
@@ -43,7 +106,7 @@ uv run pyinstaller --noconfirm --clean --onedir --name ocr-server `
--hidden-import paddlex.inference.models.text_detection.processors `
--copy-metadata paddlex `
--copy-metadata paddleocr `
--copy-metadata paddlepaddle `
--copy-metadata $PaddleDist `
--copy-metadata imagesize `
--add-data "config.yaml;." `
--add-data "http;http" `
@@ -54,20 +117,35 @@ uv run pyinstaller --noconfirm --clean --onedir --name ocr-server `
--hidden-import ocr_server.config `
scripts/packaged_entry.py
Copy-Item -Force config.yaml (Join-Path $ReleaseDir "config.yaml")
$ConfigArgs = @(
"scripts/prepare_release_config.py",
"config.yaml",
(Join-Path $ReleaseDir "config.yaml")
)
if ($ConfigOverride) { $ConfigArgs += $ConfigOverride }
uv run --no-sync python @ConfigArgs
if (Test-Path models) {
Copy-Item -Recurse -Force models (Join-Path $ReleaseDir "models")
}
$Exe = Join-Path $ReleaseDir "ocr-server.exe"
$Exe = Join-Path $ReleaseDir "$AppName.exe"
if (-not (Test-Path $Exe)) {
throw "打包失败:未生成 $Exe"
}
$Hash = (Get-FileHash -Algorithm SHA256 $Exe).Hash.ToLower()
$TotalMB = (Get-ChildItem -Recurse -File $ReleaseDir | Measure-Object -Property Length -Sum).Sum / 1MB
Write-Host ""
Write-Host "Windows 发布目录:$ReleaseDir"
Write-Host "启动:$DistPath\ocr-server\ocr-server.exe"
Write-Host "变体:$BuildVariant"
Write-Host "启动:$DistPath\$AppName\$AppName.exe"
Write-Host ("整个发布目录体积:{0:N1} MB" -f $TotalMB)
Write-Host ("exe 体积:{0:N1} MB" -f ((Get-Item $Exe).Length / 1MB))
Write-Host "exe SHA256:$Hash"
if ($BuildVariant -eq "gpu") {
Write-Host "已把发布包里的 config.yaml 预置为 device: auto;有可用显卡时用 GPU,否则自动用 CPU。"
} else {
Write-Host "CPU 包。客户机若要用 GPU,需要改用 GPU 版分发包(用 paddlepaddle-gpu 环境重新打包)。"
}
Write-Host "(发布时要连 _internal 和 models 一起复制,不能只替换 exe)"