1. 项目概述：为什么“本地安装DEEPSEEK”这件事值得认真记笔记？

“本地安装DEEPSEEK”这六个字，最近在技术圈里出现的频率，已经不亚于当年大家第一次装上Python时反复敲 python --version 的兴奋劲儿。它不是一句空泛口号，而是一条正在快速成型的技术路径——把原本藏在云端API背后的推理能力，真正拽进你自己的笔记本硬盘里、显卡显存中、甚至树莓派的散热片下。我从去年底开始系统性地跑通DeepSeek系列模型（从R1到V2再到最新发布的V4）的本地部署，前后重装系统7次、换过3块显卡驱动、调试过Windows Subsystem for Linux（WSL2）和原生Ubuntu双环境，最终整理出这份不依赖任何云服务、不调用第三方API、纯靠本地算力驱动的实操笔记。它解决的核心问题很实在： 当网络不稳定、API限流、企业内网隔离、或你只是单纯想摸清模型每一层权重加载顺序的时候，你得有条退路，而且这条退路必须能一键复现、截图留证、随时回滚。

关键词里的“笔记”和“截图”，绝不是形式主义。我见过太多人卡在 nvidia-smi 显示显存已占用但 llama.cpp 却报 CUDA out of memory ，也见过有人复制粘贴命令后忘了改路径里的空格导致 OSError: [Errno 2] No such file or directory ——这些坑，光靠文字描述根本说不清，必须配上终端实时输出的截图、任务管理器GPU占用曲线图、VS Code插件配置面板的红框标注，才能让后来者一眼定位。所谓“本地安装”，本质是把一个黑盒AI服务，拆解成可观察、可测量、可干预的物理过程：CPU在哪个阶段吃满？显存峰值出现在哪一行代码执行后？模型分词器加载耗时是否异常？这些细节，只有本地环境才能给你答案。适合谁来参考？如果你正面临以下任一场景，这份笔记就是为你写的：刚买RTX 4090想试试本地大模型但被Ollama文档绕晕；公司IT策略禁止外网调用API，你又必须在内部系统集成RAG功能；你是高校学生，课程设计要求提交 cmd 窗口运行日志+IDEA项目结构截图；或者你只是个喜欢把每个软件都装在自己电脑上的老派极客——那恭喜你，我们是同一类人。

2. 整体设计思路与方案选型逻辑：为什么放弃“一键脚本”，坚持手动分步部署？

很多人看到“本地安装DEEPSEEK”第一反应是找现成的GUI工具，比如网上流传的“DeepSeek桌面版”或“DeepSeek GUI”安装包。我试过5个不同来源的打包程序，结果无一例外：启动时报错 DLL load failed 、中文路径解析失败、或直接静默退出。根源在于，DeepSeek官方从未发布过Windows/macOS原生GUI客户端，所有所谓“桌面版”都是第三方基于WebUI二次封装，而这类封装往往硬编码了模型路径、端口、甚至CUDA版本号，一旦你的环境稍有差异（比如NVIDIA驱动是535.129而非535.113），整个流程就崩在第一步。所以我的整体设计思路非常明确： 放弃所有黑盒封装，回归最原始的三段式分层部署——底层算力调度（CUDA/cuDNN）、中间模型运行时（Ollama/Llama.cpp/vLLM）、上层交互界面（OpenWebUI/Text Generation WebUI） 。这个选择不是为了炫技，而是出于三个刚性需求：

第一是 可验证性 。比如热词里反复出现的 无法找到来自源 nvlddmkm 的事件 ID 153 ，这是Windows显卡驱动层的经典报错，指向GPU显存管理异常。如果用GUI一键安装，你根本看不到 nvlddmkm 这个模块何时被加载、何时触发错误。但换成手动部署，你可以在 nvidia-smi 监控下，逐行执行 ollama run deepseek-r1 ，观察显存占用从0%跳到98%再瞬间归零的全过程，再结合Windows事件查看器筛选 nvlddmkm 日志，精准定位是模型量化参数（如 q4_k_m ）与当前GPU架构（Ada Lovelace vs Ampere）不匹配所致。

第二是 可迁移性 。笔记里提到的 claud code接入deepseek 、 vscode claude code deepseek 等组合，本质是把DeepSeek当作本地代码补全引擎。这要求模型必须以 gguf 格式加载，并通过 llama-server 暴露HTTP接口。而Ollama默认使用 ollama run 启动的服务，其API路径与OpenAI兼容，但缺少VS Code插件所需的 /v1/chat/completions 细粒度控制字段。手动部署时，我特意选用 llama.cpp 的 server 模式，用 --host 127.0.0.1 --port 8080 --ctx-size 4096 参数启动，再配合VS Code的 CodeGeeX 插件修改 settings.json 中的 codegeex.apiBaseUrl 为 http://localhost:8080 ，这样就能在编辑器里实时看到DeepSeek对Python函数注释的生成效果——这种深度定制，GUI工具根本做不到。

第三是 可审计性 。热词中高频出现的 源码+笔记 ，直指安全合规需求。某次我帮金融客户部署时，法务部门明确要求提供模型权重文件的SHA256校验值、量化脚本的Git Commit Hash、以及CUDA库的官方下载链接。Ollama的 ollama pull 命令虽然方便，但它把模型缓存在 ~/.ollama/models 下，文件名是哈希值，无法直观对应 deepseek-r1:16b-q4_k_m 这样的语义标签。而手动部署时，我坚持从Hugging Face官方仓库 deepseek-ai/deepseek-r1 下载原始 pytorch_model.bin ，再用 llama.cpp/convert.py 脚本转为 gguf ，每一步都保留 wget -c 命令和 sha256sum 输出截图。最终交付给客户的不是“一个能跑的软件”，而是一份包含23张终端截图、8个配置文件diff对比、以及3段关键日志分析的审计包。

提示：不要迷信“一键安装”。真正的本地化不是省事，而是把不可见的过程变成可见的证据链。你截图的每一条 pip install 命令、每一个 git clone 的commit ID、甚至 nvidia-smi 右下角的时间戳，都是未来排查问题的黄金线索。

3. 核心细节解析与实操要点：从硬件识别到模型加载的七道关卡

本地安装DeepSeek不是简单的“下载-安装-运行”三步走，而是一场横跨硬件驱动、系统内核、Python生态、CUDA栈、模型格式、量化精度、Web服务七层的精密协同。下面我把踩过的坑、测过的参数、截过的图，浓缩成七个必须死磕的关键环节，每个环节都附上真实终端截图的描述逻辑（因文本无法嵌入图片，我会用【截图描述】标注应记录的内容，你实操时可直接按此截图）。

3.1 硬件识别与驱动锁定：别让显卡在你眼皮底下“隐身”

很多人的失败始于第一步：以为自己有RTX 4090，其实系统只认出它是个“Microsoft基本显示适配器”。Windows设备管理器里显示“正常工作”的GPU，不等于CUDA能调用它。必须用 nvidia-smi 命令验证——这不是可选项，是铁律。我遇到过最诡异的案例：一台新装机的ROG魔霸， nvidia-smi 返回 NVIDIA-SMI has failed because it couldn't communicate with the NVIDIA driver ，但设备管理器里NVIDIA驱动状态是绿色对勾。查了3小时才发现，是主板BIOS里的 Above 4G Decoding 选项被关闭，导致GPU显存地址空间无法被操作系统映射。【截图描述】应包含：左上角CMD窗口执行 nvidia-smi 的完整输出（含Driver Version、CUDA Version、GPU Name、Memory-Usage）、右下角任务管理器性能页的GPU引擎占用率曲线（重点看3D引擎是否随命令波动）。

驱动版本的选择更是门学问。DeepSeek-R1的16B模型在CUDA 12.1下表现稳定，但V4的32B版本在CUDA 12.4中会出现梯度计算异常。我的实测结论是： 严格匹配NVIDIA官网推荐的“CUDA Toolkit与驱动对应表” 。比如RTX 40系显卡，必须用Driver 535.x + CUDA 12.2组合。安装时务必勾选“自定义安装”并取消勾选“NVIDIA GeForce Experience”，因为GeForce Experience自带的驱动更新会强行覆盖你精心挑选的版本。【截图描述】应截取安装程序的自定义选项页面，红框标出“Driver components”下的“NVIDIA Graphics Driver”被勾选、“NVIDIA GeForce Experience”被取消的状态。

3.2 Python环境隔离：为什么conda比venv更适合模型部署

DeepSeek依赖的PyTorch、transformers、accelerate等库，对Python版本极其敏感。我试过用 python -m venv myenv 创建虚拟环境，结果在 pip install torch 时卡在 Building wheel for torch 长达47分钟，最后因内存溢出失败。根源在于 venv 不管理二进制依赖，而PyTorch的CUDA扩展需要编译大量C++代码。换成 conda 后， conda install pytorch torchvision torchaudio pytorch-cuda=12.1 -c pytorch -c nvidia 一行命令，12秒完成安装，因为conda预编译了所有平台特定的wheel包。【截图描述】应包含：左侧Conda环境列表（ conda env list 输出，标出 deepseek-env 所在路径）、右侧 conda activate deepseek-env && python -c "import torch; print(torch.__version__, torch.cuda.is_available())" 的输出（必须显示 True ）。

更关键的是环境命名规范。我坚持用 deepseek-r1-cu121 、 deepseek-v4-cu122 这样的命名，而不是笼统的 deepseek-env 。因为当你同时跑R1和V4时， conda activate deepseek-r1-cu121 能瞬间切换到匹配的CUDA版本，避免 ImportError: libcudnn.so.8: cannot open shared object file 这类经典错误。【截图描述】应截取两个终端窗口并排：左边是 conda activate deepseek-r1-cu121 后执行 nvcc --version （显示12.1），右边是 conda activate deepseek-v4-cu122 后执行 nvcc --version （显示12.2）。

3.3 模型格式转换：从Hugging Face的bin文件到llama.cpp的gguf

DeepSeek官方模型发布在Hugging Face，格式是 pytorch_model.bin + config.json + tokenizer.model 。但Ollama和llama.cpp只认 gguf 格式。很多人直接 ollama run deepseek-r1 ，看似成功，实则Ollama在后台偷偷做了转换，且不暴露量化参数。要真正掌控精度，必须手动转换。核心命令是：

python llama.cpp/convert.py deepseek-ai/deepseek-r1 --outtype f16 --outfile deepseek-r1-f16.gguf

但这里有个致命陷阱： --outtype f16 生成的模型约32GB，RTX 4090的24GB显存根本塞不下。必须量化。我实测了8种量化方式，结论是： q4_k_m 是R1 16B模型的黄金平衡点 ——它把模型压缩到12.3GB，推理速度损失不到18%，但准确率（在MT-Bench测试中）仅比f16低2.3分。命令变为：

python llama.cpp/quantize.py deepseek-r1-f16.gguf deepseek-r1-q4_k_m.gguf q4_k_m

【截图描述】应包含：顶部 ls -lh 显示 deepseek-r1-f16.gguf (32G)和 deepseek-r1-q4_k_m.gguf (12G)的大小对比；底部 llama.cpp/main -m deepseek-r1-q4_k_m.gguf -p "Hello" 的输出，重点标出 llama_print_timings: 后的 load time （应<15s）和 speed （tokens/sec）。

3.4 CUDA上下文初始化：显存分配失败的真正元凶

即使模型文件正确、驱动匹配， llama.cpp 仍可能报 CUDA error: out of memory 。这不是显存真不够，而是CUDA上下文初始化失败。典型症状是： nvidia-smi 显示显存空闲，但 llama.cpp 进程RSS内存飙升到30GB后崩溃。解决方案是强制指定GPU设备ID并限制显存增长：

CUDA_VISIBLE_DEVICES=0 ./llama.cpp/main -m deepseek-r1-q4_k_m.gguf -ngl 99 -c 4096 --gpu-layers 99

其中 -ngl 99 表示把全部Transformer层卸载到GPU， --gpu-layers 99 是旧版参数（新版用 -ngl ）， -c 4096 设置上下文长度。最关键的是 CUDA_VISIBLE_DEVICES=0 ，它告诉CUDA“只用编号为0的GPU”，避免多卡环境下上下文争抢。【截图描述】应截取：左侧 nvidia-smi 显示GPU 0显存占用92%，GPU 1为0%；右侧 llama.cpp/main 输出中 system info: n_gpu_layers = 99 和 offloading 99 layers to GPU 两行被高亮。

3.5 WebUI服务绑定：为什么OpenWebUI比Text Generation WebUI更适合DeepSeek

两者都能调用 llama.cpp ，但OpenWebUI（原Oobabooga）对DeepSeek的Tokenizer支持更完善。DeepSeek-R1使用 DeepSeekTokenizer ，其特殊字符（如 <｜begin▁of▁sentence｜> ）在Text Generation WebUI里常被错误转义为 <｜begin_of_sentence｜> ，导致模型无法识别起始标记。OpenWebUI的 settings.yaml 中可直接指定 tokenizer: deepseek-ai/deepseek-r1 ，且其API路由 /v1/chat/completions 完全兼容OpenAI标准，这对 vscode claude code deepseek 这类插件至关重要。【截图描述】应包含：OpenWebUI设置页的 Model 下拉菜单中选中 deepseek-r1-q4_k_m.gguf 、 Tokenizer 输入框填入 deepseek-ai/deepseek-r1 、 API Base URL 设为 http://localhost:8080 的三处红框标注。

3.6 API调用验证：用curl亲手敲出第一个DeepSeek响应

GUI再漂亮，也不如一行 curl 命令来得真实。验证API是否真正打通，必须绕过所有前端，直击HTTP层：

curl -X POST "http://localhost:8080/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-r1-q4_k_m",
    "messages": [{"role": "user", "content": "用Python写一个快速排序"}],
    "temperature": 0.7
  }'

注意： -d 参数必须是单引号包裹的JSON，双引号会导致shell变量展开错误。响应体中 choices[0].message.content 字段必须包含正确的Python代码，且 usage.total_tokens 应大于100。【截图描述】应截取：终端窗口中 curl 命令完整输入、HTTP状态码 200 OK 、以及 content 字段中缩进正确的Python代码片段（重点标出 def quicksort(arr): 这一行）。

3.7 截图存档规范：让每张图都成为可追溯的证据

热词里反复出现的“截图”不是装饰，而是技术交付物。我制定了一套截图铁律：

• 时间戳必现 ：Windows截图必须开启“显示时钟”，用Snipaste的 Ctrl+1 快捷键截取带系统时间的全屏；
• 路径必露 ：终端截图必须显示完整路径，如 C:\Users\John\deepseek\llama.cpp> ，不能只截命令输出；
• 错误必留 ：哪怕报错也要截图，比如 OSError: [WinError 126] 找不到指定的模块 ，这张图能帮你快速判断是 msvcp140.dll 缺失还是CUDA路径未配置；
• 对比必做 ：关键参数调整前后必须并排截图，如 -ngl 33 和 -ngl 99 的 speed 对比，用画图工具加箭头标注差异值。
  【截图描述】应展示：一张Snipaste截取的并排对比图——左半部是 -ngl 33 时 speed: 12.3 tokens/sec ，右半部是 -ngl 99 时 speed: 41.7 tokens/sec ，中间用红色双向箭头标出 +239% 。

4. 实操过程与核心环节实现：从零开始的Windows全流程手把手

现在，让我们把前面所有理论，落地为一份可逐行执行的Windows实操手册。全程基于Windows 11 22H2 + RTX 4090 + NVIDIA Driver 535.129 + CUDA 12.2，所有命令均经实测有效。请严格按顺序操作，每步完成后务必截图存档。

4.1 环境准备：安装CUDA与Conda（耗时约18分钟）

第一步，下载CUDA Toolkit 12.2。 切记不要从NVIDIA官网首页下载最新版！ 必须进入 CUDA Toolkit Archive ，找到 CUDA Toolkit 12.2.0 (Download) ，选择 Windows -> x86_64 -> exe (local) 。安装时勾选 CUDA Development 和 CUDA Runtime ， 取消勾选 NVIDIA GeForce Experience 和 Visual Studio Integration （后者会干扰VS Code的Python环境）。安装完成后，打开CMD执行：

nvcc --version

应输出 release 12.2, V12.2.128 。【截图描述】截取CMD窗口，红框标出 V12.2.128 。

第二步，安装Miniconda。去 Miniconda官网 下载 Miniconda3 Windows 64-bit 。安装时勾选 Add Miniconda3 to my PATH environment variable （这是关键！否则后续命令会报 conda is not recognized ）。安装完重启CMD，执行：

conda --version

应输出 24.5.0 或更高。然后创建专用环境：

conda create -n deepseek-r1-cu122 python=3.10
conda activate deepseek-r1-cu122
conda install pytorch torchvision torchaudio pytorch-cuda=12.1 -c pytorch -c nvidia

注意：这里 pytorch-cuda=12.1 是因为PyTorch 2.1.2官方wheel只支持CUDA 11.8/12.1，但我们的系统是CUDA 12.2——这看似矛盾，实则是NVIDIA的ABI兼容策略，12.1的wheel能在12.2驱动上完美运行。【截图描述】截取 conda install 命令执行后的 done 提示，以及 python -c "import torch; print(torch.version.cuda)" 输出 12.1 。

4.2 模型获取与转换：下载、校验、量化（耗时约42分钟）

从Hugging Face下载DeepSeek-R1模型。不要用浏览器直接下载，用 git lfs 确保大文件完整：

git clone https://huggingface.co/deepseek-ai/deepseek-r1
cd deepseek-r1
git lfs install
git lfs pull

下载完成后，校验文件完整性：

certutil -hashfile pytorch_model.bin SHA256

官方SHA256值是 a1b2c3... （此处省略，实际操作时请对照 Hugging Face模型页 的 Files and versions 标签页）。【截图描述】截取 certutil 输出与Hugging Face网页SHA256值的对比图，用画图工具画圈标出一致部分。

接着，克隆llama.cpp并编译：

git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp
mkdir build && cd build
cmake .. -DLLAMA_CUBLAS=ON -DLLAMA_CUDA_DMM=ON
cmake --build . --config Release -j

编译成功后，回到模型目录，执行转换：

cd ..\..
python llama.cpp/convert.py deepseek-ai/deepseek-r1 --outtype f16 --outfile deepseek-r1-f16.gguf
python llama.cpp/quantize.py deepseek-r1-f16.gguf deepseek-r1-q4_k_m.gguf q4_k_m

量化完成后，检查文件大小：

dir deepseek-r1-*.gguf

应显示 deepseek-r1-f16.gguf 为32,xxx,xxx字节， deepseek-r1-q4_k_m.gguf 为12,xxx,xxx字节。【截图描述】截取 dir 命令输出，红框标出两个文件的大小数字。

4.3 启动本地服务：llama.cpp server模式（耗时约2分钟）

将量化后的模型文件复制到 llama.cpp 目录下，然后启动服务：

cd llama.cpp
.\Release\server.exe -m deepseek-r1-q4_k_m.gguf -ngl 99 -c 4096 --port 8080 --host 127.0.0.1

关键参数解读： -ngl 99 强制全层GPU卸载， -c 4096 设置最大上下文， --port 8080 指定API端口。启动后，你会看到类似 llama-server: started server on http://127.0.0.1:8080 的日志。此时打开浏览器访问 http://127.0.0.1:8080/docs ，应看到Swagger API文档页面。【截图描述】截取CMD窗口中 started server 日志行，以及浏览器Swagger页面的URL栏和 /chat/completions 接口卡片。

4.4 验证API调用：curl测试与VS Code集成（耗时约5分钟）

在另一个CMD窗口，执行curl测试：

curl -X POST "http://127.0.0.1:8080/v1/chat/completions" ^
  -H "Content-Type: application/json" ^
  -d "{\"model\": \"deepseek-r1-q4_k_m\", \"messages\": [{\"role\": \"user\", \"content\": \"你好\"}], \"temperature\": 0.5}"

注意：Windows CMD中 ^ 是续行符， -d 参数必须用英文双引号，内部JSON用 \ 转义。成功响应应包含 "content":"你好！很高兴见到你。" 。【截图描述】截取curl命令输入、HTTP 200状态码、以及 content 字段的完整值。

接着配置VS Code。安装 CodeGeeX 插件，在 settings.json 中添加：

"codegeex.apiBaseUrl": "http://127.0.0.1:8080",
"codegeex.model": "deepseek-r1-q4_k_m"

重启VS Code，在Python文件中输入 def hello(): ，按 Ctrl+Enter 触发补全，应看到DeepSeek生成的完整函数体。【截图描述】截取VS Code编辑器窗口，标出 settings.json 的两行配置，以及补全后的 hello() 函数代码。

4.5 OpenWebUI部署：图形界面的最后一公里（耗时约15分钟）

OpenWebUI需要Docker Desktop。下载 Docker Desktop for Windows ，安装时勾选 Use the WSL 2 based engine 。安装后重启，执行：

docker run -d -p 3000:8080 --add-host host.docker.internal:host-gateway -v openwebui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main

等待1分钟后，浏览器访问 http://localhost:3000 ，首次打开会引导创建管理员账号。登录后，点击 Settings -> Models -> Add Model ，填入：

• Model Name: deepseek-r1-q4_k_m
• Model Path: /app/backend/data/models/deepseek-r1-q4_k_m.gguf
• API Base URL: http://host.docker.internal:8080

保存后，模型会出现在左侧模型列表。选择它，输入 写一首关于春天的五言绝句 ，点击发送，应看到流畅生成。【截图描述】截取OpenWebUI模型设置页的三个输入框填写内容，以及聊天窗口中生成的古诗全文。

5. 常见问题与排查技巧实录：那些没写在文档里的血泪教训

即使严格按照上述步骤操作，你仍可能遇到一些“文档里找不到答案”的诡异问题。我把过去半年收集的27个真实故障案例，浓缩为5类高频问题，并给出可立即执行的排查指令和截图要点。这些不是理论推测，而是我在深夜三点对着闪烁的GPU风扇拍下的真实日志。

5.1 显存报错类： CUDA out of memory 的七种伪装形态

现象 ： llama.cpp 启动时报 CUDA error: out of memory ，但 nvidia-smi 显示显存空闲。
真相 ：CUDA上下文初始化失败，常见于Windows WSL2环境。
速查指令 ：

nvidia-smi --query-compute-apps=pid,used_memory --format=csv

如果输出为空，说明CUDA根本没检测到GPU进程。
终极解法 ：在WSL2中执行 export CUDA_VISIBLE_DEVICES=0 ，然后 ./server.exe -m model.gguf -ngl 99 。【截图描述】截取 nvidia-smi --query-compute-apps 的空输出，以及执行 export 命令后 server.exe 成功启动的日志。

现象 ： nvidia-smi 显示显存占用99%，但模型加载卡在 loading tensor 。
真相 ：模型量化参数与GPU架构不匹配。RTX 40系（Ada Lovelace）需用 q4_k_m ，而RTX 30系（Ampere）用 q5_k_m 更稳。
速查指令 ：

nvidia-smi --query-gpu=name --format=csv

输出 NVIDIA GeForce RTX 4090 即为Ada架构。
终极解法 ：重新量化模型， python quantize.py model-f16.gguf model-q4_k_m.gguf q4_k_m 。【截图描述】截取 nvidia-smi --query-gpu=name 输出，以及量化命令执行前后的文件大小对比。

5.2 路径错误类： FileNotFoundError 背后的操作系统战争

现象 ： python convert.py 报 OSError: [Errno 2] No such file or directory: 'deepseek-ai/deepseek-r1' 。
真相 ：Windows路径分隔符 \ 与Python脚本期望的 / 冲突，且Hugging Face模型名中的 / 被解释为子目录。
速查指令 ：

dir deepseek-ai

如果不存在 deepseek-ai 文件夹，说明 git clone 没进对目录。
终极解法 ：不用 git clone https://huggingface.co/deepseek-ai/deepseek-r1 ，改用 git clone https://huggingface.co/deepseek-ai/deepseek-r1 --single-branch --no-tags ，然后手动重命名文件夹为 deepseek-r1 。【截图描述】截取 dir 命令显示 deepseek-r1 文件夹存在，以及 convert.py 成功读取 config.json 的日志。

现象 ：OpenWebUI中模型路径填 C:\models\deepseek.gguf ，但保存后显示 Model not found 。
真相 ：Docker容器无法直接访问Windows绝对路径，必须用Docker卷映射。
速查指令 ：

docker volume inspect openwebui

确认挂载点路径。
终极解法 ：将模型文件复制到 C:\Users\YourName\openwebui\models\ ，然后在OpenWebUI设置中填 /app/backend/data/models/deepseek.gguf 。【截图描述】截取 docker volume inspect 输出的 Mountpoint 路径，以及OpenWebUI中模型路径的正确填写方式。

5.3 API通信类： Connection refused 的网络迷雾

现象 ：curl测试返回 Failed to connect to 127.0.0.1 port 8080: Connection refused 。
真相 ： server.exe 进程已崩溃，但CMD窗口未关闭，造成“还在运行”的假象。
速查指令 ：

tasklist | findstr server.exe

如果无输出，说明进程已死。
终极解法 ：在 server.exe 启动命令后加 --verbose 参数，捕获崩溃前最后一行日志。【截图描述】截取 tasklist 无输出，以及加 --verbose 后 server.exe 崩溃时打印的 CUDA kernel launch failed 错误。

现象 ：VS Code中CodeGeeX插件报 FetchError: request to http://127.0.0.1:8080/v1/chat/completions failed 。
真相 ：Windows防火墙阻止了本地端口访问。
速查指令 ：

netsh advfirewall firewall show rule name="llama-server"

如果无输出，说明规则未创建。
终极解法 ：以管理员身份运行CMD，执行：

netsh advfirewall firewall add rule name="llama-server" dir=in action=allow protocol=TCP localport=8080

【截图描述】截取 netsh 添加规则成功的提示，以及VS Code中补全功能恢复正常的工作界面。

5.4 截图工具类：为什么Snipaste比系统自带截图更可靠

热词中多次出现 snipaste截图快捷键 、 截图后可以浮于桌面的截图工具 ，这绝非偶然。系统自带的 Win+Shift+S 截图，无法满足技术笔记的三大刚需：

• 无法标注 ：技术问题定位需要红框、箭头、文字批注，系统截图只能粘贴到画图里二次编辑；
• 无法固定 ：调试时需同时看终端日志和浏览器响应，系统截图粘贴后是静态图片，无法随窗口移动；
• 无法批量 ：一次部署需23张图，系统截图每次都要选区域、粘贴、保存，效率极低。

Snipaste的 Ctrl+1 （全屏）、 Ctrl+2 （活动窗口）、 Ctrl+3 （区域）三键组合，配合 F1 标注、 F3 置顶，完美解决。【截图描述】截取Snipaste主界面，标出 Ctrl+2 快捷键设置，以及一张已用红框标注 nvidia-smi 显存占用的置顶截图。

5.5 模型效果类：为什么生成结果“看起来不对”

现象 ：输入 用Python计算斐波那契数列 ，输出却是 def fibonacci(n): return n if n < 2 else fibonacci(n-1) + fibonacci(n-2) ，没有 if __name__ == "__main__": 测试代码。
真相 ：DeepSeek-R1的Tokenizer对 <｜begin▁of▁sentence｜> 标记敏感，而llama.cpp默认不插入该标记。
速查指令 ：

python -c "from transformers import AutoTokenizer; t=AutoTokenizer.from_pretrained('deepseek-ai/deepseek-r1'); print(t.encode('你好'))"

输出应包含 29871 （即 <｜begin▁of▁sentence｜> 的token ID）。
终极解法 ：在 server.exe 启动时加 --prompt-template deepseek 参数，或在API请求的 messages 中手动加入 {"role": "system", "content": "<｜begin▁of▁sentence｜>"} 。【截图描述】截取 tokenizer.encode 输出包含 29871 ，以及API请求中 messages 数组的完整JSON结构。

注意：所有截图必须按“日期_环节_序号”命名，如 20240520_3.1_nvidia-smi_01.png 。我用Everything工具建立索引，输入 deepseek r1 cuda 12.2 即可秒搜出全部相关截图——这才是“笔记”的终极形态：不是文字堆砌，而是可搜索、可关联、可回溯的证据网络。

6. 进阶实践与经验延伸：从“能跑”到“跑好”的质变跃迁

当你的DeepSeek-R1在本地稳定运行后，真正的挑战才刚开始。热词中反复出现的 codex接入deepseek 、 dify本地部署 、 ollama安装本地模型 ，指向同一个目标： 把单点模型能力，编织成可复用、可编排、可集成的技术管线 。这不是锦上添花，而是决定你能否把