目标机器（参考）：两卡 GPU（2 × 32GB），CPU 18–20 核，内存 80 GiB，硬盘 >= 200 GB（模型大）。
本指南给出从零到可运行 demo 的完整步骤、排错要点和「截图占位」位置，方便你边做边截图贴回。关键外部资源（驱动 / CUDA / PyTorch / vLLM / ModelScope）已在文末给出参考链接。(NVIDIA)

一、准备工作（开工前请确认）

1. 你有 root 或能 sudo 的用户。
2. 已在腾讯云控制台选择正确镜像：Ubuntu 22.04。
3. 有稳定网络（下载模型时建议能访问 ModelScope / 或使用国内镜像）。
4. 硬盘空间建议 ≥ 300 GB（模型、缓存、临时文件、系统更新余量）。
5. 推荐先把所有命令在一个终端按顺序执行并截图（在每个「截图占位」处插入截图）。

二、总体步骤概览（快速看板）

1. 系统更新 + 必要工具
2. 安装 NVIDIA 驱动（535.216.01）并验证 nvidia-smi。(NVIDIA)
3. 安装 CUDA Toolkit 12.2（及设置环境变量并验证 nvcc --version）。(NVIDIA Developer)
4. 安装 Miniconda / 建立 conda env（Python 3.10）。
5. 安装 PyTorch（与 CUDA 匹配）与其他 Python 依赖（transformers、vllm、bitsandbytes 等）。(PyTorch)
6. 安装 ModelScope，使用 modelscope download 获取 Keye-VL 模型文件并检查路径。(ModelScope)
7. 运行示例 keye_gradio_demo.py 或使用 vLLM 启动高效推理。(VLLM Docs)
8. 验证推理（样例图片/视频输入），保存日志/截图。

三、详细步骤（保姆级命令 + 说明）

3.0 进入首个 shell（建议）

3.1 系统更新 & 基础依赖

sudo apt update && sudo apt upgrade -y
sudo apt install -y build-essential git wget curl ca-certificates gnupg lsb-release
# kernel headers (用于编译驱动/模块)
sudo apt install -y linux-headers-$(uname -r)

3.2 安装 NVIDIA 驱动（推荐 Data Center driver 535.216.01）

说明：你可以用仓库方式安装 nvidia-driver-535，或从 NVIDIA 官方下载 runfile/deb 安装。驱动版本需与 CUDA/显卡兼容。参考 NVIDIA Driver 535 系列文档。(NVIDIA)

A. 最简（apt 仓库）方式（推荐）

# 添加 NVIDIA PPA（Ubuntu 22.04）
sudo apt install -y software-properties-common
sudo add-apt-repository ppa:graphics-drivers/ppa -y
sudo apt update
sudo apt install -y nvidia-driver-535
sudo reboot

B. 官方 runfile（如需指定 535.216.01）

# 下载后切换到控制台，停止 X 或在无 GUI 的 server 上操作
wget https://us.download.nvidia.com/XFree86/Linux-x86_64/535.216.01/NVIDIA-Linux-x86_64-535.216.01.run
chmod +x NVIDIA-Linux-x86_64-535.216.01.run
sudo ./NVIDIA-Linux-x86_64-535.216.01.run
sudo reboot

验证

nvidia-smi
# 应显示两块 GPU、驱动版本 535.216.01

3.3 安装 CUDA Toolkit 12.2（与环境变量）

说明：建议用 NVIDIA 官方 deb / runfile。安装 CUDA runtime（对应 cuBLAS/cuDNN）并将 PATH/LD_LIBRARY_PATH 写入 ~/.bashrc。请以官方 CUDA 12.2 下载页为准。(NVIDIA Developer)

示例（deb network）

# 示例仅作参考，实际请从 NVIDIA CUDA 12.2 页面选择 Ubuntu 22.04 并按官方步骤
wget https://developer.download.nvidia.com/compute/cuda/12.2.0/local_installers/cuda_12.2.0_*.run
sudo sh cuda_12.2.0_*.run
# 或使用 deb 网络安装

设置环境变量

echo 'export PATH=/usr/local/cuda-12.2/bin:$PATH' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda-12.2/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc
source ~/.bashrc
nvcc --version

注意：有时系统会自动安装较新 CUDA（例如 12.5/12.6），导致与 PyTorch wheel 不匹配。若发现 nvcc 版本与目标不符，请按官方文档安装指定 12.2 版本或使用 PyTorch 与系统 CUDA 一致的 wheel。(NVIDIA Developer)

3.4 安装 Miniconda、创建 conda 环境（推荐）

# 若未安装 Miniconda
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh -b -p $HOME/miniconda
eval "$($HOME/miniconda/bin/conda shell.bash hook)"
conda init
source ~/.bashrc

# 创建环境
conda create -n keye python=3.10 -y
conda activate keye

3.5 安装 PyTorch（与 CUDA 匹配）和常用依赖

说明：你提供的命令 pip install torch==2.1.2 torchvision==0.16.2 --index-url
https://download.pytorch.org/whl/cu121 是为 CUDA 12.1 (cu121) 的 wheel。若系统 CUDA 是 12.2，你可仍用 cu121 wheel（通常兼容），但最好以 PyTorch 官方「选择器」为准。(PyTorch)

示例命令（保留用户原始版本）

pip install --upgrade pip
pip install torch==2.1.2 torchvision==0.16.2 --index-url https://download.pytorch.org/whl/cu121

常用 Python 包（建议顺序安装以避免依赖冲突）

pip install --upgrade "transformers>=4.55.0" "tokenizers>=0.21.1"
pip install pillow opencv-python-headless ffmpeg-python
pip install modelscope
# bitsandbytes、peft、accelerate
pip install bitsandbytes==0.42.0 peft==0.7.0 accelerate==0.27.0
# vLLM（高效推理）
pip install "vllm>=0.9.2"
# Keye-VL 官方工具包（若可用）
pip install keye-vl-utils

验证 torch + CUDA

python - <<'PY'
import torch, sys
print("torch:", torch.__version__)
print("cuda available:", torch.cuda.is_available())
print("cuda version (build):", torch.version.cuda)
print("gpu count:", torch.cuda.device_count())
print("current device name:", torch.cuda.get_device_name(0))
PY

3.6 bitsandbytes / 编译问题（常见坑）

• bitsandbytes 可能因为系统 CUDA 映像或 GCC 版本不匹配导致报错（常见）。若 pip install bitsandbytes 失败，参考 bitsandbytes 官方安装说明，必要时编译或使用官方 wheel。(Hugging Face)
• 若遇到 libcusparse/symbol not found 类错误，通常是 CUDA runtime / driver 不匹配或需要重装 bitsandbytes 对应的 wheel。解决办法：尝试匹配 PyTorch wheel，或按 bitsandbytes 文档从源码编译（会用到 CUDA_HOME 等环境变量）。

3.7 vLLM 安装注意（高效推理）

• vLLM 对 GPU / CUDA 版本敏感：若 pip wheel 不匹配你的 CUDA，有时需要从源代码编译。若使用官方 pip 安装遇到问题，参考 vLLM 官方文档的 GPU 安装章节（包含从源构建说明）。(VLLM Docs)

3.8 安装 ModelScope & 下载 Keye-VL 模型

安装 CLI

pip install --upgrade modelscope

命令行下载（你之前的命令）

modelscope download --model Kwai-Keye/Keye-VL-1.5-8B --local_dir ./Keye-VL-1.5-8B
# 或不指定 local_dir，让 modelscope 放到 cache（例如 /root/.cache/modelscope/...）

说明：ModelScope 有时需要登录/Token 或有权限控制（依据模型发布策略）。若下载失败，请登陆 ModelScope 网站并检查是否需要 API token。ModelScope 文档描述了下载与凭证流程。(ModelScope)

下载完成后检查路径（示例）

/root/.cache/modelscope/hub/models/Kwai-Keye/Keye-VL-1___5-8B/

3.9 运行官方示例 keye_gradio_demo.py

假设：仓库里已包含 keye_gradio_demo.py 或官方示例。先 cd 到 repo，然后运行。

# 进入示例目录（视实际路径）
cd ./Keye-VL-1.5-8B/examples
# 如果示例依赖额外 requirements
pip install -r requirements.txt

# 运行 demo（示例）
python keye_gradio_demo.py --model_dir /root/.cache/modelscope/hub/models/Kwai-Keye/Keye-VL-1___5-8B/ --device cuda

若想用 vLLM 启动更高效的服务（示例）

# 基于 vLLM 启动一个服务（示例参数，须按项目 README 调整）
vllm_server --model /path/to/your/model --port 8000 --tensor_parallel_size 2

四、验证 & 测试（必须做）

1. nvidia-smi（GPU 驱动、显存、进程）——截图。
2. nvcc --version（CUDA）——截图。
3. python 中运行 torch.cuda.is_available() & vllm 模块 import 成功测试。
4. 使用示例图片或短视频做一次推理（保存输出文件与日志）。

五、常见错误与解决办法（排错速查）

• ModuleNotFoundError: No module named 'bitsandbytes' / 导入后 OOM：确认 bitsandbytes 安装成功并与 CUDA 兼容；尝试 pip uninstall bitsandbytes && pip install bitsandbytes --no-cache-dir 或参考官方文档编译。(Hugging Face)
• transformers 版本冲突：你遇到过安装 transformers 报错，通常通过 pip install --upgrade "transformers>=4.55.0" "tokenizers>=0.21.1" 修复（你已做）。若仍冲突，建议使用 clean conda env 重来，先安装 torch，再安装 transformers（避免 pip 自动降级）。
• vLLM 导入或运行报错（CUDA mismatch）：按 vLLM 文档，如果 CUDA 版本与 pip wheel 不匹配，需从源码编译。(VLLM Docs)
• 下载被中断或慢：ModelScope 在国内通常较快；也可以尝试 hugggingface（如果模型在 HF 有镜像）或利用分片下载工具。(Hugging Face)

六、建议的安全/性能优化（可选）

• 启用 NVIDIA persistence mode：sudo nvidia-smi -pm 1。
• 调整 ulimit -n / ulimit -u，确保大并发时 socket/file 描述符充足。
• 设置 NCCL_DEBUG=INFO、NCCL_SOCKET_IFNAME=eth0 等网络优化（多机场景）。
• 若使用两张卡并行，考虑使用 tensor/model parallel 或 vLLM 的并行配置。

七、完整命令清单（可复制粘贴）

把常用命令整理成一块，按需运行（与以上步骤重复，仅作速查）。

# 系统更新
sudo apt update && sudo apt upgrade -y
sudo apt install -y build-essential git wget curl ca-certificates gnupg lsb-release linux-headers-$(uname -r)

# 安装驱动（apt 方式）
sudo add-apt-repository ppa:graphics-drivers/ppa -y
sudo apt update
sudo apt install -y nvidia-driver-535
sudo reboot

# 安装 Miniconda & env
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh -b -p $HOME/miniconda
eval "$($HOME/miniconda/bin/conda shell.bash hook)"
conda create -n keye python=3.10 -y
conda activate keye

# CUDA: 按官方步骤安装 CUDA 12.2（网页下载后执行）
# 设置环境变量
echo 'export PATH=/usr/local/cuda-12.2/bin:$PATH' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda-12.2/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc
source ~/.bashrc

# Python packages (示例)
pip install --upgrade pip
pip install torch==2.1.2 torchvision==0.16.2 --index-url https://download.pytorch.org/whl/cu121
pip install --upgrade "transformers>=4.55.0" "tokenizers>=0.21.1"
pip install pillow opencv-python-headless ffmpeg-python
pip install bitsandbytes==0.42.0 peft==0.7.0 accelerate==0.27.0
pip install "vllm>=0.9.2"
pip install modelscope keye-vl-utils

# 下载模型
modelscope download --model Kwai-Keye/Keye-VL-1.5-8B --local_dir ./Keye-VL-1.5-8B

# 运行 demo
python keye_gradio_demo.py --model_dir ./Keye-VL-1.5-8B --device cuda

八、附件（关键参考与出处）

• 参考：https://blog.csdn.net/adreammaker/article/details/134622792#1_35
• CUDA Toolkit 12.2 Downloads（官方安装包和安装说明）。(NVIDIA Developer)
• PyTorch — previous versions / wheel 安装说明（选择合适的 cu* wheel）。(PyTorch)
• vLLM — GPU 安装与从源码构建提示（当 wheel 与 CUDA 不匹配时）。(VLLM Docs)
• ModelScope — 模型下载与 CLI 使用说明。(ModelScope)