# K100/gfx926 原生 vLLM 完整运行环境 这是一套面向 K100 显卡用户的通用大模型运行环境。目标是让已经安装好 Linux 系统和 K100 驱动的机器，通过一个完整运行环境包获得 DTK/HIP、Python 运行环境、改造后的 PyTorch/vLLM 源树和通用启动脚本，从而直接用 Hugging Face 模型目录启动 vLLM OpenAI API server。 这条路线不依赖厂商 demo 程序。它使用标准 PyTorch + DTK/HIP + vLLM 服务入口，模型目录、HTTP API、并发参数和张量并行参数都按通用 vLLM 方式暴露，方便后续接入业务服务、测试工具或其他 OpenAI-compatible 客户端。 ## 1. 适用范围 推荐环境： ```text 系统 Ubuntu 22.04 x86_64 或兼容发行版 显卡 K100 / gfx926 驱动 已安装 K100 驱动，hy-smi 可以正常看到显卡 磁盘 建议至少预留 40 GB 给运行环境，模型权重另算 权限 需要 sudo 解压到 /opt 和 /data ``` 运行环境包会安装到这些通用路径： ```text /opt/dtk-26.04 DTK/HIP 运行时 /opt/dtk 指向 /opt/dtk-26.04 的符号链接 /opt/k100-vllm Python 环境、PyTorch/vLLM 源树、脚本、教程 /data/models 默认模型目录 /data/k100-cache 默认缓存目录 ``` 包内不包含模型权重。模型权重需要按各模型 license 自行下载。 ## 2. 一条命令解包 如果系统已经有 `zstd`： ```bash sudo tar --zstd -xpf k100-vllm-gfx926-full-runtime-20260621.tar.zst -C / ``` 如果系统没有 `zstd`，可以用一条 shell 命令先安装再解包： ```bash sudo apt-get update && sudo apt-get install -y zstd && sudo tar --zstd -xpf k100-vllm-gfx926-full-runtime-20260621.tar.zst -C / ``` 解包后先做基础检查： ```bash source /opt/k100-vllm/env.sh bash /opt/k100-vllm/check_runtime.sh ``` 正常情况下会看到： ```text hy-smi 能看到 K100 hipcc 能输出 DTK/HIP 版本 torch 可以 import vllm 可以 import triton 可以 import torch.cuda.is_available() 为 True device_count 大于 0 ``` ## 3. 当前运行栈版本 该运行环境固定了一组已经在 K100/gfx926 上验证过的组合： ```text DTK/HIP 26.04 Python 3.10 PyTorch 2.9.1a0+gitd38164a，K100/gfx926 改造构建 vLLM 0.21.1.dev0+gad7125a43.d20260522.rocm633，K100/gfx926 改造构建 Triton 3.6.0+git7c56a5e4.k100gfx926 Transformers 5.5.4 FastAPI 0.135.3 Uvicorn 0.44.0 FunASR 1.3.1 ``` 实际版本以 `bash /opt/k100-vllm/check_runtime.sh` 输出为准。 ## 4. 不使用厂商 demo 的原理 厂商 demo 通常把模型、入口、参数、服务协议和部分算子路径封装在固定示例中，能快速演示，但不利于运行更多 Hugging Face 模型，也不利于业务侧按 OpenAI API、vLLM 参数和多模型服务方式接入。 本路线采用的是： 1. 使用 DTK/HIP 作为底层运行时。 2. 使用 PyTorch 作为通用张量和模型执行框架。 3. 使用改造后的 vLLM 作为 OpenAI-compatible 推理服务。 4. 对 gfx926/K100 缺失或不稳定的 ROCm/Triton/CUDA 生态路径增加识别、fallback 或 HIP/C++ kernel。 5. 模型仍然按标准 Hugging Face 目录组织，不绑定 demo 内置模型。 换句话说，启动模型时不调用厂商 demo，而是直接调用： ```bash python -m vllm.entrypoints.openai.api_server ``` 包内的 `/opt/k100-vllm/run_openai_server.sh` 只是把常用环境变量和参数整理成脚本。 ## 5. 重新编译和改造过的内容 核心重编译内容： ```text PyTorch K100/gfx926 构建 vLLM C++/HIP 扩展 vllm._C vllm._rocm_C vllm._moe_C Triton K100/gfx926 Python 包 ``` 主要改造方向： ```text vLLM ROCm 平台识别和 gfx926 selector attention / paged prefill / decode fallback Qwen/Qwen3/Qwen3.6 相关 RoPE、MRoPE、GDN、linear attention 路线 small batch decode / skinny GEMM 兼容 AWQ/GPTQ/bitsandbytes/flash-attn/xformers import 兼容层 采样、KV cache、spec decode 的稳定 fallback ``` 包内还保留了 AITER/CK Tile 相关可选源码快照，位置： ```text /opt/k100-vllm/optional-src/aiter ``` 默认不启用 AITER fused MoE，因为不同 DTK/驱动/模型组合下需要单独验证。需要实验时再基于该源码编译，不建议作为默认生产路径直接打开。 ## 6. 下载模型 默认模型目录是： ```bash /data/models ``` 可以直接使用 Hugging Face： ```bash source /opt/k100-vllm/env.sh hf download Qwen/Qwen3-0.6B --local-dir /data/models/Qwen3-0.6B ``` 如果网络环境需要镜像： ```bash export HF_ENDPOINT=https://hf-mirror.com hf download Qwen/Qwen3-0.6B --local-dir /data/models/Qwen3-0.6B ``` 也可以把已有模型目录复制到 `/data/models/`。目录里应包含 `config.json`、tokenizer 文件、权重文件等标准 Hugging Face 内容。 ## 7. 启动 vLLM OpenAI API server 单卡启动： ```bash source /opt/k100-vllm/env.sh export HIP_VISIBLE_DEVICES=0 export K100_MODEL=/data/models/Qwen3-0.6B export SERVED_MODEL_NAME=Qwen3-0.6B export PORT=8000 export MAX_MODEL_LEN=32768 export MAX_NUM_SEQS=8 export MAX_NUM_BATCHED_TOKENS=16384 bash /opt/k100-vllm/run_qwen_tp1.sh ``` 同 CPU 下双卡 TP2： ```bash source /opt/k100-vllm/env.sh export HIP_VISIBLE_DEVICES=0,1 export K100_MODEL=/data/models/Qwen3-8B export SERVED_MODEL_NAME=Qwen3-8B export PORT=8000 export MAX_MODEL_LEN=65536 export MAX_NUM_SEQS=8 export MAX_NUM_BATCHED_TOKENS=32768 bash /opt/k100-vllm/run_qwen_tp2.sh ``` 四卡 TP4： ```bash source /opt/k100-vllm/env.sh export HIP_VISIBLE_DEVICES=0,1,2,3 export K100_MODEL=/data/models/Qwen3-14B export SERVED_MODEL_NAME=Qwen3-14B export PORT=8000 export MAX_MODEL_LEN=65536 export MAX_NUM_SEQS=8 export MAX_NUM_BATCHED_TOKENS=32768 bash /opt/k100-vllm/run_qwen_tp4.sh ``` 通用脚本参数说明： ```text K100_MODEL 模型目录 SERVED_MODEL_NAME 对外暴露的模型名 HIP_VISIBLE_DEVICES 使用哪些 K100 TP 张量并行数量，run_qwen_tp1/2/4 会自动设置 MAX_MODEL_LEN 最大上下文长度 MAX_NUM_SEQS 最大并发序列数 MAX_NUM_BATCHED_TOKENS 单批最大 token 数 GPU_MEMORY_UTILIZATION vLLM 显存利用率，默认 0.90 EXTRA_ARGS 追加给 vLLM 的参数 ``` 检查服务： ```bash curl http://127.0.0.1:8000/v1/models ``` 发起一次 chat completions： ```bash curl http://127.0.0.1:8000/v1/chat/completions \ -H 'Content-Type: application/json' \ -d '{ "model": "Qwen3-0.6B", "messages": [{"role": "user", "content": "用一句话介绍 K100 原生 vLLM 路线。"}], "max_tokens": 128, "temperature": 0.2 }' ``` ## 8. 已测试模型类型 下面是已做过 runtime smoke 或服务 bakeoff 的模型类型。详细表格见： ```text /opt/k100-vllm/public-guide/docs/tested_models.md ``` 已完成 smoke 的代表模型： ```text Qwen/Qwen3-0.6B Qwen/Qwen2.5-0.5B-Instruct HuggingFaceTB/SmolLM2-135M-Instruct TinyLlama/TinyLlama-1.1B-Chat-v1.0 deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B facebook/opt-125m BAAI/bge-small-zh-v1.5 BAAI/bge-small-en-v1.5 sentence-transformers/all-MiniLM-L6-v2 BAAI/bge-reranker-base dslim/bert-base-NER Helsinki-NLP/opus-mt-en-zh google/vit-base-patch16-224 microsoft/resnet-50 facebook/detr-resnet-50 nvidia/segformer-b0-finetuned-ade-512-512 depth-anything/Depth-Anything-V2-Small-hf Salesforce/blip-image-captioning-base HuggingFaceTB/SmolVLM-256M-Instruct openai/whisper-tiny MIT/ast-finetuned-audioset-10-10-0.4593 facebook/mms-tts-eng segmind/tiny-sd TheBloke/TinyLlama-1.1B-Chat-v1.0-AWQ TheBloke/TinyLlama-1.1B-Chat-v1.0-GPTQ unsloth/Qwen3-0.6B-bnb-4bit FunAudioLLM/SenseVoiceSmall ``` 语音服务 bakeoff 中验证过： ```text Qwen3-ASR-1.7B zai-org/GLM-ASR-Nano-2512 VibeVoice-ASR-HF FunAudioLLM/Fun-ASR-Nano-2512 mistralai/Voxtral-Mini-4B-Realtime-2602 CosyVoice2-0.5B ``` Qwen3.6/GDN/MTP 路线验证过可加载和测试，但长上下文、TP4 和高并发性能仍强依赖 PCIe 拓扑、功耗策略、kernel selector 和模型大小。建议先用 TP1/TP2 确认质量，再逐步扩大上下文和并发。 ## 9. 量化和 CUDA 生态兼容边界 本环境包含 AWQ/GPTQ/bitsandbytes/flash-attn/xformers 相关兼容处理，目标是让更多模型能导入、能 smoke、能走 fallback。 需要注意： 1. 这不是 CUDA 原生 bitsandbytes/flash-attn 的完整等价替代。 2. AWQ/GPTQ/bnb 4-bit 已做小模型 smoke，但大模型和高性能路径要逐模型验证。 3. flash-attn 类 import 能兼容不代表一定会走高性能 native flash-attn kernel。 4. 需要追求极限吞吐时，应优先用 vLLM 已验证的 ROCm/HIP 路线和稳定 fallback，再逐个打开实验 kernel。 ## 10. 常见问题 ### hy-smi 看不到卡 先处理驱动和 PCIe 识别问题。运行环境包不包含驱动，也不会替代驱动安装。 ```bash hy-smi lspci | grep -i -E 'display|vga|hygon|k100' ``` ### import torch 失败 确认已经 source 环境： ```bash source /opt/k100-vllm/env.sh which python python -c "import torch; print(torch.__version__)" ``` `which python` 应指向： ```text /opt/k100-vllm/venv/bin/python ``` ### vLLM 启动显存不够 降低这些参数： ```bash export MAX_MODEL_LEN=32768 export MAX_NUM_SEQS=4 export MAX_NUM_BATCHED_TOKENS=8192 export GPU_MEMORY_UTILIZATION=0.85 ``` ### TP4 比 TP2 慢 K100 多卡性能强依赖 PCIe 拓扑。跨 CPU root complex 的 TP4 可能让通信开销压过计算收益。推荐顺序： ```text 先测 TP1 再测同 CPU 下 TP2 最后再测 TP4 ``` 如果目标是吞吐而不是单请求延迟，也可以考虑多个 TP1/TP2 服务副本加业务侧调度，但这属于服务架构选择，不是 vLLM 单进程参数。 ### 长上下文启动失败 先从小上下文开始： ```text 8k -> 32k -> 64k -> 128k -> 256k ``` 每一步确认能加载、能出字、质量正常，再增加并发。 ## 11. 建议的验证顺序 ```bash source /opt/k100-vllm/env.sh bash /opt/k100-vllm/check_runtime.sh ``` 然后： 1. 下载或复制一个小模型到 `/data/models`。 2. 用 TP1 启动。 3. `curl /v1/models`。 4. 做一次 `chat/completions`。 5. 增大上下文。 6. 增加并发。 7. 再切换 TP2/TP4。 8. 最后再测试量化、多模态、ASR/TTS 或业务模型。 ## 12. 包内文档 ```text /opt/k100-vllm/POST_EXTRACT_README.md /opt/k100-vllm/public-guide/README.md /opt/k100-vllm/public-guide/docs/tested_models.md /opt/k100-vllm/public-guide/docs/rebuilt_components.md /opt/k100-vllm/MANIFEST.json ``` 推荐先看 `POST_EXTRACT_README.md` 做快速启动，再看 `public-guide/README.md` 理解完整路线。