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
+183
View File
@@ -0,0 +1,183 @@
"""安装 paddlepaddle(CPU 版或 GPU 版)。
paddlepaddle 不在 pyproject.toml 的依赖里,原因见那里的注释:CPU/GPU 两个发行包
互斥、GPU 版还要按显卡选 CUDA 通道,写死任何一个都会被 `uv sync` / PyCharm 自动同步
冲掉。所以单独用这个脚本安装。
用法:
python scripts/install_paddle.py # 自动:检测到 NVIDIA 显卡就装 GPU 版,否则 CPU 版
python scripts/install_paddle.py --cpu # 强制 CPU 版
python scripts/install_paddle.py --gpu # 强制 GPU 版,CUDA 通道按显卡自动推荐
python scripts/install_paddle.py --gpu --cuda cu126 # 指定 CUDA 通道
python scripts/install_paddle.py --gpu --version 3.2.2 # 指定版本
"""
import argparse
import re
import subprocess
import sys
DEFAULT_VERSION = "3.2.2"
SUPPORTED_CUDA = ("cu118", "cu126", "cu129")
INDEX_TEMPLATE = "https://www.paddlepaddle.org.cn/packages/stable/{cuda}/"
CPU_PACKAGE = "paddlepaddle"
GPU_PACKAGE = "paddlepaddle-gpu"
BOTH_PACKAGES = (CPU_PACKAGE, GPU_PACKAGE)
# paddlepaddle-gpu 会顺带装上的 CUDA 运行库(约 3GB)。装 CPU 版时一并清理,
# 否则环境里会白留着几个 G 的 .venv 体积。
NVIDIA_PACKAGES = (
"nvidia-cublas-cu12",
"nvidia-cuda-runtime-cu12",
"nvidia-cudnn-cu12",
"nvidia-cufft-cu12",
"nvidia-curand-cu12",
"nvidia-cusolver-cu12",
"nvidia-cusparse-cu12",
"nvidia-nvjitlink-cu12",
)
def run(command: list[str], check: bool = True) -> subprocess.CompletedProcess[str]:
print(f" $ {' '.join(command)}", flush=True)
result = subprocess.run(command, capture_output=True, text=True, encoding="utf-8")
if result.stdout.strip():
print(" " + result.stdout.strip().replace("\n", "\n "))
if result.stderr.strip():
print(" " + result.stderr.strip().replace("\n", "\n "))
if check and result.returncode != 0:
raise SystemExit(result.returncode)
return result
def pip_command(*args: str, python: str | None = None) -> list[str]:
"""优先用 uv pip,没有 uv 就退回 pip。python 指定目标解释器(多环境时用)。"""
uv = subprocess.run(
["uv", "--version"], capture_output=True, text=True, check=False
)
if uv.returncode == 0:
base = ["uv", "pip", *args]
if python:
base += ["--python", python]
return base
target = python or sys.executable
return [target, "-m", "pip", *args]
def detect_gpu_name() -> str | None:
"""读 nvidia-smi 拿显卡型号;没有 NVIDIA 卡或没装驱动时返回 None。"""
try:
result = subprocess.run(
["nvidia-smi", "--query-gpu=name", "--format=csv,noheader"],
capture_output=True,
text=True,
timeout=20,
check=False,
)
except (OSError, subprocess.SubprocessError):
return None
if result.returncode != 0:
return None
first = result.stdout.strip().splitlines()
return first[0].strip() if first and first[0].strip() else None
def recommend_cuda(gpu_name: str | None) -> str:
"""按显卡型号推荐 CUDA 通道。
RTX 50 系是 Blackwell(sm_120),只有 cu129 的内核包含它;装 cu118/cu126 会
在推理时报 Mismatched GPU Architecture。
"""
if not gpu_name:
return "cu126"
upper = gpu_name.upper()
if re.search(r"RTX\s*50\d0", upper):
return "cu129"
if re.search(r"RTX\s*[34]0\d0", upper):
return "cu126"
return "cu118"
def explain_uninstall_failure(output: str) -> None:
if "拒绝访问" in output or "Access is denied" in output or "os error 5" in output:
print(
"\n[错误] 卸载旧版失败:文件被占用。\n"
" 最常见的原因是 OCR 服务正在运行,或者 PyCharm 的 Python 控制台\n"
" 导入过 paddle。请先停掉它们再重试。",
file=sys.stderr,
)
def main() -> int:
parser = argparse.ArgumentParser(description="安装 paddlepaddle(CPU 或 GPU 版)")
group = parser.add_mutually_exclusive_group()
group.add_argument("--cpu", action="store_true", help="强制安装 CPU 版")
group.add_argument("--gpu", action="store_true", help="强制安装 GPU 版")
parser.add_argument(
"--cuda",
choices=SUPPORTED_CUDA,
help=f"GPU 版的 CUDA 通道({' / '.join(SUPPORTED_CUDA)}),默认按显卡型号推荐",
)
parser.add_argument("--version", default=DEFAULT_VERSION, help="paddle 版本,默认 3.2.2")
parser.add_argument(
"--dry-run", action="store_true", help="只打印将要执行的安装方案,不做任何改动"
)
parser.add_argument(
"--python",
help="目标解释器路径(多套虚拟环境时用),默认当前环境",
)
args = parser.parse_args()
gpu_name = detect_gpu_name()
use_gpu = args.gpu or (not args.cpu and gpu_name is not None)
cuda = args.cuda or recommend_cuda(gpu_name)
print("检测到显卡:" + (gpu_name or "无 NVIDIA 显卡"))
print(f"安装目标:{'GPU 版' if use_gpu else 'CPU 版'}"
+ (f"(CUDA 通道 {cuda})" if use_gpu else ""))
if use_gpu and not gpu_name:
print(" ⚠️ 没检测到 NVIDIA 显卡,但仍按要求装 GPU 版;")
print(" 这样装在无卡机器上可能连 import 都失败,请确认目标机器。")
if args.dry_run:
package = GPU_PACKAGE if use_gpu else CPU_PACKAGE
print(f"\n[dry-run] 将安装 {package}=={args.version}"
+ (f",来源 {INDEX_TEMPLATE.format(cuda=cuda)}" if use_gpu else ""))
return 0
# 装 CPU 版时顺带清掉 GPU 版拖进来的 CUDA 运行库;装 GPU 版时不用管(本来就要装)。
to_remove = BOTH_PACKAGES if use_gpu else (*BOTH_PACKAGES, *NVIDIA_PACKAGES)
print("\n[1/2] 卸载已有的 " + " / ".join(to_remove))
result = run(pip_command("uninstall", *to_remove, python=args.python), check=False)
explain_uninstall_failure((result.stdout or "") + (result.stderr or ""))
if result.returncode != 0:
return result.returncode
print(f"\n[2/2] 安装 {GPU_PACKAGE if use_gpu else CPU_PACKAGE}=={args.version}")
if use_gpu:
command = pip_command(
"install",
f"{GPU_PACKAGE}=={args.version}",
# 用 extra-index-url 而不是 index-url:paddlepaddle-gpu 只在官方源上,
# 但它的依赖(numpy 等)还得从 PyPI 取。
"--extra-index-url",
INDEX_TEMPLATE.format(cuda=cuda),
python=args.python,
)
else:
command = pip_command(
"install", f"{CPU_PACKAGE}=={args.version}", python=args.python
)
run(command)
print("\n完成。验证方式:")
if use_gpu:
print(" python -c \"import paddle; print(paddle.device.is_compiled_with_cuda())\"")
print(" config.yaml 里 device: auto 即可自动走 GPU")
else:
print(" config.yaml 里 device: cpu(或 auto,无卡时自动用 CPU)")
return 0
if __name__ == "__main__":
raise SystemExit(main())