# 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= 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 保持为空。