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

90 lines
5.6 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Qwen 节点本地模型缓存(通用默认关闭;POC 已验收启用)
这个优化只服务于 `operator-builtin-qwen-behavior-rough-cut`。它不会改变
Qwen3-VL 的固定 revision、模型 manifest、BOS/PVC 来源、工作流图或任何已经验收的
运行记录;未开启时保持原有“每个 Pod 复制到 `/tmp` 后加载”的行为。
## 开关与调度边界
Worker 仅在以下配置全部成立时,才给这个 **唯一 allowlisted builtin** 注入缓存 PVC、
缓存环境变量和 node selector:
```text
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 保持为空。