各位读者朋友大家好。近期在项目里尝试把 DeepSeek 接入到本地工具链时我发现网上关于“DeepSeek Harness”的资料非常零散很多教程停留在“申请 API Key 后跑一次聊天请求”的层面真正能落地的操作步骤、参数调整、异常定位内容少之又少。这篇文章我会从实际工程角度出发把 DeepSeek 从云端 API 到本地开发工具、再到简易 AI 助手的完整链路拆开讲一遍。无论你是刚接触大模型开发的新手还是已经在用 Cursor、Codex 这类 AI 编程工具的开发者都可以按文中的流程搭建一套属于自己的电脑助手并在生产环境里避开常见的坑。需要提前说明的是本文讨论的是把 DeepSeek 作为 AI 能力底座来构建工具所有操作都要在合规前提下进行。文中的代码示例以 OpenAI SDK 兼容接口为主因为 DeepSeek 对外提供的接口严格遵循 OpenAI Chat Completions 规范这样可以复用大量现有生态。同时我也会介绍“Harness”这种封装思路它并不是某个神秘框架的专属名词而是一种工程模式把大模型、提示词、工具调用、记忆管理统一封装成可编程的助手层。搞懂这个模式后面接任何模型都会轻松很多。1. 背景与核心概念1.1 什么是 DeepSeek Harness在正式开始之前先聊清楚“Harness”这个词。Harness 本意是“马具、挽具”在软件工程里常被翻译成“装配”、“封装”或“测试夹具”。比如测试领域有 Test Harness用来把被测模块和外部依赖组合起来统一执行用例。放到 AI 应用场景中DeepSeek Harness 可以理解为一套围绕 DeepSeek 模型打造的“工具装配层”它把模型接口、上下文管理、工具调用、日志、异常处理全部串起来最终对外暴露一个更易用的助手能力。很多开发者第一次听到“DeepSeek Harness”会误以为它必须是一个独立的开源软件需要下载安装某个固定程序。其实不是社区里确实存在一些叫“Harness”的项目或插件但更常见的是我们自己用代码搭建的一层工程封装。你可以用 Python 写一个命令行助手也可以用 FastAPI 包装成 HTTP 服务还可以接入 Cursor、Codex 之类的 AI 编程工具。核心目的都一样让 DeepSeek 不再只是网页里的对话机器人而是能本地调用、能处理文件、能执行工具、能被其他程序集成的“电脑助手”。换句话说这篇文章讲的“DeepSeek Harness”是一套实操方法而不是让你去装某个神仙软件。理解了这一点你就不会在安装环节迷失方向。1.2 为什么需要把 DeepSeek 变成电脑助手现在 DeepSeek 的官网聊天界面已经足够好用那为什么还要自己封装一个助手主要原因有三点第一数据流可控。网页聊天时对话记录往往保存在服务端虽然官方有隐私政策但企业项目里很多内部数据不能直接粘贴到网页对话框。通过 API 接入后我们可以把提示词、上下文、敏感信息全部保存在本地服务中按需发送。第二自动化能力。网页聊天只能人工输入而封装成 Harness 后它就能被脚本调度、被定时任务触发、被其他系统调用。比如我当前项目的需求是每天晚上读取数据库中的日志让 DeepSeek 自动生成异常摘要再推送到钉钉群。这种需求网页版根本做不了必须走 API 封装。第三工具调用与多模型切换。借助 OpenAI 兼容接口我们可以把 DeepSeek 和本地模型、其他商业模型放在同一套工程框架中。当某个模型不可用时自动切换不用改动调用方代码。这正是 Harness 模式的工程价值。1.3 常见应用场景我梳理了几个比较典型的“DeepSeek Harness”落地场景方便你快速判断自己的需求属于哪一类场景说明推荐方案个人命令行助手在终端里快速提问支持上下文记忆Python Rich本地知识库问答读取本地 Markdown/文本文件自动检索并回答向量库 DeepSeek API办公自动化根据模板生成邮件、周报、PPT 大纲FastAPI 定时任务AI 编程助手在 Cursor/Codex 中接入 DeepSeekOpenAI 兼容接口配置团队内部机器人接入钉钉、飞书、企业微信机器人回调 HTTP 服务本地离线部署完全离线环境数据不出内网Ollama 本地模型本文会重点覆盖“个人命令行助手”和“AI 编程工具接入”两条线因为它们最容易上手也最能体现 Harness 的封装价值。2. 环境准备与版本说明2.1 本机环境要求我以 Windows 11 作为演示系统但你完全可以在 macOS 或 Linux 上操作原理一致。Python 建议使用 3.10 或以上版本因为一些类型注解和异步语法在 3.10 之后更友好。Node.js 不是必需但如果后续要接入前端或某些桌面插件建议安装 18 以上的 LTS 版本。需要说明的是当前 DeepSeek API 和周边生态更新很快本文的版本组合如下并非唯一选择你可以根据实际情况调整操作系统: Windows 11 / macOS 14 / Ubuntu 22.04 Python: 3.10 - 3.12 OpenAI SDK: 1.0 dotenv: 1.0 左右 FastAPI: 0.115 左右如果你在安装依赖时发现版本冲突优先保证 openai 库是最新版因为 DeepSeek 接口紧随 OpenAI 的规范演进。2.2 申请 DeepSeek API Key既然要打造电脑助手首先需要能调用 DeepSeek 大模型。打开 DeepSeek 开放平台注册账号后进入 API Keys 页面创建一个新的 Key。创建后请立即复制保存因为平台不会再次展示完整 Key。登录 DeepSeek 开放平台进入“API Keys”菜单点击“创建 API Key”输入名称比如local-assistant创建后复制保存在正式环境中API Key 一定不要硬编码在代码里我会在后面的配置管理中专门说明。现在你只需要在项目根目录创建一个.env文件把 Key 放进去DEEPSEEK_API_KEYsk-你的真实key在开始写代码之前可以先验证一下 Key 是否有效。用 curl 或者 Postman 发一个最简单的 Chat 请求curl https://api.deepseek.com/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $DEEPSEEK_API_KEY \ -d { model: deepseek-chat, messages: [{role: user, content: 你好}] }如果返回内容包含choices数组说明 Key 和网络都没问题。这里需要特别注意DeepSeek API 的 Base URL 是https://api.deepseek.com而不是常见的https://api.openai.com。这也是很多初学同学第一次接入时最容易写错的地方。2.3 安装 Python 依赖我习惯用虚拟环境来隔离项目依赖尤其是在做 AI 工程时不同项目可能依赖不同版本的 openai 库。新建项目目录后执行mkdir deepseek-harness-demo cd deepseek-harness-demo python -m venv venv # Windows venv\Scripts\activate # macOS / Linux source venv/bin/activate然后安装接下来会用到的依赖pip install openai python-dotenv rich fastapi uvicornopenai官方 SDKDeepSeek 兼容其调用方式python-dotenv读取.env文件中的环境变量rich让命令行输出更美观fastapiuvicorn用于构建 Web API装完后可以用pip list查看版本如果发现 openai 版本过低建议升级。2.4 本地部署的硬件说明如果你不想走云端 API而是希望在本地部署 DeepSeek 模型那么需要一台配置合适的机器。虽然 DeepSeek 官方提供了不同大小的模型但完整版大模型的参数量很大不是普通笔记本能跑的。我建议个人开发者优先使用 Ollama 这类工具运行量化后的小模型比如deepseek-r1:7b或deepseek-r1:14b。最低配置参考CPU8 核以上内存16GB 以上显存8GB 以上推荐 16GB磁盘SSD预留 20GB 以上如果你的机器达不到要求仍然可以继续本文后续章节因为大部分实战内容都基于云端 API对本地资源要求不高。本地部署适合数据敏感或离线场景后面我会单独给出接入方案。3. 核心原理与封装设计3.1 OpenAI 兼容接口的调用原理DeepSeek 的 API 接口非常克制它没有另起炉灶而是直接兼容 OpenAI Chat Completions。这意味着你现在写的很多 AI 应用只要把base_url和api_key换掉就能切换到 DeepSeek。一个最简单的调用请求包含三部分model模型名称DeepSeek 目前常用deepseek-chat和deepseek-reasonermessages对话消息数组每条消息有role和contenttemperature等采样参数用于控制随机性下面是最小 Python 示例文件路径为quick_start.pyfrom openai import OpenAI client OpenAI( api_keysk-你的key, base_urlhttps://api.deepseek.com ) resp client.chat.completions.create( modeldeepseek-chat, messages[ {role: system, content: 你是一个乐于助人的助手。}, {role: user, content: 用一句话介绍 DeepSeek。} ], temperature0.7 ) print(resp.choices[0].message.content)运行后你应该会看到一段 DeepSeek 生成的文字。如果报错请检查 Key 是否正确、网络是否能访问api.deepseek.com、模型名称是否拼写准确。这里的system角色非常关键它用来设定助手的人格、回复风格和边界条件。在 Harness 封装中我们通常会单独管理 system 提示词而不是写死在调用处。3.2 Harness 封装的核心模块一个合格的 DeepSeek Harness 不应该只是简单调用 API它至少要包含以下几个模块3.2.1 配置管理模块配置管理的目的是把 API Key、模型名称、温度参数等外部变量和业务代码解耦。项目里我会统一读取.env文件并且支持用环境变量覆盖。这样部署到服务器时不用修改代码只需要在环境里设置变量。示例.env文件DEEPSEEK_API_KEYsk-你的key DEEPSEEK_BASE_URLhttps://api.deepseek.com DEEPSEEK_MODELdeepseek-chat DEEPSEEK_TEMPERATURE0.7 DEEPSEEK_MAX_TOKENS2000配置文件与代码分离后你可以在本地使用个人 Key在测试环境使用测试 Key在生产环境使用正式 Key。切记不要把.env文件提交到 Git 仓库。3.2.2 对话管理器对话管理器负责维护历史消息队列。我们知道大模型本身是无状态的每次请求都需要把完整的历史消息传上去它才能理解上下文。如果直接拼接用户消息很容易导致 token 超限或费用失控。我通常会定义一个Conversation类内部维护一个 Python 列表提供add_user_message、add_assistant_message、get_messages这几个方法。在每次请求前还要对历史做截断处理只保留最近 N 条消息。3.2.3 提示词模板管理在 Harness 模式中提示词是核心资产。写一个助手的时候不是把系统提示词直接写在代码里而是放到独立模板文件或字符串常量中。这样可以更轻松地做 A/B 测试、多语言适配。例如创建一个prompts.py文件SYSTEM_PROMPT 你是一个运行在本地电脑上的 AI 助手。 你可以帮助用户写代码、整理笔记、生成文案、回答问题。 请始终使用中文回复但代码变量名保持英文。 如果遇到无法确定的事实请如实说明。 这样后续我们可以为不同场景定义不同的 System Prompt比如CODE_ASSISTANT_PROMPT、WRITING_ASSISTANT_PROMPT等。3.2.4 工具调用与扩展大模型本身不能执行外部操作但我们可以通过函数调用机制让它决定要不要调用工具。OpenAI 兼容接口支持tools参数我们可以把本机的函数注册给模型。模型在需要时会返回一个tool_calls信息程序解码后执行本地函数再把结果回传给模型。不过为了控制文章篇幅下面我先把基础命令行助手做出来工具调用放到进阶篇。3.3 流式输出的原理与优势很多开发者第一次接入时明明请求成功了但界面一直转圈很久不出结果。这是因为没有使用流式输出。streamTrue时模型会逐字返回结果而不是等到全部生成完再返回。这样体验会好很多尤其适合长文本场景。流式原理是 SSEServer-Sent EventsOpenAI SDK 已经封装好了迭代器。使用起来并不复杂只需给create请求加上streamTrue然后遍历结果stream client.chat.completions.create( modeldeepseek-chat, messages[{role: user, content: 写一首描写冬天的短诗}], streamTrue ) for chunk in stream: if chunk.choices[0].delta.content is not None: print(chunk.choices[0].delta.content, end)流式输出也是 Harness 封装中非常值得做的一层优化。我在实际项目中会把流式输出和日志记录结合起来每次请求都记录 token 消耗、耗时、模型名称方便后续做成本分析。4. 完整实战从零搭建一个本地 AI 助手现在开始进入实操环节。这一章我们会完成一个可以反复使用的本地 AI 助手你将学会如何管理配置、维护多轮对话、实现流式输出以及最后用 FastAPI 把助手封装成一个 HTTP 服务。4.1 创建项目结构首先在项目根目录下创建以下文件和目录deepseek-harness-demo/ ├── .env ├── requirements.txt ├── assistant.py ├── conversation.py ├── prompts.py ├── app.py └── templates/ └── index.html其中assistant.py核心助手类负责调用 DeepSeek APIconversation.py对话历史管理prompts.py提示词模板app.pyFastAPI 服务提供 Web 入口templates/index.html极简前端页面4.2 编写环境配置和依赖文件先写requirements.txt固定版本区间避免未来升级导致不兼容openai1.0.0 python-dotenv1.0.0 rich13.0.0 fastapi0.110.0 uvicorn0.27.0 jinja23.1.0然后创建.envDEEPSEEK_API_KEYsk-你的key DEEPSEEK_BASE_URLhttps://api.deepseek.com DEEPSEEK_MODELdeepseek-chat DEEPSEEK_TEMPERATURE0.7 DEEPSEEK_MAX_TOKENS20004.3 实现对话管理类对话管理是 Harness 的核心之一。我把历史消息封装成一个类源码放在conversation.py# conversation.py from typing import List, Dict, Optional class Conversation: def __init__(self, max_history: int 20): max_history: 最多保留多少条历史消息超出后按先进先出丢弃。 self.messages: List[Dict[str, str]] [] self.max_history max_history def add_system_message(self, content: str) - None: self.messages.insert(0, {role: system, content: content}) def add_user_message(self, content: str) - None: self.messages.append({role: user, content: content}) self._trim() def add_assistant_message(self, content: str) - None: self.messages.append({role: assistant, content: content}) self._trim() def get_messages(self) - List[Dict[str, str]]: return self.messages def _trim(self) - None: 保留 system 消息同时限制历史长度。 system_msg [m for m in self.messages if m[role] system] other_msg [m for m in self.messages if m[role] ! system] if len(other_msg) self.max_history: other_msg other_msg[-self.max_history:] self.messages system_msg other_msg def clear(self) - None: 清空历史但保留 system 提示词。 self.messages [m for m in self.messages if m[role] system]这里需要注意_trim方法中的逻辑是先取出 system 消息再对非 system 消息做长度裁剪。这样即便用户聊了很多轮也不会因为消息太长导致 API 请求费用失控。4.4 编写提示词模板提示词放在prompts.py中后面对接不同场景时只需要修改这里# prompts.py SYSTEM_PROMPT 你是一个运行在本地电脑上的 AI 助手。 你可以帮助用户回答问题、写代码、整理信息、制作大纲。 请坚持使用中文回复除非用户明确要求使用其他语言。 回复内容要简洁、准确、不输出多余解释。 CODE_ASSISTANT_PROMPT 你是一名资深程序员。 当用户提出编程问题时请先解释思路再给出完整代码。 所有代码需要标注语言并说明如何运行。 如果问题不够清晰请主动确认需求。 在 Harness 设计里提示词不应与业务逻辑耦合。我见过很多项目把一大段 system prompt 直接写在调用 API 的代码里后续想调整人格和语气时每次都要在代码中查找替换非常痛苦。建议所有项目都用独立模板文件。4.5 实现核心助手类现在编写assistant.py这是整个 Harness 的核心。它需要完成读取环境变量创建 OpenAI Client接收用户输入维护会话调用 DeepSeek API支持流式输出返回结果并记忆历史代码如下# assistant.py import os from dotenv import load_dotenv from openai import OpenAI from conversation import Conversation from prompts import SYSTEM_PROMPT load_dotenv() class DeepSeekAssistant: def __init__(self, system_prompt: str SYSTEM_PROMPT): self.api_key os.getenv(DEEPSEEK_API_KEY) self.base_url os.getenv(DEEPSEEK_BASE_URL, https://api.deepseek.com) self.model os.getenv(DEEPSEEK_MODEL, deepseek-chat) self.temperature float(os.getenv(DEEPSEEK_TEMPERATURE, 0.7)) self.max_tokens int(os.getenv(DEEPSEEK_MAX_TOKENS, 2000)) if not self.api_key: raise ValueError(请在 .env 文件中配置 DEEPSEEK_API_KEY) self.client OpenAI(api_keyself.api_key, base_urlself.base_url) self.conversation Conversation() self.conversation.add_system_message(system_prompt) def chat(self, user_input: str) - str: 同步聊天返回完整回复。 self.conversation.add_user_message(user_input) try: resp self.client.chat.completions.create( modelself.model, messagesself.conversation.get_messages(), temperatureself.temperature, max_tokensself.max_tokens, ) reply resp.choices[0].message.content self.conversation.add_assistant_message(reply) return reply except Exception as e: # 出错时从对话历史里移除最近这条用户消息避免上下文污染 self.conversation.messages.pop() raise e def chat_stream(self, user_input: str) - str: 流式聊天逐字返回结果。 self.conversation.add_user_message(user_input) collected [] try: stream self.client.chat.completions.create( modelself.model, messagesself.conversation.get_messages(), temperatureself.temperature, max_tokensself.max_tokens, streamTrue, ) for chunk in stream: delta chunk.choices[0].delta.content if delta: collected.append(delta) yield delta full_reply .join(collected) self.conversation.add_assistant_message(full_reply) except Exception as e: self.conversation.messages.pop() raise e def reset(self) - None: 清空对话历史。 self.conversation.clear()这里有个细节值得强调在chat方法中如果 API 调用抛异常我会把最近一条用户消息从历史中移除。这样做的好处是用户下一次重试时上下文不会带上一条失败的消息模型不会产生“记忆错乱”。4.6 编写命令行交互入口为了快速测试助手类可以写一个简单的cli.py命令行入口。我们使用rich库让输出更清晰# cli.py from rich.console import Console from rich.markdown import Markdown from assistant import DeepSeekAssistant console Console() assistant DeepSeekAssistant() def main(): console.print([bold green]DeepSeek Harness 命令行助手已启动[/bold green]) console.print(输入内容后回车即可对话输入 /exit 退出输入 /clear 清空对话。\n) while True: try: user_input console.input([bold cyan]你 [/bold cyan]).strip() except KeyboardInterrupt: console.print(\n再见) break if not user_input: continue if user_input /exit: console.print(再见) break if user_input /clear: assistant.reset() console.print([yellow]对话已清空[/yellow]) continue console.print([bold magenta]助手 [/bold magenta]) with console.status(思考中...): try: reply_chunks [] for chunk in assistant.chat_stream(user_input): reply_chunks.append(chunk) console.print(chunk, end) console.print(\n) except Exception as e: console.print(f[bold red]请求失败: {e}[/bold red]) console.print(请检查 API Key、网络或模型名称。) if __name__ __main__: main()运行命令python cli.py预期效果控制台出现绿色提示输入“你好”后助手会逐字打印回复。输入“帮我用 Python 写一个读取 CSV 文件的函数”可以验证多轮上下文是否正常工作。4.7 用 FastAPI 封装成 Web 服务命令行助手适合个人使用但如果你想分享给团队或者集成到其他系统最好提供一个 HTTP 接口。下面用 FastAPI 实现一个极简 Web 服务。app.py内容如下# app.py from fastapi import FastAPI, Request, Form from fastapi.responses import HTMLResponse, StreamingResponse from fastapi.templating import Jinja2Templates from pydantic import BaseModel from assistant import DeepSeekAssistant app FastAPI() templates Jinja2Templates(directorytemplates) # 全局助手实例简单起见使用单例 assistant DeepSeekAssistant() class ChatRequest(BaseModel): message: str app.get(/, response_classHTMLResponse) async def index(request: Request): return templates.TemplateResponse(index.html, {request: request}) app.post(/api/chat) async def chat_api(request: ChatRequest): 非流式接口返回完整 JSON。 reply assistant.chat(request.message) return {reply: reply} app.post(/api/chat/stream) async def chat_stream_api(request: ChatRequest): 流式接口返回 SSE 格式。 async def event_generator(): for chunk in assistant.chat_stream(request.message): yield fdata: {chunk}\n\n return StreamingResponse(event_generator(), media_typetext/event-stream)这里需要注意FastAPI 的接口在每次请求时都使用的是同一个assistant实例因此多用户共享同一个会话历史这在生产环境中是不合理的。完整项目里应该使用会话 ID 区分不同用户或者干脆设计为无状态接口。本文是为了演示封装思路所以简单处理。4.8 编写前端页面接下来是templates/index.html一个极简聊天页面。它通过fetch调用后端的/api/chat接口把用户输入发送过去然后显示返回内容!DOCTYPE html html langzh-CN head meta charsetUTF-8 titleDeepSeek Harness/title style body { max-width: 700px; margin: 40px auto; font-family: Segoe UI, PingFang SC, Microsoft YaHei, sans-serif; background: #f5f7fa; color: #333; } .container { background: #fff; border-radius: 12px; padding: 24px; box-shadow: 0 2px 8px rgba(0,0,0,0.08); } #chat-box { height: 400px; overflow-y: auto; border: 1px solid #ddd; border-radius: 8px; padding: 12px; margin-bottom: 12px; background: #fafbfc; } .msg { margin-bottom: 12px; line-height: 1.6; } .user { text-align: right; color: #1a73e8; } .bot { text-align: left; color: #333; } input { width: 100%; padding: 10px; border: 1px solid #ccc; border-radius: 8px; font-size: 14px; box-sizing: border-box; } /style /head body div classcontainer h2DeepSeek Harness 本地助手/h2 div idchat-box/div input typetext idmessage placeholder输入你的问题回车发送 / /div script const chatBox document.getElementById(chat-box); const input document.getElementById(message); function addMessage(role, content) { const div document.createElement(div); div.className msg role; div.innerText content; chatBox.appendChild(div); chatBox.scrollTop chatBox.scrollHeight; } async function send() { const text input.value.trim(); if (!text) return; input.value ; addMessage(user, text); const response await fetch(/api/chat, { method: POST, headers: {Content-Type: application/json}, body: JSON.stringify({ message: text }) }); const data await response.json(); addMessage(bot, data.reply); } input.addEventListener(keydown, function (e) { if (e.key Enter) { send(); } }); /script /body /html启动服务uvicorn app:app --host 0.0.0.0 --port 8000浏览器访问http://localhost:8000即可看到聊天界面。这是最基础的 Web Harness 形态。后续你可以把前端换成 Vue 或 React也可以接入流式接口实现打字机效果。4.9 用 Ollama 本地部署 DeepSeek 小模型云端 API 响应快、效果好但总有些场景需要离线运行或数据不出内网。下面用 Ollama 做本地部署。Ollama 是一个很流行的本地模型运行工具支持多种开源模型包括 DeepSeek 系列。安装 Ollama 后在终端执行ollama pull deepseek-r1:7b ollama run deepseek-r1:7b成功后在本地打开对话窗口。如果你想通过代码调用本地 Ollama可以使用 OpenAI 兼容接口因为 Ollama 自带了/v1/chat/completions路由from openai import OpenAI client OpenAI( api_keyollama, # Ollama 不校验 Key但需要占位 base_urlhttp://localhost:11434/v1 ) resp client.chat.completions.create( modeldeepseek-r1:7b, messages[{role: user, content: 你好}] ) print(resp.choices[0].message.content)注意本地部署的模型效果、响应速度和上下文窗口都和云端 API 不完全一样。如果电脑配置一般建议先试 1.5B 或 7B 模型别一上来就拉 70B。在我的测试中7B 模型在 16GB 内存的 M 系列 Mac 上可以流畅运行但生成速度依然比云端慢不少。因此本地模型更适合“隐私优先”的任务比如文档摘要、代码片段生成。4.10 在 Cursor / Codex 等工具中接入 DeepSeek热搜词里有很多人在搜“Codex 接入 DeepSeek”和“Cursor AI 编程”说明这类需求非常旺盛。实现思路其实很统一这类工具基本都支持自定义 OpenAI 兼容的 API Base URL。以 Cursor 为例在设置中找到 Model API 配置API Key填写你的 DeepSeek API KeyBase URL填写https://api.deepseek.comModel 名称填写deepseek-chat或deepseek-reasoner具体菜单可能随版本变化但核心配置项不会变。需要注意Cursor 等工具对模型返回格式有强校验如果配置不正确通常会在请求日志里给出提示。建议先在代码里用 curl 测试接口无误后再配置到工具中。Codex 其实也可以利用 OpenAI 兼容接口进行自定义设置但不同版本的 Codex 界面差异较大。如果界面里没有“自定义 Base URL”入口也可以用环境变量的方式注入export OPENAI_API_KEY你的DeepSeekKey export OPENAI_BASE_URLhttps://api.deepseek.com然后启动 Codex。这样 Codex 就会把请求发到 DeepSeek 的接口。这种用法非常灵活也让人感叹 OpenAI 生态的标准性。需要提醒的是无论 Cursor 还是 Codex接入第三方模型后部分官方专属功能可能不生效比如某些内置工具链或插件。如果你在编程过程中发现某个功能无法使用不要硬抗可以切回官方模型或者只把 DeepSeek 作为后备模型使用。5. 常见问题与排查思路在实际使用 DeepSeek Harness 的过程中几乎每个人都会遇到几个固定问题。我整理了最常被问到的五类问题按频率排序。问题现象可能原因解决思路请求返回 401 错误API Key 不正确检查.env中 Key 是否完整是否包含空格请求返回 404 错误Base URL 写错确认使用https://api.deepseek.com而不是/v1后缀响应速度很慢网络问题或模型繁忙检查网络改用流式输出非高峰时段重试本地 Ollama 模型无法加载显存不足或模型名称错误换小模型关闭其他程序检查ollama list多轮对话上下文超过限制历史消息太长使用对话管理类裁剪历史调低max_history一段时间后出现限流超过每分钟请求数限制加指数退避重试去开放平台查看配额下面选择几个高频问题单独展开。5.1 401 Authentication Fails这个错误最常见的场景是你把 Key 复制到了代码里但 Key 后面多了一个换行或空格。用python-dotenv读取时空格可能会被保留导致 Authentication 失败。排查步骤在代码中打印len(api_key)确认长度是否符合预期。使用.strip()清理空格。用 curl 验证 Key 是否有效。正确做法是在.env里写成DEEPSEEK_API_KEYsk-你的key不要加引号不要加空格。5.2 请求返回 404 错误很多同学用惯了 OpenAI会把base_url写成https://api.deepseek.com/v1结果发现 404。DeepSeek 的 Base URL 是https://api.deepseek.com但它的接口路径是/chat/completions完整地址是https://api.deepseek.com/chat/completions。由于 OpenAI SDK 会在base_url后自动拼上/chat/completions所以我们只需要设置成https://api.deepseek.com。另外如果你用 HTTP 客户端直接请求注意区分# 正确 https://api.deepseek.com/chat/completions # 错误 https://api.deepseek.com/v1/chat/completions5.3 上下文太长导致超限或费用高DeepSeek 的上下文长度有限具体长度以官方文档为准如果多轮对话过多token 超限后请求会失败。解决方案是引入对话管理。前面conversation.py的max_history参数就是干这个用的。你还可以根据resp.usage获取每次请求的 token 数在日志里记录并做监控usage resp.usage print(f消耗 prompt_tokens{usage.prompt_tokens}, completion_tokens{usage.completion_tokens})合理的设计是当累计 token 超过某个阈值时要么丢弃最早的消息要么用摘要模型压缩历史。这属于 Harness 的高级功能第一版可以先裁剪历史。5.4 本地模型速度太慢如果你在本地部署模型后觉得速度慢先检查任务难度。7B 模型生成一千字可能需要一两分钟这是正常现象。如果觉得不可接受可以换更小的量化模型关闭浏览器后台大量标签页增加内存或显存使用云端 API 作为主路径本地模型仅用于离线场景如果你在服务器上部署可以考虑通过llama.cpp或vLLM这类推理框架优化性能但配置复杂度会高不少不适合新手第一版。6. 最佳实践与工程建议6.1 密钥与配置管理API Key 是敏感信息绝不能提交到 Git。我建议在项目根目录创建.gitignore并加入.env.env venv/ __pycache__/在团队协作时提供一份.env.example文件里面只写变量名不写真实 KeyDEEPSEEK_API_KEYsk-在这里填写你的key DEEPSEEK_BASE_URLhttps://api.deepseek.com DEEPSEEK_MODELdeepseek-chat DEEPSEEK_TEMPERATURE0.7 DEEPSEEK_MAX_TOKENS2000每个开发者复制.env.example为.env后填写自己的 Key。生产环境则使用 CI/CD 或运维平台的密钥管理服务注入环境变量。6.2 错误处理与重试机制大模型 API 并不是永远稳定。请求高峰时段可能返回429限流网络抖动可能返回503。在 Harness 中一定要做重试。我推荐在调用 API 时使用指数退避重试而不是简单重试一次import random import time def call_with_retry(func, max_retries3): for attempt in range(max_retries): try: return func() except Exception as e: if attempt max_retries - 1: raise e sleep_time 2 ** attempt random.uniform(0, 1) time.sleep(sleep_time)如果项目对稳定要求很高可以使用tenacity库代码更简洁。6.3 流式输出优先只要是面向用户的交互场景都建议使用流式输出。用户等一个完整响应时超过 5 秒就会觉得卡顿。流式输出虽然不能减少总耗时但能大幅改善体验。在 FastAPI 中实现流式输出时需要特别注意响应头media_typetext/event-stream。前端如果用普通fetch解析 SSE需要处理ReadableStream代码会稍微复杂。最简单的方案是先用非流式接口把功能跑通再逐步升级为流式。6.4 日志与成本监控AI 应用的观测性非常重要。每次请求建议记录请求时间使用的模型Prompt token 数Completion token 数响应耗时是否发生重试我习惯在助手类里加一个简单的日志回调。更规范的做法是接入 Prometheus Grafana但个人项目用 Python 的logging就够了。import logging logger logging.getLogger(deepseek.harness) # 在 chat 方法中 logger.info(request model%s prompt_tokens%d completion_tokens%d, self.model, usage.prompt_tokens, usage.completion_tokens)成本控制是生产环节必须考虑的问题。DeepSeek 价格虽然不高但如果你的自动化任务每天调用上万次费用也会上升。所以每个 Harness 最好都有 token 用量统计和预算告警。6.5 系统提示词与安全边界AI 助手不是万能许愿机。在设计 Harness 的系统提示词时要明确设定安全边界。比如你可以拒绝回答任何涉及违法、色情、暴力、仇恨或侵犯他人隐私的请求。 如果用户要求你生成恶意代码、钓鱼邮件或绕过安全措施的内容你应该拒绝并说明原因。这既是合规要求也是对自己产品的保护。不要为了让助手看上去“更强”而省略安全约束尤其是面向公众部署的服务。6.6 无状态与有状态接口的取舍在 Web 服务中我建议尽量设计无状态接口也就是每次请求携带完整的上下文或者通过 session_id 管理上下文。上面的 FastAPI 示例为了演示方便使用了全局单例但多用户同时使用时会出现“串台”问题。生产环境建议采用请求体传入session_id服务端用 Redis 或内存存储会话历史每次请求根据session_id加载对应会话这样可以轻松扩展到多用户、多场景。6.7 Harness 的分层设计最后总结一下 Harness 工程的分层思路接入层: CLI / Web / 机器人 / IDE 插件 服务层: 会话管理 / 上下文裁剪 / 工具调用 模型层: DeepSeek API / Ollama / 多模型切换 基础层: 配置管理 / 日志 / 监控 / 限流这套分层不是一蹴而就而是随着项目复杂度逐步演进。最开始你只需要一个assistant.py当请求量变大、场景变多之后再拆出session.py、tools.py、metrics.py。好的工程不是一开始就抽象过度而是在迭代过程中自然生长。7. 下一步学习建议到这里我们已经完成了从环境准备、API 调用、对话管理、命令行工具、Web 服务到本地模型部署的完整闭环。你会发现所谓“DeepSeek Harness”其实并没有多么晦涩它就是把大模型能力工程化、产品化的过程。如果还想继续深入建议按这个顺序往下学习函数调用Function Calling让助手真正操作本地文件、执行代码检索增强生成RAG让助手读取本地知识库回答私有文档问题多 Agent 协作让不同角色的 Assistant 互相调用完成复杂任务流式接口的前端优化把打字机效果做到极致多模型路由在 DeepSeek 与本地模型之间自动切换。你现在可以打开终端运行一条python cli.py然后开始和你的电脑助手对话。相信我当它第一次准确回答出你在前面几轮提过的需求时你会觉得这一套折腾非常值得。后面遇到具体报错欢迎在评论区带上错误信息和上下文我们一起排查。 DeepSeek Harness 实战：从 API 到本地 AI 助手的完整搭建指南
各位读者朋友大家好。近期在项目里尝试把 DeepSeek 接入到本地工具链时我发现网上关于“DeepSeek Harness”的资料非常零散很多教程停留在“申请 API Key 后跑一次聊天请求”的层面真正能落地的操作步骤、参数调整、异常定位内容少之又少。这篇文章我会从实际工程角度出发把 DeepSeek 从云端 API 到本地开发工具、再到简易 AI 助手的完整链路拆开讲一遍。无论你是刚接触大模型开发的新手还是已经在用 Cursor、Codex 这类 AI 编程工具的开发者都可以按文中的流程搭建一套属于自己的电脑助手并在生产环境里避开常见的坑。需要提前说明的是本文讨论的是把 DeepSeek 作为 AI 能力底座来构建工具所有操作都要在合规前提下进行。文中的代码示例以 OpenAI SDK 兼容接口为主因为 DeepSeek 对外提供的接口严格遵循 OpenAI Chat Completions 规范这样可以复用大量现有生态。同时我也会介绍“Harness”这种封装思路它并不是某个神秘框架的专属名词而是一种工程模式把大模型、提示词、工具调用、记忆管理统一封装成可编程的助手层。搞懂这个模式后面接任何模型都会轻松很多。1. 背景与核心概念1.1 什么是 DeepSeek Harness在正式开始之前先聊清楚“Harness”这个词。Harness 本意是“马具、挽具”在软件工程里常被翻译成“装配”、“封装”或“测试夹具”。比如测试领域有 Test Harness用来把被测模块和外部依赖组合起来统一执行用例。放到 AI 应用场景中DeepSeek Harness 可以理解为一套围绕 DeepSeek 模型打造的“工具装配层”它把模型接口、上下文管理、工具调用、日志、异常处理全部串起来最终对外暴露一个更易用的助手能力。很多开发者第一次听到“DeepSeek Harness”会误以为它必须是一个独立的开源软件需要下载安装某个固定程序。其实不是社区里确实存在一些叫“Harness”的项目或插件但更常见的是我们自己用代码搭建的一层工程封装。你可以用 Python 写一个命令行助手也可以用 FastAPI 包装成 HTTP 服务还可以接入 Cursor、Codex 之类的 AI 编程工具。核心目的都一样让 DeepSeek 不再只是网页里的对话机器人而是能本地调用、能处理文件、能执行工具、能被其他程序集成的“电脑助手”。换句话说这篇文章讲的“DeepSeek Harness”是一套实操方法而不是让你去装某个神仙软件。理解了这一点你就不会在安装环节迷失方向。1.2 为什么需要把 DeepSeek 变成电脑助手现在 DeepSeek 的官网聊天界面已经足够好用那为什么还要自己封装一个助手主要原因有三点第一数据流可控。网页聊天时对话记录往往保存在服务端虽然官方有隐私政策但企业项目里很多内部数据不能直接粘贴到网页对话框。通过 API 接入后我们可以把提示词、上下文、敏感信息全部保存在本地服务中按需发送。第二自动化能力。网页聊天只能人工输入而封装成 Harness 后它就能被脚本调度、被定时任务触发、被其他系统调用。比如我当前项目的需求是每天晚上读取数据库中的日志让 DeepSeek 自动生成异常摘要再推送到钉钉群。这种需求网页版根本做不了必须走 API 封装。第三工具调用与多模型切换。借助 OpenAI 兼容接口我们可以把 DeepSeek 和本地模型、其他商业模型放在同一套工程框架中。当某个模型不可用时自动切换不用改动调用方代码。这正是 Harness 模式的工程价值。1.3 常见应用场景我梳理了几个比较典型的“DeepSeek Harness”落地场景方便你快速判断自己的需求属于哪一类场景说明推荐方案个人命令行助手在终端里快速提问支持上下文记忆Python Rich本地知识库问答读取本地 Markdown/文本文件自动检索并回答向量库 DeepSeek API办公自动化根据模板生成邮件、周报、PPT 大纲FastAPI 定时任务AI 编程助手在 Cursor/Codex 中接入 DeepSeekOpenAI 兼容接口配置团队内部机器人接入钉钉、飞书、企业微信机器人回调 HTTP 服务本地离线部署完全离线环境数据不出内网Ollama 本地模型本文会重点覆盖“个人命令行助手”和“AI 编程工具接入”两条线因为它们最容易上手也最能体现 Harness 的封装价值。2. 环境准备与版本说明2.1 本机环境要求我以 Windows 11 作为演示系统但你完全可以在 macOS 或 Linux 上操作原理一致。Python 建议使用 3.10 或以上版本因为一些类型注解和异步语法在 3.10 之后更友好。Node.js 不是必需但如果后续要接入前端或某些桌面插件建议安装 18 以上的 LTS 版本。需要说明的是当前 DeepSeek API 和周边生态更新很快本文的版本组合如下并非唯一选择你可以根据实际情况调整操作系统: Windows 11 / macOS 14 / Ubuntu 22.04 Python: 3.10 - 3.12 OpenAI SDK: 1.0 dotenv: 1.0 左右 FastAPI: 0.115 左右如果你在安装依赖时发现版本冲突优先保证 openai 库是最新版因为 DeepSeek 接口紧随 OpenAI 的规范演进。2.2 申请 DeepSeek API Key既然要打造电脑助手首先需要能调用 DeepSeek 大模型。打开 DeepSeek 开放平台注册账号后进入 API Keys 页面创建一个新的 Key。创建后请立即复制保存因为平台不会再次展示完整 Key。登录 DeepSeek 开放平台进入“API Keys”菜单点击“创建 API Key”输入名称比如local-assistant创建后复制保存在正式环境中API Key 一定不要硬编码在代码里我会在后面的配置管理中专门说明。现在你只需要在项目根目录创建一个.env文件把 Key 放进去DEEPSEEK_API_KEYsk-你的真实key在开始写代码之前可以先验证一下 Key 是否有效。用 curl 或者 Postman 发一个最简单的 Chat 请求curl https://api.deepseek.com/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $DEEPSEEK_API_KEY \ -d { model: deepseek-chat, messages: [{role: user, content: 你好}] }如果返回内容包含choices数组说明 Key 和网络都没问题。这里需要特别注意DeepSeek API 的 Base URL 是https://api.deepseek.com而不是常见的https://api.openai.com。这也是很多初学同学第一次接入时最容易写错的地方。2.3 安装 Python 依赖我习惯用虚拟环境来隔离项目依赖尤其是在做 AI 工程时不同项目可能依赖不同版本的 openai 库。新建项目目录后执行mkdir deepseek-harness-demo cd deepseek-harness-demo python -m venv venv # Windows venv\Scripts\activate # macOS / Linux source venv/bin/activate然后安装接下来会用到的依赖pip install openai python-dotenv rich fastapi uvicornopenai官方 SDKDeepSeek 兼容其调用方式python-dotenv读取.env文件中的环境变量rich让命令行输出更美观fastapiuvicorn用于构建 Web API装完后可以用pip list查看版本如果发现 openai 版本过低建议升级。2.4 本地部署的硬件说明如果你不想走云端 API而是希望在本地部署 DeepSeek 模型那么需要一台配置合适的机器。虽然 DeepSeek 官方提供了不同大小的模型但完整版大模型的参数量很大不是普通笔记本能跑的。我建议个人开发者优先使用 Ollama 这类工具运行量化后的小模型比如deepseek-r1:7b或deepseek-r1:14b。最低配置参考CPU8 核以上内存16GB 以上显存8GB 以上推荐 16GB磁盘SSD预留 20GB 以上如果你的机器达不到要求仍然可以继续本文后续章节因为大部分实战内容都基于云端 API对本地资源要求不高。本地部署适合数据敏感或离线场景后面我会单独给出接入方案。3. 核心原理与封装设计3.1 OpenAI 兼容接口的调用原理DeepSeek 的 API 接口非常克制它没有另起炉灶而是直接兼容 OpenAI Chat Completions。这意味着你现在写的很多 AI 应用只要把base_url和api_key换掉就能切换到 DeepSeek。一个最简单的调用请求包含三部分model模型名称DeepSeek 目前常用deepseek-chat和deepseek-reasonermessages对话消息数组每条消息有role和contenttemperature等采样参数用于控制随机性下面是最小 Python 示例文件路径为quick_start.pyfrom openai import OpenAI client OpenAI( api_keysk-你的key, base_urlhttps://api.deepseek.com ) resp client.chat.completions.create( modeldeepseek-chat, messages[ {role: system, content: 你是一个乐于助人的助手。}, {role: user, content: 用一句话介绍 DeepSeek。} ], temperature0.7 ) print(resp.choices[0].message.content)运行后你应该会看到一段 DeepSeek 生成的文字。如果报错请检查 Key 是否正确、网络是否能访问api.deepseek.com、模型名称是否拼写准确。这里的system角色非常关键它用来设定助手的人格、回复风格和边界条件。在 Harness 封装中我们通常会单独管理 system 提示词而不是写死在调用处。3.2 Harness 封装的核心模块一个合格的 DeepSeek Harness 不应该只是简单调用 API它至少要包含以下几个模块3.2.1 配置管理模块配置管理的目的是把 API Key、模型名称、温度参数等外部变量和业务代码解耦。项目里我会统一读取.env文件并且支持用环境变量覆盖。这样部署到服务器时不用修改代码只需要在环境里设置变量。示例.env文件DEEPSEEK_API_KEYsk-你的key DEEPSEEK_BASE_URLhttps://api.deepseek.com DEEPSEEK_MODELdeepseek-chat DEEPSEEK_TEMPERATURE0.7 DEEPSEEK_MAX_TOKENS2000配置文件与代码分离后你可以在本地使用个人 Key在测试环境使用测试 Key在生产环境使用正式 Key。切记不要把.env文件提交到 Git 仓库。3.2.2 对话管理器对话管理器负责维护历史消息队列。我们知道大模型本身是无状态的每次请求都需要把完整的历史消息传上去它才能理解上下文。如果直接拼接用户消息很容易导致 token 超限或费用失控。我通常会定义一个Conversation类内部维护一个 Python 列表提供add_user_message、add_assistant_message、get_messages这几个方法。在每次请求前还要对历史做截断处理只保留最近 N 条消息。3.2.3 提示词模板管理在 Harness 模式中提示词是核心资产。写一个助手的时候不是把系统提示词直接写在代码里而是放到独立模板文件或字符串常量中。这样可以更轻松地做 A/B 测试、多语言适配。例如创建一个prompts.py文件SYSTEM_PROMPT 你是一个运行在本地电脑上的 AI 助手。 你可以帮助用户写代码、整理笔记、生成文案、回答问题。 请始终使用中文回复但代码变量名保持英文。 如果遇到无法确定的事实请如实说明。 这样后续我们可以为不同场景定义不同的 System Prompt比如CODE_ASSISTANT_PROMPT、WRITING_ASSISTANT_PROMPT等。3.2.4 工具调用与扩展大模型本身不能执行外部操作但我们可以通过函数调用机制让它决定要不要调用工具。OpenAI 兼容接口支持tools参数我们可以把本机的函数注册给模型。模型在需要时会返回一个tool_calls信息程序解码后执行本地函数再把结果回传给模型。不过为了控制文章篇幅下面我先把基础命令行助手做出来工具调用放到进阶篇。3.3 流式输出的原理与优势很多开发者第一次接入时明明请求成功了但界面一直转圈很久不出结果。这是因为没有使用流式输出。streamTrue时模型会逐字返回结果而不是等到全部生成完再返回。这样体验会好很多尤其适合长文本场景。流式原理是 SSEServer-Sent EventsOpenAI SDK 已经封装好了迭代器。使用起来并不复杂只需给create请求加上streamTrue然后遍历结果stream client.chat.completions.create( modeldeepseek-chat, messages[{role: user, content: 写一首描写冬天的短诗}], streamTrue ) for chunk in stream: if chunk.choices[0].delta.content is not None: print(chunk.choices[0].delta.content, end)流式输出也是 Harness 封装中非常值得做的一层优化。我在实际项目中会把流式输出和日志记录结合起来每次请求都记录 token 消耗、耗时、模型名称方便后续做成本分析。4. 完整实战从零搭建一个本地 AI 助手现在开始进入实操环节。这一章我们会完成一个可以反复使用的本地 AI 助手你将学会如何管理配置、维护多轮对话、实现流式输出以及最后用 FastAPI 把助手封装成一个 HTTP 服务。4.1 创建项目结构首先在项目根目录下创建以下文件和目录deepseek-harness-demo/ ├── .env ├── requirements.txt ├── assistant.py ├── conversation.py ├── prompts.py ├── app.py └── templates/ └── index.html其中assistant.py核心助手类负责调用 DeepSeek APIconversation.py对话历史管理prompts.py提示词模板app.pyFastAPI 服务提供 Web 入口templates/index.html极简前端页面4.2 编写环境配置和依赖文件先写requirements.txt固定版本区间避免未来升级导致不兼容openai1.0.0 python-dotenv1.0.0 rich13.0.0 fastapi0.110.0 uvicorn0.27.0 jinja23.1.0然后创建.envDEEPSEEK_API_KEYsk-你的key DEEPSEEK_BASE_URLhttps://api.deepseek.com DEEPSEEK_MODELdeepseek-chat DEEPSEEK_TEMPERATURE0.7 DEEPSEEK_MAX_TOKENS20004.3 实现对话管理类对话管理是 Harness 的核心之一。我把历史消息封装成一个类源码放在conversation.py# conversation.py from typing import List, Dict, Optional class Conversation: def __init__(self, max_history: int 20): max_history: 最多保留多少条历史消息超出后按先进先出丢弃。 self.messages: List[Dict[str, str]] [] self.max_history max_history def add_system_message(self, content: str) - None: self.messages.insert(0, {role: system, content: content}) def add_user_message(self, content: str) - None: self.messages.append({role: user, content: content}) self._trim() def add_assistant_message(self, content: str) - None: self.messages.append({role: assistant, content: content}) self._trim() def get_messages(self) - List[Dict[str, str]]: return self.messages def _trim(self) - None: 保留 system 消息同时限制历史长度。 system_msg [m for m in self.messages if m[role] system] other_msg [m for m in self.messages if m[role] ! system] if len(other_msg) self.max_history: other_msg other_msg[-self.max_history:] self.messages system_msg other_msg def clear(self) - None: 清空历史但保留 system 提示词。 self.messages [m for m in self.messages if m[role] system]这里需要注意_trim方法中的逻辑是先取出 system 消息再对非 system 消息做长度裁剪。这样即便用户聊了很多轮也不会因为消息太长导致 API 请求费用失控。4.4 编写提示词模板提示词放在prompts.py中后面对接不同场景时只需要修改这里# prompts.py SYSTEM_PROMPT 你是一个运行在本地电脑上的 AI 助手。 你可以帮助用户回答问题、写代码、整理信息、制作大纲。 请坚持使用中文回复除非用户明确要求使用其他语言。 回复内容要简洁、准确、不输出多余解释。 CODE_ASSISTANT_PROMPT 你是一名资深程序员。 当用户提出编程问题时请先解释思路再给出完整代码。 所有代码需要标注语言并说明如何运行。 如果问题不够清晰请主动确认需求。 在 Harness 设计里提示词不应与业务逻辑耦合。我见过很多项目把一大段 system prompt 直接写在调用 API 的代码里后续想调整人格和语气时每次都要在代码中查找替换非常痛苦。建议所有项目都用独立模板文件。4.5 实现核心助手类现在编写assistant.py这是整个 Harness 的核心。它需要完成读取环境变量创建 OpenAI Client接收用户输入维护会话调用 DeepSeek API支持流式输出返回结果并记忆历史代码如下# assistant.py import os from dotenv import load_dotenv from openai import OpenAI from conversation import Conversation from prompts import SYSTEM_PROMPT load_dotenv() class DeepSeekAssistant: def __init__(self, system_prompt: str SYSTEM_PROMPT): self.api_key os.getenv(DEEPSEEK_API_KEY) self.base_url os.getenv(DEEPSEEK_BASE_URL, https://api.deepseek.com) self.model os.getenv(DEEPSEEK_MODEL, deepseek-chat) self.temperature float(os.getenv(DEEPSEEK_TEMPERATURE, 0.7)) self.max_tokens int(os.getenv(DEEPSEEK_MAX_TOKENS, 2000)) if not self.api_key: raise ValueError(请在 .env 文件中配置 DEEPSEEK_API_KEY) self.client OpenAI(api_keyself.api_key, base_urlself.base_url) self.conversation Conversation() self.conversation.add_system_message(system_prompt) def chat(self, user_input: str) - str: 同步聊天返回完整回复。 self.conversation.add_user_message(user_input) try: resp self.client.chat.completions.create( modelself.model, messagesself.conversation.get_messages(), temperatureself.temperature, max_tokensself.max_tokens, ) reply resp.choices[0].message.content self.conversation.add_assistant_message(reply) return reply except Exception as e: # 出错时从对话历史里移除最近这条用户消息避免上下文污染 self.conversation.messages.pop() raise e def chat_stream(self, user_input: str) - str: 流式聊天逐字返回结果。 self.conversation.add_user_message(user_input) collected [] try: stream self.client.chat.completions.create( modelself.model, messagesself.conversation.get_messages(), temperatureself.temperature, max_tokensself.max_tokens, streamTrue, ) for chunk in stream: delta chunk.choices[0].delta.content if delta: collected.append(delta) yield delta full_reply .join(collected) self.conversation.add_assistant_message(full_reply) except Exception as e: self.conversation.messages.pop() raise e def reset(self) - None: 清空对话历史。 self.conversation.clear()这里有个细节值得强调在chat方法中如果 API 调用抛异常我会把最近一条用户消息从历史中移除。这样做的好处是用户下一次重试时上下文不会带上一条失败的消息模型不会产生“记忆错乱”。4.6 编写命令行交互入口为了快速测试助手类可以写一个简单的cli.py命令行入口。我们使用rich库让输出更清晰# cli.py from rich.console import Console from rich.markdown import Markdown from assistant import DeepSeekAssistant console Console() assistant DeepSeekAssistant() def main(): console.print([bold green]DeepSeek Harness 命令行助手已启动[/bold green]) console.print(输入内容后回车即可对话输入 /exit 退出输入 /clear 清空对话。\n) while True: try: user_input console.input([bold cyan]你 [/bold cyan]).strip() except KeyboardInterrupt: console.print(\n再见) break if not user_input: continue if user_input /exit: console.print(再见) break if user_input /clear: assistant.reset() console.print([yellow]对话已清空[/yellow]) continue console.print([bold magenta]助手 [/bold magenta]) with console.status(思考中...): try: reply_chunks [] for chunk in assistant.chat_stream(user_input): reply_chunks.append(chunk) console.print(chunk, end) console.print(\n) except Exception as e: console.print(f[bold red]请求失败: {e}[/bold red]) console.print(请检查 API Key、网络或模型名称。) if __name__ __main__: main()运行命令python cli.py预期效果控制台出现绿色提示输入“你好”后助手会逐字打印回复。输入“帮我用 Python 写一个读取 CSV 文件的函数”可以验证多轮上下文是否正常工作。4.7 用 FastAPI 封装成 Web 服务命令行助手适合个人使用但如果你想分享给团队或者集成到其他系统最好提供一个 HTTP 接口。下面用 FastAPI 实现一个极简 Web 服务。app.py内容如下# app.py from fastapi import FastAPI, Request, Form from fastapi.responses import HTMLResponse, StreamingResponse from fastapi.templating import Jinja2Templates from pydantic import BaseModel from assistant import DeepSeekAssistant app FastAPI() templates Jinja2Templates(directorytemplates) # 全局助手实例简单起见使用单例 assistant DeepSeekAssistant() class ChatRequest(BaseModel): message: str app.get(/, response_classHTMLResponse) async def index(request: Request): return templates.TemplateResponse(index.html, {request: request}) app.post(/api/chat) async def chat_api(request: ChatRequest): 非流式接口返回完整 JSON。 reply assistant.chat(request.message) return {reply: reply} app.post(/api/chat/stream) async def chat_stream_api(request: ChatRequest): 流式接口返回 SSE 格式。 async def event_generator(): for chunk in assistant.chat_stream(request.message): yield fdata: {chunk}\n\n return StreamingResponse(event_generator(), media_typetext/event-stream)这里需要注意FastAPI 的接口在每次请求时都使用的是同一个assistant实例因此多用户共享同一个会话历史这在生产环境中是不合理的。完整项目里应该使用会话 ID 区分不同用户或者干脆设计为无状态接口。本文是为了演示封装思路所以简单处理。4.8 编写前端页面接下来是templates/index.html一个极简聊天页面。它通过fetch调用后端的/api/chat接口把用户输入发送过去然后显示返回内容!DOCTYPE html html langzh-CN head meta charsetUTF-8 titleDeepSeek Harness/title style body { max-width: 700px; margin: 40px auto; font-family: Segoe UI, PingFang SC, Microsoft YaHei, sans-serif; background: #f5f7fa; color: #333; } .container { background: #fff; border-radius: 12px; padding: 24px; box-shadow: 0 2px 8px rgba(0,0,0,0.08); } #chat-box { height: 400px; overflow-y: auto; border: 1px solid #ddd; border-radius: 8px; padding: 12px; margin-bottom: 12px; background: #fafbfc; } .msg { margin-bottom: 12px; line-height: 1.6; } .user { text-align: right; color: #1a73e8; } .bot { text-align: left; color: #333; } input { width: 100%; padding: 10px; border: 1px solid #ccc; border-radius: 8px; font-size: 14px; box-sizing: border-box; } /style /head body div classcontainer h2DeepSeek Harness 本地助手/h2 div idchat-box/div input typetext idmessage placeholder输入你的问题回车发送 / /div script const chatBox document.getElementById(chat-box); const input document.getElementById(message); function addMessage(role, content) { const div document.createElement(div); div.className msg role; div.innerText content; chatBox.appendChild(div); chatBox.scrollTop chatBox.scrollHeight; } async function send() { const text input.value.trim(); if (!text) return; input.value ; addMessage(user, text); const response await fetch(/api/chat, { method: POST, headers: {Content-Type: application/json}, body: JSON.stringify({ message: text }) }); const data await response.json(); addMessage(bot, data.reply); } input.addEventListener(keydown, function (e) { if (e.key Enter) { send(); } }); /script /body /html启动服务uvicorn app:app --host 0.0.0.0 --port 8000浏览器访问http://localhost:8000即可看到聊天界面。这是最基础的 Web Harness 形态。后续你可以把前端换成 Vue 或 React也可以接入流式接口实现打字机效果。4.9 用 Ollama 本地部署 DeepSeek 小模型云端 API 响应快、效果好但总有些场景需要离线运行或数据不出内网。下面用 Ollama 做本地部署。Ollama 是一个很流行的本地模型运行工具支持多种开源模型包括 DeepSeek 系列。安装 Ollama 后在终端执行ollama pull deepseek-r1:7b ollama run deepseek-r1:7b成功后在本地打开对话窗口。如果你想通过代码调用本地 Ollama可以使用 OpenAI 兼容接口因为 Ollama 自带了/v1/chat/completions路由from openai import OpenAI client OpenAI( api_keyollama, # Ollama 不校验 Key但需要占位 base_urlhttp://localhost:11434/v1 ) resp client.chat.completions.create( modeldeepseek-r1:7b, messages[{role: user, content: 你好}] ) print(resp.choices[0].message.content)注意本地部署的模型效果、响应速度和上下文窗口都和云端 API 不完全一样。如果电脑配置一般建议先试 1.5B 或 7B 模型别一上来就拉 70B。在我的测试中7B 模型在 16GB 内存的 M 系列 Mac 上可以流畅运行但生成速度依然比云端慢不少。因此本地模型更适合“隐私优先”的任务比如文档摘要、代码片段生成。4.10 在 Cursor / Codex 等工具中接入 DeepSeek热搜词里有很多人在搜“Codex 接入 DeepSeek”和“Cursor AI 编程”说明这类需求非常旺盛。实现思路其实很统一这类工具基本都支持自定义 OpenAI 兼容的 API Base URL。以 Cursor 为例在设置中找到 Model API 配置API Key填写你的 DeepSeek API KeyBase URL填写https://api.deepseek.comModel 名称填写deepseek-chat或deepseek-reasoner具体菜单可能随版本变化但核心配置项不会变。需要注意Cursor 等工具对模型返回格式有强校验如果配置不正确通常会在请求日志里给出提示。建议先在代码里用 curl 测试接口无误后再配置到工具中。Codex 其实也可以利用 OpenAI 兼容接口进行自定义设置但不同版本的 Codex 界面差异较大。如果界面里没有“自定义 Base URL”入口也可以用环境变量的方式注入export OPENAI_API_KEY你的DeepSeekKey export OPENAI_BASE_URLhttps://api.deepseek.com然后启动 Codex。这样 Codex 就会把请求发到 DeepSeek 的接口。这种用法非常灵活也让人感叹 OpenAI 生态的标准性。需要提醒的是无论 Cursor 还是 Codex接入第三方模型后部分官方专属功能可能不生效比如某些内置工具链或插件。如果你在编程过程中发现某个功能无法使用不要硬抗可以切回官方模型或者只把 DeepSeek 作为后备模型使用。5. 常见问题与排查思路在实际使用 DeepSeek Harness 的过程中几乎每个人都会遇到几个固定问题。我整理了最常被问到的五类问题按频率排序。问题现象可能原因解决思路请求返回 401 错误API Key 不正确检查.env中 Key 是否完整是否包含空格请求返回 404 错误Base URL 写错确认使用https://api.deepseek.com而不是/v1后缀响应速度很慢网络问题或模型繁忙检查网络改用流式输出非高峰时段重试本地 Ollama 模型无法加载显存不足或模型名称错误换小模型关闭其他程序检查ollama list多轮对话上下文超过限制历史消息太长使用对话管理类裁剪历史调低max_history一段时间后出现限流超过每分钟请求数限制加指数退避重试去开放平台查看配额下面选择几个高频问题单独展开。5.1 401 Authentication Fails这个错误最常见的场景是你把 Key 复制到了代码里但 Key 后面多了一个换行或空格。用python-dotenv读取时空格可能会被保留导致 Authentication 失败。排查步骤在代码中打印len(api_key)确认长度是否符合预期。使用.strip()清理空格。用 curl 验证 Key 是否有效。正确做法是在.env里写成DEEPSEEK_API_KEYsk-你的key不要加引号不要加空格。5.2 请求返回 404 错误很多同学用惯了 OpenAI会把base_url写成https://api.deepseek.com/v1结果发现 404。DeepSeek 的 Base URL 是https://api.deepseek.com但它的接口路径是/chat/completions完整地址是https://api.deepseek.com/chat/completions。由于 OpenAI SDK 会在base_url后自动拼上/chat/completions所以我们只需要设置成https://api.deepseek.com。另外如果你用 HTTP 客户端直接请求注意区分# 正确 https://api.deepseek.com/chat/completions # 错误 https://api.deepseek.com/v1/chat/completions5.3 上下文太长导致超限或费用高DeepSeek 的上下文长度有限具体长度以官方文档为准如果多轮对话过多token 超限后请求会失败。解决方案是引入对话管理。前面conversation.py的max_history参数就是干这个用的。你还可以根据resp.usage获取每次请求的 token 数在日志里记录并做监控usage resp.usage print(f消耗 prompt_tokens{usage.prompt_tokens}, completion_tokens{usage.completion_tokens})合理的设计是当累计 token 超过某个阈值时要么丢弃最早的消息要么用摘要模型压缩历史。这属于 Harness 的高级功能第一版可以先裁剪历史。5.4 本地模型速度太慢如果你在本地部署模型后觉得速度慢先检查任务难度。7B 模型生成一千字可能需要一两分钟这是正常现象。如果觉得不可接受可以换更小的量化模型关闭浏览器后台大量标签页增加内存或显存使用云端 API 作为主路径本地模型仅用于离线场景如果你在服务器上部署可以考虑通过llama.cpp或vLLM这类推理框架优化性能但配置复杂度会高不少不适合新手第一版。6. 最佳实践与工程建议6.1 密钥与配置管理API Key 是敏感信息绝不能提交到 Git。我建议在项目根目录创建.gitignore并加入.env.env venv/ __pycache__/在团队协作时提供一份.env.example文件里面只写变量名不写真实 KeyDEEPSEEK_API_KEYsk-在这里填写你的key DEEPSEEK_BASE_URLhttps://api.deepseek.com DEEPSEEK_MODELdeepseek-chat DEEPSEEK_TEMPERATURE0.7 DEEPSEEK_MAX_TOKENS2000每个开发者复制.env.example为.env后填写自己的 Key。生产环境则使用 CI/CD 或运维平台的密钥管理服务注入环境变量。6.2 错误处理与重试机制大模型 API 并不是永远稳定。请求高峰时段可能返回429限流网络抖动可能返回503。在 Harness 中一定要做重试。我推荐在调用 API 时使用指数退避重试而不是简单重试一次import random import time def call_with_retry(func, max_retries3): for attempt in range(max_retries): try: return func() except Exception as e: if attempt max_retries - 1: raise e sleep_time 2 ** attempt random.uniform(0, 1) time.sleep(sleep_time)如果项目对稳定要求很高可以使用tenacity库代码更简洁。6.3 流式输出优先只要是面向用户的交互场景都建议使用流式输出。用户等一个完整响应时超过 5 秒就会觉得卡顿。流式输出虽然不能减少总耗时但能大幅改善体验。在 FastAPI 中实现流式输出时需要特别注意响应头media_typetext/event-stream。前端如果用普通fetch解析 SSE需要处理ReadableStream代码会稍微复杂。最简单的方案是先用非流式接口把功能跑通再逐步升级为流式。6.4 日志与成本监控AI 应用的观测性非常重要。每次请求建议记录请求时间使用的模型Prompt token 数Completion token 数响应耗时是否发生重试我习惯在助手类里加一个简单的日志回调。更规范的做法是接入 Prometheus Grafana但个人项目用 Python 的logging就够了。import logging logger logging.getLogger(deepseek.harness) # 在 chat 方法中 logger.info(request model%s prompt_tokens%d completion_tokens%d, self.model, usage.prompt_tokens, usage.completion_tokens)成本控制是生产环节必须考虑的问题。DeepSeek 价格虽然不高但如果你的自动化任务每天调用上万次费用也会上升。所以每个 Harness 最好都有 token 用量统计和预算告警。6.5 系统提示词与安全边界AI 助手不是万能许愿机。在设计 Harness 的系统提示词时要明确设定安全边界。比如你可以拒绝回答任何涉及违法、色情、暴力、仇恨或侵犯他人隐私的请求。 如果用户要求你生成恶意代码、钓鱼邮件或绕过安全措施的内容你应该拒绝并说明原因。这既是合规要求也是对自己产品的保护。不要为了让助手看上去“更强”而省略安全约束尤其是面向公众部署的服务。6.6 无状态与有状态接口的取舍在 Web 服务中我建议尽量设计无状态接口也就是每次请求携带完整的上下文或者通过 session_id 管理上下文。上面的 FastAPI 示例为了演示方便使用了全局单例但多用户同时使用时会出现“串台”问题。生产环境建议采用请求体传入session_id服务端用 Redis 或内存存储会话历史每次请求根据session_id加载对应会话这样可以轻松扩展到多用户、多场景。6.7 Harness 的分层设计最后总结一下 Harness 工程的分层思路接入层: CLI / Web / 机器人 / IDE 插件 服务层: 会话管理 / 上下文裁剪 / 工具调用 模型层: DeepSeek API / Ollama / 多模型切换 基础层: 配置管理 / 日志 / 监控 / 限流这套分层不是一蹴而就而是随着项目复杂度逐步演进。最开始你只需要一个assistant.py当请求量变大、场景变多之后再拆出session.py、tools.py、metrics.py。好的工程不是一开始就抽象过度而是在迭代过程中自然生长。7. 下一步学习建议到这里我们已经完成了从环境准备、API 调用、对话管理、命令行工具、Web 服务到本地模型部署的完整闭环。你会发现所谓“DeepSeek Harness”其实并没有多么晦涩它就是把大模型能力工程化、产品化的过程。如果还想继续深入建议按这个顺序往下学习函数调用Function Calling让助手真正操作本地文件、执行代码检索增强生成RAG让助手读取本地知识库回答私有文档问题多 Agent 协作让不同角色的 Assistant 互相调用完成复杂任务流式接口的前端优化把打字机效果做到极致多模型路由在 DeepSeek 与本地模型之间自动切换。你现在可以打开终端运行一条python cli.py然后开始和你的电脑助手对话。相信我当它第一次准确回答出你在前面几轮提过的需求时你会觉得这一套折腾非常值得。后面遇到具体报错欢迎在评论区带上错误信息和上下文我们一起排查。