DeepSeek工程实践：模型选型、提示词模板与长文档接入

简介围绕清华大学新闻与传播学院新媒体研究中心团队整理的《DeepSeek从入门到精通》PDF讲义内容面向大模型初学者、开发者以及内容与产品从业者帮助读者系统认识DeepSeek-R1的能力边界、适用场景与使用方法并回应推理模型选型、提示语设计等常见问题。压缩包内共1个PDF文件大小约5.5MB便于直接阅读和检索。已有1873人学习下载具备一定参考热度。讲义从“DeepSeek是什么、能做什么、如何使用”展开覆盖智能对话、文本生成、语义理解、计算推理、代码生成补全等应用并进一步比较推理模型与通用模型在优势领域、决策方式、创造力及人机互动上的差异。读者还可了解快思慢想、CoT链式思维、提示语策略差异以及数学证明、创意写作、代码生成等任务对应的提示语设计原则并沿入门到精通路径建立较完整的实践框架。1. 从一份 PDF 到一条能跑的工作流这份手册到底解决什么问题某高校那份《DeepSeek 从入门到精通》PDF 传开之后我身边大多数人的动作是一样的存进网盘再也没打开过。这类「从入门到精通」的文档真正的价值不在于讲了多少新概念而在于它把模型分类、提示词写法和接入参数按一条能落地的顺序串起来了——从入门到精通这条路上卡住人的往往不是「不会提问」而是不知道什么时候该上推理模型、哪些参数调了有用、几十页的 PDF 到底怎么喂进去。这篇笔记就按这个骨架往下走讲清楚三件事模型怎么选、提示词怎么固化成模板、工程里怎么接。适合已经能把模型跑通、但输出质量忽高忽低、每次都要重调一遍的人。2. 手册里最容易被跳过的一页DeepSeek 的模型谱系与选型决策表2.1 通用模型和推理模型不是二选一而是两段流水线接口里最常见的两个模型标识一个是通用对话模型一个是推理模型。很多人第一次接触时的直觉是「推理的肯定更强那就全用推理的」这是第一个坑。推理模型在给出答案前会先生成一大段思考内容这段思考同样按 token 计费、同样占用延迟在信息抽取、格式转换、简单分类这类任务上它不但不快还容易把一句本来该直接给结果的话讲成三百字的分析过程。反过来全用通用模型也不行。凡是需要多步约束同时满足的任务——比如「从这段配置里找出三处互相冲突的设置并按优先级给出修改顺序」——通用模型经常只满足其中两条就收工。这不是模型能力问题是这类任务本身需要显式的中间推理步骤而通用模型不会主动展开。所以合理的结构是级联不是二选一前面用通用模型做清洗、抽取、意图分类、任务拆解这些便宜的活把真正需要深推理的那一两步单独路由给推理模型。我一般把这条规则写在代码里而不是写在文档里因为人一旦赶进度就会图省事全用推理模型成本翻几倍还不自知。提示推理模型的思考过程在返回结构里通常是单独字段常见字段名带 reasoning 前缀正文在常规的 content 字段里。解析时只取 content否则你会把思考过程当成答案传进下游。2.2 用一张参数对照表把「选哪个」变成可执行判断选型判断光靠感觉没用落到表格上才能复用。下面这张表是我自己在项目里用的版本左边是任务特征右边是可执行的结论任务特征首选模型关键理由常见错配后果批量字段抽取、格式转换通用模型单步映射无需推理用推理模型延迟翻倍、成本翻倍意图分类、路由判断通用模型类别有限短输出同上且输出啰嗦影响解析文案改写、润色、扩写通用模型需要风格稳定可控推理模型会自作主张改结构多约束规划、方案权衡推理模型需要显式比较多个条件用通用模型会漏约束数学计算、逻辑推演推理模型中间步骤必须展开通用模型容易在第二步就跑偏代码报错定位与修复推理模型需要沿着调用链回溯通用模型常给出「检查一下配置」这类废话长文档问答通用模型 检索瓶颈在召回不在于推理直接上推理模型答非所问且更慢采样参数这块的差异更容易被忽略。通用模型支持 temperature、top_p、频率惩罚这些采样参数推理模型在多数实现里会对这些参数不生效或者直接忽略——你把它设成 0.1 期待输出稳定结果发现该变的还是变然后开始怀疑是不是「玄学」。这不是玄学是参数根本没起作用。推理模型的稳定性靠的是推理路径本身不靠采样温度。参数常见取值范围抽取/代码场景文案场景说明temperature0 ~ 20 ~ 0.30.8 ~ 1.2越低越确定推理模型上通常无效top_p0.1 ~ 10.90.95与 temperature 二选一调不要同时大改max_tokens按任务定512 ~ 10241024 ~ 2048推理模型要把思考 token 也算进预算streamtrue / false交互式界面用 true同左批处理用 false省去拼装逻辑timeout30 ~ 120 秒6060推理模型务必放宽别用默认值2.3 把选型结论写进配置一份可复用的路由表光有表没用人的记忆靠不住。我一般把路由规则写成一份配置用规则先粗分只有规则判不准的才交给模型判断这样能省掉一次额外调用。# router.py # 用一个轻量规则表决定走哪个模型避免每次都靠人回忆 import os # 模型标识以你接入时文档给出的为准这里用两个语义化的键 MODEL_CHAT os.environ.get(DS_MODEL_CHAT, chat) # 通用对话模型 MODEL_REASON os.environ.get(DS_MODEL_REASON, reason) # 推理模型 # 命中关键词即走高推理路径关键词宁少勿多多了等于全走推理 REASON_HINTS (证明, 为什么, 冲突, 权衡, 报错, 定位, 几步, 推导) def pick_model(task: str, text: str ) - str: task: 任务类型标签如 extract / rewrite / plan / debug text: 原始输入用于关键词兜底判断 返回模型标识 # 1) 任务类型优先这一类是稳定的、可预期的 if task in (plan, debug, reason): return MODEL_REASON if task in (extract, rewrite, classify, summarize): return MODEL_CHAT # 2) 任务类型未知时看输入里有没有强推理信号 if any(h in text for h in REASON_HINTS): return MODEL_REASON # 3) 兜底走便宜的那个错了再升级 return MODEL_CHAT这段代码的逻辑是三级判断任务标签最可靠放在第一优先级关键词是兜底只在任务标签缺失时启用最后一级永远返回通用模型保证默认成本最低。参数说明两点。第一REASON_HINTS不要堆太多词我见过有人塞了四十个关键词结果 80% 的请求都路由到推理模型等于没做路由。控制在十个以内只保留那些「出现就一定需要多步推理」的词。第二模型标识用环境变量读不要硬编码在源码里换接入方或者换模型版本时只改环境变量不用全文搜索替换。这套路由跑一周之后你会看到两个数推理模型的调用占比和整体延迟。占比超过 30% 基本说明关键词表太宽或者任务标签设计得太粗需要回头拆任务类型而不是继续加机器。3. 提示词从「聊天」到「可复用模板」DeepSeek 上的四段式写法3.1 同一问题问两遍差一个量级差在哪新手最典型的提问方式是「帮我看看这段代码有什么问题」。这句话里有三处缺失没有说明运行环境没有说明期望行为没有说清输出要什么形式。模型只能猜猜的结果就是你问十次得到十种答案然后归因成「模型不稳定」。我做过一个很朴素的对比同一段有边界问题的分页代码用开放式提问模型会给五六条泛泛的建议其中两条跟实际 bug 无关换成结构化提问明确说「只找数组越界和空值两类问题每条给出出错行号、触发条件、修复代码」输出立刻收敛到两条而且都能直接改。差别不在模型在提问里有没有把「验收标准」写出来。还有一个隐藏变量是上下文长度。对话越长前面随手说的话越容易污染后面的判断。这也是为什么模板要固化——模板是每次都从干净状态开始的不受上一轮对话残留影响。3.2 角色、约束、输入、验收四段式模板拆解四段式的顺序是有讲究的不是随便排的。角色决定语气和知识边界约束决定输出范围输入决定事实来源验收决定输出形态。四个都缺一个输出就会在某个维度上漂。段落写什么常见反例改成这样角色身份 服务对象 专业边界「你是一个专家」「你是一名做后端接口评审的工程师服务对象是刚接手项目的初级开发」约束必须做 / 禁止做 / 信息不足怎么办「回答要准确」「只基于我给出的日志判断日志里没出现的信息标注为未知不要推测」输入数据本体 明确分隔符直接把内容粘在后面用固定标签包住如log.../log并在提示里指明标签名验收输出格式 字段 长度 失败处理「给我一个结论」「输出 JSON字段为 cause、evidence、fix证据不足时 cause 填 unknown」约束那一段有个经验写「要做什么」比写「不要做什么」有效得多。你写十条「不要编造」模型该编还是编你写一条「每个结论后面必须跟原文引用找不到引用就输出 unknown」编造率立刻下来。因为前半句是禁止后半句是可执行的检查动作。输入段的分隔符别省。用 XML 风格的标签把数据包起来模型对标签边界的识别比空行可靠得多尤其是输入里本身混着代码和自然语言的时候。标签名用语义化的code、error_log、user_feedback别用data1。验收段最容易漏的是失败路径。任何抽取类任务都要显式规定「抽不到怎么办」否则模型会用编造来填满字段这在批量跑的时候是灾难——你拿到一千条结果没法分辨哪条是真的。3.3 把模板固化成函数与文件避免每次手敲模板写在聊天框里第二次用就变形了。我一般把它落到文件里代码里只做变量替换。# prompt_tpl.py # 模板与代码分离改提示词不用改业务逻辑也不用重新部署 from string import Template EXTRACT_TPL Template( 你是做接口日志分析的工程师服务对象是刚接手项目的初级开发。 约束 1. 只依据 log 标签内的内容判断标签外的一切不作为证据。 2. 每条结论必须引用日志中的原文片段引用不到的结论不要给。 3. 信息不足时对应字段填 unknown不要推测。 输入 log $log_text /log 验收 输出 JSON字段为 cause根因一句话、evidence原文引用可为空数组、 fix修复建议不超过三条。不要输出 JSON 以外的任何内容。 ) def build_extract_prompt(log_text: str) - str: # safe_substitute 避免日志里出现 $ 符号时抛异常 return EXTRACT_TPL.safe_substitute(log_textlog_text)这里用Template而不是 f-string是因为日志里经常出现$、{}这类字符f-string 会直接抛 KeyError 或者把花括号吃掉这个坑我踩过一次排查了半小时才发现是模板引擎的问题。safe_substitute遇到未定义的占位符不会报错代价是拼错了变量名也不会提醒你所以变量名要统一我一般全用_text后缀。模板文件要进版本管理每次改动留一条注释说明为什么改。原因是提示词改动的影响不像代码那么直观你以为只是加了一句话实际可能让某类输入的抽取率掉十个点。有版本记录出问题能回滚这就是提示词的后悔药。4. 接进工程DeepSeek 的调用脚本、流式输出与长文档链路4.1 最小可跑通的调用脚本与五个必调参数接入层没什么神秘主流做法是按 OpenAI 兼容协议调SDK 换一下 base_url 和 key 就能用。下面是最小可跑通的一段重点是那几个参数怎么设。# client_demo.py import os from openai import OpenAI client OpenAI( api_keyos.environ[DS_API_KEY], base_urlos.environ[DS_BASE_URL], # 填接入方给你的地址 timeout60.0, # 推理模型要给足默认值经常不够 max_retries2, # SDK 自带重试别自己再套一层 ) def ask(prompt: str, model: str, stream: bool False): resp client.chat.completions.create( modelmodel, messages[{role: user, content: prompt}], temperature0.2, # 抽取类任务压到 0.2 上下推理模型上通常无效 max_tokens1024, # 推理模型要把思考 token 算进预算别卡太死 streamstream, ) if stream: # 流式只拼 content推理字段不参与业务 for chunk in resp: delta chunk.choices[0].delta if getattr(delta, content, None): yield delta.content else: return resp.choices[0].message.content五个必调参数分别是 model、temperature、max_tokens、stream、timeout。timeout和max_retries是在客户端构造时设的很多人只在单次调用里设超时结果 SDK 层重试时用的还是默认值长任务照样断。max_tokens对推理模型尤其要放宽因为思考内容也算在里面卡 512 的话经常思考到一半就被截断返回的正文是空的——这个现象特别容易误判成模型故障。流式输出在交互界面上是刚需但批处理场景别开。流式意味着你要自己处理分片拼装、异常中断、半句话截断这些在批量任务里都是纯负担。我一般的做法是面向人的界面开流式面向管道的任务关掉。4.2 长 PDF 的分块、摘要与回填那份手册 PDF 本身就是个很好的测试样本——几十页、有表格、有代码片段。直接整篇塞进上下文有三个问题一是超窗口二是中间部分容易被忽略三是每次问答都全量计费。所以要分块。分块策略上按固定字数硬切是最省事也最差的做法它会把表格从中间劈开。我一般按标题层级切一级标题一 chunk二级标题再拆每个 chunk 控制在 800 到 1200 个 token相邻 chunk 留 100 到 150 的重叠防止一句话被切断导致语义丢失。表格单独抽出来走一条链路转成 Markdown 表格再喂比让它嵌在正文里识别率高得多。# chunk_and_summarize.py # 先切块再逐块摘要最后聚合避免一次性喂整篇 def split_by_heading(text: str, max_len: int 1000, overlap: int 120): 按标题行切分超长的再按长度兜底切保留重叠区 lines, chunks, buf text.splitlines(), [], [] for line in lines: # 遇到标题且当前缓冲区已经够长就落一块 if line.startswith(#) and len(\n.join(buf)) max_len: chunks.append(\n.join(buf)) # 重叠保留上一块的最后一段防止跨块语义断裂 buf [\n.join(buf)[-overlap:]] buf.append(line) if buf: chunks.append(\n.join(buf)) return chunks def summarize_each(chunks, ask_fn, model): 逐块摘要提示词里强制要求保留数字和专有名词 out [] for c in chunks: p (用三句话概括以下内容保留所有数字、参数名和结论性表述 不要评价不要补充原文没有的信息。\n\n c) out.append(ask_fn(p, modelmodel)) return out参数上有两个地方值得调。max_len不是越大越好一千 token 左右是实测下来召回和成本的平衡点超过两千之后单块的摘要质量反而下降因为模型开始抓不住重点。overlap不能省我见过有人设成 0结果每块开头都是半句话摘要出来的东西前言不搭后语。聚合那一步也有讲究。逐块摘要完成后不要简单拼接要让模型做一次归并去重因为相邻 chunk 的重叠区会产生重复结论。归并的提示词里加一句「相同结论合并为一条冲突的结论并列保留并标注来源块编号」能明显减少最终输出里的重复段落。4.3 延迟与成本一张能拿去做决策的对照表下面这张表是我自己压测后的相对关系绝对值会随接入方和时段变化看比例就够了链路相对延迟相对成本适用场景通用模型 短提示1x1x抽取、分类、改写通用模型 长文档全量3x ~ 5x4x ~ 6x不推荐改用检索推理模型 短提示4x ~ 8x3x ~ 5x规划、调试、复杂判断分块摘要 归并6x ~ 10x2x ~ 3x一次性处理长文档结果可复用检索 通用模型2x1.5x长文档高频问答首选省成本最有效的动作不是换模型是把稳定的前缀固定下来。系统提示、格式说明、示例这几段放在消息数组最前面且每次内容完全一致命中前缀缓存后这部分基本不重复计费。反过来说如果你每次都把时间戳、随机 ID 拼在提示开头缓存永远命不中成本会一直是满额。这个细节在手册里通常不会写但它对批量任务的花费影响是数量级的。5. 避坑排查五个「以为是模型不行」的现场5.1 推理模型返回一大段思考正文却是空的现象调用推理模型返回里有一大段分析过程但content字段是空字符串下游直接报错。原因有两个。最常见的是max_tokens设得太小思考过程把预算吃完了正文还没开始生成就被截断另一种是解析代码写错了把带 reasoning 前缀的字段当成正文取取到的是思考内容业务侧一判断格式不符就当成空。解决先把max_tokens提到 2048 以上复测一次能出正文就是预算问题。解析层统一只取content并且在取不到时显式判断finish_reason如果是长度截断就自动放大预算重试一次而不是直接把空串传下去。这个判断很便宜能挡掉大部分线上「模型答非所问」的假故障。5.2 JSON 解析十次错三次现象要求输出 JSON实际返回里混着「好的以下是结果」这种前缀或者末尾多一个逗号json.loads直接抛异常。原因一是没开结构化输出模式二是开了但提示里没出现 json 这个词、也没给字段样例模型不知道要遵守三是字段太多模型在中途开始自由发挥。解决先开结构化输出模式然后提示词里显式写「输出 JSON」并给一个两字段的极简样例字段控制在六个以内。解析层再包一层容错去掉代码块围栏、截取第一个左花括号到最后一个右花括号之间的内容、失败后带着错误信息重试一次。三层下来成功率能到 99% 以上剩下那 1% 走降级返回空结构不要让整批任务挂掉。5.3 长文档问答答非所问现象PDF 明明写了某个参数问它的时候答「文中未提及」或者答的是另一个章节的内容。原因多半是分块把相关内容切散了或者检索只按向量相似度召回把标题信息丢了。手册类文档尤其严重因为答案常常在表格里而表格在切块时经常被拆成几段。解决分块时给每块补上标题路径一级标题 / 二级标题这样即使内容被切散块本身还带着上下文表格单独抽取成 Markdown 后单独建索引召回改成「向量 关键词」双路参数名这种精确词走关键词路更靠谱。调完之后先别急着上线拿二十个已知答案的问题跑一遍看召回块里有没有正确段落没有就是切块问题有但答错才是模型问题。5.4 同一提示两次结果差很多现象完全一样的输入上午跑出来是 A下午跑出来是 B字段还少了一个。原因通用模型默认温度不低采样本身就带随机性另外提示里有隐含变量比如把当前时间、随机排序的候选列表拼进去了还有一种情况是对话历史被带上了上一轮的残留影响了这一轮。解决抽取类任务把温度压到 0.2 以下每轮请求都从干净的消息数组开始不复用历史排查时把完整请求体打日志对比两次的差异通常能立刻看到那个多出来的变量。这里有个血泪经验日志要打完整请求体只打提示词没用参数才是最常见的隐形变量。5.5 并发一上来就超时现象单条测试都正常压到二十并发之后大量超时和限流错误。原因没有客户端侧的限流SDK 自带的重试在高峰期会把请求放大越重试越堵另外推理模型的单次耗时本来就长连接池开得太小会排队。解决加一个令牌桶在调用前做限流超出配额的请求进队列而不是直接发重试改成指数退避加随机抖动别用固定间隔超时时间按模型分开配推理模型单独给到 120 秒。做之前先量一下 P95 延迟把并发数卡在系统能稳住的位置别追求峰值吞吐长任务场景下稳定比快重要。6. 把「精通」变成可验证20 条回归集怎么建、怎么跑调提示词最怕的是改完 A 场景好了、B 场景坏了而你只测了 A。这类问题的解法很土但管用建一个二十条左右的小回归集每次改提示词、换模型、调参数之前先跑一遍。回归集不用大关键在覆盖面。我的分法是四个维度每个维度五条维度条数覆盖内容通过标准正常输入5结构完整、信息齐全的典型样本字段齐全且值正确边界输入5空输入、超长输入、纯符号输入不崩溃返回明确的空结果标记信息缺失5关键字段缺失、内容自相矛盾缺失字段填 unknown不编造格式约束5要求 JSON、要求字数上限可被json.loads直接解析跑法上不要人工看写成脚本自动判定只把失败项打出来看。# regress.py # 只做机械判定能否解析、字段是否齐全、缺失项是否标 unknown import json def check(case: dict, output: str) - tuple[bool, str]: case 里有 expect_keys 和 allow_unknown 两个字段 try: # 去掉可能存在的代码块围栏再解析 raw output.strip().removeprefix(json).removeprefix().removesuffix() data json.loads(raw) except Exception as e: return False, f解析失败: {e} missing [k for k in case[expect_keys] if k not in data] if missing: return False, f缺字段: {missing} if case.get(allow_unknown) is False: # 明确不允许 unknown 的用例出现即失败用来抓编造 bad [k for k, v in data.items() if str(v).lower() unknown] if bad: return False, f不该出现 unknown 的字段: {bad} return True, ok def run(cases, ask_fn, model): fails [] for c in cases: ok, msg check(c, ask_fn(c[prompt], modelmodel)) if not ok: fails.append({id: c[id], msg: msg}) return fails这段代码的重点不在逻辑复杂度在于allow_unknown这个开关。大部分回归集只检查字段齐不齐结果模型学会了用 unknown 填满所有字段来骗过测试。给一部分用例设成不允许 unknown才能把编造行为抓出来。跑回归集的时机我定在三个节点改提示词之后、换模型标识之后、以及每周固定一次全量跑。前两个是必须第三个是为了抓那些不声不响的行为漂移——模型侧的小版本更新你未必能第一时间知道但回归集能。最后说个我的习惯每次回归集出现新失败先不要改提示词先把失败样本补进用例集再改。这样用例集是只增不减的半年之后它就是你手里最值钱的东西比任何一份「从入门到精通」的文档都贴近你自己的业务。真正让你从入门走到精通的不是把手册读完是手里有一套能随时告诉你「这次改动到底有没有变差」的尺子。希望帮到你。本文还有配套的精品资源点击获取