Tutti × vLLM 操作手册
本机（TENCENT64）专用。权威架构：
integration/vllm-connector/ARCHITECTURE.md； 设计复盘：doc/intergration/tutti-vllm-integration.md；编排：ai-orch/。
0. 命名与位置（统一，勿混用）
名称 |
路径 |
状态（2026-08-20） |
|---|---|---|
Python 环境 |
|
就绪（uv 建的 venv，python 3.11.16；torch 2.13.0+cu130、numpy、pytest 已装） |
C/C++ 编译器 |
|
就绪（conda 独立环境，gcc/g++ 12.4.0；vllm 要求 ≥11.3） |
rust |
|
就绪（stable 1.97.1， |
环境入口 |
|
就绪（source 即用，见 §7） |
tutti 源码 |
|
主仓库 |
tutti_runtime（pybind） |
|
就绪（T-101，editable 已装） |
connector 适配层 |
|
R1 进行中 |
KV 引擎层 |
|
就绪（T-116：core/backend/memory_backend/chunk_index，59 tests 绿） |
vLLM fork |
|
就绪（0.1.dev20081+gb0e9cff5e，editable 已装） |
vendored CUDA |
|
就绪（CUDA 13.3） |
模型 |
|
冒烟候选：qwen2-5-7B |
trace 负载 |
|
R3 bench 用 |
测试日志 |
|
|
pip/tmp 缓存 |
|
磁盘纪律（系统盘曾满） |
1. 环境要求（已核实）
8×GPU（驱动 580.105.08）；8×NVMe（NUMA1 四盘已 bring-up， NUMA0 四盘待补，见 §3）
系统 python3.6 + gcc8.5：不用，一切进 tutti-env/tutti-compilers
磁盘纪律：TMPDIR/PIP_CACHE/RUSTUP/CARGO 一律指向
/data/home/ryeqiu/
2. 构建 tutti C++（一次，已完成）
cd /data/home/ryeqiu/Tutti
cmake --build build -j # build/ 已有产物，含 libtutti_presets.a
3. snvme 内核模块 + tutti_daemon bring-up
严格三步（详见 doc/tutti_daemon.md）：
# 1) 内核模块（snvme.ko）
# 2) tutti_daemon（controller bring-up + mount）：
sudo env TUTTI_VERBOSE=1 nohup \
./build/cuda-module/bin/tutti_daemon \
--config config/local/tutti_daemon.yaml \
> /data/home/ryeqiu/log/tutti_daemon.log 2>&1 &
# 3) 验证：
ls /dev/snvme* /dev/ssnvme* # 设备节点出现
ls /mnt/nvme*/ # daemon 挂载点非空
# 真机测试 preset：config/local/preset_gpu0.json
# TUTTI_NVME_PRESET=.../preset_gpu0.json \
# python -m pytest tests/contract/test_local_store.py -k real -v
机器重启后需重跑（内核模块不持久）。
4. Python 环境 tutti-env（已完成，T-110）
实际构建方式（uv venv，非 conda）：
# 基座：uv 管理的 cpython-3.11
# /data/home/ryeqiu/uv-python/cpython-3.11-linux-x86_64-gnu/
# tutti-env 是其 venv；torch 2.13.0+cu130（cu130 wheel）已装
source /data/home/ryeqiu/tutti-env/bin/activate
python -c "import torch; print(torch.__version__, torch.cuda.is_available())"
5. 编译器环境 tutti-compilers（已完成）
vllm 要求 GCC≥11.3（PyTorch C++20 headers），系统 gcc8.5 不可用：
# 已用系统 conda 装独立编译器环境（不污染 tutti-env）：
# conda create -y -p /data/home/ryeqiu/tutti-compilers -c conda-forge \
# gcc_linux-64=12 gxx_linux-64=12
/data/home/ryeqiu/tutti-compilers/bin/x86_64-conda-linux-gnu-gcc --version
# 12.4.0
6. 编译 vLLM（进行中，T-110）
source /data/home/ryeqiu/tutti-env/bin/activate
export CUDA_HOME=/data/home/ryeqiu/Tutti/third_pkgs/nvidia/cuda-toolkit
export PATH=$CUDA_HOME/bin:/data/home/ryeqiu/.cargo/bin:$PATH
export CC=/data/home/ryeqiu/tutti-compilers/bin/x86_64-conda-linux-gnu-gcc
export CXX=/data/home/ryeqiu/tutti-compilers/bin/x86_64-conda-linux-gnu-g++
export CUDAHOSTCXX=$CXX # 必须！nvcc host 编译器，CC/CXX 不会传给 nvcc（见 §10）
export TMPDIR=/data/home/ryeqiu/tmp
export RUSTUP_HOME=/data/home/ryeqiu/.rustup CARGO_HOME=/data/home/ryeqiu/.cargo
cd /data/home/ryeqiu/Tutti/third_pkgs/vllm
pip install packaging setuptools-rust setuptools-scm
pip install -r requirements/common.txt -r requirements/cuda.txt # 已完成
# 后台编译（断连不影响）：
nohup bash -c 'MAX_JOBS=48 pip install -e . --no-build-isolation' \
> /data/home/ryeqiu/log/vllm_build.log 2>&1 &
tail -f /data/home/ryeqiu/log/vllm_build.log
# 验证（编译完成后）：
python -c "import vllm; print(vllm.__version__, vllm.__file__)"
# __file__ 必须指向 third_pkgs/vllm（editable 生效）
cd third_pkgs/vllm && git status --porcelain | grep "^ M" | head # 必须无输出
踩过的坑（已解决）：① CUDA_HOME 未设置 → 报错
AssertionError: CUDA_HOME is not set；② GCC 8.5 →
GCC >= 11.3 is required；③ PEP517 元数据阶段挂起（pip -q 无输出假象，
改用 tee 实时日志）；④ 未设 CUDAHOSTCXX → nvcc 用系统 gcc 8.5 当 host，
-std=c++20 被静默忽略，CCCL 报 CUB requires at least C++17（详见 §10）。
7. 每次使用
source /data/home/ryeqiu/env-tutti.sh
env-tutti.sh 内容（已写好）：
source /data/home/ryeqiu/tutti-env/bin/activate
export TMPDIR=/data/home/ryeqiu/tmp PIP_CACHE_DIR=/data/home/ryeqiu/pip-cache
export CUDA_HOME=/data/home/ryeqiu/Tutti/third_pkgs/nvidia/cuda-toolkit
export PATH=$CUDA_HOME/bin:/data/home/ryeqiu/.cargo/bin:$PATH
export CC=/data/home/ryeqiu/tutti-compilers/bin/x86_64-conda-linux-gnu-gcc
export CXX=/data/home/ryeqiu/tutti-compilers/bin/x86_64-conda-linux-gnu-g++
export CUDAHOSTCXX=$CXX # nvcc host 编译器（缺它 → CUB requires at least C++17）
export RUSTUP_HOME=/data/home/ryeqiu/.rustup CARGO_HOME=/data/home/ryeqiu/.cargo
export VLLM_SOURCE=/data/home/ryeqiu/Tutti/third_pkgs/vllm
8. vLLM 端到端测试（R2 起生效）
冒烟（T-202 产出 start_tutti_vllm.sh）
bash <scripts>/start_tutti_vllm.sh --detach # qwen2-5-7B 起步
curl http://localhost:8000/v1/completions -H "Content-Type: application/json" \
-d '{"model":"qwen2-5-7B","prompt":"Hello","max_tokens":16}'
配置核心（外部 connector，零 vLLM 侵入，D-005）：
kv_transfer_config = {
"kv_connector": "TuttiConnectorV1",
"kv_connector_module_path": "adapter.connector",
"kv_role": "kv_both",
"extra_config": {"capacity_bytes": ..., # 必需；硬件无关
"blocks_per_chunk": 0}} # 0=自动（segment≥256KiB 对齐）
验收口径：同一 prompt 两遍，第二遍日志出现外部命中，输出 token 一致。
在环 bench（T-203）
LocalStoreBackend 真实建池（GB 级）→ GPU-direct 写 pattern → 读回校验 → 上报 GB/s（分级对照：单盘 ~7 / NUMA 4 盘 ~28 / 全机峰值 50+GB/s）。
trace 负载（R3，run_tutti_bench.sh）
/data2/traces 持续发压（populate/interleave/stream），结果
/data/home/ryeqiu/log/tutti_bench_*/（TTFT p50/p90/p99 JSON）。
9. 更新后重建
更新了什么 |
操作 |
|---|---|
tutti C++ |
|
connector 适配层 |
无需重编，直接重启 vllm |
engine/kernels |
重装对应包（pip install -e） |
vllm C++/rust |
重跑 §6（增量，rust 缓存有效） |
内核模块/daemon |
重启机器后重跑 §3 |
10. 常见问题
Q: No space left on device（系统盘）
确认 TMPDIR/PIP_CACHE_DIR/RUSTUP_HOME/CARGO_HOME 全部指向 /data
（env-tutti.sh 已封装）；df -h /data。
Q: vllm 编译报 CUDA_HOME is not set
export CUDA_HOME=/data/home/ryeqiu/Tutti/third_pkgs/nvidia/cuda-toolkit。
Q: vllm 编译报 GCC >= 11.3 is required (found 8.5.0)
用 tutti-compilers 的 gcc-12：export CC/CXX（env-tutti.sh 已含）。
Q: vllm 编译报 CUB/Thrust/libcu++ requires at least C++17（大量 .cu 齐挂）
根因：CC/CXX 只管 CMake 的 C++ 侧，不会传给 nvcc。未设
CUDAHOSTCXX 时 nvcc 落回 PATH 的系统 gcc 8.5 当 host 编译器，
-std=c++20 被静默忽略（日志中有一行
nvcc warning : The -std=c++20 flag is not supported with the configured host compiler. Flag will be ignored.），等效按 C++14 编译；而 CUDA 13.0
自带的 CCCL 3.0 要求 ≥C++17，于是所有含 CUB/Thrust 头（torch stable 头
会拉入 thrust/complex.h）的 .cu 全部 #error。
修复：export CUDAHOSTCXX=/data/home/ryeqiu/tutti-compilers/bin/x86_64-conda-linux-gnu-g++
（env-tutti.sh 已含）后重跑 §6。验证：构建日志的 nvcc 命令行应含
-ccbin .../x86_64-conda-linux-gnu-g++。
Q: pip 装依赖长时间无输出（似卡死）
-q + tail 会吞掉下载进度；改用 tee 实时日志（如 pip_cuda.log）。
Q: ls /dev/snvme* 为空 / 拓扑显示 N/A
daemon 未 bring-up 或内核模块未加载：重跑 §3 三步；NUMA0 先用 NUMA1。
Q: import tutti_runtime 失败
TUTTI_BUILD_DIR 未指对，或 tutti C++ 未构建：先 §2 再 §5。
Q: vllm 装成了 pip wheel 而非源码
vllm.__file__ 必须含 third_pkgs/vllm，否则 uninstall 后重跑 §6。
Q: 子 session 的 worktree 里跑测试
全部用 /data/home/ryeqiu/tutti-env/bin/python（3.11，含 pytest）；
T-116/T-117 零 vllm 依赖可直接跑，T-113 起等 T-110 编译完成后。