DeepSeek Harness本地部署实战：从Ollama到VSCode接入

赶了个晚集，这个标题我是认真的。DeepSeek 相关的工具链社区里早就玩出花来了，我到现在才把 DeepSeek Harness 认认真真在本地跑通。但折腾完一圈，我发现晚折腾也有晚折腾的好处：前人踩过的坑都晒在论坛和 Issue 里了，我这个后来者照着绕过去就行。所以这篇东西不是来科普 DeepSeek 是什么的，而是把从零开始下载安装 DeepSeek Harness、接入本地模型、再把它接到 VSCode 和文档问答里的完整过程记录下来。如果你也正卡在"装了不知道怎么配""配了不知道为什么连不上"这一步，这篇应该能帮你省下不少时间。

1. 搞清楚再动手：DeepSeek Harness 是什么

1.1 拆开"Harness"这层壳

先说结论：DeepSeek Harness 不是一个像微信那样双击安装就能用的单体软件，它更像是一套把 DeepSeek 模型能力"牵引"到本地工作流的工具集合。你在网上搜"DeepSeek Harness"，能看到的东西其实很杂：有的是社区维护的桌面客户端，有的是把 DeepSeek 模型接进 IDE 的插件组合，还有的干脆就是开发者自己攒的一套命令行脚本。严格说，它并没有一个唯一"正版"的安装包入口。

但不管它外面套的是什么壳，底层要解决的事情只有三件：模型从哪来、怎么调用、界面在哪里。模型可以来自官方 API，也可以来自本地运行时；调用接口目前主流都走 OpenAI 兼容协议；界面则是命令行、桌面窗口、VSCode 插件三选一或者三选多。理解了这三层，后面所有的安装和配置都是在往这三个框里填东西，就不会被网上各种碎片信息带偏。

1.2 本地安装的最大价值：数据与自由度

我选择本地安装而不是直接调官方 API，最重要的原因是"数据不出门"。写代码的时候经常要贴大段报错信息或者项目片段进去，每次都发到云端心里总有点别扭。本地部署之后，请求打到的是你自己的机器，适合处理一些不太方便外传的内容。

另一个好处是自由度。云端对话有长度上限，聊着聊着就提示"达到对话长度上限，请开启新对话"，这在处理长文档、做批量分析时非常折磨人。本地模型只要显存和上下文参数设置得当，你想把上下文窗口撑多大就撑多大，而且单次调用的成本约等于电费。对我来说，"上下文可控 + 调用量不心疼"这两点就已经值回折腾成本了。

1.3 这套方案适合谁、不适合谁

在动手之前，建议先对照下面的表格做个自我评估，别一上来就装，装完发现硬件根本带不动，心态容易崩。

2. 安装前的准备：先把地基打牢

2.1 硬件选型参考

本地部署 DeepSeek 模型，硬件是绕不开的坎。我的机器是 16G 内存加 8G 显存的 NVIDIA 显卡，跑 7B 参数的量化模型比较舒服，14B 模型能跑但上下文稍微一长就会吃紧。如果你的显存更大，可以上更高的量化等级或者更大参数量的模型。

这里给一个我实测下来比较靠谱的参考：8G 显存适合 7B 量化模型；12G 到 16G 显存适合 14B 量化模型，并且可以开 8K 左右的上下文；24G 以上显存就可以尝试 32B 甚至更大模型了。如果只有 CPU，别指望实时对话，实测在 CPU 上跑 7B 模型，每秒生成几个 token 都算不错了，基本只适合跑批处理任务。

系统方面，Windows、Linux、macOS 都能装。Windows 用户注意一下显卡驱动要更新到较新版本，后面我会专门讲一个显卡驱动的坑。

2.2 Ollama 安装与初始化

DeepSeek Harness 本身只管"调度"和"界面"，真正在背后跑模型的是本地运行时。目前最省心的选择是 Ollama，它封装了模型下载、权重加载、API 暴露，几乎你不需要手动去管 Python 环境和 CUDA 版本，装上就能用。

Ollama 的安装方式按系统来：Windows 直接下载安装包，下一步下一步就行；macOS 用 Homebrew 装也方便；Linux 用户执行官方脚本：

curl -fsSL https://ollama.com/install.sh | sh

安装完先验证一下：

ollama --version

看到版本号输出就说明装好了。紧接着启动服务。Windows 和 macOS 上 Ollama 一般会作为后台服务自动启动，Linux 上可能需要手动执行ollama serve，或者设置成 systemd 服务。

2.3 拉取 DeepSeek 模型，以及模型大小的选择

Ollama 装好之后，拉取模型就一条命令：

ollama pull deepseek-r1:7b

如果你想试试更大一点的，可以拉 14b：

ollama pull deepseek-r1:14b

注意：7b 和 14b 指的是模型参数量，理论上参数量越大，模型的推理能力越强，但对显存和内存的要求也水涨船高。新手我强烈建议从 7b 开始，先跑通整条链路再考虑升级。拉完模型可以用ollama list确认一下当前机器上有哪些模型。

拉下来之后，先手动跑一次，验证模型本身没问题：

ollama run deepseek-r1:7b

能正常对话就说明模型引擎没问题，后面配置 Harness 连不上时，至少你能确定问题不在模型这一层。

3. DeepSeek Harness 本地安装全流程

3.1 用隔离环境安装依赖

很多人在这一步翻车：直接用全局 Python 环境装了一堆依赖，结果跟其他项目冲突，卸载都来不及。我建议无论你拿到的是桌面版源码还是命令行工具，都用虚拟环境隔离。

以最常见的 Python 形态为例，先建一个干净的虚拟环境：

python -m venv deepseek-harness-env

Windows 下激活：

deepseek-harness-env\Scripts\activate

Linux / macOS 下激活：

source deepseek-harness-env/bin/activate

激活之后，从官方仓库克隆或者下载源码包，进入项目目录安装依赖。一般不推荐直接pip install deepseek-harness这种全网同名的方式，因为第三方 PyPI 包鱼龙混杂，认准仓库里的 requirements 文件更稳：

pip install -r requirements.txt

依赖装完之后，先看一下项目目录结构。通常会有config或.env.example这类文件，这就是后面所有配置的关键。

3.2 写配置文件：一行一行说清楚

DeepSeek Harness 的核心配置就是一个环境变量文件。把项目提供的.env.example复制一份成.env，然后逐项改。我这份配置基本可以直接抄：

# 本地 Ollama 服务的地址，OpenAI 兼容协议的默认路径是 /v1 BASE_URL=http://localhost:11434/v1 # 对应 Ollama 里已经拉取的模型名 MODEL=deepseek-r1:7b # 本地服务不需要真实密钥，随便填一个占位符即可 API_KEY=ollama # 生成温度，0 到 1 之间，数值越小回答越保守 TEMPERATURE=0.7 # 单次生成的最大 token 数，避免回答过长导致超时 MAX_TOKENS=2048 # 上下文窗口大小，单位是 token，默认 4096，显存足够可以调大 CONTEXT_WINDOW=4096

这里最容易被忽略的是BASE_URL里的/v1后缀。很多人在配置对接本地模型时只填了http://localhost:11434，结果怎么调都报 404，因为 OpenAI 兼容接口的路由前缀就是/v1。至于API_KEY，本地服务不校验身份，但客户端库一般要求非空，所以填个ollama或者local都行。

3.3 用一段测试脚本验证链路是否通了

配置写完了，别急着打开界面，先跑一段最朴素的脚本确认链路是通的。这一步能帮你把"Harness 配置问题"和"模型问题"快速分开。在虚拟环境里装好 OpenAI 客户端库之后，执行下面这段：

from openai import OpenAI client = OpenAI( base_url="http://localhost:11434/v1", api_key="ollama", ) resp = client.chat.completions.create( model="deepseek-r1:7b", messages=[ {"role": "system", "content": "你是本地部署的 DeepSeek 助手，用简洁的中文回答。"}, {"role": "user", "content": "用一句话说明什么是 DeepSeek Harness。"}, ], temperature=0.7, max_tokens=1024, ) print(resp.choices[0].message.content)

能正常返回一段文字，说明 Ollama 里的模型没问题、接口路径没问题、配置也没问题。这时候再打开 Harness 的桌面端或者命令行入口，把同样的BASE_URL、MODEL填进去，基本上就是水到渠成的事情。很多人在这一步卡了很久，最后发现是端口被占或者防火墙拦了本地回环请求，脚本一出错，问题定位就快多了。

4. 把 DeepSeek 接到日常工具链里

4.1 VSCode 接入：写代码时顺手用起来

本地模型跑通之后，我最常用的场景是写代码时让 DeepSeek 帮忙看报错、补注释、整理 diff。VSCode 里接 DeepSeek 的常用做法是装一个支持自定义模型供应商的 AI 插件，比如 Continue 或者 Cline。

以 Continue 为例，安装插件之后打开它的配置文件，加入一个指向本地服务的连接：

{ "provider": "openai", "apiBase": "http://localhost:11434/v1", "apiKey": "ollama", "model": "deepseek-r1:7b" }

保存之后，在插件面板里切换到刚才配置的模型，就可以直接在侧边栏对话。实测下来，7B 模型对简单问题、代码片段的解释完全够用，横跨大项目做代码重构这类复杂任务就比较吃力。这里有个细节：VSCode 插件本身也会维护一轮对话的上下文，所以如果遇到"回答到一半突然报错"的情况，先清空当前会话，再重启插件，多半能恢复正常。

4.2 让 Harness 读取本地 md 文件

官方对话界面只能纯聊，没法直接"看"本地文件，所以很多人问 DeepSeek Harness 怎么读取 md 文件。其实思路很简单：把 md 文件内容读进内存，拼到 prompt 里发给模型。

我自己写了一个极简脚本，放在项目里当工具用：

from pathlib import Path from openai import OpenAI client = OpenAI( base_url="http://localhost:11434/v1", api_key="ollama", ) # 读取本地 Markdown 文件 content = Path("README.md").read_text(encoding="utf-8") resp = client.chat.completions.create( model="deepseek-r1:7b", messages=[ {"role": "system", "content": "根据用户提供的文档内容回答问题，尽量引用原文。"}, {"role": "user", "content": f"以下是文档内容：\n\n{content}\n\n请总结这篇文章的核心要点。"}, ], temperature=0.3, max_tokens=1024, ) print(resp.choices[0].message.content)

一个小建议：如果 md 文件特别长，不要一股脑全塞进去。本地模型的上下文窗口虽然能调大，但窗口越大推理越慢，显存占用也越高。稳妥的办法是按标题或者按固定长度把文档切成块，每次只塞一段进去提问，缺什么信息再补充哪一块。这其实就是最朴素的 RAG 思路，不需要上什么高端框架。

4.3 把服务接到局域网和 Ubuntu 机器上

我平时主力机是 Windows，但有些活要在 Ubuntu 服务器上跑，两边共用同一个模型服务就很舒服。Ollama 默认只监听本机回环地址127.0.0.1，要在局域网内被其他机器访问，需要把监听地址放开。

Linux 上启动服务时指定：

OLLAMA_HOST=0.0.0.0:11434 ollama serve

Windows 上则在系统环境变量里新增OLLAMA_HOST=0.0.0.0:11434，然后重启 Ollama 服务。放开监听之后，在另一台机器上先用 curl 验证一下：

curl http://<Ubuntu的IP>:11434/api/tags

能返回模型列表 JSON，说明网络通了。然后把 Harness 配置里的BASE_URL从http://localhost:11434/v1改成http://<Ubuntu的IP>:11434/v1，其他什么都不用动。

这里必须提醒一句：把模型服务暴露到局域网意味着局域网内任何人都能调你的模型，白嫖资源是小，带来安全隐患是大。如果不是长期多机协作，用完就把OLLAMA_HOST改回127.0.0.1，或者在防火墙层面对 11434 端口做访问限制。

5. 折腾中遇到的高频问题与排错记录

5.1 对话长度上限：怎么把上下文撑大

本地模型同样会遇到对话长度上限的问题，这个"上限"来自上下文窗口大小的设置。Ollama 默认的上下文窗口往往偏保守，对话一长就提示要开新对话。解决方法是把上下文窗口调大。

Ollama 运行中可以直接在会话里设置：

/set parameter num_ctx 8192

或者通过 API 调用时在请求参数里显式传：

client.chat.completions.create( model="deepseek-r1:7b", messages=[...], extra_body={"num_ctx": 8192} )

把num_ctx从默认的 4096 提到 8192 之后，能明显感觉到"对话变长不再失忆"。但代价也很直接：显存占用上涨，生成速度下降。如果你的显卡只有 8G 显存，num_ctx建议控制在 8192 以内，贪多了容易触发显卡崩溃。

5.2 request extension preparation failed 的排查

这个报错我在本地折腾时遇到过好几次，字面意思是"请求扩展准备失败"，实际原因却五花八门。最常见的两种：一是上下文窗口不够，prompt 太长导致请求还没发出去就被掐断；二是本地服务并发处理能力不足，多个请求同时打到 Ollama 上，其中一个就莫名其妙失败了。

排查思路按顺序来：先重启 Ollama 服务，排除临时状态问题；然后把num_ctx调小，比如回到 4096，看看问题是否消失；最后打开 Ollama 的详细日志，运行ollama serve --verbose，看报错时前后日志里有没有显存分配失败的记录。如果日志里出现 CUDA out of memory 之类的字样，那就是显存不够，别调参数了，换小模型吧。

5.3 NVIDIA 事件 ID 153：本地推理的显卡坑

跑本地模型最怕的不是模型答得烂，而是系统日志里突然蹦出一条"来自源 nvlddmkm 的事件 ID 153"，然后画面卡死、驱动重置、模型进程直接消失。这个错误本质上是 NVIDIA 显卡驱动在长时间高负载下触发了 TDR 机制，系统认为显卡"无响应"就强制重启驱动，推理进程自然就没了。

解决办法有几个方向：更新到较新的显卡驱动，老驱动对长时间 CUDA 负载的容忍度确实差一些；减小模型规模或者把num_ctx调低，给显存留出余量；检查机器上有没有其他程序在抢 GPU 资源，比如浏览器硬件加速、其他训练任务。还有一个小技巧是修改系统的 TDR 延迟时间，但不建议新手动注册表，风险大于收益。我在把num_ctx从 8192 降回 4096 之后，这个问题就基本没有复发过。

5.4 常见问题速查表

遇到问题先对照这张表过一次，能省下大量盲目搜索的时间。我自己踩过的坑里，最后查出原因最简单的反而是最容易被忽略的：模型名多打了一个冒号，或者大小写不一致。这类低级错误用ollama list对一遍就能暴露出来。

折腾完这一圈，最大的体会是本地跑模型本质上就是把"模型运行时、配置、调用端"这三件事逐一理顺，每一步都不难，但它们之间的衔接细节决定了最终能不能丝滑跑起来。赶了个晚集最大的好处，就是我踩过的这些坑你其实都可以绕开。如果你也打算从云端 API 切到本地运行，我只有一个建议：别贪大，先拿 7B 量化模型把链路跑通，再谈升级。毕竟模型再大，跑不起来也等于零。