如何本地运行 DeepSeek-V4：Pro 与 Flash 安装指南

大约 11 分钟

如何本地运行 DeepSeek-V4：Pro 与 Flash 安装指南

DeepSeek-V4 是 DeepSeek 迄今为止最具野心的开源权重模型发布之一。该系列包含 DeepSeek-V4-Pro，一个拥有 1.6T 参数的 Mixture-of-Experts 模型，激活参数为 490 亿，以及 DeepSeek-V4-Flash，一个较小的 2840 亿参数 MoE 模型，激活参数为 130 亿。两款模型均支持最长 一百万 token 的上下文长度。

这个组合听起来令人兴奋，但也带来了一个实际问题：你真的能在本地运行 DeepSeek-V4 吗？

答案是肯定的，但有一个重要的前提。DeepSeek-V4 并非笔记本级别的模型。即使是 Flash 版本，也需要严肃的多 GPU 部署。本文将通过官方 DeepSeek 模型仓库（Hugging Face）介绍本地设置流程，说明你应规划的硬件，并展示如何正确使用官方推理和编码文件。

参考模型页面：

DeepSeek-V4-Pro 与 DeepSeek-V4-Flash 对比

下载前，请选择合适的模型版本。

模型	总参数量	激活参数量	上下文长度	精度	适用场景
DeepSeek-V4-Flash	2840亿	130亿	1M	FP4 + FP8 混合	更快的本地实验，低成本服务，代码助手，长上下文测试
DeepSeek-V4-Pro	1.6万亿	490亿	1M	FP4 + FP8 混合	最高质量，研究实验室，大型 GPU 集群，严肃推理与智能体任务

最重要的细节是 DeepSeek-V4 采用了 Mixture-of-Experts (MoE) 架构。每个 token 只激活模型的一部分，从而降低计算成本。但你仍需存储和加载完整模型权重，这意味着 GPU 显存和存储需求依然非常高。

对于大多数开发者来说，DeepSeek-V4-Flash 是现实的起点。DeepSeek-V4-Pro 更适合集群级部署。

DeepSeek-V4 有何不同？

根据 DeepSeek 的模型卡，V4 系列引入了多项重大升级：

混合注意力架构：DeepSeek 结合了压缩稀疏注意力（CSA）和高度压缩注意力（HCA），提升长上下文效率。在一百万 token 设置下，DeepSeek-V4-Pro 据称使用的 KV 缓存远少于 DeepSeek-V3.2。
流形约束超连接（mHC）：提升极深网络的稳定性，同时保持模型容量。
Muon 优化器：训练时使用 Muon 优化器以获得更好收敛和稳定性。
长上下文支持：Pro 和 Flash 均支持最高 1M token，DeepSeek 推荐 Think Max 模式至少使用 384K 上下文。
多种推理模式：DeepSeek-V4 支持非思考、Think High 和 Think Max 三种使用风格。

对于本地部署，两个最重要的实用变化是 混合 FP4/FP8 精度 和 自定义聊天编码格式。

硬件需求

DeepSeek-V4 并非为消费级 GPU（如 RTX 4090）设计，除非你未来只做大量修改的社区量化实验。官方权重建议使用服务器级 GPU。

实际硬件规划

用例	推荐硬件	备注
DeepSeek-V4-Flash 测试部署	4-8 张大显存 NVIDIA GPU	H100/H200/A100 级 GPU 是实际目标
DeepSeek-V4-Flash 生产服务	8 张以上大显存 GPU	更多 GPU 有助于吞吐和长上下文工作负载
DeepSeek-V4-Pro 研究部署	大型多节点 GPU 集群	视为集群基础设施，而非单机模型
Think Max 长上下文	额外 GPU 显存和 KV 缓存预算	DeepSeek 推荐 Think Max 至少 384K 上下文

存储需求

下载前请规划充足本地存储：

尽量使用 NVMe SSD 存储。
预留转换权重的额外空间。
避免直接下载到小容量系统盘。
Pro 模型存储需求远高于 Flash。

推荐目录结构：

/data/models/deepseek-v4-flash-hf      # 原始 Hugging Face 文件
/data/models/deepseek-v4-flash-infer   # 转换后的推理权重
/data/cache/huggingface                # HF 缓存

如果租用云 GPU 服务器，选择带本地 NVMe 的实例或挂载大容量高吞吐卷。VPS 部署规划可通过 LightNode 等供应商比较 GPU 或大内存服务器，但务必确认实例具备此类模型所需的 GPU 显存。

软件需求

需要 Linux 环境，配备最新 NVIDIA 驱动和 CUDA。

推荐基础环境：

组件	推荐版本
操作系统	Ubuntu 22.04 或更新
Python	3.10+
GPU 驱动	最新 NVIDIA 数据中心驱动
CUDA	推荐 CUDA 12.x
PyTorch	支持 CUDA 的版本
Git LFS	模型文件必需
Hugging Face CLI	可靠下载必需

安装基础工具：

sudo apt update
sudo apt install -y git git-lfs python3 python3-venv python3-pip

git lfs install
pip install -U huggingface_hub

如果使用 Python 虚拟环境：

python3 -m venv dsv4-env
source dsv4-env/bin/activate
pip install -U pip wheel setuptools
pip install -U huggingface_hub torch transformers safetensors

第一步：下载 DeepSeek-V4-Flash

大多数用户从 Flash 开始：

mkdir -p /data/models
cd /data/models

huggingface-cli download deepseek-ai/DeepSeek-V4-Flash \
  --local-dir DeepSeek-V4-Flash \
  --local-dir-use-symlinks False

如果想要 Pro 版本：

huggingface-cli download deepseek-ai/DeepSeek-V4-Pro \
  --local-dir DeepSeek-V4-Pro \
  --local-dir-use-symlinks False

下载中断时，重新运行相同命令即可续传。

第二步：检查官方仓库结构

下载完成后，查看模型文件夹：

cd /data/models/DeepSeek-V4-Flash
ls

模型卡指向两个重要文件夹：

inference/ - 官方本地推理代码，包括权重转换和生成脚本
encoding/ - DeepSeek-V4 的提示编码和输出解析工具

这很重要，因为 DeepSeek-V4 不附带标准的 Jinja 格式聊天模板。不要假设任何通用的 OpenAI 兼容聊天包装器能开箱即用地正确格式化提示。

第三步：转换权重以供官方推理使用

官方推理 README 中，运行生成前需先转换权重。

进入模型仓库：

cd /data/models/DeepSeek-V4-Flash/inference

export HF_CKPT_PATH=/data/models/DeepSeek-V4-Flash
export SAVE_PATH=/data/models/DeepSeek-V4-Flash-infer
export EXPERTS=256
export MP=4
export CONFIG=config.json

python convert.py \
  --hf-ckpt-path ${HF_CKPT_PATH} \
  --save-path ${SAVE_PATH} \
  --n-experts ${EXPERTS} \
  --model-parallel ${MP}

参数说明：

变量	含义
`HF_CKPT_PATH`	原始 Hugging Face 模型文件路径
`SAVE_PATH`	转换后推理权重输出路径
`EXPERTS=256`	DeepSeek-V4 推理转换使用的专家数量
`MP=4`	模型并行大小；通常与运行时 GPU 数量匹配
`CONFIG`	生成脚本使用的模型配置文件

若使用更多 GPU，请相应调整 MP。例如 8 GPU 节点：

export MP=8

FP8 专家选项

官方推理 README 提到，如需使用 FP8 专家替代 FP4 专家，需从 config.json 中删除：

"expert_dtype": "fp4"

然后转换时添加参数 --expert-dtype fp8：

python convert.py \
  --hf-ckpt-path ${HF_CKPT_PATH} \
  --save-path ${SAVE_PATH} \
  --n-experts ${EXPERTS} \
  --model-parallel ${MP} \
  --expert-dtype fp8

大多数用户建议先用默认混合 FP4/FP8 设置，确认基线正常后再调整精度。

第四步：启动交互式聊天

转换完成后，运行官方生成脚本：

cd /data/models/DeepSeek-V4-Flash/inference

export MP=4
export SAVE_PATH=/data/models/DeepSeek-V4-Flash-infer
export CONFIG=config.json

torchrun --nproc-per-node ${MP} generate.py \
  --ckpt-path ${SAVE_PATH} \
  --config ${CONFIG} \
  --interactive

批量输入文件示例：

torchrun --nproc-per-node ${MP} generate.py \
  --ckpt-path ${SAVE_PATH} \
  --config ${CONFIG} \
  --input-file prompts.txt

多节点运行示例：

torchrun \
  --nnodes ${NODES} \
  --nproc-per-node $((MP / NODES)) \
  --node-rank $RANK \
  --master-addr $ADDR \
  generate.py \
  --ckpt-path ${SAVE_PATH} \
  --config ${CONFIG} \
  --input-file prompts.txt

确保每个节点都能访问转换后的检查点路径，或将转换文件复制到每台机器的相同路径。

第五步：使用正确的采样设置

DeepSeek 推荐本地部署采样参数：

temperature = 1.0
top_p = 1.0

如果生成脚本支持命令行参数，直接使用；否则在脚本或配置中设置采样参数。

Think Max 模式建议至少使用：

384K tokens

首次测试时不要一开始就用超大上下文窗口。先用小窗口确认模型能正常加载和生成，再逐步增加上下文长度，同时监控 GPU 显存。

第六步：理解 DeepSeek-V4 聊天编码

DeepSeek-V4 不包含标准 Jinja 聊天模板。仓库提供了 encoding/ 文件夹内的 Python 工具。

基本用法示例：

from encoding_dsv4 import encode_messages, parse_message_from_completion_text

messages = [
    {"role": "system", "content": "你是一个乐于助人的助手。"},
    {"role": "user", "content": "2+2 等于多少？"},
]

prompt = encode_messages(messages, thinking_mode="thinking")
print(prompt)

非思考聊天使用 chat 模式：

prompt = encode_messages(messages, thinking_mode="chat")

思考模式下，模型使用显式推理分隔符：

<think> ... </think>

解析器可将生成文本转换回结构化助手消息：

completion = "简单算术。</think>2 + 2 = 4.<｜end▁of▁sentence｜>"
parsed = parse_message_from_completion_text(completion, thinking_mode="thinking")
print(parsed)

如果你想构建自己的本地 API 包装器，这一点尤其重要。

推理模式说明

DeepSeek-V4 支持三种实用推理风格：

模式	行为	适用场景
非思考 (Non-think)	快速直接回答	简单问答、摘要、常规代码帮助
Think High	经过推理的答案，带有深思熟虑分析	调试、规划、数学、架构决策
Think Max	最大推理努力	复杂编码任务、智能体工作流、研究级问题解决

本地服务器可将它们作为不同模型名暴露，例如：

deepseek-v4-flash-chat
deepseek-v4-flash-thinking
deepseek-v4-flash-max

内部每个路由可使用不同的提示编码、上下文限制和生成参数。

能用 vLLM 或 SGLang 运行 DeepSeek-V4 吗？

发布时，最稳妥的路径是使用模型仓库中的 官方 DeepSeek 推理代码。通用服务框架可能需要更新，才能完全支持 DeepSeek-V4 的架构、混合精度、长上下文行为和自定义编码。

实用步骤：

先成功运行官方 inference/generate.py。
使用官方 encoding/ 工具确认输出质量和提示格式。
再检查你喜欢的框架是否已明确支持 DeepSeek-V4。
仅在确认支持后，迁移到 vLLM、SGLang、TensorRT-LLM 或其他服务框架。

这样避免常见失败模式：模型加载成功，但聊天质量差，因提示模板错误。

构建简单本地 API 包装器

如果想要 OpenAI 风格的本地接口，可以用 FastAPI 包装官方生成路径。具体实现取决于如何集成 generate.py，但大致流程是：

接收 OpenAI 兼容的 messages。
用 encoding_dsv4.encode_messages() 转换。
将编码后的提示发送给 DeepSeek-V4 推理引擎。
用 parse_message_from_completion_text() 解析输出。
返回 OpenAI 兼容的 JSON 响应。

伪代码示例：

from encoding_dsv4 import encode_messages, parse_message_from_completion_text

messages = [
    {"role": "system", "content": "你是一个乐于助人的助手。"},
    {"role": "user", "content": "用简单的话解释 KV 缓存。"},
]

prompt = encode_messages(messages, thinking_mode="thinking")

# 发送提示给本地 DeepSeek-V4 推理工作进程
raw_completion = run_deepseek_v4(prompt)

assistant_message = parse_message_from_completion_text(
    raw_completion,
    thinking_mode="thinking",
)

print(assistant_message["content"])

生产环境还需添加：

请求排队
流式输出
超时处理
GPU 健康检查
最大上下文限制
结构化日志
认证机制

故障排除

1. CUDA 显存不足

通过以下方式降低显存压力：

缩短上下文长度
减少批量大小
增加张量/模型并行度
使用更多 GPU
先用 DeepSeek-V4-Flash 代替 Pro

调试时通常先减少上下文长度。

2. 下载失败或卡住

使用 huggingface-cli download 替代浏览器下载。重新运行相同命令可续传。

也可设置专用缓存目录：

export HF_HOME=/data/cache/huggingface
export HUGGINGFACE_HUB_CACHE=/data/cache/huggingface/hub

3. 模型生成奇怪的聊天输出

检查提示格式。DeepSeek-V4 不使用标准 Jinja 聊天模板，务必使用官方 encoding/ 实现。

4. 多 GPU 运行失败

确认 PyTorch 能识别所有 GPU：

python - <<'PY'
import torch
print(torch.cuda.device_count())
for i in range(torch.cuda.device_count()):
    print(i, torch.cuda.get_device_name(i))
PY

多节点运行时检查 NCCL 网络：

export NCCL_DEBUG=INFO

5. Think Max 太慢

Think Max 设计用于在复杂推理上花费更多计算资源。仅在任务需要时使用。日常助手使用非思考或 Think High 更实用。

结语

DeepSeek-V4 功能强大，但不是轻量级本地模型。Flash 版本是实用入门，Pro 适合严肃的多 GPU 或多节点环境。成功部署的关键是遵循官方流程：下载 Hugging Face 仓库，使用提供的推理工具转换权重，使用 torchrun 运行生成，并使用专用 DeepSeek-V4 编码工具，而非假设通用聊天模板。

如果只需做提示实验，托管的 DeepSeek 聊天服务或 API 路径更简单。但若需数据隐私、完全控制、无按 token 计费或定制基础设施，本地运行 DeepSeek-V4 为构建私有长上下文 AI 系统提供了坚实基础。