droboticflow/docs/qwen-node-local-cache.md
2026-08-22 08:47:40 +08:00

5.6 KiB
Raw Permalink Blame History

Qwen 节点本地模型缓存(通用默认关闭;POC 已验收启用)

这个优化只服务于 operator-builtin-qwen-behavior-rough-cut。它不会改变 Qwen3-VL 的固定 revision、模型 manifest、BOS/PVC 来源、工作流图或任何已经验收的 运行记录;未开启时保持原有“每个 Pod 复制到 /tmp 后加载”的行为。

开关与调度边界

Worker 仅在以下配置全部成立时,才给这个 唯一 allowlisted builtin 注入缓存 PVC、 缓存环境变量和 node selector:

DROBOTICFLOW_QWEN_NODE_CACHE_ENABLED=true
DROBOTICFLOW_QWEN_NODE_CACHE_PVC=droboticflow-qwen-node-cache
DROBOTICFLOW_QWEN_NODE_CACHE_MOUNT_PATH=/qwen-node-cache
DROBOTICFLOW_QWEN_NODE_CACHE_NODE_SELECTOR=kubernetes.io/hostname=<gpu-node>
DROBOTICFLOW_QWEN_NODE_CACHE_STALE_STAGING_SECONDS=86400

通用渲染/部署模板仍默认 false、空 PVC、/qwen-node-cache、空 selector 和 86400 秒;只有 scripts/deploy-envs/poc.env 为已验收的 POC Local PV 预置了上面的五项值。 启用时 PVC 和 selector 缺失会 fail-closed;其它 builtin、普通 operator、Qwen 时间定位、 训练和姿态算子都不会得到该挂载或这些环境变量。工作流 hyperparameter 也不能覆盖这些 平台保留键。

本 POC 已只读确认 GPU node 192.168.80.136 上 /home/cce 是独立的 /dev/nvme1n1 ext4 文件系统,不是 /dev/vda2 root 盘。生产 PV 必须使用一个新的、 唯一目录(例如 /home/cce/droboticflow-qwen-cache),并由受限的节点准备步骤创建为 UID/GID 10001 可写;禁止指向 /、/var/lib/kubelet、现有 real2sim PV 或 root 盘目录。

完整性与并发

每个启动的粗切 Pod 都会先重新校验源模型的 MODEL_MANIFEST.json、sidecar、固定 manifest SHA、Qwen repository/revision、config/processor/index 和完整布局。缓存键是 该 manifest SHA-256。

  • 同一 key 通过 flock 串行化;staging 目录带 PID/UUID,不能互相覆盖。
  • 首次复制时每个文件都计算 SHA-256 和 size;CACHE_RECEIPT.json 写入来源 provenance 与所有文件证据后才原子 rename 为 sealed key 目录。
  • cache hit 会再次对本地每个文件重算 SHA-256/size;receipt、manifest 和 sidecar 有任何 不一致均不被使用。
  • 空间不足、不可写或缓存损坏时,不删除 sealed cache,而是回退原有 Pod-local staging; provenance 记录 status=fallback 和原因。
  • 最小 GC 只会在拿到同 key 锁后清理该 key 已过期的未完成 staging 目录;不会自动删除 已验证的 sealed 模型目录。

输出 clips-manifest.json 的 provenance.nodeLocalCache 固化 enabled、cacheHit、 status、cacheRoot、receipt、copiedBytes 和 fallback 原因。真实验收要求第一次 cacheHit=false,第二次独立 Pod cacheHit=true 且 copiedBytes=0,两次输出保持一致。

Local PV 准备顺序

  1. 保持 feature disabled 部署并验证 Worker 健康。
  2. 在 GPU node 上只创建 /home/cce/droboticflow-qwen-cache,初始权限为 10001:10001、0750;不执行递归 chmod,也不格式化或挂载任何盘。Local PVC 被 运行时 Pod 以 fsGroup=10001 挂载后,Linux 可能将根目录表现为 2770(setgid, 同一受限组可写);这不是 world-writable,也不应被递归改回。 在渲染 --preflight-job 或 --prepare-job 前,必须显式提供 digest-pinned QWEN_NODE_CACHE_PREPARE_IMAGE,并运行 scripts/verify-qwen-node-cache-control-image.sh:它分别验证 registry manifest、API Deployment spec 和所有 API Pod imageID,三者任一不一致即停止。--preflight-job 只读挂载父目录和候选目录,以 UID/GID 10001 检查 realpath、权限和内容; --prepare-job 只挂载精确候选目录,使用最小 CHOWN、DAC_OVERRIDE、FOWNER capability 顺序执行 chown/chmod/UID 10001 可写探针,无 service-account token、GPU、 privileged 或 host namespace。两者均只渲染,不会 apply。默认 PV/PVC 同样通过 scripts/render-qwen-node-cache-local-pv.sh 仅渲染,固定为 80Gi、Retain 与 hostname affinity,模板不属于 deploy-k8s.sh。
  3. 创建一个带 hostname nodeAffinity 的 ReadWriteOnce Local PV/PVC,再在 Worker 配置中 填入相同 PVC、mount path 与 hostname selector。
  4. 先用真实固定 manifest 预热,检查 receipt、17.5GB 级别文件和 SHA 证据;再启用开关。
  5. 启动两个独立 Qwen 粗切 Pod,记录首次 miss、第二次 hit、输出 hash 和 GPU 证据。

已验收的 POC 证据

  • operator image 为 ccr-29eug8s3-pub.cnc.bj.baidubce.com/dataflow-poc/droboticflow-operator-qwen-behavior-rough-cut@sha256:f1c4889b664d8bc24bf61ec9abf230a0c95c479fe54716514e370620450c25c7。
  • disabled compatibility Job fanyu-qwen-cache-disabled-compat-r2-20260822、cache miss Job fanyu-qwen-cache-miss-r2-20260822 与独立 Pod cache hit Job fanyu-qwen-cache-hit-r2-20260822 都成功。三次经过删除运行/缓存特有 provenance 后的 canonical 输出 SHA-256 都是 a7656873eef8fe4d59ff46e07ff5dce66f4379fd684ec2800d04f4c1e156a775。
  • 固定模型 manifest SHA-256 是 3c00bb1b1ada0542de91785001395fc6d4252e3d8a0844ec5fdfe05b306a481a;sealed receipt SHA-256 是 dde9e72fd1d72b5556f16a121967dfc62ed57217a8b6be030923af4bcda870bb。 miss 复制 17,545,915,883 bytes,hit copiedBytes=0 且 modelStagedBytes=0。
  • Worker scope fixture contract 的 SHA-256 是 0e799649aeb9bd41018f8ad831bbc7eee7380d363c2be3aab9a0e04d94411c09;它证明只会把 PVC/env/selector 注入 exact Qwen 粗切 builtin,其他 operator 保持为空。