简介《2025 DeepSeek自学手册》以73页PDF呈现面向希望系统掌握DeepSeek V3与R1的AI初学者、开发者及研究人员。内容从模型起源、架构设计与性能表现切入延伸到提示词技巧、数据处理、微调及无监督、监督与强化学习实现路径并以13个官方示例演示代码编写、数学求解、自然语言理解、创意写作和角色扮演等场景附在线与本地部署方案。手册对MoE专家混合、MLA多头潜在注意力、多Token预测、无辅助损失负载均衡以及R1的冷启动数据、多阶段训练与模型蒸馏等机制均有展开并给出数学、编程及通用知识基准对比便于理解V3与R1的差异和选型。资源包为1个PDF文件约25.31MB已有154人学习适合按章节精读或按场景检索用作理论梳理与落地实践参考。1. 从理论到实践这份 73 页 DeepSeek 自学手册该从哪里切进去一份 73 页的 DeepSeek 自学手册多数人卡在两个位置前 20 页讲注意力机制与 MoE 路由读得懂但落不到工位上后 20 页是提示词模板抄完换个业务场景立刻失效。真正撑住从理论到实践这句话的是中间那部分——模型怎么选、deepseek api如何调用、本地部署 deepseek 的硬件底线在哪、vscode 接入 deepseek 之后补全为什么老是截断。这篇按一线落地的顺序重排这些内容先讲模型与计费再讲本地化部署的两条路线然后把它接进 VSCode、命令行编码工具和企业微信最后处理 deepseek 达到对话长度上限和 deepseek 导出这类绕不开的运维细节。适合需要把 DeepSeek 接进自己系统的后端、算法和运维也适合想在本地把数据圈住的小团队。2. DeepSeek 模型选型与 deepseek api 如何调用2.1 先分清 deepseek-chat 和 deepseek-reasoner 的调用差异开放平台上能直接调的两个主力模型差异不在参数量而在要不要把思考过程还给你。deepseek-chat 是常规对话模型响应快、采样参数生效deepseek-reasoner 会把推理链放在reasoning_content字段里单独返回正文仍然在content。这两者的接口地址、鉴权方式完全一致只有模型名和行为不同。模型名推理链适合任务常见坑deepseek-chat不显式输出日常问答、代码补全、结构化抽取复杂多步数学题容易跳步deepseek-reasoner返回 reasoning_content算法推导、SQL 优化、逻辑排查首 token 延迟高采样参数不生效选型上我的习惯是凡是能用确定性规则或单轮 prompt 解决的问题一律用 chat只有需要模型先想再做的题型才切 reasoner因为推理 token 同样计费用错场景成本会翻两三倍。2.2 用 OpenAI SDK 跑通第一条请求DeepSeek 的 HTTP 接口兼容 OpenAI 协议所以不需要专用 SDK改 base_url 就能复用现成的客户端。下面是 Python 侧的最小可运行版本from openai import OpenAI client OpenAI( api_keysk-你的Key, base_urlhttps://api.deepseek.com/v1, # 与 OpenAI 协议兼容 ) resp client.chat.completions.create( modeldeepseek-chat, messages[ {role: system, content: 你是后端架构顾问回答只给结论和代价}, {role: user, content: 这条 SQL 为什么会走全表扫描}, ], temperature0.3, # 代码类任务压低随机性 max_tokens2048, # 只约束输出不含输入 streamFalse, ) print(resp.choices[0].message.content) print(resp.usage) # 用来核对 prompt/completion token 数逻辑说明base_url决定流量打到哪个端点路径里的/v1是协议约定而非版本号messages里 system 放在第一位能让缓存前缀稳定命中usage字段返回的是本次真实计费的 token 拆分写成本监控时直接读它别自己估算。参数上几个易错点temperature调到 0 不代表输出完全确定只是概率分布被压平max_tokens只限制输出长度和上下文窗口是两个概念开streamTrue后usage会在最后一个 chunk 才出现。命令行排查用 curl 更直观curl https://api.deepseek.com/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $DEEPSEEK_API_KEY \ -d { model: deepseek-reasoner, messages: [{role: user, content: 解释 TCP 三次握手为什么不是两次}], stream: false }返回体里choices[0].message.reasoning_content是推理过程content是最终答案。业务代码里要显式判断这个字段是否存在否则切模型时会取到空字符串。2.3 成本与并发把 deepseek 价格算在写代码之前计费口径按输入、输出分开输入里又区分缓存命中与未命中未命中的单价明显更高。控制成本最有效的三件事按性价比排序如下手段做法效果稳定前缀system prompt、few-shot 示例固定不变放在 messages 最前面命中缓存输入单价大幅下降限制输出明确要求只输出 JSON不要解释并设 max_tokens输出是最贵的一段批量合并把 10 条小请求合成 1 条结构化抽取请求减少重复的系统提示开销并发上个人开发者的限额通常够用但批量跑数据时会撞到 429。稳妥的做法是加指数退避并在队列层限制在飞请求数而不是无脑重试import time, random def call_with_backoff(fn, retries5): for i in range(retries): try: return fn() except Exception as e: if 429 not in str(e) and rate not in str(e).lower(): raise # 指数退避 抖动避免多实例同时重试 time.sleep(min(2 ** i, 30) random.random()) raise RuntimeError(重试耗尽)2.4 请求报错的定位顺序遇到失败时按这个顺序查能省掉大半时间401 先看 Key 有没有多余空格和换行400 多半是 messages 结构不合法比如 role 写成了assistant带尾空格超长报错说明输入已经超过上下文窗口需要先做截断或摘要返回服务器繁忙请稍后再试属于服务端限流退避重试即可不要改参数硬刚。deepseek request extension preparation failed这类报错一般出现在浏览器插件或客户端侧先用 curl 确认服务端本身通不通能把问题范围直接砍一半。3. 本地部署 deepseekOllama 与 vLLM 两条路线的落地参数3.1 本地化部署 deepseek 的决策边界先想清楚为什么要本地跑。数据不能出内网、要离线可用、要固定版本做回归测试这三条成立才值得投入显卡。反之如果只是想省 API 费用算上电费和运维时间通常不划算——一张 24G 卡跑 32B 量化的吞吐很难比按量付费更便宜。场景建议路线单机自用、验证效果Ollama五分钟起服务团队内网、多人并发vLLM吞吐和并发明显更好生产级高并发多卡张量并行 前置网关排队3.2 用 Ollama 跑通本地 DeepSeek 的最小命令集Ollama 把模型权重、量化和运行时打包在一起装完就能用# 拉取蒸馏版模型数字是参数量按显存选 ollama pull deepseek-r1:14b # 交互式跑一轮 ollama run deepseek-r1:14b # 以常驻服务方式启动供其他程序调用 OLLAMA_HOST0.0.0.0:11434 OLLAMA_KEEP_ALIVE30m ollama serveOLLAMA_KEEP_ALIVE控制模型在显存里驻留多久默认几分钟就卸载多人使用时反复加载会非常慢调到 30 分钟以上更实际。服务起来后用 OpenAI 兼容端点验证curl http://localhost:11434/v1/chat/completions \ -H Content-Type: application/json \ -d {model:deepseek-r1:14b,messages:[{role:user,content:写一个带超时的 LRU 缓存}],stream:false}上下文长度默认偏小长文档场景需要自定义。用 Modelfile 固化参数比每次命令行传更省事FROM deepseek-r1:14b PARAMETER num_ctx 16384 PARAMETER temperature 0.6 SYSTEM 你是运维助手命令必须带注释num_ctx直接决定显存占用从 4096 提到 32768KV cache 可能多吃好几 GB调之前先看显存余量。3.3 vLLM 起服务的 5 个关键参数多人并发场景换 vLLM它的连续批处理和 PagedAttention 能把显存碎片压下去python -m vllm.entrypoints.openai.api_server \ --model deepseek-ai/DeepSeek-R1-Distill-Qwen-14B \ --served-model-name deepseek-local \ --tensor-parallel-size 2 \ --max-model-len 32768 \ --gpu-memory-utilization 0.92 \ --enable-prefix-caching \ --port 8000参数作用调整建议tensor-parallel-size权重切到几张卡等于可见 GPU 数单卡填 1max-model-len单请求最大上下文越大 KV cache 占用越高按业务实际需要设gpu-memory-utilization预分配的显存比例0.850.95留一点给驱动enable-prefix-caching复用公共前缀的 KV多请求共享同一 system prompt 时必开max-num-seqs同时处理的请求数显存紧张就调小避免频繁抢占--served-model-name是给客户端用的别名写死一个稳定名字后面换底层模型时业务代码不用改。3.4 显存不够时的量化取舍与排错参数量BF16 权重Q4_K_M 权重建议显存7B约 15 GB约 4.5 GB8 GB14B约 28 GB约 9 GB16 GB32B约 64 GB约 20 GB24 GB 起70B约 140 GB约 42 GB双卡 48 GB 起上表只算权重实际还要加上 KV cache 和框架开销。常见故障有三类启动即 OOM先把max-model-len砍半再试输出重复或断句异常通常是量化损失叠加 temperature 过低把温度提到 0.6 左右观察首 token 延迟几十秒多半是模型被换出显存检查 keep-alive 或并发数是否超了。4. 把 DeepSeek 接进开发工具链VSCode、Claude Code 与企业微信4.1 vscode 接入 deepseek 的补全与对话配置VSCode 里接入不需要自己写插件用支持自定义 OpenAI 兼容端点的助手类插件即可。核心是三件事填对apiBase、填对模型名、把上下文长度写准。name: deepseek-local version: 0.0.1 models: - name: DeepSeek Chat provider: openai model: deepseek-chat apiBase: https://api.deepseek.com/v1 apiKey: sk-你的Key roles: [chat, edit, apply] defaultCompletionOptions: contextLength: 65536 maxTokens: 2048contextLength填小了插件会频繁裁剪文件内容补全看起来变傻填大了超出服务端窗口会直接报错。字段名在不同插件版本间有差异以当前版本的配置文档为准别硬抄旧博客。改完配置后先在对话面板发一句读一下当前文件并说明它的职责能读全文件就说明上下文生效了。4.2 Claude Code 接入 DeepSeek 的协议转换层命令行编码工具大多走 Anthropic 的 Messages 协议而 DeepSeek 提供的是 OpenAI 协议两者结构不同Anthropic 的 system 是顶层字段content 支持块数组。常见做法是本地起一层轻量转换把/v1/messages转成/chat/completions。from fastapi import FastAPI, Request import httpx app FastAPI() UPSTREAM https://api.deepseek.com/v1/chat/completions app.post(/v1/messages) async def messages(req: Request): body await req.json() key req.headers.get(x-api-key) or \ req.headers.get(authorization, ).replace(Bearer , ) msgs [] if body.get(system): # Anthropic 顶层 system 要下沉 msgs.append({role: system, content: body[system]}) for m in body.get(messages, []): msgs.append({role: m[role], content: m[content]}) async with httpx.AsyncClient(timeout180) as c: r await c.post( UPSTREAM, json{model: deepseek-chat, messages: msgs, max_tokens: body.get(max_tokens, 2048), stream: False}, headers{Authorization: fBearer {key}}, ) text r.json()[choices][0][message][content] return { id: msg_local, type: message, role: assistant, model: deepseek-chat, stop_reason: end_turn, content: [{type: text, text: text}], usage: {input_tokens: 0, output_tokens: 0}, }客户端侧只要把 BASE_URL 指向本地 8082 端口AUTH_TOKEN 留 DeepSeek 的 Key 即可export ANTHROPIC_BASE_URLhttp://127.0.0.1:8082 export ANTHROPIC_AUTH_TOKENsk-你的DeepSeekKey export ANTHROPIC_MODELdeepseek-chat这层转换只覆盖文本对话工具调用和流式事件需要单独补。如果用的是走 OpenAI 协议的 CLI 编码工具就不必转换把 base_url 换成https://api.deepseek.com/v1直接可用。4.3 企业微信接入 deepseek 的消息回调链路企业微信自建应用接收消息有个硬约束回调必须在 3 秒内响应否则会重试重试会导致同一条消息被处理多次。所以正确链路是先落库、立即返回空串再用客服消息接口把模型结果异步推回去。环节关键动作注意点验签解密校验 msg_signature解密 Encrypt用官方库处理别手写立即响应返回空字符串超 3 秒必然触发重试异步推理队列里调 DeepSeek按用户维度做去重结果回推调消息推送接口超过 48 小时窗口无法主动推送app.post(/wecom/callback) async def callback(request: Request): xml await request.body() msg parse_and_decrypt(xml) # 官方库验签 解密 enqueue(user_idmsg.FromUserName, textmsg.Content) # 只入队不阻塞 return # 必须立即返回否则重试消息按用户维度做幂等去重、推理放在独立 worker 里跑这两条比模型选型更影响实际体验。群聊场景还要处理 机器人 的触发判定否则会把所有闲聊都送进模型。5. 长对话治理达到对话长度上限后的续接与导出5.1 deepseek 达到对话长度上限怎么办网页版弹出达到对话长度上限请开启新对话本质是上下文窗口被占满了。直接重开新对话会丢掉前文约束比较稳的做法是主动滚存把靠前的轮次压缩成一段事实摘要塞进新会话的 system 位置只保留最近几轮原文。def rollover(client, history, keep_last4): 旧轮次压缩成摘要保留最近几轮原文成本远低于全量重放 old, recent history[:-keep_last], history[-keep_last:] digest client.chat.completions.create( modeldeepseek-chat, messages[ {role: system, content: 把以下对话压缩成不超过 300 字的事实清单 保留结论、约束条件、未决问题和命名约定}, *old, ], temperature0.2, max_tokens600, ).choices[0].message.content return [{role: system, content: f历史会话摘要\n{digest}}] recent关键在摘要提示词要显式要求保留约束条件和命名约定否则模型倾向于只留结论重开会话后变量命名、技术栈偏好全丢。keep_last一般取 35太少会丢语境太多摘要没意义。5.2 deepseek 导出后如何切成可检索片段把长对话导出成 markdown 之后不要整份塞进新会话按轮次切分再按需召回更省 tokenimport re, json def split_turns(md_text): # 以 ### 用户 / ### 助手 之类的分隔标记切轮次 blocks re.split(r\n(?###\s), md_text) out [] for b in blocks: lines b.strip().splitlines() if not lines: continue role user if 用户 in lines[0] else assistant out.append({role: role, content: \n.join(lines[1:]).strip()}) return out turns split_turns(open(chat_export.md, encodingutf-8).read()) json.dump(turns, open(turns.json, w, encodingutf-8), ensure_asciiFalse, indent2)切完之后每轮单独算 token超过阈值的轮次做二次切分检索时只带最相关的两三段进上下文比整份重放节省一个数量级的输入。5.3 用 token 计数验证上下文有没有被浪费判断上下文是否被无效占用最快的办法是统计每类消息占的 token 占比。system 和工具描述占比超过三成就该精简历史轮次占比过高就该触发上面的滚存逻辑。每次调用把usage落到日志表里按天聚合输入输出的缓存命中率能直接反映 system prompt 是否稳定——命中率突然掉到零通常是有人往前缀里塞了时间戳。本文还有配套的精品资源点击获取 DeepSeek API 调用、本地部署与工具链接入实战
简介《2025 DeepSeek自学手册》以73页PDF呈现面向希望系统掌握DeepSeek V3与R1的AI初学者、开发者及研究人员。内容从模型起源、架构设计与性能表现切入延伸到提示词技巧、数据处理、微调及无监督、监督与强化学习实现路径并以13个官方示例演示代码编写、数学求解、自然语言理解、创意写作和角色扮演等场景附在线与本地部署方案。手册对MoE专家混合、MLA多头潜在注意力、多Token预测、无辅助损失负载均衡以及R1的冷启动数据、多阶段训练与模型蒸馏等机制均有展开并给出数学、编程及通用知识基准对比便于理解V3与R1的差异和选型。资源包为1个PDF文件约25.31MB已有154人学习适合按章节精读或按场景检索用作理论梳理与落地实践参考。1. 从理论到实践这份 73 页 DeepSeek 自学手册该从哪里切进去一份 73 页的 DeepSeek 自学手册多数人卡在两个位置前 20 页讲注意力机制与 MoE 路由读得懂但落不到工位上后 20 页是提示词模板抄完换个业务场景立刻失效。真正撑住从理论到实践这句话的是中间那部分——模型怎么选、deepseek api如何调用、本地部署 deepseek 的硬件底线在哪、vscode 接入 deepseek 之后补全为什么老是截断。这篇按一线落地的顺序重排这些内容先讲模型与计费再讲本地化部署的两条路线然后把它接进 VSCode、命令行编码工具和企业微信最后处理 deepseek 达到对话长度上限和 deepseek 导出这类绕不开的运维细节。适合需要把 DeepSeek 接进自己系统的后端、算法和运维也适合想在本地把数据圈住的小团队。2. DeepSeek 模型选型与 deepseek api 如何调用2.1 先分清 deepseek-chat 和 deepseek-reasoner 的调用差异开放平台上能直接调的两个主力模型差异不在参数量而在要不要把思考过程还给你。deepseek-chat 是常规对话模型响应快、采样参数生效deepseek-reasoner 会把推理链放在reasoning_content字段里单独返回正文仍然在content。这两者的接口地址、鉴权方式完全一致只有模型名和行为不同。模型名推理链适合任务常见坑deepseek-chat不显式输出日常问答、代码补全、结构化抽取复杂多步数学题容易跳步deepseek-reasoner返回 reasoning_content算法推导、SQL 优化、逻辑排查首 token 延迟高采样参数不生效选型上我的习惯是凡是能用确定性规则或单轮 prompt 解决的问题一律用 chat只有需要模型先想再做的题型才切 reasoner因为推理 token 同样计费用错场景成本会翻两三倍。2.2 用 OpenAI SDK 跑通第一条请求DeepSeek 的 HTTP 接口兼容 OpenAI 协议所以不需要专用 SDK改 base_url 就能复用现成的客户端。下面是 Python 侧的最小可运行版本from openai import OpenAI client OpenAI( api_keysk-你的Key, base_urlhttps://api.deepseek.com/v1, # 与 OpenAI 协议兼容 ) resp client.chat.completions.create( modeldeepseek-chat, messages[ {role: system, content: 你是后端架构顾问回答只给结论和代价}, {role: user, content: 这条 SQL 为什么会走全表扫描}, ], temperature0.3, # 代码类任务压低随机性 max_tokens2048, # 只约束输出不含输入 streamFalse, ) print(resp.choices[0].message.content) print(resp.usage) # 用来核对 prompt/completion token 数逻辑说明base_url决定流量打到哪个端点路径里的/v1是协议约定而非版本号messages里 system 放在第一位能让缓存前缀稳定命中usage字段返回的是本次真实计费的 token 拆分写成本监控时直接读它别自己估算。参数上几个易错点temperature调到 0 不代表输出完全确定只是概率分布被压平max_tokens只限制输出长度和上下文窗口是两个概念开streamTrue后usage会在最后一个 chunk 才出现。命令行排查用 curl 更直观curl https://api.deepseek.com/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $DEEPSEEK_API_KEY \ -d { model: deepseek-reasoner, messages: [{role: user, content: 解释 TCP 三次握手为什么不是两次}], stream: false }返回体里choices[0].message.reasoning_content是推理过程content是最终答案。业务代码里要显式判断这个字段是否存在否则切模型时会取到空字符串。2.3 成本与并发把 deepseek 价格算在写代码之前计费口径按输入、输出分开输入里又区分缓存命中与未命中未命中的单价明显更高。控制成本最有效的三件事按性价比排序如下手段做法效果稳定前缀system prompt、few-shot 示例固定不变放在 messages 最前面命中缓存输入单价大幅下降限制输出明确要求只输出 JSON不要解释并设 max_tokens输出是最贵的一段批量合并把 10 条小请求合成 1 条结构化抽取请求减少重复的系统提示开销并发上个人开发者的限额通常够用但批量跑数据时会撞到 429。稳妥的做法是加指数退避并在队列层限制在飞请求数而不是无脑重试import time, random def call_with_backoff(fn, retries5): for i in range(retries): try: return fn() except Exception as e: if 429 not in str(e) and rate not in str(e).lower(): raise # 指数退避 抖动避免多实例同时重试 time.sleep(min(2 ** i, 30) random.random()) raise RuntimeError(重试耗尽)2.4 请求报错的定位顺序遇到失败时按这个顺序查能省掉大半时间401 先看 Key 有没有多余空格和换行400 多半是 messages 结构不合法比如 role 写成了assistant带尾空格超长报错说明输入已经超过上下文窗口需要先做截断或摘要返回服务器繁忙请稍后再试属于服务端限流退避重试即可不要改参数硬刚。deepseek request extension preparation failed这类报错一般出现在浏览器插件或客户端侧先用 curl 确认服务端本身通不通能把问题范围直接砍一半。3. 本地部署 deepseekOllama 与 vLLM 两条路线的落地参数3.1 本地化部署 deepseek 的决策边界先想清楚为什么要本地跑。数据不能出内网、要离线可用、要固定版本做回归测试这三条成立才值得投入显卡。反之如果只是想省 API 费用算上电费和运维时间通常不划算——一张 24G 卡跑 32B 量化的吞吐很难比按量付费更便宜。场景建议路线单机自用、验证效果Ollama五分钟起服务团队内网、多人并发vLLM吞吐和并发明显更好生产级高并发多卡张量并行 前置网关排队3.2 用 Ollama 跑通本地 DeepSeek 的最小命令集Ollama 把模型权重、量化和运行时打包在一起装完就能用# 拉取蒸馏版模型数字是参数量按显存选 ollama pull deepseek-r1:14b # 交互式跑一轮 ollama run deepseek-r1:14b # 以常驻服务方式启动供其他程序调用 OLLAMA_HOST0.0.0.0:11434 OLLAMA_KEEP_ALIVE30m ollama serveOLLAMA_KEEP_ALIVE控制模型在显存里驻留多久默认几分钟就卸载多人使用时反复加载会非常慢调到 30 分钟以上更实际。服务起来后用 OpenAI 兼容端点验证curl http://localhost:11434/v1/chat/completions \ -H Content-Type: application/json \ -d {model:deepseek-r1:14b,messages:[{role:user,content:写一个带超时的 LRU 缓存}],stream:false}上下文长度默认偏小长文档场景需要自定义。用 Modelfile 固化参数比每次命令行传更省事FROM deepseek-r1:14b PARAMETER num_ctx 16384 PARAMETER temperature 0.6 SYSTEM 你是运维助手命令必须带注释num_ctx直接决定显存占用从 4096 提到 32768KV cache 可能多吃好几 GB调之前先看显存余量。3.3 vLLM 起服务的 5 个关键参数多人并发场景换 vLLM它的连续批处理和 PagedAttention 能把显存碎片压下去python -m vllm.entrypoints.openai.api_server \ --model deepseek-ai/DeepSeek-R1-Distill-Qwen-14B \ --served-model-name deepseek-local \ --tensor-parallel-size 2 \ --max-model-len 32768 \ --gpu-memory-utilization 0.92 \ --enable-prefix-caching \ --port 8000参数作用调整建议tensor-parallel-size权重切到几张卡等于可见 GPU 数单卡填 1max-model-len单请求最大上下文越大 KV cache 占用越高按业务实际需要设gpu-memory-utilization预分配的显存比例0.850.95留一点给驱动enable-prefix-caching复用公共前缀的 KV多请求共享同一 system prompt 时必开max-num-seqs同时处理的请求数显存紧张就调小避免频繁抢占--served-model-name是给客户端用的别名写死一个稳定名字后面换底层模型时业务代码不用改。3.4 显存不够时的量化取舍与排错参数量BF16 权重Q4_K_M 权重建议显存7B约 15 GB约 4.5 GB8 GB14B约 28 GB约 9 GB16 GB32B约 64 GB约 20 GB24 GB 起70B约 140 GB约 42 GB双卡 48 GB 起上表只算权重实际还要加上 KV cache 和框架开销。常见故障有三类启动即 OOM先把max-model-len砍半再试输出重复或断句异常通常是量化损失叠加 temperature 过低把温度提到 0.6 左右观察首 token 延迟几十秒多半是模型被换出显存检查 keep-alive 或并发数是否超了。4. 把 DeepSeek 接进开发工具链VSCode、Claude Code 与企业微信4.1 vscode 接入 deepseek 的补全与对话配置VSCode 里接入不需要自己写插件用支持自定义 OpenAI 兼容端点的助手类插件即可。核心是三件事填对apiBase、填对模型名、把上下文长度写准。name: deepseek-local version: 0.0.1 models: - name: DeepSeek Chat provider: openai model: deepseek-chat apiBase: https://api.deepseek.com/v1 apiKey: sk-你的Key roles: [chat, edit, apply] defaultCompletionOptions: contextLength: 65536 maxTokens: 2048contextLength填小了插件会频繁裁剪文件内容补全看起来变傻填大了超出服务端窗口会直接报错。字段名在不同插件版本间有差异以当前版本的配置文档为准别硬抄旧博客。改完配置后先在对话面板发一句读一下当前文件并说明它的职责能读全文件就说明上下文生效了。4.2 Claude Code 接入 DeepSeek 的协议转换层命令行编码工具大多走 Anthropic 的 Messages 协议而 DeepSeek 提供的是 OpenAI 协议两者结构不同Anthropic 的 system 是顶层字段content 支持块数组。常见做法是本地起一层轻量转换把/v1/messages转成/chat/completions。from fastapi import FastAPI, Request import httpx app FastAPI() UPSTREAM https://api.deepseek.com/v1/chat/completions app.post(/v1/messages) async def messages(req: Request): body await req.json() key req.headers.get(x-api-key) or \ req.headers.get(authorization, ).replace(Bearer , ) msgs [] if body.get(system): # Anthropic 顶层 system 要下沉 msgs.append({role: system, content: body[system]}) for m in body.get(messages, []): msgs.append({role: m[role], content: m[content]}) async with httpx.AsyncClient(timeout180) as c: r await c.post( UPSTREAM, json{model: deepseek-chat, messages: msgs, max_tokens: body.get(max_tokens, 2048), stream: False}, headers{Authorization: fBearer {key}}, ) text r.json()[choices][0][message][content] return { id: msg_local, type: message, role: assistant, model: deepseek-chat, stop_reason: end_turn, content: [{type: text, text: text}], usage: {input_tokens: 0, output_tokens: 0}, }客户端侧只要把 BASE_URL 指向本地 8082 端口AUTH_TOKEN 留 DeepSeek 的 Key 即可export ANTHROPIC_BASE_URLhttp://127.0.0.1:8082 export ANTHROPIC_AUTH_TOKENsk-你的DeepSeekKey export ANTHROPIC_MODELdeepseek-chat这层转换只覆盖文本对话工具调用和流式事件需要单独补。如果用的是走 OpenAI 协议的 CLI 编码工具就不必转换把 base_url 换成https://api.deepseek.com/v1直接可用。4.3 企业微信接入 deepseek 的消息回调链路企业微信自建应用接收消息有个硬约束回调必须在 3 秒内响应否则会重试重试会导致同一条消息被处理多次。所以正确链路是先落库、立即返回空串再用客服消息接口把模型结果异步推回去。环节关键动作注意点验签解密校验 msg_signature解密 Encrypt用官方库处理别手写立即响应返回空字符串超 3 秒必然触发重试异步推理队列里调 DeepSeek按用户维度做去重结果回推调消息推送接口超过 48 小时窗口无法主动推送app.post(/wecom/callback) async def callback(request: Request): xml await request.body() msg parse_and_decrypt(xml) # 官方库验签 解密 enqueue(user_idmsg.FromUserName, textmsg.Content) # 只入队不阻塞 return # 必须立即返回否则重试消息按用户维度做幂等去重、推理放在独立 worker 里跑这两条比模型选型更影响实际体验。群聊场景还要处理 机器人 的触发判定否则会把所有闲聊都送进模型。5. 长对话治理达到对话长度上限后的续接与导出5.1 deepseek 达到对话长度上限怎么办网页版弹出达到对话长度上限请开启新对话本质是上下文窗口被占满了。直接重开新对话会丢掉前文约束比较稳的做法是主动滚存把靠前的轮次压缩成一段事实摘要塞进新会话的 system 位置只保留最近几轮原文。def rollover(client, history, keep_last4): 旧轮次压缩成摘要保留最近几轮原文成本远低于全量重放 old, recent history[:-keep_last], history[-keep_last:] digest client.chat.completions.create( modeldeepseek-chat, messages[ {role: system, content: 把以下对话压缩成不超过 300 字的事实清单 保留结论、约束条件、未决问题和命名约定}, *old, ], temperature0.2, max_tokens600, ).choices[0].message.content return [{role: system, content: f历史会话摘要\n{digest}}] recent关键在摘要提示词要显式要求保留约束条件和命名约定否则模型倾向于只留结论重开会话后变量命名、技术栈偏好全丢。keep_last一般取 35太少会丢语境太多摘要没意义。5.2 deepseek 导出后如何切成可检索片段把长对话导出成 markdown 之后不要整份塞进新会话按轮次切分再按需召回更省 tokenimport re, json def split_turns(md_text): # 以 ### 用户 / ### 助手 之类的分隔标记切轮次 blocks re.split(r\n(?###\s), md_text) out [] for b in blocks: lines b.strip().splitlines() if not lines: continue role user if 用户 in lines[0] else assistant out.append({role: role, content: \n.join(lines[1:]).strip()}) return out turns split_turns(open(chat_export.md, encodingutf-8).read()) json.dump(turns, open(turns.json, w, encodingutf-8), ensure_asciiFalse, indent2)切完之后每轮单独算 token超过阈值的轮次做二次切分检索时只带最相关的两三段进上下文比整份重放节省一个数量级的输入。5.3 用 token 计数验证上下文有没有被浪费判断上下文是否被无效占用最快的办法是统计每类消息占的 token 占比。system 和工具描述占比超过三成就该精简历史轮次占比过高就该触发上面的滚存逻辑。每次调用把usage落到日志表里按天聚合输入输出的缓存命中率能直接反映 system prompt 是否稳定——命中率突然掉到零通常是有人往前缀里塞了时间戳。本文还有配套的精品资源点击获取