简介面向深度学习及多模态应用人群的Deepseek应用手册聚焦提示词工程、私有数据接入和模型知识科普适合正在学习大模型微调、API集成及日常AI辅助创作的技术读者。手册包含使用技巧、私有数据集接入与模型原理三大部分从多模型协同R1深度分析、V3快速生成、上传文件类型、联网搜索时机、常用指令集及万能提问模板讲起并结合API、本地、远程三条路径讲解知识库构建方法同时用通俗语言解释蒸馏、思维链、配置参数如max_seq_len、hidden_size等概念帮助理解不同模型架构差异与微调原理。资源为单个docx文档总大小约207KB目录模块化便于按章节查阅、二次编辑或导入笔记工具。目前已有285人学习浏览可支撑从快速上手到私有数据落地的完整学习路径也为后续模型微调与部署打下基础。1. 从一句“会话已达上限”说起这本 DeepSeek 应用手册先解决什么问题我用 DeepSeek 做批量问答和长文生成时最常撞见的不是模型答得差而是对话框突然来一句“内容已达上限”或者请求发过去直接被截断。第一反应是模型不行后来才发现是接入方式不对上下文没做预算、max_tokens 没显式设置、历史消息一股脑全塞进去API 端只要超过窗口就翻车。所以这份 deepseek 应用手册不打算重复官方文档里的请求格式而是按“接入 → 参数 → 部署 → 避坑 → 导出”这条路线把真实使用中容易踩的坑和可复现的操作步骤讲清楚。适合正在调官方 API、想本地部署、需要把 DeepSeek 接进编辑器或企业微信的从业者。下面每章都会给到能直接跑的配置或代码并说明参数为什么这么设。2. 接入方式先选对官方API、本地部署和编辑器工具各自解决什么问题先说结论不要一上来就想着部署大模型。DeepSeek 的接入路线可以分成三类——官方 API、本地部署、以及把 API 封装进工具链。选哪条取决于你的数据敏感程度、调用频率和可用硬件。2.1 官方API的最小调用用 Python 把第一句对话跑通“deepseek api如何调用”这个问题在官方文档里其实有标准答案但很多人卡在鉴权、模型名和响应解析上。最简做法是用 requests 直接调 OpenAI 兼容接口import requests url https://api.deepseek.com/chat/completions headers { Authorization: fBearer {DEEPSEEK_API_KEY}, Content-Type: application/json, } payload { model: deepseek-chat, messages: [ {role: system, content: 你是一个严谨的运维助手}, {role: user, content: 解释一下什么是上下文窗口}, ], max_tokens: 1024, temperature: 0.7, stream: False, } resp requests.post(url, jsonpayload, headersheaders, timeout60) print(resp.json()[choices][0][message][content])逻辑说明请求体里的 messages 是完整对话数组system 用来设定行为边界user 是本次输入。响应结构是 choices[0].message.content如果你用的是 deepseek-reasoner响应里可能多出 reasoning_content 字段那是模型先输出的推理过程不能当作正式回答直接展示给用户。参数说明max_tokens 控制单次输出上限调试阶段建议压到 256确认逻辑后再放开不然一次长回答就把账单拉高timeout 设 60 秒是因为推理模型首字延迟通常比普通模型长。如果返回 401先检查环境变量是否真的写入了 key如果返回 400多半是 messages 里少了 user 角色。两个模型的选型可以直接看下表不需要猜模型 ID适合场景注意事项deepseek-chat日常问答、信息抽取、代码生成、消息机器人响应快适合做高频低延迟应用deepseek-reasoner数学推理、复杂逻辑、长链条分析会多输出一段推理过程解析时要注意 extra 字段价格方面官方是按 token 计费控制成本的关键是别把历史和系统提示词无限堆长这一点在下一章会专门讲。2.2 本地部署和官方API的分界线哪类需求才值得上 Ollama不是所有场景都适合走云端 API。如果你要做企业内部知识库文本内容不能出内网或者你的调用量很大按 token 付费会变成固定成本又或者内网机器本来就有闲置 GPU。这时候就需要本地部署。本地部署最简单的入口是 Ollama一个命令就能把模型拉下来ollama pull deepseek-r1:7b ollama run deepseek-r1:7bpull 会从模型仓库下载对应参数规模的文件run 会进入交互式对话。这里 7b 是参数量级实际下载的是量化后的权重默认通常是 Q4 级别也就是在显存占用和生成质量之间取了一个平衡点。如果你机器只有 8G 显存直接上 70b 必然 OOM先拿 7b 把流程跑通再换大模型这是最省钱的做法。本地部署不是免费的午餐它的成本从 API 账单转移到了硬件和运维上要管 GPU 驱动、CUDA 版本、量化精度、显存分配还要处理并发请求。如果你的目标是快速验证功能官方 API 仍然是第一选择如果目标是给业务系统提供内网模型服务再走这条路线。值得提醒的是本地起服务后接口地址也要按 OpenAI 兼容格式暴露这样上层应用不用改代码这一点在第 4 章会展开。2.3 把 DeepSeek 接进 VSCode 和 Codex配置文件的常见写法不少人是通过“vscode接入deepseek”或“codex接入deepseek”搜到这里的。这类编辑器工具大多数支持自定义模型端点配置核心就三个字段模型名、API 地址、密钥。VSCode 里用 Continue 插件时配置文件长这样{ models: [ { title: DeepSeek Chat, provider: openai, model: deepseek-chat, apiBase: https://api.deepseek.com, apiKey: sk-xxx } ] }逻辑说明因为 DeepSeek 对外提供的是 OpenAI 兼容接口所以 provider 要写成 “openai”插件才会用 /chat/completions 这个路径去请求。apiBase 只填到域名根不要拼 /v1很多插件自己会补路径拼了反而 404。Codex 这类命令行工具一般读 config.toml[model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com env_key DEEPSEEK_API_KEY [model] provider deepseek model deepseek-chatenv_key 的意思是工具会从环境变量 DEEPSEEK_API_KEY 里读密钥而不是把 key 写死在 TOML 里。这比直接写在配置文件里安全得多尤其是配置要提交到 Git 仓库的时候泄露一个 key 等于把 API 账单送给别人。配置完先跑一句最简单的对话确认能返回内容再开始接业务提示词不要一上来就测长文本出错时很难判断是配置问题还是模型问题。2.4 企业微信和公众号接入消息转发的最小后端热搜里经常出现“企业微信接入deepseek”和“deepseek api 快速接入微信公众号”这类需求的本质不是写提示词而是做一个消息转发服务。用户在聊天框发来的消息通过微信后台回调推到你的服务器你的后端组装成 messages 调 DeepSeek再把返回内容发回对话框。Flask 写最小后端大概是这样的from flask import Flask, request, jsonify import requests app Flask(__name__) DEEPSEEK_KEY sk-xxx app.route(/chat, methods[POST]) def chat(): data request.get_json() user_text data.get(text, ) headers {Authorization: fBearer {DEEPSEEK_KEY}} resp requests.post( https://api.deepseek.com/chat/completions, json{ model: deepseek-chat, messages: [{role: user, content: user_text}], max_tokens: 512, }, headersheaders, timeout30, ) reply resp.json()[choices][0][message][content] return jsonify({reply: reply}) if __name__ __main__: app.run(host0.0.0.0, port8000)逻辑说明这个接口只做转发不处理微信侧的验签和加密。真实接入时微信后台会把消息包装成特定 XML 或 JSON 结构不同平台不一样所以要先接一个测试号把消息结构打出来再决定解析字段。开发阶段别直接上生产公众号先用企业微信自建应用内部测试成本低很多。参数说明timeout 不要设太长微信对被动回复有超时限制一般建议在 25 秒内把结果回给用户。如果 DeepSeek 这边响应慢宁可先回一句“正在处理”也不要让微信端等太久直接报错。这条路线的核心是把 AI 服务当作一个普通后端依赖来对待所有鉴权、重试、超时策略都和调用普通 HTTP 服务一样。3. 参数与上下文才是应用的分水岭temperature、max_tokens 与对话续接接口调通了下一步就是让输出“可控”。很多人把参数当玄学来回试几个值发现差不多就放弃了。实际上对一个具体的落地场景参数组合是能稳定复现的关键在于你知道每个参数控制的是哪一部分。3.1 一组能直接抄的参数表下面这张表是我在真实项目里用的基线值不是从文档抄的而是经过对比得出的参数取值范围作用我的常用值temperature0 到 2控制随机性越低越保守0.3 到 0.7top_p0 到 1核采样控制候选词范围0.8 左右max_tokens1 到上下文上限限制单次输出长度显式设置不省略streamtrue / false是否流式返回长对话用 truefrequency_penalty-2 到 2惩罚重复词0.5presence_penalty-2 到 2鼓励谈论新话题0 或 0.3逻辑说明temperature 和 top_p 不要同时调到极端。如果只需要抽取信息temperature 设 0.3top_p 设 0.8输出已经足够规整如果是写作文案可以放到 0.9但要接受格式偶尔变乱。调参数时一次只动一个变量同时改两个你根本不知道是谁影响了结果。max_tokens 是这里最容易被忽略的。很多人以为不设置就会输出完整内容实际上很多调用 SDK 会给一个默认值长回答写到一半就硬停。做代码生成或长文输出时我会把它设置成 2048 或更高宁可让响应慢一点也不要让内容腰斩。3.2 到达对话上限后怎么续接摘要压缩与历史合入日志里最常见的问题是“deepseek到达对话上限之后怎么让新对话承接上一个对话”。原因是上下文窗口有大小限制当历史消息加上新问题超过窗口API 就会返回错误或截断。解决思路不是扩大窗口而是主动压缩历史。常用做法是把早期对话先让模型自己总结成摘要再在发起新对话时把摘要放进 system 角色最近几轮原文放进 messages这样新对话看起来才像是有前情延续的。import json import requests def summarize_history(history, api_key): 把 history 压缩成 300 字摘要保留结论和未决问题 resp requests.post( https://api.deepseek.com/chat/completions, json{ model: deepseek-chat, messages: [ {role: system, content: 把对话压缩成300字摘要保留数字、结论和未解决问题}, {role: user, content: json.dumps(history, ensure_asciiFalse)}, ], max_tokens: 500, temperature: 0.3, }, headers{Authorization: fBearer {api_key}}, timeout60, ) return resp.json()[choices][0][message][content] def build_next_messages(history, question, api_key): 当历史超长时先摘要再拼装下一轮请求 if len(history) 20: summary summarize_history(history[:-4], api_key) messages [{role: system, content: f之前对话摘要{summary}}] messages.extend(history[-4:]) else: messages history.copy() messages.append({role: user, content: question}) return messages逻辑说明build_next_messages 的规则是历史超过 20 轮时把前 16 轮交给模型做摘要保留最近 4 轮原文再加当前问题。这样请求体不会无限膨胀窗口压力小模型也能拿到关键前情。注意摘要动作本身也在消耗 token如果历史实在太大可以先把历史分段摘要再摘要摘要但没必要过度设计大多数场景一次摘要就够。参数说明summarize_history 里 temperature 设 0.3是为了让摘要尽量忠实不容易添油加醋。max_tokens 设 500摘要控制在 300 字左右省下空间给真正的对话内容。如果你发现续接后模型经常答偏问题大概率出在摘要丢细节而不是模型本身。3.3 让 JSON 输出不再翻车response_format 与解析兜底做自动化流程时最烦的是模型返回的内容里夹带解释文字或 Markdown 代码块。解决办法是双重保险一边用 response_format 约束一边在代码里做容错解析。请求里加上格式约束payload { model: deepseek-chat, response_format: {type: json_object}, messages: [ {role: system, content: 只输出JSON对象不要输出任何解释和代码块标记}, {role: user, content: 给出3条运维告警字段包括level和message}, ], max_tokens: 1024, }即使这样偶尔仍会出现输出被三个反引号包住的情况。所以解析端必须做兜底import json import re def parse_json_response(text: str) - dict: text text.strip() if text.startswith(): text re.sub(r^(?:json)?\s*|\s*$, , text) try: return json.loads(text) except json.JSONDecodeError: match re.search(r\{.*\}, text, re.S) if match: return json.loads(match.group(0)) raise ValueError(f无法从模型输出中解析JSON: {text[:200]})逻辑说明第一步去掉外层的 Markdown 代码块标记第二步直接 json.loads第三步用正则抓取第一个完整的 JSON 对象。这套逻辑能覆盖绝大多数“模型多说了句话”的情况但不能覆盖“模型输出完全坏掉”的情况后者需要退回去检查 system 提示词是不是给了足够明确的约束。参数说明response_format 并不是所有模型版本都支持接本地部署模型时尤其要注意。如果接口不认识这个字段一般会忽略或报错所以调用前先确认部署模型的版本支持情况不然线上环境会突然一路报错。这也是为什么很多生产环境宁可用解析兜底而不是完全依赖格式参数。4. 本地部署与 vLLM显存估算、量化选择与离线局域网本地化部署和云端 API 是两条完全不同的运维路线。很多人看了“本地部署deepseek”的热搜就冲动下载模型结果卡在显存不足或速度太慢上。这一章把硬件估算、部署命令和离线内网场景一次讲清楚。4.1 先算显存再选模型一张表解决选型问题部署前第一件事不是拉模型而是算显存。下面这组数据是我在常见量化配置下的经验值不是官方数值不同上下文长度会有浮动但作为选型参考足够模型参数量常见量化级别显存参考适合硬件7B 到 8BQ4_K_M6 到 8 GB消费级显卡也能跑14BQ4_K_M10 到 14 GB24 GB 显存单卡32BQ4_K_M20 到 24 GB48 GB 单卡或双卡70BQ4_K_M40 到 48 GB多卡或大显存服务器逻辑说明量化是把模型权重从高精度压缩到低精度Q4 表示每个权重用 4 bit 存储显存占用低但生成质量会比 FP16 略差。如果你的业务对输出质量敏感比如做代码生成建议至少从 14B 起步如果只是做意图识别或摘要7B 已经够用没必要追求大参数。算显存时还要留出一部分给上下文和并发请求。比如 7B 模型理论占用 6 到 8 GB不代表 8 GB 显存的卡就能舒服跑。上下文越长KV cache 占用越高并发请求越多显存越紧张。我的习惯是模型权重占 70%给缓存和并发留 30%宁可少跑几个并发也不要频繁 OOM。4.2 用 Ollama 把模型部署到内网机器Ollama 是本地部署最快的路径因为它把模型下载、量化、服务启动都封装好了。最简命令只有两条ollama pull deepseek-r1:7b ollama servepull 会把模型下载到本地模型目录serve 启动 HTTP 服务。部署完成后可以用 curl 验证curl http://localhost:11434/v1/chat/completions \ -H Content-Type: application/json \ -d {model: deepseek-r1:7b, messages: [{role: user, content: 你好}]}如果要让内网其它机器访问启动时设置监听地址而不是默认的 localhostOLLAMA_HOST0.0.0.0 ollama serve逻辑说明OLLAMA_HOST 决定服务绑定在哪个网络接口。默认只监听本机回环地址内网其它机器根本访问不到。用 0.0.0.0 表示监听所有网卡接口之后其它机器把 API 地址改成 http://内网IP:11434 就能调用。这个动作在云服务器上要格外小心建议配合访问控制使用别把端口裸奔到公网。离线内网部署时Ollama 模型的加载路径也值得注意OLLAMA_MODELS/data/models ollama serve提前把模型文件放到 /data/models 对应子目录服务起来后会从本地读取不需要在线拉取。先跑一遍 ollama list 确认模型已经在列表里再启动服务避免离线环境下启动时去检查在线更新而卡住。4.3 vLLM 部署参数比模型名更重要如果业务有并发压力Ollama 不一定顶得住。vLLM 是生产环境更常见的选择它通过连续批处理和 PagedAttention 大幅提高吞吐部署命令如下python -m vllm.entrypoints.openai.api_server \ --model /data/models/deepseek-chat \ --served-model-name deepseek-chat \ --host 0.0.0.0 \ --port 8000 \ --max-model-len 32768 \ --gpu-memory-utilization 0.9逻辑说明--served-model-name 特别关键。它决定客户端请求时填的模型名。如果你手头的推理代码里写死了 deepseek-chat部署时也保持这个名字调用端就可以完全不改代码只把 API 地址换成本地地址。参数说明--max-model-len 设 32768 表示最大上下文长度显存不够时会出现 OOM这时不是加显存而是先把这个值降到 16384。--gpu-memory-utilization 0.9 表示允许 vLLM 用掉 90% 显存留 10% 给显卡驱动和其它进程。并发量大的时候这两个参数比模型选择更影响稳定性需要实测调整。vLLM 启动后把第 2 章的请求地址从 https://api.deepseek.com 改成 http://localhost:8000/v1调用代码原封不动就能用。这也是为什么我一直强调要用 OpenAI 兼容接口做封装改底座只是改配置不是改业务代码。4.4 harness 工具能不能在离线局域网里用先看它依赖什么很多人在问“deepseek harness可以在离线局域网使用吗”或者“harness附带skill怎么部署到内网服务器”。我的观点是能用但要先拆清楚这个工具的依赖边界。harness 这类工具通常只是把 API 调用封装成了工作流真正的模型推理还是在后端。如果工具支持自定义端点把它指向内网里第 4.2 或 4.3 启动的服务就行离线完全没问题。但如果它带了 skill 市场、在线提示词库、自动更新这类联网功能离线环境下这些模块会失效安装阶段就会卡住。部署到内网服务器时我一般会做三件事第一把模型文件预置到内网机器确保服务启动不需要在线检查第二关闭工具的自动更新和在线插件市场第三把会用到的 skill 和提示词模板提前下载好放到本地目录。只要这三件事做完离线局域网里跑通基本没有障碍。反之如果工具内部硬编码了在线端点那这个工具就不适合内网场景别浪费时间去改它。5. 避坑DeepSeek 接入中常见的 5 个坑这章是踩坑合集每一条都有真实的现象、原因和解决路径照着排查能省下不少时间。5.1 坑 1对话到达上限后新对话不承接历史现象聊天工具提示“内容已达上限”你新建会话后问同样的问题模型完全不记得之前讨论过什么。原因客户端没有做历史合入新会话的 messages 里只有当前这句话没有前情。服务端只按单次请求的上下文计算不管是“上限”还是“新会话”本质都是同一件事你没有把历史带进请求。解决把旧对话先压缩成摘要再和最近几轮原文一起拼进新请求。具体代码用 3.2 节的 build_next_messages 就行。这里记住一个原则对话续接不是聊天工具自动完成的而是调用方主动维护 messages。谁调用谁负责记忆。5.2 坑 2长响应“丢了尾巴”max_tokens 默认值过小现象让 DeepSeek 写一份完整的故障复盘报告写到“影响范围”就停了没有总结也没有后续建议。原因请求里没显式设置 max_tokensSDK 或服务端用了默认值输出长度到了上限就被强制截断模型不是不会写而是被叫停了。解决把 max_tokens 显式设置成 2048 或更高。如果业务场景要生成的内容特别长不用一味调大可以改成多次生成先要求模型输出大纲再根据大纲逐段生成。截断问题不只是参数问题也可能和单次生成能力上限有关分段生成才是更可用的方案。5.3 坑 3JSON 输出被 Markdown 代码块包住现象明明设置了 response_format解析 json.loads 仍然报错打开响应发现内容是json ...包裹的。原因模型在个别情况下不遵守格式约束尤其是当 system 提示词里没有明确“不要输出代码块标记”时更容易犯这个毛病。解决不要只靠 response_format 一个字段解析端按 3.3 节的 parse_json_response 做兜底。先剥代码块再正则抓取 JSON 对象。另外把 system 提示词写成“只输出JSON对象不要输出任何解释和代码块标记”比单靠格式参数可靠得多。5.4 坑 4429 限流与指数退避现象脚本一跑起来前 10 个请求正常第 11 个开始连续返回 429 请求过多而且重试几次还是 429。原因账号有并发配额或每分钟请求数上限。业务侧没有做限速短时间把配额打满服务端开始拒绝。解决调用层统一做退避重试。先休息再重试休息时间按指数增长比如第一次等 2 秒、第二次等 4 秒、第三次等 8 秒最多试 5 次后放弃并记录日志import time def request_with_retry(payload, headers, retries5): for attempt in range(retries): resp requests.post(url, jsonpayload, headersheaders, timeout60) if resp.status_code ! 429: return resp time.sleep(2 ** attempt) raise RuntimeError(DeepSeek API 连续限流)注意不要每次都在业务代码里写重试逻辑应该封装成公共函数所有调用方共用。429 时响应体里通常有 Retry-After 头解析这个字段做等待比固定等 2 秒更准确。5.5 坑 5harness 工具在 Windows 下无法读取文件现象安装或运行 harness 类工具时读取文件报错日志里出现 SetNamedSecurityInfoW failed (win32) 或 Permission denied重装也没用。原因常见情况是工具想往系统目录写日志或配置但当前用户没有目录权限或者工作目录被安全软件锁了 ACL导致写入系统 API 调用失败。这类问题在 Windows 下尤其容易出现在 C:\Program Files 这类受保护目录。解决第一优先把工作目录和日志目录改到用户目录下比如 C:\Users\你的用户名\deepseek-work而不是系统盘 Program Files第二用普通用户重新安装尽量不要用管理员权限装了再降权跑权限归属容易错乱第三如果还是不行用 icacls 给当前用户增加目录权限或者把安全软件对该目录的实时扫描关掉。不要一上来就重装先看事件日志里具体是哪个文件被拒绝往往一分钟就能定位。6. 把“导出”和“回归验证”写进一条流水线调模型时最怕的不是输错参数而是调了半天没留下记录。后来习惯养成每次调完参先把对话导出成可读文件再拿导出结果做一轮回归验证。导出其实很简单把 messages 数组写成 Markdownimport json def export_md(chat_pathconversation.json): with open(chat_path, r, encodingutf-8) as f: data json.load(f) output [] for turn in data[messages]: output.append(f## {turn[role]}\n\n{turn[content]}\n) with open(conversation.md, w, encodingutf-8) as out: out.write(\n.join(output))导出后顺手做一轮回归把历史里最长的那条用户输入重新发给 API看返回是否为空、JSON 能否解析、回答是否被截断。回归脚本不需要复杂关键就是断言两个条件resp requests.post(url, jsonpayload, headersheaders, timeout60) assert resp.status_code 200, fAPI 返回 {resp.status_code} assert resp.json().get(choices), 响应里没有 choices 字段我吃过一次亏花两天调好的提示词组合重启服务后全忘了只能从聊天记录里翻聊天记录痛苦得很。后来导出的 Markdown 文件就成了对比基准——换了参数、换了版本直接看diff哪里变了清清楚楚。这个习惯对你同样适用把导出和回归绑成一条流水线再调新配置时只跑一遍脚本就能知道这次改动是变好了还是变坏了。希望帮到你。本文还有配套的精品资源点击获取