简介：这份PDF由清华大学新闻与传播学院新媒体研究中心整理，以DeepSeek-R1开源推理模型为主线，系统展示智能对话、文本生成、代码补全、知识推理、联网搜索与文件读取等能力，并专门对比了推理模型与非推理模型在快慢思考、创造力、决策能力上的差异。资源面向AI研发工程师、NLP学习者及技术爱好者，既帮助理解AGI大模型原理，也从任务类型出发给出模型选择与提示语设计策略，包含常见的角色扮演、分解提问等误区规避方法，可直接用于日常开发、学术研究和内容创作。文件为1个PDF，大小4.83MB，内容从DeepSeek是什么、能做什么到如何从入门到精通层层展开，配有大量场景示例与提示语对比，便于对照实践。已有590人学习下载，适合希望系统掌握DeepSeek的读者。
1. 从开源模型到能跑的业务系统：DeepSeek 到底给了我们什么
做过私有化部署的人都有体会：评估一个开源大模型，最怕的不是模型效果差，而是文档只讲“多厉害”，不讲“怎么跑起来”。这篇笔记要解决的正是这件事——把清华大学 DeepSeek 这个通用人工智能开源项目，从“看新闻”变成“能跑、能接、能调”。它不只是一组模型权重，而是一条完整的工具链：开源模型、官方 API、社区部署方案，以及围绕它长出来的 Agent 和编码工具生态。适合正在做技术选型、打算本地部署或想接 API 的工程师。先给结论：DeepSeek 的实用价值不在“最强”，而在“开源 + 便宜 + 兼容 OpenAI 接口”这个组合，让中小团队第一次有了认真做私有化落地的底气。
2. 开源的 DeepSeek 模型家族：先选对模型，再谈部署
很多人第一次接触 DeepSeek，以为它就是“一个对话机器人”，打开官网聊两句就完了。真正做工程的人必须先把模型家族摸清楚，因为不同模型的架构、推理成本和适用场景差别非常大，选错模型直接决定你是花几千块还是几十万块把事办成。
2.1 模型矩阵：Chat、Reasoner、Coder、VL 分别在什么场景扛活
DeepSeek 开源的不只是一个模型，而是一族模型，各自有明确的分工。我先列一个自己常用的对应关系，这也是社区里被验证过的选型思路：
- deepseek-chat：通用对话模型，日常问答、文案、翻译、代码解释这些常规任务都用它。响应速度快，成本最低，适合做业务系统的默认模型。
- deepseek-reasoner：推理增强模型，数学、逻辑、复杂代码设计、多步规划这类任务表现明显更强。代价是推理时会生成一段思维链，响应时间更长，token 消耗更大。
- DeepSeek-Coder：代码专项模型，在代码补全、跨文件理解、仓库级代码生成上专门优化过。做编码助手类产品时它比通用模型更稳。
- DeepSeek-VL：多模态模型，能处理图片输入，但文本能力弱于同代语言模型。需要图像理解功能时才考虑它。
- 蒸馏小模型系列：从 1.5B 到 70B 的多档位开源权重，适合本地部署、边缘设备、离线环境。
这个矩阵说明一件事：DeepSeek 的设计思路不是“一个模型通吃一切”，而是把不同成本档位的模型铺开，让开发者按场景选。我在实际项目里的做法是：默认对话走 deepseek-chat，遇到数学推理或复杂逻辑问题再切 deepseek-reasoner，本地离线环境用蒸馏小模型，绝不拿一个模型扛所有需求。
2.2 MoE 架构与推理成本：为什么便宜还能打
DeepSeek 系列模型采用 MoE 架构，这叫混合专家架构。传统稠密模型处理每个 token 时，要把全部参数参与计算；MoE 模型则是把模型拆成多个“专家”子网络，输入每个 token 时由门控网络决定激活哪些专家。以公开的 V3 配置为例，模型总参数量达到数千亿级，但实际推理时只激活其中一小部分参数。
这个设计带来的直接收益是推理成本大幅下降。同样规模的稠密模型，部署需要整卡甚至多卡集群，而 MoE 模型在推理时的算力需求和显存占用要友好得多，这解释了为什么 DeepSeek 的 API 价格能压到很低——不是亏本补贴，是架构决定的成本优势。另外还配套了多头潜在注意力机制，压缩了 KV Cache 的占用，这直接影响上下文长度的部署成本。做技术选型时，别只看“多少亿参数”，要看“激活参数”和“KV Cache 开销”，这两个指标才是账单上的大头。
2.3 选型决策：按硬件、场景、响应速度怎么选
模型选型要落在具体约束条件上，我一般按三个维度卡：
- 硬件约束：单卡 16GB 以下，只看蒸馏小模型；单卡 24GB 到 48GB，跑 14B 到 32B 的量化版本；多卡集群，才考虑服务化部署大模型。
- 场景约束：实时对话选 Chat，离线批量推理选小模型，复杂推理任务选 Reasoner，代码生成选 Coder。
- 响应速度约束：Reasoner 的思维链会带来明显延迟，对响应时间敏感的交互场景要把这个因素算进去，不能只看效果。
| 场景 | 推荐模型 | 部署形态 | 说明 |
|---|---|---|---|
| 业务系统默认问答 | deepseek-chat | API 调用 | 成本低、响应快 |
| 数学/逻辑/复杂推理 | deepseek-reasoner | API 调用 | 思维链长，延迟可接受 |
| 本地离线编码助手 | DeepSeek-Coder 蒸馏版 | Ollama / vLLM | 看显存选 7B~32B |
| 嵌入式/边缘设备 | 1.5B~7B 蒸馏版 | 端侧推理 | 需量化到 INT4 |
| 私有代码库处理 | deepseek-chat + RAG | 私有化部署 | 数据不出内网 |
选型这件事上没有“最好的模型”，只有“最合适的档位”。我见过不少团队一上来就部署最大的模型，结果显存不够、并发上不去、成本爆炸，最后退回到小模型反而跑得挺好。
3. 本地部署 DeepSeek：显存预算与两条可复现路径
本地部署是 DeepSeek 开源项目里被问得最多的需求。尤其是数据敏感行业或离线环境，API 调用不满足合规要求时，本地部署几乎是唯一选择。但本地部署的第一个门槛不是模型效果，而是显存——显存算不明白，后面全是坑。
3.1 显存预算是第一步：量化等级和卡的关系
模型权重占用的显存有个粗算公式：参数量乘以每个参数的字节数。FP16 精度下每个参数占 2 字节，INT8 占 1 字节，INT4 占 0.5 字节。以 32B 模型为例，FP16 权重约 64GB，单张 80GB 的卡勉强放得下，算上推理时的 KV Cache 和中间激活，实际占用会再上浮 20% 到 40%。如果做 INT4 量化，权重降到约 16GB 到 20GB，一张 24GB 的消费级卡就能跑。
| 模型规模 | FP16 权重约需 | INT8 约需 | INT4 约需 | 推荐硬件 |
|---|---|---|---|---|
| 7B | 14GB | 7GB | 4GB | 8GB 以上显卡 |
| 14B | 28GB | 14GB | 8GB | 16GB 以上显卡 |
| 32B | 64GB | 32GB | 16GB | 24GB 以上显卡 |
| 70B | 140GB | 70GB | 35GB | 多卡或 80GB 单卡 |
注意这里的数值只算权重，没算上下文缓存。把上下文设到 32K 时，KV Cache 可能再吃掉几个 GB 到几十个 GB。我的建议是：先确定业务需要的上下文长度，再反推显存预算，最后才决定量化档位。顺序反了，大概率要返工。
3.2 个人机路径：用 Ollama 跑通最小命令
个人电脑和开发机上最省事的部署方式是 Ollama，它把模型下载、量化、运行封装成一条命令，内置 OpenAPI 兼容接口，对新手极其友好。我一般在拿到新机器时先跑通这一步，确认模型效果满足需求，再上 vLLM 做服务化。
# 拉取并运行 DeepSeek-R1 的 7B 蒸馏版 # 首次运行会自动下载模型，需要耐心等待 ollama run deepseek-r1:7b这条命令会做三件事：从模型仓库拉取对应权重、自动选择量化版本（通常是 Q4_K_M 附近）、启动一个本地交互对话。过程中可以直接在终端里输入问题测试效果，不需要写任何代码。确认模型正常后，可以用另一个命令查看本地已有的模型列表：
# 查看本地已安装的模型 ollama listOllama 默认监听 11434 端口，并且提供 OpenAI 兼容接口，这意味着本地跑起来的模型可以直接被支持 OpenAI SDK 的应用调用：
# 验证 Ollama 的 OpenAI 兼容接口是否可用 curl http://localhost:11434/v1/models对这个接口看到模型列表，说明整个链路已经通了。值得说明的是，Ollama 适合单机调试、个人使用、小团队试用，它帮你把复杂的事情藏起来了，但代价是并发能力、吞吐控制和精细参数调优都受限。真要面向业务做服务，还是得看 vLLM。
3.3 服务化路径：用 vLLM 部署并暴露 OpenAI 兼容接口
当 Ollama 满足不了并发和吞吐要求时，vLLM 是我目前用得最顺手的方案。它是专门为大模型推理优化的服务框架，核心卖点是 PagedAttention 显存管理，能把显存利用率提到很高，吞吐量通常比朴素的实现提升数倍。部署步骤也不复杂：
# 创建独立环境并安装 vLLM python -m venv .venv && source .venv/bin/activate pip install vllm # 启动 OpenAI 兼容服务 python -m vllm.entrypoints.openai.api_server \ --model deepseek-ai/DeepSeek-R1-Distill-Qwen-14B \ --tensor-parallel-size 1 \ --max-model-len 8192 \ --gpu-memory-utilization 0.9 \ --port 8000这里几个参数是按生产要求设的，逐个说明：--model指定模型名称，这里用的是 14B 蒸馏版，你换成自己需要的模型 ID 即可；--tensor-parallel-size是张量并行的 GPU 数量，单卡填 1，多卡按卡数填；--max-model-len设置最大上下文长度，不要贪大，按业务实际需要设，这直接决定 KV Cache 占用；--gpu-memory-utilization 0.9允许 vLLM 使用 90% 的显存，预留一部分给 CUDA 上下文和其他进程。启动后验证服务：
curl http://localhost:8000/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "deepseek-ai/DeepSeek-R1-Distill-Qwen-14B", "messages": [{"role": "user", "content": "用 Python 写一个二分查找"}], "max_tokens": 512 }'看到正常返回 JSON 结果，说明服务已经就绪。此时它提供的接口和 OpenAI 的/v1/chat/completions格式完全一致，任何支持 OpenAI 协议的工具都能直接接入，不用改业务代码。这是整个开源生态里最有价值的设计——工具生态是现成的，DeepSeek 只是把底座换掉了。
4. 调用 DeepSeek 的 API：官方接口与常见工具接法
本地部署解决的是私有化和成本问题，但很多时候官方 API 反而是更务实的选择：不用管运维、不用买显卡、按量付费。DeepSeek 的 API 兼容 OpenAI 协议，所以调用方式几乎没有学习成本。这一章把 API 调用和常见开发工具的接法讲透。
4.1 最直接的调用：Python 和 curl 两种写法
Python 侧我推荐直接用 OpenAI 官方 SDK，因为 DeepSeek 的接口协议完全兼容，只需要改 base_url 和 api_key 即可。这是最小可用的调用示例：
# 使用 OpenAI SDK 调用 DeepSeek 官方 API from openai import OpenAI # api_key 从 DeepSeek 开放平台获取，建议用环境变量传递，别写死在代码里 client = OpenAI( api_key=os.getenv("DEEPSEEK_API_KEY"), base_url="https://api.deepseek.com" ) resp = client.chat.completions.create( model="deepseek-chat", messages=[ {"role": "system", "content": "你是一个嵌入式 C 语言专家"}, {"role": "user", "content": "解释一下 volatile 关键字，给出使用场景"} ], temperature=0.3, max_tokens=1024, stream=False ) print(resp.choices[0].message.content)model参数的选择很关键，前面讲过 deepseek-chat 和 deepseek-reasoner 的分工，日常任务用 chat 即可。temperature控制随机性，代码和技术问答任务我习惯设 0.3，避免输出过于发散。max_tokens限制最大生成长度，防止模型“说个没完”。stream参数控制是否流式返回，需要打字机效果或处理超长输出时设为 True。
curl 写法适合快速验证接口连通性和做脚本调试：
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": "用一句话解释什么是死锁"}], "max_tokens": 256, "temperature": 0.7 }'接口返回的 JSON 结构里，choices[0].message.content是生成结果，usage字段包含 prompt_tokens、completion_tokens 和 total_tokens，做成本统计时一定要把这个字段记下来。我见过不少团队上线后才意识到 token 用量没监控，月底账单出来直接傻眼。
4.2 四个必调参数：temperature、top_p、max_tokens、stream
这四个参数是每次调用都要过一遍脑子的，不是随便填了就行。temperature 控制随机性，值越高输出越发散，代码任务压到 0.2 到 0.4，创意写作可以放到 0.8 以上。top_p 是核采样参数，控制候选 token 的累积概率，官方建议是 temperature 和 top_p 不要同时调，固定其中一个、微调另一个即可。max_tokens 决定生成上限，按任务预期长度设，别贪大，生成超长内容既费钱又费时间。stream 决定是否流式返回，实时交互场景建议开，离线批处理可以关。
| 参数 | 范围 | 推荐值 | 场景说明 |
|---|---|---|---|
| temperature | 0~2 | 0.3（代码） | 0.2~0.4 技术任务，0.8+ 创意任务 |
| top_p | 0~1 | 默认即可 | 不要与 temperature 同时大改 |
| max_tokens | 1~8192 | 按需 | 代码 512~1024，长文 2048+ |
| stream | true/false | 交互开 | 流式提升首字响应体验 |
一个重要细节：deepseek-reasoner 模型对 temperature 有限制，官方建议设 0.6，调太高会让推理过程失控。这个模型和 chat 模型在参数行为上有不少差异，后面避坑章节细说。
4.3 把 DeepSeek 接进 VSCode、Cline、Codex：配置怎么写
DeepSeek 接入编码工具是最近社区里最热门的玩法。思路都差不多：工具的 API 配置指到 DeepSeek 的接口地址即可，因为协议兼容。以 Cline 这类 VSCode 编码插件为例，在设置里填入对应的 base URL 和 API Key：
# 以 Cline 插件为例的配置思路 API Provider: OpenAI Compatible Base URL: https://api.deepseek.com 或本地 vLLM 地址 API Key: 你的密钥 Model ID: deepseek-chat 或本地模型名用本地部署的 vLLM 服务时，配置方式同样简单，把地址换成自己的服务就行：
# 让 OpenCode / Codex 类命令行工具指向本地 vLLM 服务 export OPENAI_API_KEY="sk-local" export OPENAI_BASE_URL="http://localhost:8000/v1"这样做的好处很实际：代码仓库不出内网，敏感代码不会被送到外部服务；同时 API 费用变成一次性硬件投入，长期使用成本可控。我目前的主力编码工作流就是本地 vLLM 服务加编辑器插件，配合 DeepSeek-Coder 蒸馏模型，效果接近云端 API，但延迟和隐私都可控。
5. DeepSeek 实战避坑：四条让我返工的血泪经验
这一章写的都是我自己在实际部署和调用中踩过的坑，每条都花了不少时间排查。按“现象、原因、解决”三段式写清楚，希望能让你少走弯路。
5.1 上下文一长显存就爆：真正吃掉显存的是 KV Cache
现象：本地部署后，短对话一切正常，上下文超过一定长度后显存占用暴涨，随后直接 OOM，服务崩溃。明明模型权重才占了一半显存，为什么长对话就扛不住了？
原因：推理时每个 token 都会产生对应的 Key 和 Value 缓存，供后续注意力计算复用。上下文越长，KV Cache 越大，而且它是按 token 数线性增长的。模型权重是固定开销，KV Cache 才是动态的大头。
解决：先把--max-model-len按业务实际值设置，别贪大。其次用支持 KV Cache 量化的版本，vLLM 提供了相关参数可以将缓存压到 FP8，能显著降低长上下文的显存压力。最后，监控不能省：
# 用 nvidia-smi 实时观察显存变化 watch -n 1 nvidia-smi注意：
--max-model-len不是越大越好，它直接决定 KV Cache 的最大预分配空间。先统计业务里最长的真实对话长度，再加 20% 余量，这个值才是合理的。
5.2 “messages tool calls need immediate results”：Agent 循环的时序坑
现象：写 Agent 应用做工具调用时，模型返回了 tool_calls，你把结果塞回对话再请求，结果报错提示 tool calls need immediate results，整个会话中断。
原因：这个报错的本质是时序问题。工具调用要求：assistant 返回 tool_calls 后，你必须立即把工具执行结果以 tool 消息形式传回，并且每条 tool 消息都要通过 tool_call_id 与对应的调用配对。常见的错误是把多条工具结果合并成一条消息，或者把历史消息截断导致配对信息丢失。
解决：严格按协议逐条处理，提供参考代码：
# 工具调用的正确姿势：逐条执行、逐条回传 resp = client.chat.completions.create( model="deepseek-chat", messages=messages, tools=tools ) msg = resp.choices[0].message if msg.tool_calls: # 完整的 assistant 消息先放回对话，保留 tool_calls 字段 messages.append(msg.model_dump()) for tc in msg.tool_calls: # 执行工具，拿到结果 result = run_tool(tc.function.name, tc.function.arguments) # 按 tool_call_id 配对回传，不能用数组顺序代替 messages.append({ "role": "tool", "tool_call_id": tc.id, "content": result }) # 所有工具结果回传后，立刻发起第二次请求 resp = client.chat.completions.create(model="deepseek-chat", messages=messages)关键就是tool_call_id必须一一对应，工具结果立即返回中间不能插其他请求。Agent 循环里最容易翻车的不是模型效果，而是这里的状态管理。
5.3 代码生成忽好忽坏：Reasoner 模型跟 temperature 不兼容
现象：本地部署蒸馏的 R1 模型生成代码，有时答案很漂亮，有时逻辑混乱、重复输出，甚至思维链部分和最终答案混在一起。同一个 prompt 反复测试，结果不稳定。
原因：Reasoner 系列模型在训练时使用了强化学习，输出风格与普通 chat 模型差异很大。这类模型对采样参数非常敏感，temperature 调高了，思维链部分就会发散、重复；同时它的输出里会包含完整的推理过程，max_tokens 设置不够时，推理过程直接挤占最终答案的空间。
解决：deepseek-reasoner 模型的 temperature 固定为 0.6，不要为了“更随机”往上调。代码任务如果对响应格式有强要求，优先选 deepseek-chat 而不是 reasoner。另外给 reasoner 留足 max_tokens，比如同样写一个算法题，chat 模型 512 token 够用，reasoner 可能要 1024 到 2048，要算上思维链开销。
5.4 本地服务并发上不去：瓶颈不在显存而在调度
现象：本地 vLLM 服务部署好后，单请求响应正常，但多人同时使用时长连接排队、请求超时，显存明明还有剩余。
原因：并发瓶颈通常是 vLLM 内部的调度配置，比如最大并发序列数、KV Cache 预分配策略、连续批处理窗口等。显存有余量不代表能同时处理更多请求，调度参数限制了实际并发。
解决：按需调整 vLLM 的并发参数，比如增大最大序列数，同时限制单请求的上下文长度，让更多请求能挤进批处理窗口。应用层也要加超时和重试机制：
# 本地服务调用建议加超时控制，避免线程阻塞 resp = client.chat.completions.create( model="deepseek-ai/DeepSeek-R1-Distill-Qwen-14B", messages=messages, max_tokens=1024, timeout=120 )部署服务前先用压测工具测一下并发上限，别等线上告警才回头调参。本地部署的收益是数据可控、边际成本低，代价是运维和调优都得自己来，这块不能偷懒。
6. 部署完之后：用评测脚本和调优习惯守住质量
模型部署完成只是起点，真正考验工程能力的是上线后的持续调优。我习惯在部署第一天就写好一个评测脚本，每轮改动后跑一遍，把质量波动控制在可见范围内。参考做法：
# 简单的质量和延迟评测脚本，用于部署后的回归验证 import time from openai import OpenAI client = OpenAI( base_url="http://localhost:8000/v1", api_key="sk-local" ) cases = [ {"q": "用 python 写一个快速排序", "keyword": "def quick_sort"}, {"q": "解释 TCP 三次握手", "keyword": "SYN"}, {"q": "如何避免 Python 列表遍历时修改元素", "keyword": "副本"}, ] for case in cases: start = time.time() resp = client.chat.completions.create( model="deepseek-ai/DeepSeek-R1-Distill-Qwen-14B", messages=[{"role": "user", "content": case["q"]}], max_tokens=1024, temperature=0.6 ) elapsed = time.time() - start text = resp.choices[0].message.content hit = case["keyword"] in text print(f"{case['q'][:20]}... 耗时 {elapsed:.1f}s | 命中: {hit}") print("token 用量:", resp.usage.total_tokens)这个脚本每次改动模型、参数或提示词后跑一遍，能快速发现回退。除了脚本，我有三条调优习惯：第一，每个业务场景固定一套参数，用配置文件管理，不随手改；第二，system prompt 里给出明确格式约束，比如“只输出 JSON 结构，不要多余解释”，能省大量 token 和解析成本；第三，上线前统计业务最大上下文长度，超出部分做截断或摘要，把成本控制住。最早我把 max_tokens 设得很大，结果等半天、账单翻倍，后来才意识到先问自己“这次回答最长该是多少”。这些毛病都是烧钱烧出来的。希望帮到你。
本文还有配套的精品资源，点击获取
