简介《DeepSeek 在 Linux 系统下的手动部署步骤与注意事项》是一份面向深度学习开发者及 Linux 运维人员的 PDF 操作指南聚焦如何在 Ubuntu 等系统中从零完成 DeepSeek 的安装、配置与运行适合准备用 GPU 加速训练或推理的读者参考。资源共 1 个 PDF 文件大小 215KB内容紧凑、步骤清晰涵盖环境准备、创建 Python 虚拟环境、克隆代码库、安装依赖包、修改 config.yaml、准备数据以及执行 train.py 和 infer.py 的完整流程。目前已有 794 人学习下载。文档不仅给出终端命令还特别分析了依赖包冲突、GPU 未被检测到、内存不足、文件权限等部署中常见的坑并给出对应检查方向如确认 CUDA/cuDNN 版本兼容性、检查 PATH 与 LD_LIBRARY_PATH 环境变量等。对首次在 Linux 上部署 DeepSeek 的新手来说这份资源能帮助少走弯路快速完成模型运行环境的搭建。1. DeepSeek 在 Linux 下的手动部署先想清楚这三件事如果你已经拿到一台 Linux 服务器想在它上面把 DeepSeek 跑起来最省事的做法当然是甩一个 Docker 命令或者一键脚本但手动部署的意义恰恰在于你能看清每个组件在做什么也能在出问题时知道去哪一行日志里找答案。DeepSeek 这类大模型在 Linux 下的手动部署本质上就是三件事——准备环境、选对推理引擎、把模型权重下载下来并以服务形式启动。它解决的核心诉求是对环境的完全掌控定制量化格式、指定显存分配策略、接入你自己的鉴权和调度逻辑。这篇文章适合两类人一是手上有多卡 GPU 机器、想跑满血版 DeepSeek-R1 的工程师二是只有一张消费级显卡、想跑蒸馏版做原型验证的开发者。手动部署比看起来简单但坑也集中在环境版本和显存估算上下文会一步步拆开。2. Linux 部署前的环境盘点显卡、驱动与 Python 解释器2.1 先确认你是哪一类部署者单卡跑蒸馏版还是多卡跑大模型DeepSeek 模型分两条线一条是满血版参数量达到 671B 的 MoE 架构哪怕用 FP8 量化权重也有 700GB 上下单张 80GB 的卡根本装不下必须走多卡张量并行或多机推理另一条是蒸馏版常见的有 7B、14B、32B、70B 等是在小模型上把满血版的推理风格蒸馏出来的单张 24GB 的卡就能跑量化后的 32B 版本。手动部署的第一步不是敲命令而是先回答「我到底要跑哪个模型」因为这一决定直接约束后面所有环节模型文件从哪下载、用哪个推理引擎、需要几张卡、显存够不够。我一般会这样判断如果你的机器是单卡且显存在 24GB 以下主战场是 7B 到 32B 的蒸馏版部署重点是量化格式和 CPU/GPU 协同如果你手上有 4 到 8 张 80GB 的卡目标就是满血版部署重点是并行策略和推理引擎版本。想清楚这些再动手能省下大量试错时间。2.2 用这几条命令把硬件底细摸清进入实操前先花两分钟把机器的家底摸清。下面三组命令我在每台新机器上都会跑一遍它们能回答「显卡是否可用」「驱动和 CUDA 是否匹配」「内存够不够」三个问题。# 查看 GPU 型号、显存总量和当前占用 nvidia-smi # 查看 GPU 拓扑确认多卡之间是否支持 NVLink / PCIe 直连 nvidia-smi topo -m # 查看系统内存总量和当前可用内存模型权重缓存、CPU offload 都需要 free -gnvidia-smi是最先要看的。注意右上角的 CUDA Version 表示驱动支持的最高 CUDA 版本而不是已安装的 CUDA 工具包版本推理引擎如 vLLM很多情况下自带 CUDA runtime所以系统里装不装 CUDA 工具包反而没那么关键驱动版本拖了后腿才更常见。nvidia-smi topo -m在多卡场景下要看 NV# 标记NVLink 直连的卡之间通信延迟低张量并行效率高如果显示都是 PCIe 连接就要考虑降低并行度、改用数据并行或干脆选小模型。free -g用来确认内存——大模型权重在加载时会先落到内存再搬运到显存内存不足会直接加载失败。2.3 依赖安装CUDA、cuDNN 与 Python 虚拟环境的取舍很多人在依赖这步翻车根源是把「系统级依赖」和「应用级依赖」混在一起处理。对于 DeepSeek 手动部署系统级依赖只有两个NVIDIA 驱动和 Python 解释器其余全部放进虚拟环境。CUDA 工具包和 cuDNN 不是必须手动装的——像 vLLM 这类推理框架会通过 pip 依赖拉取自己的 CUDA runtime 库你系统里装了一套 CUDA 工具包反而可能与框架自带的版本冲突。我踩过的坑是某次在系统里装了 CUDA 12.x 并改了LD_LIBRARY_PATHvLLM 启动时加载了系统动态库结果libcudart版本对不上直接崩。后面统一原则不在全局环境动 CUDA 相关变量依赖全部交给虚拟环境。# 创建专用虚拟环境Python 版本建议 3.10 或 3.11多数推理引擎适配较好 python3 -m venv deepseek-venv # 激活虚拟环境 source deepseek-venv/bin/activate # 升级 pip 和基础工具链 pip install --upgrade pip setuptools wheel虚拟环境的优势不只是隔离包版本更关键的是它把LD_LIBRARY_PATH这类全局变量也一并隔离了你可以在环境内部自由指定 CUDA 相关路径而不影响系统其他服务。Python 版本我建议 3.10 或 3.11太老的解释器装不上新版推理引擎太新的解释器部分依赖库的预编译 wheel 还没跟上。到这里环境准备就绪下一步是选推理引擎和模型格式。3. 推理引擎与模型格式选型vLLM 主路线与备选方案3.1 为什么首选 vLLM连续批处理与 PagedAttention大模型推理的吞吐瓶颈不在计算而在「显存管理和批调度」。vLLM 之所以成为主流选择是因为它解决了两件关键事PagedAttention 让 KV Cache 不再需要一整块连续显存而是像操作系统的内存分页一样按需分配显存碎片率大幅下降continuous batching 让推理引擎在每个 step 动态决定哪些请求进入批处理多用户并发时吞吐量能比朴素实现高出一个量级。对 DeepSeek 这种超大规模 MoE 模型这两点直接影响部署后的实际使用体验。选型时我还会看重生态对齐DeepSeek 的 MoE 结构里用到 MLA 注意力机制主流推理框架对它的支持是逐步完善的每次版本更新都可能带来兼容性变化。我的建议是选 vLLM 时优先用当前稳定版本线的最新小版本避开刚从 alpha 转正的激进版本。如果你已经在用某个版本且模型能正常返回结果不要为了升级而升级。3.2 备选路线 Ollama 与 llama.cpp什么时候换vLLM 不是唯一选择也不是所有场景的最佳选择。Ollama 的亮点是开箱即用一条命令就能把模型拉下来并以 OpenAI 兼容接口暴露适合个人开发机快速体验llama.cpp 则是纯 CPU/GPU 混合推理的典范量化格式 GGUF 在显存不足时可以依靠 CPU offload 硬跑。但这两条路线在 DeepSeek 满血版面前都有限制Ollama 对超大规模 MoE 的多卡并行支持不如 vLLM 细llama.cpp 的 CPU 推理对于 671B 模型来说速度不现实。我一般这样决策只有一张卡、显存 24GB 以下、目标是跑蒸馏版做功能验证选 Ollama 最省心需要自定义调度、追求高并发吞吐、跑满血版多卡并行选 vLLM。中间地带比如显存 48GB 单卡则看你对速度还是易用性的权重更大。手动部署说到底是为了掌控细节vLLM 的启动参数和监控手段也更适合作为主路线。3.3 量化格式怎么选BF16、FP8 与 AWQ 的现实差异模型量化是部署中最容易陷入「玄学」的环节。按工程惯例量化方式的选择取决于显存瓶颈的类型权重占用是主要瓶颈时考虑 FP8 或 AWQKV Cache 显存不足时考虑 KV Cache 量化。BF16 是基线格式精度最高但体积也最大FP8 是当前大模型部署的主流折中点精度损失在多数场景下难以察觉体积却直接减半AWQ 这类权重量化则更适合显存紧张的单卡场景代价是推理速度可能略降。对 DeepSeek 系列模型的常见选择是多卡显存充足时直接用 BF16 或 FP8 权重蒸馏版在单卡上优先试 AWQ 或 GGUF 的 4-bit 版本。不要一味追求低比特——量化位数越低幻觉和乱答的概率越高这在大模型上比在 CV 任务上更敏感。如果量化后发现输出质量明显下降先往高比特回退而不是急着调温度参数。4. 手动部署实操从创建虚拟环境到启动服务4.1 安装 vLLM 推理引擎与核心依赖进入真实部署环节。激活虚拟环境后先安装 vLLM 本身及配套依赖。这里要说明的是不同模型在 vLLM 里的兼容性存在差异建议以「当前模型在 vLLM 官方文档中的支持状态」为判断基准而不是追新安装 nightly 构建。# 激活前面创建的虚拟环境 source deepseek-venv/bin/activate # 安装 vLLM 及依赖pip 会自动解析 CUDA 版本对应的 wheel如果网络受限可切换国内 PyPI 镜像 pip install vllm # 确认安装版本方便后续对照日志排查 pip show vllmpip show vllm输出的 Version 字段很重要后续如果推理异常到 vLLM 的 GitHub issues 或项目文档里排查时对方第一句就会问你版本号。网络受限时可以用-i https://pypi.tuna.tsinghua.edu.cn/simple这类镜像站但要注意镜像站的同步延迟可能需要错开一段时间再拉取。vLLM 安装时会把torch、transformers、tokenizers等一并装上不需要手动单独安装也不要提前装好这些库以免版本互踩。4.2 下载模型权重目录规划与校验模型权重是纯黑匣子环节——看不到内部结构只能通过哈希值和文件大小判断是否正确。下载前先规划目录我习惯把所有模型权重放在一个独立磁盘分区下避免和系统盘抢占空间。# 创建模型目录按「模型名-参数量-量化格式-日期」命名方便后续多版本共存 mkdir -p /data/models/DeepSeek-R1-Distill-32B-AWQ-20250101 cd /data/models/DeepSeek-R1-Distill-32B-AWQ-20250101 # 使用 huggingface-cli 下载指定仓库示例下载 32B AWQ 量化版按需替换仓库名 pip install -U huggingface_hub huggingface-cli download [模型仓库名] --local-dir .--local-dir .把权重下载到当前目录而不是默认的缓存目录这样模型路径可控。下载前通过模型仓库页面确认文件总大小和量化格式如果仓库包含多个分支用--revision指定分支。下载完成后做两件事占用空间较大的权重文件用du -sh确认体积符合预期若仓库提供了sha256校验文件跑一遍校验避免传输损坏导致推理时出现随机乱答。4.3 写一个最小启动脚本并跑起来手动部署与一键脚本最大的区别在于你应该保留一份能看懂每行参数的启动命令。我习惯把启动参数写进一个 shell 脚本而不是每次敲一长串命令这样换模型、调参数时只改一处。#!/bin/bash # 启动脚本 vllm_start.sh source /data/deepseek-venv/bin/activate # 关键参数说明 # --model 模型权重目录或仓库路径 # --tensor-parallel-size 张量并行卡数建议不超过同一 NUMA 节点内 GPU 数 # --max-model-len 最大上下文长度直接影响 KV Cache 显存占用 # --gpu-memory-utilization 允许使用的显存比例留一定余量给模型权重外的开销 # --port API 服务端口 python -m vllm.entrypoints.openai.api_server \ --model /data/models/DeepSeek-R1-Distill-32B-AWQ-20250101 \ --tensor-parallel-size 1 \ --max-model-len 8192 \ --gpu-memory-utilization 0.9 \ --port 8000--tensor-parallel-size是单卡部署时最容易填错的地方只有一张卡就填 1填 2 会直接报错。--max-model-len要按实际业务需要来定填得太大 KV Cache 显存就大能支撑的并发就少填得太小长文本被截断。--gpu-memory-utilization 0.9表示允许用到 90% 显存剩余 10% 留给驱动和模型加载临时开销如果模型刚好卡在显存边缘可以尝试降到 0.95但要承担 OOM 风险。启动后要等日志出现类似Application startup complete的字样才算就绪这个阶段看似卡住是在做模型权重加载和预热。4.4 验证服务可用性的三条命令服务起来后先用最简单的方式验证推理链路是否打通。我常犯的错误是一上来就写复杂测试脚本结果分不清是网络问题还是模型问题正确顺序是先确认进程、再确认接口、最后确认推理。# 1. 确认服务进程和端口在监听 ps -ef | grep vllm ss -tlnp | grep 8000 # 2. 用 curl 直接打一个最小请求确认接口返回 curl http://localhost:8000/v1/models # 3. 发送一条推理请求确认模型能正常生成 curl http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -d {model: deepseek, messages: [{role: user, content: 你好}], max_tokens: 64}第一步失败说明进程没起稳回到终端看启动日志的具体报错第二步失败说明服务还没就绪或端口被防火墙挡住第三步失败才轮到排查模型本身问题。/v1/models返回的模型 ID 可能与你传入的目录名不同它是从模型配置读取的写请求体时model字段要填接口返回的 ID而不是目录名这是最常见的低级错误。5. 部署避坑指南五条真实踩坑记录5.1 现象启动时报 CUDA error: device-side assert triggered模型加载完成、服务也起来了但第一次请求就崩掉终端刷出CUDA error。原因是在消费级显卡上跑需要较新计算能力的量化算子或者驱动版本太旧。解决先升级 NVIDIA 驱动到当前较新稳定版重启机器如果还不行把量化格式从 AWQ 换成 GPTQ 或直接 BF16 验证——有些量化 Kernel 对特定 GPU 架构的支持不完善。这类问题最怕的不是报错本身而是错误的模糊性所以一定要先确认驱动版本和模型量化格式的匹配关系。5.2 现象模型加载到一半就 OOM 被杀vllm启动日志显示权重加载到某个百分比就报显存不足。原因通常有两个一是模型量化格式选得太高如 BF16 权重占了过多显存二是--max-model-len或--gpu-memory-utilization计算不合理。解决先算一笔账——权重大小除以卡数加上 KV Cache 预留是否超过单卡显存再尝试降低--max-model-len比如从 16384 降到 8192最后一招是换更低位宽的量化版本。注意看的是nvidia-smi里的Memory-Usage而不是进程内显存统计两者可能对不上。5.3 现象服务能起但端口一访问就卡死或超时这不是网络问题而是「请求进入推理队列后无法完成生成」。常见原因是--max-model-len设置得过大导致 KV Cache 显存几乎占满一旦有并发请求逐 token 生成阶段显存不够就持续阻塞。解决重启时把--max-model-len调低同时设置--served-model-name显式指定模型名避免请求体里的模型名与配置不一致导致请求被拒。排查时可以观察日志里是否反复出现GC或Timeout字样这类信息远比「卡死」这个现象更有指向性。5.4 现象下载模型时中断重新下载又从零开始huggingface-cli download走的是断点续传但如果网络长时中断进程退出后缓存会被清理下次重新执行确实可能从头开始。解决不修改默认行为而是改用以下方式——先下载到缓存目录再硬链接到目标目录或者用小工具hf_transfer加速下载减少中断概率。更重要的一点是别在模型下载中途去做系统升级或重启这类大文件下载本身就适合放在 tmux 或 systemd 服务里托管避免 SSH 断连导致进程被杀。5.5 现象一次请求正常并发一上来就大量报错这是部署后最常遇到也最容易被误判为「模型不行」的问题。原因通常是并发请求全部挤在同一时刻进入批处理KV Cache 瞬时分配失败或max-num-seqs参数限得过死。解决--max-num-seqs适当调大默认值对于大模型往往偏保守同时压测工具的并发数先从小到大分级探测另外确认--gpu-memory-utilization不要卡在临界值——显存利用率越高并发下的波动容忍度越低。遇事不要先怀疑模型多数并发报错能从显存余量和批处理参数找到答案。6. 部署后的验证、监控与调优技巧6.1 压测是最快的验证方式服务跑通只是起点真正的验证是用模拟业务流量测试并发吞吐。我习惯用简易的 Python 并发脚本测三个指标首 token 延迟、平均输出速度、并发上限。并发脚本可以控制请求数和 batch 数量观察显存与日志的变化。# 简易并发压测脚本 import requests, concurrent.futures URL http://localhost:8000/v1/chat/completions data { model: deepseek, messages: [{role: user, content: 写一段 200 字的技术说明}], max_tokens: 512, temperature: 0.7, } def send_req(idx): resp requests.post(URL, jsondata, timeout120) return idx, resp.status_code, resp.elapsed.total_seconds() with concurrent.futures.ThreadPoolExecutor(max_workers8) as pool: results list(pool.map(send_req, range(16))) for r in results: print(r)脚本里max_workers8是并发请求数可以先从 1 起步逐级加观察不同并发档位下各请求的耗时变化这比一次性压满更能暴露瓶颈区。如果并发 8 时部分请求超时回到第 5.5 节的方法调整参数而不是压完就下结论。压测结果要记录到本地后续每次调整参数都跑同一套脚本对比这是最朴素的调优闭环。6.2 监控显存与日志的习惯部署完成后养成两个习惯每跑完一轮压测随手nvidia-smi看显存余量变化定期翻 vLLM 的请求日志关注每轮生成的prefix cache hit rate指标——这个指标代表多少 token 命中了前缀缓存命中率越高重复前缀的请求响应越快。手动部署带来的控制力就体现在这些细颗粒度的观察上容器化部署反而很难接触到这层指标。6.3 进阶调优的几条实用技巧到最后阶段给你三个可持续优化的方向第一服务入口前加一层请求缓存对重复性高的查询如固定模板生成直接命中缓存可以显著降低推理负载第二如果模型支持分离部署把预填充和解码阶段拆到不同节点能改善长时间生成场景下的整体吞吐第三设置--enable-prefix-caching这类显式选项让系统自动复用公共前缀的 KV Cache与 6.2 节的命中率指标互相照应。我自己的习惯是每次部署都会把启动参数、压测记录、问题日志三个文件放在同一目录下出问题时先翻旧账而不是急着重启换参。这种「手动」记录方式在初期看起来比脚本慢但一旦遇到复现性问题它的价值就完全体现了。希望这些真实踩过的坑能帮你少折腾一晚让 DeepSeek 在你的机器上真正跑起来、跑得稳。本文还有配套的精品资源点击获取