FAQ.zh

常见问题（FAQ）

English | Русский | 中文

为什么专家权重要放主机内存，而不是「直接装下」？

一个 384 专家 × 69 层的模型，仅专家权重就是每 TP rank 约 118 GiB。四块 96 GB 卡 共约 384 GB，但你还需要 KV cache、CUDA graph、激活值和预留。没有 NVLink 时， 唯一的合理卸载路径就是经 PCIe 到锁定的主机内存（UVA）。专家均衡决定什么常驻显存。

什么是 UVA？

统一虚拟寻址（Unified Virtual Addressing）：GPU 可以通过 PCIe 直接读取锁定的主机内存， 无需显式拷贝内核。run-tp4-uva.sh 以 --offload-backend uva 启动 vLLM。 冷门专家驻留在 UVA 中；热门专家在真正的显存中。

为什么显存带宽不是瓶颈？

常常确实不是：冷门命中受 PCIe 限制（本主机：PCIe 4.0 插槽，每卡约 25 GB/s）。 规划器尽量减少冷门命中；dynamic 模式进一步提升热门命中率。关注日志行 hot/cold hit-rate。

GLM-5.3-Flash 在 vLLM 上启动不了 —— 怎么回事？

已知阻塞项。 glm5_next 使用无 rope 的 MLA（qk_rope_head_dim=0），原版 vLLM 在 SM120（RTX PRO 6000）上崩溃：assert "pe_dim must be 64 for fp8_ds_mla" （vLLM issues #53963、#55773）。修复候选 PR #55277 / #55778 / FlashInfer #4802 尚未合入上游。配方诚实地记录了该阻塞；均衡数学已就绪并经测试 —— 上游修复 一到，启动即可工作。

需要 NVLink 吗？

不需要。全部四个配方都是为纯 PCIe 的 TP4 设计的。NUMA 感知放置 （HOTSPLIT_NUMA_POLICY = preferred / bind）有助于让主机内存靠近 对应 GPU 的 PCIe root complex。

Static 还是 dynamic？

• Static：可预测、零运行时开销，来自你的流量直方图。
• Dynamic（默认）：适应实时流量，换入换出代价极小，命中率随时间提升。 可测量：每次更新的 hot/cold hit-rate。

为什么启动脚本拒绝启动（IMAGE / MODEL_REVISION / API_KEY）？

这是有意设计。三个参数必填：

• IMAGE 必须以 @sha256:<digest> 固定 —— 浮动标签被拒绝。
• MODEL_REVISION（40 字符 commit SHA）在按 id 下载模型时必需。
• API_KEY 即使 127.0.0.1 也必需 —— 只有 ALLOW_NO_AUTH=1 可跳过，且仅限回环。 启动脚本不会“凑合”启动配错的服务器。见快速上手。

信任边界是什么（清单、remote code、docker inspect）？

首次运行前需要了解三件事：

1. patches/MANIFEST.sha256 能抓住意外修改和简单替换，但清单和补丁在同一目录树里。 对仓库有写权限的攻击者可以同时替换两者。请固定你审阅过的 git 修订版 （git rev-parse HEAD）并与之比对。
2. --trust-remote-code 允许模型执行自己的 Python。固定 MODEL_REVISION 能防止后续 下载时的静默变更，但不使代码本身安全。首次运行前请审阅模型的 remote code。
3. API 密钥通过容器环境变量传递（VLLM_API_KEY）。能执行 docker inspect 的人都能 读到它。docker 访问等同于 root —— 请加以限制。

API 会暴露到外网吗？

默认 BIND=127.0.0.1（仅回环）。要对局域网提供服务，请设 BIND=0.0.0.0 并且设置 API_KEY —— 启动脚本拒绝没有密钥的非回环绑定（ALLOW_NO_AUTH=1 只在回环下被接受）。

启动后怎么确认一切真的在工作？

scripts/check-hotsplit-tp4.sh <container> <dynamic|static> —— 每个 rank 必须报告 dynamic_hook=ACTIVE（dynamic）和 hotsplit done。然后对 /v1/chat/completions 做冒烟测试。完整测量流程（TTFT/TPOT、PCIe 流量、compute-sanitizer 竞态检查）： 见配方的 RUNNING.md。

我可以贡献吗？

可以 —— 见 CONTRIBUTING.md。 契约：数字必须有出处，硬件以机器实际报告为准，补丁带 sha256，已知限制必须列出。 欢迎提交 issue 和 PR。