DeepSeek模型下载与安装详细教程

普通电脑先选择R1 Distill Qwen 1.5B。它是官方蒸馏模型，不能用它的硬件条件估计V4.1 Flash完整模型。参考文档中的V4.1 Flash 1017也已单独核对并提供完整文件地址。

阅读顺序：先完成第1节选型与空间检查，再安装下载工具，下载并校验。只有确认满足运行条件后，才进入运行章节。

1 先选对模型

R1系列偏重推理，Distill表示蒸馏版；V系列为另一条模型路线。Coder用于代码，VL和OCR涉及视觉任务，不能全部套用本教程的纯文本运行脚本。

容量按官方API的文件字节数相加，包含文档、配置及仓库内可能并存的其他权重格式；不是运行内存最低要求。GB按十进制，GiB按二进制换算。

下载目录建议至少预留10 GB可用空间。这是整仓大小加约30%和5 GB余量的建议，不含额外转换副本、框架环境、系统空间及其他缓存。

打开官方模型主页

打开固定版本文件列表

检查自己的电脑

Windows：按Win加I打开设置，进入系统中的系统信息查看内存；在任务管理器的性能页查看GPU及专用显存。macOS：打开苹果菜单中的关于本机，查看芯片与内存。内存和硬盘空间是两回事。

下载只依赖网络与磁盘；运行还需要内存、显存、对应架构和框架。FP16或BF16权重可用总参数量乘2字节估算基础权重占用，float32约乘4字节，实际还要加运行开销和上下文缓存。MoE不能仅按激活参数估算。

磁盘必须支持大文件。Windows通常用NTFS，Mac通常用APFS，跨系统外置盘可用exFAT。不要为了下载随意格式化已有资料的硬盘。FAT32无法保存超过4 GB的单个文件。

2 安装下载工具与准备账号

Windows 按顺序操作

1. 打开Python官方下载页，安装Python 3.12。若安装器显示Add python.exe to PATH，请勾选；安装结束后重新打开PowerShell。可在开始菜单搜索PowerShell。

Python Windows官方下载页

2. 每次复制一行命令，按回车，等待完成后再执行下一行。使用独立环境可减少与电脑上其他Python软件冲突。

py --version
py -3.12 -m venv "$env:USERPROFILEhf-deepseek-env"
& "$env:USERPROFILEhf-deepseek-envScriptsActivate.ps1"
python -m pip install --upgrade pip huggingface_hub
hf --help

应看到Python版本、安装成功信息和hf帮助列表。若py -3.12找不到版本，确认安装了Python 3.12；若系统只有python可用，可将创建环境命令中的py -3.12替换为python。

如果PowerShell阻止激活脚本，可在本窗口执行下面一行后再激活；只影响当前窗口。关闭窗口后恢复原状态。

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

macOS 与 Linux 按顺序操作

macOS按Command加空格搜索终端；Linux打开终端。先安装Python 3.12并确认python3存在。Linux若缺少venv模块，按发行版官方说明安装python3-venv。

Python macOS官方下载页

python3 --version
python3 -m venv "$HOME/hf-deepseek-env"
source "$HOME/hf-deepseek-env/bin/activate"
python -m pip install --upgrade pip huggingface_hub
hf --help

以后新开窗口时，Windows重新执行Activate.ps1那一行；macOS和Linux重新执行source那一行。不必每次重建环境。

需要审批时如何处理

1. 在Hugging Face注册并验证邮箱。2. 登录后打开目标模型主页。3. 如果页面要求接受许可证、填写用途或申请访问，按页面要求完成。4. 等页面确认获准，再创建具备该仓库读取权限的令牌。5. 回到终端执行下面命令，按提示粘贴令牌。粘贴时没有字符显示可能是正常的。

hf auth login
hf auth whoami

创建或管理读取令牌

访问审批官方说明

公开仓库通常可先直接下载。令牌只填在工具提示中，不写进文档、截图或聊天消息。申请等待时间由发布方决定，登录成功不等于已获得仓库权限。

3 固定版本完整下载

本节下载主示例的全部文件。仓库ID由发布者名称、斜杠和模型名组成；revision是这次核对的固定提交。请不要自行把名称换成相似的社区仓库。

Windows 保存到D盘示例

先在此电脑中确认D盘存在且空间足够。没有D盘时，把下面的D:Models改为你实际的大容量磁盘路径。保留英文双引号，防止路径含空格时出错。

$repo = "deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B"
$rev = "ad9f0ae0864d7fbcd1cd905e3c6c5b069cc8b562"
$dest = "D:ModelsDeepSeek-R1-Distill-Qwen-1.5B"
New-Item -ItemType Directory -Force $dest
hf download $repo --revision $rev --local-dir $dest --dry-run

上面的dry-run只查看待下载文件和预计下载量，不下载模型权重。若CLI不认识dry-run，先升级huggingface_hub。确认预计大小、目标磁盘和权限无误，再执行正式下载：

hf download $repo --revision $rev --local-dir $dest

macOS 与 Linux 保存到主目录示例

先确认主目录所在磁盘足够大。外置盘用户需替换dest为真实挂载路径；Mac常见路径以/Volumes/开头，Linux以实际挂载位置为准。

repo="deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B"
rev="ad9f0ae0864d7fbcd1cd905e3c6c5b069cc8b562"
dest="$HOME/Models/DeepSeek-R1-Distill-Qwen-1.5B"
mkdir -p "$dest"
hf download "$repo" --revision "$rev" --local-dir "$dest" --dry-run
hf download "$repo" --revision "$rev" --local-dir "$dest"

变量只在当前窗口有效。换窗口后先激活环境，再重新执行repo、rev和dest三行赋值。Word自动换行不代表命令结束，请按完整段落复制。

下载过程怎样判断

正常会出现文件进度与传输信息，完成后回到命令提示符。第一次连接和大分片可能等待较久。电脑保持供电，关闭自动睡眠，外置盘不要中途拔出。按Ctrl加C可停止，恢复时按第4节重试。

按固定有效速度粗算：10 MB每秒约0.10小时，50 MB每秒约0.02小时；实际还受网络、磁盘和服务器影响。网络套餐的Mbps与下载界面的MB每秒单位不同，需除以8再估算。

4 校验完整性与恢复下载

整仓下载应保留原始目录结构。所有safetensors分片、索引、配置和分词器文件都属于配套内容；不要把多个分片手工合成一个文件，也不要只留最大的一个分片。

本示例整仓共9项，其中名称以.safetensors结尾的文件1个。是否包含重复格式、视觉模块或额外目录，以附录实际文件名为准。

Windows 校验

hf cache verify $repo --revision $rev --local-dir $dest --fail-on-missing-files

macOS 与 Linux 校验

hf cache verify "$repo" --revision "$rev" --local-dir "$dest" --fail-on-missing-files

以校验摘要显示All checksums match且没有缺失文件为整仓完成标准。校验需要联网获取元数据，还会读取本地大文件；运行时间可能较长。只数文件个数不能代替校验。

中断以后怎么继续

重新打开终端并激活环境，恢复相同repo、rev和dest，重新执行第3节正式下载命令。工具会利用已经完成的文件和可用缓存继续。未完成片段能否直接续传取决于传输后端与缓存状态。保留目标目录内的.cache/huggingface及临时文件。

若校验明确指出一个文件损坏，可只重下那个文件。下面仅是按本仓库真实文件名写出的示例；先把文件名换成报错对应的项，再执行，避免重下正常大文件。

hf download deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B "model.safetensors" --revision ad9f0ae0864d7fbcd1cd905e3c6c5b069cc8b562 --local-dir "实际模型目录" --force-download

替换实际模型目录为第3节的dest路径。重下后再做整仓校验。不要为一个文件报错就删除整个下载目录。

用网页逐个下载

打开固定文件列表，在Files and versions中找到文件并点下载图标；也可用附录直链。浏览器若显示文本而不保存，使用另存为并保留原文件名。按子目录原样创建文件夹，例如original/下的文件不能放到根目录覆盖同名配置。大量分片优先用CLI。

直链形如/resolve/固定提交/文件路径。浏览器最终跳转到的存储地址可能带临时签名，会过期；分享资料时保留本教程提供的入口。受访问审批保护的文件，打开直链仍需权限。

5 下载后开始运行

本节仅运行第1节指定的主示例，并先测试纯文本。教程附带run_model.py，读取已下载的本地目录，不会自动改用另一个在线模型。它是一轮一轮独立问答，不会记住上轮内容。

1.5B示例建议16 GB内存；纯CPU可运行但可能较慢。这些是短文本试跑的建议条件，不是官方承诺的最低配置。先关闭占内存的软件；长上下文和多用户会显著增加占用。

安装推理所需软件

在第2节已激活的环境里运行。CPU用户安装官方PyTorch CPU版本即可；Windows或Linux的NVIDIA显卡用户，如希望用CUDA，请到PyTorch安装页选择与你的系统及驱动匹配的命令。Mac使用对应的macOS安装选项。

PyTorch官方安装选择器

python -m pip install --upgrade torch transformers accelerate sentencepiece

打开脚本所在文件夹

把整份教程压缩包解压。在当前系列文件夹找到run_model.py。Windows在资源管理器地址栏输入powershell并回车；Mac打开终端，输入cd和一个空格，再把该系列文件夹拖进终端，按回车。重新激活第2节环境。

第一次运行先选择一种设备

CPU方式兼容面较广，但会把权重按float32装入内存，速度可能较慢。使用前检查本节内存建议。Windows示例：

python run_model.py --model-dir "D:ModelsDeepSeek-R1-Distill-Qwen-1.5B" --device cpu

macOS和Linux示例：

python run_model.py --model-dir "$HOME/Models/DeepSeek-R1-Distill-Qwen-1.5B" --device cpu

具备匹配CUDA版PyTorch和足够显存的NVIDIA设备，可将命令最后的cpu改为cuda。Apple Silicon可尝试mps；若当前算子或精度不受支持，回到cpu。脚本不做自动分卡或磁盘卸载，全部权重需能装入所选设备。

第一次问答与完成标准

看到Model ready后，在You提示后输入：请用一句话解释什么是人工智能模型。按回车，等待AI输出。输入exit并回车退出；Ctrl加C也可终止。第一次加载和CPU生成较慢，请先用短问题。

R1蒸馏模型可能先输出推理内容。脚本只生成256个新token，推理较长时可能还未出现最终回答；在脚本中把max_new_tokens改为1024或更大后重试，同时留出更多运行时间和内存。

运行成功标准：加载无错误、能收到与问题相关的回复、可以正常退出。文件校验通过仅代表下载完整，不能替代这个运行检查。

脚本关键逻辑

脚本从本地读取分词器或处理器与模型，套用该模型聊天模板，再生成新内容。完整脚本在同目录，下面为主示例对应的加载类：

from transformers import AutoTokenizer, AutoModelForCausalLM

6 其他版本与图形界面路线

本次重点核对的仓库

打开 deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B

打开 deepseek-ai/DeepSeek-V4.1-Flash-1017

打开 deepseek-ai/DeepSeek-V4.1-Flash

每个重点仓库的所有文件路径、原始字节大小和API提供的LFS SHA256，均在精讲仓库文件大小与校验.csv和精讲仓库全部文件地址.txt中。不同仓库固定提交不同，不混用配置、分片与分词器。

如何查找社区量化版

Hugging Face量化版本检索

该链接是检索入口，不代表列表中的结果全部由原厂发布。核对发布者、原始base_model、转换工具、量化档位、更新时间与运行时支持。对比模型卡确认同一基础模型后，再选择适合设备的版本。社区量化版不是本教程原始权重的替代文件。

如使用LM Studio，先安装官方应用，在Discover粘贴确认过的GGUF仓库URL，下载一个适合设备的量化版本，再从聊天页加载。新架构尚未受支持时，应等待运行时适配或按原厂引擎部署文档操作。

LM Studio官方支持与要求

参考文档中的V4 1 Flash 1017

已核对固定提交1bae0e1088993b9b82de08f59de5be5a34e42170，共83项、48个safetensors分片，合计510311045295字节。整套48片都要保存；最后两片各约101.54 GB。该完整模型不是1.5B蒸馏示例。

原始权重的官方参考推理需要在inference目录安装requirements，再执行convert.py转换为每个并行进程一份的检查点。官方示例MP为8，不构成最低硬件承诺；转换还要为新权重副本预留磁盘。后续通过run.sh或torchrun启动。

固定版本转换与推理步骤

7 常见问题逐项排查

hf 找不到

确认当前窗口已激活hf-deepseek-env，再运行python -m pip show huggingface_hub。若安装到了另一套Python，重新激活正确环境后安装。

401 或 403

检查是否登录正确账号、令牌是否有该仓库读取权限、网页是否已接受许可证并获准访问。公开元数据可见不代表受限权重可下载。

404 或 Revision not found

先核对完整仓库ID和固定提交，确认没有空格或多余标点。仓库可能重命名或被删除，回官方主页查询，不要凭相似名字猜地址。

下载超时或速度低

先用浏览器打开官方主页，再检查大文件下载是否也可连接。网络不稳定时保持同一路径和版本重试。出现Xet相关报错时查看官方环境变量说明，不关闭证书校验。

磁盘满了

按Ctrl加C停止，换到更大磁盘。复制完整模型目录及隐藏缓存后，更新dest路径并重新执行同版本命令。保留原目录直到新目录校验通过。

文件只有几KB

可能保存成网页、错误响应或Git LFS指针。与精讲仓库文件大小与校验.csv对比；使用hf download重新取得实际文件。

CUDA unavailable

当前PyTorch可能是CPU版，或驱动、显卡环境不可用。用PyTorch官方安装页的匹配命令；没有受支持的显卡时选择cpu。

CUDA out of memory 或系统内存不足

先退出其他程序，减小输入与输出长度。模型权重本身装不下时，换更小模型或经核对的量化版；仅缩短上下文不能消除权重占用。

KeyError 或模型架构不认识

检查依赖是否符合该仓库模型卡，区分旧自定义代码版与原生支持版。新模型可能需特定提交、专用镜像或尚未发布的运行时。

输出重复或没有最终回答

确认使用模型自己的聊天模板。推理模型可能先生成长推理；增加输出token上限，按模型卡调采样参数。小模型能力有限，先用短问题验证流程。

8 全部地址文件怎么使用

本系列按明确的官方发布账号与命名条件收录77个公开可枚举仓库。它是2026年10月29日的快照，不包含私有仓库、已删除仓库或全站社区微调、转换版本。清单收录不代表每项都适合聊天。

检索账号 deepseek-ai；命名条件 仓库名不区分大小写包含 deepseek。同名官方旧账号的历史地址可能发生跳转，以表中当前API返回的仓库ID为准。

CSV可用Excel、Numbers或文本编辑器打开，用筛选查仓库ID和任务。TXT可用记事本打开，搜索精确模型名。全部文件直链依据官方API siblings字段枚举；非精讲仓库未逐一获取文件大小，不能据此估算全部仓库总容量。

下载命令.txt中的每一组是不同模型，只执行你选择的一组。没有要求一次下载整个系列。固定版本用于重现本清单，main会持续变化；以后想下载新版，先重新查看文件和容量。

附录 主示例全部文件直链

deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B 固定提交 ad9f0ae0864d7fbcd1cd905e3c6c5b069cc8b562。共9项。字节大小来自仓库API；单击下载入口获取文件，Word中也可按Ctrl并点击。完整URL已保存在同目录TXT与CSV。

来源与核对说明

仓库列表来自官方Models API，已按分页链接读取到底；文件列表来自其siblings字段。重点仓库另查询blobs=true取得字节和LFS校验元数据。元数据核对不等于实际下载权重或完成运行测试。本教程的运行脚本依据模型卡加载方式编写，未在本机实测这些模型。

官方发布账号  |  本系列仓库API  |  主示例精确文件元数据  |  主示例固定模型卡  |  Hub CLI官方说明  |  Hub网络与环境变量  |