# Z100L gfx906 大模型推理运行环境包 这个包面向 Z100L / gfx906 显卡用户，用于在一台已经安装好系统和显卡驱动的机器上，快速部署一套可运行 vLLM / OpenAI-compatible API 的推理环境。 包内包含： - DTK 26.04 运行时 - hyhal / 管理库运行时 - 已配置好的 Python venv - 针对 Z100L/gfx906 打过补丁并用于实测的 vLLM 源码 - Qwen3.6 27B 专用启动脚本 - Qwen3/Coder 工具调用兼容 chat template - API 自检脚本 - 详细教程和排障文档 模型权重不随包发布。请自行将模型目录放到 `/opt/z100l-llm/models/` 下。 ## 1. 机器前提 建议系统：Ubuntu 22.04 系列。新机器至少需要已经能识别 Z100L 显卡，`lspci` 能看到显卡设备。安装本包后会提供 DTK 用户态运行时和 Python/vLLM 环境。 常用依赖： ```bash sudo apt-get update sudo apt-get install -y git curl ca-certificates build-essential numactl pciutils ``` 如果系统没有 `rsync`，安装脚本会自动回退到 `tar` 复制。 ## 2. 一条命令解包安装 假设压缩包位于当前目录： ```bash sudo mkdir -p /opt/z100l-llm && \ sudo tar -xzf z100l-llm-runtime-gfx906-dtk26-vllm-qwen36.tar.gz -C /opt/z100l-llm --strip-components=1 && \ sudo /opt/z100l-llm/install.sh ``` 安装脚本会： - 写入 `/opt/z100l-llm/env.sh` - 建立 `/opt/dtk -> /opt/z100l-llm/dtk-26.04` - 建立 `/usr/local/hyhal -> /opt/z100l-llm/hyhal` - 修复 Python venv 的可重定位启动路径 - 创建 cache、logs、tmp、models 目录 加载环境： ```bash source /opt/z100l-llm/env.sh python - <<'PY' import torch print(torch.__version__, torch.version.hip, torch.cuda.is_available(), torch.cuda.device_count()) PY ``` ## 3. 放置模型 示例目录： ```bash sudo mkdir -p /opt/z100l-llm/models sudo cp -a /path/to/qwen3.6-27b-uncensored-heretic-v2-native-mtp-preserved /opt/z100l-llm/models/ ``` 也可以不复制模型，启动时直接指定 `MODEL=/path/to/model`。 ## 4. 启动 Qwen3.6 27B uncensored 最大上下文服务 推荐启动命令： ```bash sudo -E bash -lc 'MODEL=/opt/z100l-llm/models/qwen3.6-27b-uncensored-heretic-v2-native-mtp-preserved PORT=18631 MAX_NUM_SEQS=3 /opt/z100l-llm/scripts/start_qwen36_27b_uncensored_262k.sh' ``` 服务参数核心值： - `--served-model-name qwen36-27b-uncensored` - `--dtype float16` - `--max-model-len 262144` - `--max-num-seqs 3` - `--max-num-batched-tokens 8192` - `--tensor-parallel-size 4` - `--attention-backend TRITON_ATTN` - `--generation-config vllm` - `--default-chat-template-kwargs '{"enable_thinking": false}'` - `--enable-auto-tool-choice` - `--tool-call-parser qwen3_coder` `MAX_NUM_SEQS=3` 是针对 262K 最大上下文的安全值。短 prompt 下可以尝试更高并发，但最大上下文下不建议超过 3。 ## 5. API 自检 ```bash python /opt/z100l-llm/scripts/check_openai_api.py http://127.0.0.1:18631/v1 qwen36-27b-uncensored ``` 手工测试： ```bash curl -s http://127.0.0.1:18631/v1/models | python -m json.tool curl -s http://127.0.0.1:18631/v1/chat/completions \ -H 'Content-Type: application/json' \ -d '{"model":"qwen36-27b-uncensored","messages":[{"role":"user","content":"只回复 NEW_MODEL_OK，不要解释。"}],"temperature":0,"max_tokens":16}' | python -m json.tool ``` ## 6. 通用模型启动 其他模型可使用通用脚本： ```bash sudo -E bash -lc 'MODEL=/opt/z100l-llm/models/YourModel SERVED_MODEL_NAME=your-model PORT=18631 MAX_MODEL_LEN=32768 /opt/z100l-llm/scripts/start_generic_vllm.sh' ``` ## 7. 文档索引 - `docs/QWEN36_27B_OPTIMIZATION.md`：Qwen3.6 27B 优化原理和参数 - `docs/REBUILD_NOTES.md`：重编译和补丁说明 - `docs/TESTED_MODELS.md`：已测试模型清单 - `docs/TROUBLESHOOTING.md`：常见问题和排障 - --------------------------------------------------------------------------------- # Qwen3.6 27B on Z100L/gfx906 优化说明 本文记录本包针对 Qwen3.6 27B 在 Z100L/gfx906 上做过并保留到启动脚本中的关键优化。目标是让非量化 Qwen3.6 27B uncensored 在最大上下文配置下仍能提供可用的单请求 decode 性能，同时保留 OpenAI-compatible API、no-thinking、tool calling 和长上下文能力。 ## 1. 为什么不直接使用通用 demo 通用厂商 demo 通常用于证明算子或框架可以跑通，但不是完整的生产推理服务： - 不覆盖 OpenAI-compatible `/v1/chat/completions` 服务行为。 - 不覆盖 Qwen3.6 27B 的 GDN、full-attention、MTP / long-context 组合路径。 - 不处理 262K 上下文下的 KV cache、chunked prefill、TP4 worker 初始化和超时问题。 - 不包含 Hermes / Codex 类 agent 所需的 no-thinking 和 tool-call parser 兼容。 - 不针对 gfx906 上 vLLM 的 slow fallback 做路由修正。 因此本包采用“DTK + PyTorch + vLLM 源码补丁 + 专用启动参数”的方式，而不是把 demo 当成服务入口。 ## 2. 实测主配置 推荐服务名：`qwen36-27b-uncensored` 核心 vLLM 参数： ```bash vllm serve "$MODEL" \ --host 0.0.0.0 \ --port 18631 \ --served-model-name qwen36-27b-uncensored \ --trust-remote-code \ --dtype float16 \ --max-model-len 262144 \ --generation-config vllm \ --default-chat-template-kwargs '{"enable_thinking": false}' \ --chat-template /opt/z100l-llm/templates/qwen36_uncensored_no_think_qwen3coder_tools_template.jinja \ --enable-auto-tool-choice \ --tool-call-parser qwen3_coder \ --attention-backend TRITON_ATTN \ --tensor-parallel-size 4 \ --gpu-memory-utilization 0.92 \ --language-model-only \ --skip-mm-profiling \ --max-num-batched-tokens 8192 \ --max-num-seqs 3 \ --decode-context-parallel-size 1 \ --kv-cache-auto-trim-ratio 0 ``` ## 3. 最大上下文与并发 在 262144 最大上下文下，`--max-num-seqs 3` 是保守稳定值。原因是最大长度请求占用 KV cache 极大，短 prompt 能跑更高并发不代表最大上下文也安全。 建议： - 面向单用户/agent：`MAX_NUM_SEQS=1` 或 `3`。 - 面向最大上下文测试：保留 `MAX_NUM_SEQS=3`，不要盲目提高。 - 面向短 prompt 吞吐：可以另起服务测试更高并发，但不应混用“短 prompt 并发通过”和“最大上下文可用”。 ## 4. full-attention fast path gfx906 上原始 vLLM 路线中，full-attention prefill 容易落到慢 fallback。保留的关键开关： ```bash export VLLM_Z100L_FULL_ATTN_FAST=1 export VLLM_ROCM_GFX906_SLOW_PREFILL=0 ``` 作用： - 避开 gfx906 slow PyTorch fallback。 - 让 Qwen3.6 full-attention prefill 进入已验证的 fast route。 - 对长上下文 TTFT 有明显影响。 correctness 保护思路： - 开关默认由启动脚本启用。 - 代码中保留 shape / dtype / backend gate。 - 若环境不满足，应 fallback，而不是静默错误。 ## 5. full-attention decode 专用路径 单请求 decode 速度主要受 full-attention decode 和 GDN decode 路径影响。本包保留了 Qwen3.6 27B 专用 decode 开关： ```bash export VLLM_Z100L_DECODE_RAW_ACC=1 export VLLM_Z100L_QWEN36_RAWACC_STAGE1_SPECIALIZED=1 export VLLM_Z100L_DECODE_DYNAMIC_SPLITS=1 export VLLM_Z100L_DECODE_DYNAMIC_THRESHOLD=200000 export VLLM_Z100L_DECODE_DYNAMIC_SHORT_SPLITS=64 export VLLM_Z100L_DECODE_DYNAMIC_LONG_SPLITS=232 export VLLM_Z100L_DECODE_STAGE2_DV_CHUNK=128 export VLLM_Z100L_DECODE_SEPARATE_LSE=1 export VLLM_Z100L_DECODE_SKIP_FINAL_LSE_STORE=1 export VLLM_Z100L_DECODE_ASSUME_CONTIG_BLOCKS=1 export VLLM_Z100L_QWEN36_RAWACC_CONTIG_PAGE_SCALAR=1 export VLLM_Z100L_QWEN36_RAWACC_CONTIG_PAGE_INCREMENTAL=1 export VLLM_Z100L_QWEN36_RAWACC_CONTIG_LINEAR_ADDR=1 ``` 优化原则： - 减少 decode 阶段不必要的通用路径开销。 - 针对 Qwen3.6 27B 的 head/layout 做 specialization。 - 对长上下文 decode 使用更多 split，降低单块工作时间。 - 尽量减少 LSE / 中间结果写回。 - 在连续 page 条件成立时走更简单的地址计算。 ## 6. GDN decode fast path 保留的 GDN decode 开关： ```bash export VLLM_Z100L_GDN_PACKED_FUSED_DECODE=1 export VLLM_Z100L_GDN_PACKED_EXTERNAL_GB=1 export VLLM_Z100L_GDN_BLOCK_TRITON_INPLACE=1 export VLLM_Z100L_GDN_TRITON_CONV_DECODE=0 export VLLM_Z100L_GDN_DECODE_TORCH_FALLBACK=0 export VLLM_Z100L_GDN_DECODE_GRAPH_SAFE=1 export VLLM_Z100L_GDN_GATING_TORCH_FALLBACK=0 ``` 说明： - 当前包保留的是服务中稳定使用的 GDN decode 加速路径。 - 对 short prompt / decode 有收益。 - 对 GDN prefill long chunk 的更激进 kernel 不作为默认启用项，因为服务真实路径中 correctness 和状态语义更复杂。 ## 7. AWQ 说明 本包主要强调非量化 Qwen3.6 27B uncensored。AWQ 模型也被测试过，但它不是本包推荐主路线。AWQ 路径可以用通用脚本运行，或者自行设置 `VLLM_USE_TRITON_AWQ=1`。 ## 8. Hermes / tool calling 兼容 Qwen3 系列若不处理 thinking 和工具模板，容易出现： - 输出 `` 或 Thinking Process。 - tool_calls arguments 不闭合。 - 把工具调用写成普通文本。 - tool result 后重复调用 terminal。 本包保留： - no-thinking chat template。 - `--default-chat-template-kwargs '{"enable_thinking": false}'`。 - `--enable-auto-tool-choice`。 - `--tool-call-parser qwen3_coder`。 如不需要工具调用，可去掉 `--enable-auto-tool-choice` 和 `--tool-call-parser`，但建议保留 no-thinking。 ## 9. 参考性能口径 在经过优化的 Qwen3.6 27B uncensored 服务上，单请求 decode 曾稳定超过 15 tok/s，在短到中等 prompt 下可达到 20 tok/s 以上。实际结果取决于： - 模型权重版本 - prompt 长度 - 是否最大上下文 - DTK/驱动版本 - GPU 供电和散热 - 并发数 请优先用自己的真实测试工具和业务 prompt 验证。 ---------------------------------------------------------------------------------- # 重编译与补丁说明 本包不是厂商 demo 的简单复制，而是把可服务化的大模型推理栈打包到一个可迁移目录中。 ## 1. 包内组件 | 组件 | 作用 | |---|---| | `dtk-26.04/` | DTK 用户态运行时、HIP、LLVM、数学库 | | `hyhal/` | 硬件管理和监控库 | | `venv/` | Python、PyTorch、vLLM 运行依赖 | | `src/vllm-z100l/` | 针对 Z100L/gfx906 补丁后的 vLLM 源码 | | `templates/` | Qwen3 no-thinking/tool-call chat template | | `scripts/` | 启动、通用运行和 API 自检脚本 | ## 2. 重编译/修改过的重点 ### vLLM gfx906 路由 - 修正 full-attention prefill 在 gfx906 上进入 slow fallback 的问题。 - 增加 env-gated fast path。 - 保留 fallback 逻辑，不满足 shape/dtype/backend 时不强行使用 fast path。 ### Qwen3.6 full-attention decode - 增加 Qwen3.6 专用 raw-acc decode 路径。 - 支持动态 split、contiguous page、简化 LSE 写回等优化。 - 通过环境变量控制，便于回滚和 A/B。 ### GDN decode - 增加 packed/fused recurrent decode 相关路径。 - 保留 graph-safe 和 fallback-safe 设计。 - long chunk prefill 激进路径没有作为默认入口。 ### Hermes / Qwen3 工具调用 - 保留 no-thinking 模板。 - 保留 Qwen3-Coder tool parser 兼容启动方式。 - 模板保留 tools 渲染，不用过度简化模板。 ## 3. 为什么不用 demo 入口 demo 适合验证单个模型或算子是否能跑，但不解决： - vLLM worker / OpenAI API 服务化 - TP4 多卡并行 - 262K 上下文 - Qwen3.6 特殊结构 - Hermes/Codex 类 tool calling - 长上下文下的 TTFT / decode 组合瓶颈 因此本包的入口是 vLLM 服务脚本，而不是 demo 脚本。 ## 4. 可调参数 常用稳定参数在 `scripts/start_qwen36_27b_uncensored_262k.sh` 中。建议先直接运行默认值，再逐项 A/B： - `MAX_NUM_SEQS` - `MAX_MODEL_LEN` - `VLLM_Z100L_DECODE_DYNAMIC_LONG_SPLITS` - `VLLM_Z100L_DECODE_NUM_PAR_SOFTMAX_SEGMENTS` - `VLLM_Z100L_GDN_PACKED_*` 如果出现异常，先关掉对应 env，再比较： ```bash VLLM_Z100L_GDN_PACKED_FUSED_DECODE=0 /opt/z100l-llm/scripts/start_qwen36_27b_uncensored_262k.sh ``` ## 5. 开发者建议 - 不要把短 prompt 成功当作最大上下文成功。 - 不要只看 prefill tok/s，decode tok/s 和输出质量同样重要。 - 大上下文模型启动前先确认 KV cache capacity。 - 修改 kernel 后必须做 correctness 检查，不能只看速度。 ---------------------------------------------------------------------------------- # 已测试模型清单 以下模型或模型族在 Z100L/gfx906 环境中做过运行、启动、性能或兼容性测试。本包不包含模型权重。 | 模型/目录名 | 类型 | 结论 | |---|---|---| | `qwen3.6-27b-uncensored-heretic-v2-native-mtp-preserved` | FP16 / uncensored / Qwen3.6 27B | 主推荐路线。用于最大上下文 262K、no-thinking、Hermes tool calling 和 decode 优化。 | | `qwen36-27b-dflash-deepsweet-fp16` | FP16 / Qwen3.6 27B 派生 | 可用于对比 FP16 路径和长上下文行为。 | | `KingsonHO_Qwen3.6-27B-DFlash` | Qwen3.6 27B DFlash | 做过服务化和性能探索。 | | `QuantTrio_Qwen3.6-27B-AWQ` | AWQ 量化 | 可运行，但不是本包主推荐路线。适合显存压力或低门槛测试。 | | Qwen3 系列 ASR/voice 相关组合 | 语音/ASR 探索 | 做过独立探索，本包重点仍是 vLLM 文本模型服务。 | ## 推荐测试顺序 1. 先用小模型或 AWQ 模型验证环境。 2. 再运行 Qwen3.6 27B FP16。 3. 最后开启 262K 最大上下文和 `MAX_NUM_SEQS=3`。 ## 命名说明 服务名建议与模型目录解耦。例如模型目录可以较长，OpenAI API 暴露的服务名固定为： ```text qwen36-27b-uncensored ``` --------------------------------------------------------------------------------- # 常见问题排障 ## 1. `torch.cuda.is_available()` 为 False 确认环境已加载： ```bash source /opt/z100l-llm/env.sh python - <<'PY' import torch print(torch.__version__) print(torch.version.hip) print(torch.cuda.is_available(), torch.cuda.device_count()) PY ``` 确认 `/opt/dtk` 指向包内 DTK： ```bash ls -l /opt/dtk ``` ## 2. 找不到模型目录 把模型放在： ```text /opt/z100l-llm/models/ ``` 或启动时显式指定： ```bash MODEL=/path/to/model /opt/z100l-llm/scripts/start_qwen36_27b_uncensored_262k.sh ``` ## 3. 服务启动慢 27B FP16 + 262K 上下文需要较长初始化时间。第一次启动还可能触发编译和缓存生成。建议保留较长 timeout，不要过早判断失败。 ## 4. 输出出现 `` 或 Thinking Process 确认启动参数包含： ```bash --generation-config vllm --default-chat-template-kwargs '{"enable_thinking": false}' --chat-template /opt/z100l-llm/templates/qwen36_uncensored_no_think_qwen3coder_tools_template.jinja ``` ## 5. Hermes / tool calling 失败 确认启动参数包含： ```bash --enable-auto-tool-choice --tool-call-parser qwen3_coder ``` 如果只做普通聊天，可以不启用工具调用；如果给 agent 使用，建议保留。 ## 6. 最大上下文下 OOM 或请求失败 先用 `MAX_NUM_SEQS=1` 运行，再逐步提高。最大上下文与短 prompt 不同，短 prompt 能跑多并发不代表 262K 请求也能跑多并发。 ```bash MAX_NUM_SEQS=1 /opt/z100l-llm/scripts/start_qwen36_27b_uncensored_262k.sh ``` ## 7. 性能低于预期 优先确认： - 是否使用 4 卡：`--tensor-parallel-size 4` - 是否启用 `--attention-backend TRITON_ATTN` - 是否使用包内 vLLM 源码：`PYTHONPATH=/opt/z100l-llm/src/vllm-z100l` - 是否开启 full-attn fast：`VLLM_Z100L_FULL_ATTN_FAST=1` - 是否误开了过高并发导致 batch decode 下降 ## 8. 回滚到纯 vLLM 行为 可以先关闭 Z100L 专用 env，再用通用脚本运行： ```bash VLLM_Z100L_FULL_ATTN_FAST=0 \ VLLM_Z100L_GDN_PACKED_FUSED_DECODE=0 \ /opt/z100l-llm/scripts/start_generic_vllm.sh ```