部署指南：DanKS如何在CPU、CUDA与昇腾NPU上快速加速运行

DanKS 是由金山 AI 产品中心发起的 SOTA 级掼蛋 AI 智能体，一个仓库完整开放三代技术路线与共享的 108 张牌规则引擎。本文是面向新手与普通用户的部署指南：带你一步步把 DanKS 跑起来，并快速在 CPU、NVIDIA CUDA 显卡与华为昇腾 NPU 三种硬件上完成加速部署，打通推理与 PPO 训练全链路。

先看懂：DanKS 的三层加速在哪里 🧭

部署前，先搞清楚加速到底发生在哪些环节。DanKS 的加速点分为三层：

层次	职责	加速手段
① 结构化候选召回	把组合爆炸的候选出牌分解为代表性候选	C++ 原生内核（danks_cover / danks_actor_core）
② 神经网络推理	共享编码器 + Actor/Critic 为 Top-K 候选打分	PyTorch：CPU / CUDA / NPU
③ PPO 自博弈训练	用 GAE 优势更新策略网络	--device auto 自动选择最优加速器

三个要点：

• C++ 原生内核属于 CPU 侧加速，无显卡也能用；Windows 会自动回退纯 Python 实现。
• 设备选择统一收敛在 accelerator.py：auto 模式按 NPU → CUDA → CPU 的优先级自动选择，无需改任何代码。
• 训练入口 train_ppo.py 本身就支持 CPU/CUDA/NPU，同一套命令跑三种硬件。

第一步：克隆仓库，搭建 CPU 基线环境 🚀

最短可运行路径是 V3 + CPU（推荐 Python 3.11，Linux / macOS / Windows 均可）：

git clone https://gitcode.com/gh_mirrors/da/DanKS
cd DanKS
python3.11 -m venv .venv
source .venv/bin/activate        # Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e versions/v3
python -m pip install torch==2.8.0 --index-url https://download.pytorch.org/whl/cpu
# macOS CPU 则直接执行: python -m pip install torch==2.8.0

随后运行两个自带自检断言的示例验证环境：

python examples/retrieval_quickstart.py --version v3   # 结构化召回链路
python examples/v3_model_smoke.py                     # 完整网络前向

两条命令全部通过，CPU 基线即部署成功。这两个示例分别是 retrieval_quickstart.py 与 v3_model_smoke.py，出问题时错误信息非常直观。

💡 V1 / V2 / V3 建议各用独立虚拟环境，避免 DanKS 命名空间与特征模式互相冲突。

第二步：NVIDIA CUDA 显卡快速加速 🎯

有 NVIDIA 显卡（官方验证参考为 H100 + 驱动 575.57.08 + CUDA 12.8）时，只需换装 CUDA 版 torch 轮子：

python -m pip install torch==2.8.0 --index-url https://download.pytorch.org/whl/cu128

就这么简单，后续链路硬件无关。auto 逻辑（见 accelerator.py#L35-L40）会自动优先 GPU，也可以显式指定：

python -m DanKS.training.train_ppo \
  --rollout /path/to/rollout.npz \
  --output /path/to/checkpoint.pt \
  --device cuda

--device 支持 cpu、cuda、npu 及 cuda:1 这类具体卡号；优化、评估、加速器等全部参数用 python -m DanKS.training.train_ppo --help 随时查看。

第三步：华为昇腾 NPU 部署加速 🇨🇳

昇腾路线需要三件套：宿主机驱动 + CANN 运行时 + 厂商提供的 torch 与 torch_npu 轮子对。已验证的参考组合记录在 requirements-training-npu.txt（910B2C + 驱动 24.1.0 + CANN 8.5.0，Python 3.10）：

torch==2.7.1+cpu
torch_npu==2.7.1.post2

部署四步走：

# 1) 加载 CANN 环境（需已安装匹配的 CANN）
source /usr/local/Ascend/cann/set_env.sh

# 2) 为 NPU 建专用 venv（共享系统 site-packages）
python3.10 -m venv --system-site-packages .venv-v3-npu
source .venv-v3-npu/bin/activate

# 3) 安装 V3 与厂商轮子对（切勿混入 NVIDIA 包）
python -m pip install -e versions/v3
python -m pip install --no-deps \
  /path/to/torch-2.7.1+cpu-cp310-cp310-manylinux_2_28_x86_64.whl \
  /path/to/torch_npu-2.7.1.post2-cp310-cp310-manylinux_2_28_x86_64.whl

# 4) 关闭后端自动加载并验证
export TORCH_DEVICE_BACKEND_AUTOLOAD=0
python -m DanKS.training.train_ppo --help

三个注意点：

• torch 与 torch_npu 的版本必须与宿主 CANN 版本匹配，--no-deps 用于防止 pip 拉入不兼容包。
• 关闭自动加载后 torch 不认识 npu 设备串，load_torch_npu 会在需要时显式注册后端，无需手动处理。
• 该 venv 建议专供昇腾路线使用，不要与 CUDA 环境混用。

CPU 隐藏大招：一条命令编译 C++ 加速内核 ⚡️

只有 CPU 也能提速。DanKS 提供了 C++17 原生内核，专门加速最耗时的候选召回计算。先一次性安装工具链：

# Ubuntu/Debian
sudo apt-get update && sudo apt-get install -y build-essential python3-dev
# macOS（运行一次）
xcode-select --install

然后在 V3 环境中一条命令完成构建与验证：

danks-build-native

这条命令（注册于 versions/v3/pyproject.toml，构建逻辑在 native_cpp/setup.py）的关键细节：

• 一次编译 danks_cover 与 danks_actor_core 两个内核，完成后输出 cover=True, actor=True 即成功；
• Linux 构建自动加 -march=native 做本机优化；可用 DANKS_NATIVE_GENERIC_ISA=1 退回兼容模式，或用 DANKS_NATIVE_PGO 开启 PGO 进一步压榨性能；
• 切换 Python 版本或 CPU 架构后重跑一次即可；Windows 自动回退纯 Python 实现，无需编译。

原生内核就位后，"召回 + 推理"在纯 CPU 上就能形成完整的加速链路。

加速配置速查表与验证方法 ✅

项目已验证过的参考配置如下：

部署目标	硬件	Python	关键框架组合
V1 结构化召回	CPU	3.11+	NumPy 选择器
V2 学习型选择	CPU	3.11+	ONNX Runtime 1.27.0
V3 · NVIDIA	H100，驱动 575.57.08	3.11.14	PyTorch 2.8.0 + CUDA 12.8
V3 · 昇腾	910B2C，驱动 24.1.0，CANN 8.5.0	3.10.12	PyTorch 2.7.1 + torch_npu 2.7.1.post2

验证加速是否生效，只需运行 v3_model_smoke.py：模型会自动落在 auto 选出的加速器上，设备名由 accelerator.py 的 device_name 报告。若显式指定了不存在的后端，会直接抛出清晰错误（如 CUDA requested, but torch.cuda.is_available() is false），排障非常快。

常见问题排查 🔍

Q1：报错 "C++ cover kernel is not available"？ Windows 上属正常（自动回退 Python 实现）；Linux/macOS 请重装 python3-dev 与 pybind11 后重跑 danks-build-native。

Q2：torch_npu 导入失败或 npu_available() 为 False？ 依次检查：CANN 环境是否已 source、torch/torch_npu 版本是否匹配 CANN 发行版、是否已设置 TORCH_DEVICE_BACKEND_AUTOLOAD=0。

Q3：V1/V2 也要加速吗？ V1 用 NumPy 选择器、V2 用 ONNX Runtime 选择器，二者均面向 CPU 优化，按 README 的包选择表安装即可。

部署完成后的效果预览 🃏

部署成功后，V3 网络前向与一次 PPO 更新均可秒级完成；策略结合共享 guandan 规则引擎 即可跑完整四人牌局。下面是项目的真实牌桌界面：

一句话总结：CPU 开箱即用、CUDA 换一行轮子、昇腾 NPU 四步走完——同一套代码，三种硬件，--device auto 全部兜底。