简介：PDF文档《DeepSeek：从入门到精通》由清华大学新闻与传播学院新媒体研究中心出品，面向AI研发工程师、NLP学习者与技术爱好者，系统讲解DeepSeek-R1开源推理模型在智能对话、文本生成、代码生成、知识推理等任务中的具体用法。文档从“是什么、能做什么、如何使用”三个层面展开，既介绍DeepSeek的免费商用、联网搜索、文件读取等特性，也对比推理模型与非推理模型在数学推导、逻辑分析、发散任务上的优劣，帮助读者按任务类型选择合适的模型。针对提示语设计，文档梳理了指令驱动、需求导向、混合模式和启发式提问等策略，并结合数学证明、创意写作、代码生成等场景示例说明如何避免常见误区。资源为单个PDF文档，压缩包大小4.83MB，轻量易读，目前已有590人学习下载，适合作为国产开源大模型研究、提示语优化与学术探索的入门参考。

1. 清华大学DeepSeek是什么：通用人工智能开源项目的真实含金量

把“清华大学DeepSeek”这个词拆开看，它指向的是深度求索团队开源的大语言模型系列：V3、R1 的权重公开可下载，API 价格低到可以当基础设施用，技术圈普遍把它看作通用人工智能开源项目里最值得研究的样本之一。标题里的“清华”多半来自行业里“清华系”的说法——DeepSeek 本身不是清华校办项目，但核心团队确实有深厚的清华系背景。这篇文章直接服务三类人：要给业务接大模型的后端工程师、要在内网部署推理服务的运维、以及想打通 Codex、Claude Code 和 VSCode 的 AI 编程玩家。下面我不做泛泛科普，只讲怎么把它落到 API 调用、本地推理和工作流里，顺带把显存账、参数玄学和部署翻车的血泪经验都给你摊开。

2. 先认模型和算账：DeepSeek 模型家谱、开源许可证与显存预算

2.1 V2/V3/R1 与蒸馏版怎么选：不要一上来就追最大模型

DeepSeek 最常见的选型误区是：部署就要上满血版。满血版 V3/R1 的总参数量是 671B，虽然推理时激活参数只有 37B，但部署时权重文件必须全部加载进显存。MoE 架构省的是计算量和单 token 的算力成本，显存并不会因为“稀疏激活”而变小。很多人看完技术报告里“激活 37B”就以为 24G 显卡能跑，这是第一步就翻车的地方。

挑版本之前先把场景问清楚。通用对话、代码补全、文案总结，用 deepseek-chat 对应的 V3 系列就足够；数学题、逻辑推理、复杂架构设计，用 deepseek-reasoner（R1 系列），它内部会多生成一段思维链，质量更高但更慢；想在自己的消费级显卡上跑，用 R1-Distill-Qwen 和 R1-Distill-Llama 蒸馏系列，7B、14B、32B 都有现成权重；社区流传的“17B”说法，多半是 DeepSeek-V2-Lite 这类小 MoE 模型被重新量化打包后的民间命名，不是官方 model id，动手前先认准仓库名字。

我一般建议新团队从 14B 蒸馏版起步。质量比 7B 高一整档，单张 24G 显卡用 Q4 量化能跑起来，又不会像 70B 那样必须双卡以上。先把 API 兼容链路跑通，再根据业务指标决定要不要上满血版，这个节奏比较稳。多智能体项目则要反向考虑：工具调用场景对模型响应速度敏感，V3 的通用对话模型往往比 R1 推理模型更合适，因为 R1 的思维链会让整个循环变慢。

这个表的显存是量级判断，不是精确值。预算时宁可按上一档卡去算，也不要卡着线买卡，后续微调或上下文加长会让你很难受。

2.2 开源许可证边界：权重能下载，不等于可以随便二次分发

DeepSeek-R1 的权重用的是相对宽松的 MIT 风格许可证，V3 及后续版本用 DeepSeek 自家的 Model License。两者的共同点是商业使用总体友好，内网部署、做 API 服务、微调后商用一般都能覆盖；差别主要在衍生和再分发条款上，第三方想重新打包、挂 DeepSeek 的名号对外发布，就要逐句读 LICENSE。

实际操作上，部署前先把模型卡和许可证拉下来做留档。这个动作对个人无所谓，但对企业项目是硬需求——上线以后法务或安全审计问起模型来源，拿不出许可证文本会非常被动。

# 用 huggingface-cli 只拉元数据，不拉权重 huggingface-cli download deepseek-ai/DeepSeek-R1 \ --include 'LICENSE' 'README.md' \ --local-dir ./deepseek-meta head -n 30 ./deepseek-meta/LICENSE

这里的 --include 参数用来过滤下载文件，避免把几百 GB 权重误拉下来，LICENSE 和 README 总共只有几十 KB。如果你用的是国内镜像或 ModelScope 渠道下载，也要先找到对应的 LICENSE 文件，不要只看二手教程里的介绍。

另一个容易被忽略的点：开源的是模型权重，不是训练数据和完整数据处理代码。DeepSeek 公开了部分合成数据方法，但你拿不到原始语料，所以“复现 DeepSeek”在工程上是不成立的。能复现的是推理服务和微调流程，不是模型本身。

2.3 买卡前先算账：显存、KV cache 与最小部署硬件

显存预算是一道算术题。FP16/BF16 权重占 2 字节/参数，671B 模型权重约 1342GB，所以满血版基本要 8 张 80G 卡；INT8 量化后权重降到约 671GB，4 张 80G 才能放下权重，KV cache 就没多少空间；INT4/Q4 量化后权重约 340GB，4 张 80G 能跑，但并发稍大同样会打满。

权重显存 ≈ 参数量 × 每参数字节数 FP16/BF16：671B × 2 = 1342GB INT8：671B × 1 = 671GB INT4/Q4：671B × 0.5 ≈ 340GB

推理时的显存除了权重，还有 KV cache，它随 max_model_len 和并发数增长。所以 vLLM 里我最先调的两个参数是 max_model_len 和 gpu-memory-utilization，前者控制单条上下文长度，后者控制预留给 KV cache 的上限。先看本机还剩多少显存，再设这两个值，是避免 OOM 的基本功。

nvidia-smi --query-gpu=name,memory.total,memory.free --format=csv free -g

注意：很多部署翻车不是因为模型太大，而是 max_model_len 设得比业务实际需求大很多，KV cache 把显存吃光了。把 8192 改成 4096，OOM 往往立竿见影地消失。

消费级显卡的判断可以更粗：8G 显存跑 7B 的 Q4 量化，生成速度可以接受；24G 显存试 14B 的 Q4 或 32B 更激进的量化；48G 以上的单卡可以考虑 V2-Lite 这类小 MoE 的 FP16。CPU 部署虽然能跑，但生成速度对交互式应用基本不可用，只适合离线批量任务。

3. 两条落地路径：DeepSeek API 调用、本地 vLLM 部署与边缘设备方案

3.1 API 闭环：从申请 Key 到第一个 ChatCompletion

官网和网页版入口很容易找到，但申请 API Key 一定要去开发者平台，不要在聊天页面找。拿到 Key 后放进环境变量，不要写死在代码里，更不要提交到 Git 仓库。DeepSeek API 兼容 OpenAI 协议，直接用 openai 这个 Python SDK 就能调，不需要额外封装。

from openai import OpenAI import os client = OpenAI( api_key=os.environ["DEEPSEEK_API_KEY"], base_url="https://api.deepseek.com", ) resp = client.chat.completions.create( model="deepseek-chat", messages=[ {"role": "system", "content": "你是资深运维工程师，回答要简短。"}, {"role": "user", "content": "vLLM 和 Ollama 有什么区别？"}, ], temperature=0.3, max_tokens=512, stream=False, ) print(resp.choices[0].message.content) print(resp.usage)

base_url 指向 OpenAI 兼容端点。model 名有两类要记牢：deepseek-chat 是通用对话模型，deepseek-reasoner 是推理模型。resp.usage 里会返回 token 消耗和缓存命中情况，第 6 章会细讲怎么看缓存。

参数经验值方面：代码生成和结构化 JSON 输出用 temperature 0 到 0.3，追求可复现；通用对话用 0.7；创意写作才拉到 1.0 以上。max_tokens 别卡着任务长度的边界设，至少留出 50% 余量，否则输出会在中间被切断，返回的 finish_reason 会变成 length。

提示：deepseek-reasoner 对 temperature 不敏感，推理模型应该用默认值或关闭温度调整。想精细控制输出风格和成本，用 deepseek-chat 更合适。

3.2 本地部署：vLLM 一条命令拉起 OpenAI 兼容服务

API 路线适合快速验收，但数据敏感或 token 开销大的场景最终要落到本地。本地部署最常见的选择是 vLLM，高性能、支持 tensor parallel、自带 OpenAI 兼容接口。先用 huggingface-cli 把蒸馏权重下到本地，再一条命令起服务。

# 拉取 14B 蒸馏权重（约 30G，网络差时用断点续传） huggingface-cli download deepseek-ai/DeepSeek-R1-Distill-Qwen-14B \ --local-dir ./models/DS-R1-14B # vLLM 启动 OpenAI 兼容服务 python -m vllm.entrypoints.openai.api_server \ --model ./models/DS-R1-14B \ --served-model-name deepseek-local \ --tensor-parallel-size 1 \ --max-model-len 8192 \ --gpu-memory-utilization 0.90 \ --port 8000

--served-model-name 是暴露给调用方的模型名，客户端请求时写 deepseek-local 即可，不用记一长串路径；tensor-parallel-size 多卡时设为卡数，4 卡就写 4；gpu-memory-utilization 建议 0.85 到 0.92，太低浪费显存，太高留给 KV cache 和碎片的余量不足。

服务起来后，用 curl 验证接口：

curl http://localhost:8000/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{"model": "deepseek-local", "messages": [{"role": "user", "content": "你好"}], "max_tokens": 64}'

刚才 Python 代码里的 client 只要把 base_url 换成 http://localhost:8000/v1，模型名换成 deepseek-local，就能从官方 API 平滑切到本地部署。这个过程最磨人的是权重下载，大文件传输中断了别从头拉，用支持断点续传的工具或国内镜像能省很多时间。

3.3 边缘设备路线：Jetson Orin 上的量化 deepseek 怎么搭

Jetson Orin 这类嵌入式设备，满血 MoE 不用想，真正可落地的是蒸馏版本的 GGUF 量化。Orin 设备通常有 8G 到 64G 的统一内存，跑 7B 的 Q4 量化可用；14B 建议 32G 以上。用小模型起步，用 Ollama 最省事，它会自己处理量化选择和上下文窗口，不需要手动配 llama.cpp。

ollama pull deepseek-r1:7b ollama run deepseek-r1:7b

确认两点再跑：模型名对应的是官方蒸馏版，不要下载来路不明的同名封装；边缘设备长期高负载会触发降频，生成速度可能从 15 token/s 掉到 5 token/s，散热和功耗要先测过。

社区里流传的“deepseek hermes”这类非官方命名，在嵌入式设备上更要留个心眼。一是确认模型来源仓库，二是核对量化后的文件哈希。边缘设备一旦加载了被篡改的权重，输出质量只是小事，数据安全和合规风险才是大问题。想要后悔药的话，下载前就把官方模型卡的 SHA256 留档。

4. 接入工作流：Codex、Claude Code、企业微信与 deepseek harness 编排

4.1 Codex 接入 DeepSeek：环境变量与模型配置

Codex 这类 AI 编程终端，本质是把大模型当作 agent 让它自己读写文件、跑命令。DeepSeek 的 OpenAI 兼容性让 Codex 用一份配置就能切过去。常见做法是配置环境变量：

export OPENAI_API_KEY=${DEEPSEEK_API_KEY} export OPENAI_BASE_URL="https://api.deepseek.com/v1" codex

更利于长期维护的做法是在 Codex 配置文件里写 provider 映射，切换模型不用反复 export：

model = "deepseek-chat" [model_providers.openai] name = "DeepSeek" base_url = "https://api.deepseek.com/v1" env_key = "DEEPSEEK_API_KEY" wire_api = "chat"

这里 model 推荐 deepseek-chat 而不是 deepseek-reasoner。Codex 要高频调用文件和终端工具，reasoner 的长思维链会拖慢整个编码循环，而且推理模型在部分 agent 框架里的工具调用支持不如 chat 模型稳定。

注意：接入 Codex 时如果出现对话初始化失败，先检查 OPENAI_BASE_URL 末尾有没有 /v1。大多数兼容端点的路径是 /v1/chat/completions，漏掉 /v1 是最高频的配置错误。

这套环境变量同样适用于 VSCode 里的 Continue、Cline 等插件：选 OpenAI 兼容 provider，base_url 指向 DeepSeek，模型名填 deepseek-chat，密钥走环境变量。这样 IDE、终端和脚本共用一套凭证。

4.2 Claude Code 切换 DeepSeek：ccswitch 与模型映射

Claude Code 默认只认 Anthropic 协议，DeepSeek 提供的是 OpenAI 兼容接口，两者不能直接对指。社区的通行做法是用 ccswitch 这类配置切换器，把 DeepSeek 的模型映射到 Claude Code 的 provider 列表里，多套模型配置用一个命令来回切换。

ccswitch 本身不做协议转换，它管理的是各家 CLI 的环境变量和模型名。使用时注意两点：模型名要按 DeepSeek 官网文档里的最新 model id 写，社区流传的“claude code deepseek 4.1”只是 API 侧的版本标签，没有固定不变的名字；Anthropic 协议的部分扩展能力在 DeepSeek 后端不生效，比如 artifacts 这类功能别指望完全复刻。

我自己的习惯是同时保一个本地 vLLM 的 provider 配置和一个官方 API 的 provider 配置，写在 ccswitch 配置目录下。切换成本从改环境变量降到一个命令，这个幸福感在频繁对比模型时非常明显。如果发现某个模型在 Claude Code 里表现不稳定，先切回官方 chat 模型验证，判断是模型问题还是转换层问题。

4.3 企业微信接入：webhook 回调与微服务拆分

企业微信接入 DeepSeek 看起来只是“调一下 API”，上了生产就变成微服务架构：入口网关、消息队列、worker 三段式，这也是 2026 年前后开源社区做 AI 机器人最常见的模板。企业微信回调要求 5 秒内返回，而一次 DeepSeek 请求可能 20 秒以上，同步调 API 必然超时重试。正确做法是回调里只入队，立刻返回 200，worker 异步处理。

from flask import Flask, request, jsonify app = Flask(__name__) @app.route("/wecom/callback", methods=["POST"]) def wecom_callback(): data = request.get_json() if data.get("MsgType") == "text": user_id = data.get("From", {}).get("UserId", "") # 只入队，不调模型，避免回调超时和重试风暴 push_to_queue(user_id, data.get("Text", {}).get("Content", "")) return jsonify({"errcode": 0, "errmsg": "ok"})

push_to_queue 可以是 Redis、RabbitMQ 或数据库任务表，保证消息至少被处理一次即可。worker 侧要做消息去重：企业微信在网络抖动时会重试回调，同一个文本可能被处理两次，给消息加 message_id 幂等键，是防止用户收到重复回复的最小成本方案。

如果要做知识库问答，常见做法是先用 markitdown 这类开源工具把 PDF、Word 转成 Markdown，再做切分和检索。别把 PDF 原文直接塞给模型，token 浪费和格式噪声都受不了。文档预处理和模型能力是互补的，这一环省不掉。

4.4 多智能体编排：deepseek harness 与工具调用协议

“deepseek harness”不是官方软件包，而是社区对“拿 DeepSeek 当多智能体大脑”的编排层的统称。你在技术社区搜 deepseek harness 多个智能体 编排，看到的方案五花八门，但核心都落在同一个机制上：function calling。

多智能体编排的正确循环只有四步：模型返回 tool_calls，外部执行工具，结果以 role=tool 回传，模型继续生成。下面是核心骨架：

messages = [{"role": "user", "content": "帮我查今天天气并设置一个提醒"}] for _ in range(max_rounds): resp = client.chat.completions.create( model="deepseek-chat", messages=messages, tools=tool_schema, temperature=0, ) msg = resp.choices[0].message messages.append(msg) # assistant 的 tool_calls 必须放回上下文 if not msg.tool_calls: break for tc in msg.tool_calls: # 调用工具，tool_call_id 必须和回包对齐 result = execute_tool(tc.function.name, tc.function.arguments) messages.append({ "role": "tool", "tool_call_id": tc.id, "content": result, })

这个模板有三个关键参数：max_rounds 设为 3 到 5，防止工具无限循环；temperature 设为 0，工具调用场景下随机性只会增加解析失败率；如果本轮不需要工具，宁可关掉 tools 参数，让模型走普通对话路径。

最容易踩坑的地方在 tool_call_id 对齐。多工具并行时，如果结果放回顺序和 tool_call_id 对不上，模型会胡言乱语甚至直接报错。这就是下一章第一个坑的根源。

5. 避坑指南：DeepSeek 生产环境的五个高频翻车现象

5.1 报错 messages tool calls need immediate results

现象：多智能体脚本跑着跑着，日志抛出 messages tool calls need immediate results 或者类似信息，agent 直接停住，不再继续生成。

原因：模型已经返回 tool_calls，但调用方没有把工具结果回传就发起了下一轮请求。部分 agent 框架要求工具结果在同一轮内尽快返回，一旦上下文里只有 tool_calls 而没有配对 role=tool 的消息，就会判定为非法对话状态。

解决：严格按照 4.4 节的循环，先 messages.append(assistant_msg)，再逐条回传 role=tool 消息。如果工具执行较慢，先把消息状态持久化，不要强行续跑。工具结果也要保持稳定顺序，并发执行时按 tool_call_id 排序后再回传。调试时把 resp.choices[0].message 完整打印出来，看看 tool_calls 字段是不是真的存在，不要凭肉眼猜。

5.2 输出被截断：导出报告最后几百字不翼而飞

现象：让 DeepSeek 导出完整方案，结果正文到一半戛然而止，返回的 finish_reason 是 length。

原因：max_tokens 按任务的预期长度设，没留余量。模型生成满指定 token 数就必须停，和文本有没有说完无关。

解决：max_tokens 设为“预期内容长度 × 1.5”；长文导出用 stream 模式，逐段落盘再合并。这样即使中途截断，已生成的部分也保存下来了，不用整段重跑。这个习惯适用于所有长文导出场景：先落盘再处理，别等着拿一个巨大的完整响应。

5.3 vLLM 服务并发一高就 OOM

现象：单请求正常，十几个并发后报 CUDA out of memory，服务崩溃或响应全部超时。

原因：vLLM 的 KV cache 按 max_model_len 预留。max_model_len 设 32768 时，每个并发占用的缓存会迅速吃光显存，即使权重本身没变。

解决：把 max-model-len 下调到业务真实需要，比如 8192；gpu-memory-utilization 设为 0.90，预留余量给碎片和临时张量；并发太高时加节点或用多卡 tensor-parallel-size，不要继续压单卡。调完这两个参数再压测，大部分 OOM 都能救回来。

5.4 第三方封装名声混乱：deepseek hermes 等非官方包别乱接

现象：照着教程下载了某个叫 deepseek hermes 的桌面版或插件，输出风格和官方差异很大，有时 API Key 不明不白被扣费。

原因：这类包是社区重新打包或重命名的版本，不来自 DeepSeek 官方仓库。名字带 deepseek 不等于它就是 DeepSeek 的模型，也不代表推理后端是官方 API。

解决：只用来源清楚的渠道。部署后看 /v1/models 返回的模型 id，和官方文档对不上就要怀疑有中间转换层；API Key 只配置在服务器端环境变量，不落到第三方插件里。项目要求来源清晰时，把“去官方仓库核对模型卡”作为验收条件，能过滤掉九成二手封装。

5.5 deepseek-reasoner 的 temperature 调了等于没调

现象：换成 deepseek-reasoner 后，把 temperature 从 0.7 改到 1.5，输出几乎没有变化，token 费用反而明显变高。

原因：reasoner 走推理链路，输出包含额外思维链 token，官方 API 对推理模型的采样参数处理策略和 chat 模型不同，temperature 在多数实现里被忽略。

解决：需要稳定可复现的输出，比如 JSON、代码、鉴权逻辑，用 deepseek-chat 并且 temperature 设为 0；需要复杂推理时用 reasoner，但接受更高的 token 消耗。调优时先看 usage 字段再决定改模型还是改参数，不要凭感觉反复试温度。

6. 纵深验证：工具调用正确率与上下文缓存命中率怎么把脉

多智能体上线后，我最关心两个数字：工具调用 JSON 合法率，以及上下文缓存命中率。前者决定链路稳不稳，后者决定 token 贵不贵。这两个指标都可以自动化验证。

工具调用验证按固定用例跑，把常见工具写成 20 条测试，看模型是否按要求触发 tool_calls，以及 arguments 是不是合法 JSON：

import json from openai import OpenAI client = OpenAI(api_key="...", base_url="...") tool_schema = [{ "type": "function", "function": { "name": "calc", "description": "计算四则运算表达式", "parameters": { "type": "object", "properties": {"expr": {"type": "string"}}, "required": ["expr"] } } }] cases = ["(1+2)*3", "100/7", "sin(30) 是多少"] for c in cases: resp = client.chat.completions.create( model="deepseek-chat", messages=[{"role": "user", "content": f"计算：{c}"}], tools=tool_schema, temperature=0, max_tokens=256, ) msg = resp.choices[0].message if not msg.tool_calls: print("FAIL：没有触发工具调用：", c) continue try: args = json.loads(msg.tool_calls[0].function.arguments) print("OK：", args) except Exception: print("JSON 格式损坏：", msg.tool_calls[0].function.arguments)

tool_schema 里最重要的不是函数名，而是 function.description 和参数的 description。写得越具体，模型越容易触发正确工具。合法率低于 90% 时不要调温度，先去完善参数描述和示例。

缓存命中率看 usage 里的 prompt_cache_hit_tokens 和 prompt_cache_miss_tokens。命中率越高，成本越低。要让缓存更容易命中，把系统提示词和长段工具说明固定在每轮请求的开头，不要带随机时间戳或动态文字。这个动作可以把命中率从 0 抬到 60% 以上，是调参之外最实在的省钱手段。

我现在的习惯是每个项目上线前跑这组用例，跑完看一遍 usage 明细，再把模型名和参数写进部署文档。这套验证动作花不了半小时，但能让整个团队避开绝大多数“改天再调”的等待。希望帮到你。

本文还有配套的精品资源，点击获取