最近DeepSeek 迎来了属于它的高光时刻。这股热度不只是刷屏的榜单数据更体现在开发者工具链里越来越多的真实接入有人在 Codex 里切换模型有人在 Claude Code 里通过代理调用 DeepSeek也有人直接把 DeepSeek 本地化部署做成内部私有化的推理服务。如果你也被这波“高光时刻”吸引但打开官方文档后不知道从哪一步开始这篇文章就很适合你。我会从 DeepSeek API 的基础调用讲起逐步覆盖 Python/curl 调用、Codex 与 Claude Code 的接入思路、本地部署的可行边界最后给出高频报错的排查清单。文章整体偏向实战代码可以直接复制但涉及版本和模型名的地方需要以你实际环境为准。1. 背景DeepSeek 的“高光时刻”到底在哪很多人注意到 DeepSeek是因为它的推理模型在数学、代码和逻辑推理任务上的表现非常亮眼同时 API 价格在同类模型里很有竞争力。但“高光时刻”并不只是模型分数本身而是它把“高性能 低成本 开放接口”这三件事同时做到了于是普通开发者也能负担得起地在自己的工具链里接一个大模型。从工程视角看DeepSeek 开放平台提供了 OpenAI 兼容的 Chat Completions 接口这意味着过往基于 OpenAI API 写的工程代码很大概率只需要改掉api_key、base_url和model三个参数就能迁移到 DeepSeek。对于使用 Codex、Claude Code、VSCode 插件、企业微信机器人等场景的人来说这是一个非常重要的低成本接入路径。还有一个高频词是“DeepSeek Harness”或各种第三方桌面端。其实不管界面怎么封装它们大多数底层都在做同一件事把 DeepSeek 的 HTTP API 包装成更易用的工具。所以你不需要被各种发行版搞花眼先把官方 API 用明白再看第三方工具时会清楚很多。本文后面所有操作都围绕“把 DeepSeek 接入开发者工作流”这一目标展开。下面从环境准备开始。2. 环境准备与前置知识在写第一行代码之前建议先把下面这些准备工作做完避免后面调接口时反复纠结是代码问题还是环境问题。2.1 注册开放平台并获取 API KeyDeepSeek 的模型能力通过开放平台对外提供服务你需要先注册账号然后在平台控制台创建 API Key。创建 Key 时要注意几点API Key 是敏感凭证只在创建时完整显示一次建议立刻保存到本地密码管理器。不要把 Key 硬编码在代码仓库里更不要复制到公开帖子里。不同平台的 Key 格式可能不同DeepSeek 的 Key 通常以sk-开头。获取 Key 之后把它写入环境变量方便后面所有终端命令使用。以 Linux/macOS 为例export DEEPSEEK_API_KEYsk-xxxxxxxxxxxxxxxxWindows PowerShell 下可以这样设置$env:DEEPSEEK_API_KEYsk-xxxxxxxxxxxxxxxx2.2 确认接口地址与模型名称DeepSeek 的 API 分为两个常见的访问地址不同文档版本写法可能略有差异但核心路径是一致的Chat Completions 接口https://api.deepseek.com/chat/completions兼容 OpenAI 的 Base URLhttps://api.deepseek.com模型名建议以官方文档当前列出的模型为准。常见的有两类deepseek-chat通用对话模型适合大多数日常任务。deepseek-reasoner推理增强模型适合数学、逻辑、代码分析等复杂任务。需要注意模型名是跟着账户权限和平台更新走的。如果你在某个工具里看到deepseek-v4-flash之类的模型名先不要盲目照抄那可能是第三方封装或版本演进的产物也可能只是某些配置示例里的占位。最稳妥的做法是登录开放平台查看当前可用模型列表。2.3 准备开发环境本文的代码示例主要依赖curl命令行请求通常系统自带。Python 3.8并安装openai或requests库。Node.js 环境用于部分 CLI 工具接入。安装openai库可以用 pippip install openai requests如果你只需要跑通一个最小示例requests就足够了如果你希望尽量复用原有 OpenAI 工程代码openai库会更方便。版本方面不做过高要求。不同版本 SDK 在响应字段的可访问性上会有差异后面碰到具体问题再调整。3. DeepSeek API 核心调用方式这一节是全文的地基。不管后面接 Codex、Claude Code还是自己写脚本本质上都是调用同一个 Chat Completions 接口。3.1 用 curl 调用 DeepSeek 通用对话模型先用最原始的 curl 跑通一次请求这样可以排除 SDK 封装带来的干扰。curl https://api.deepseek.com/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $DEEPSEEK_API_KEY \ -d { model: deepseek-chat, messages: [ {role: system, content: 你是一个简洁的助手}, {role: user, content: 用一句话说明 DeepSeek API 的接入方式} ], stream: false }如果配置正确你会得到一个类似下面的 JSON 响应{ id: chatcmpl-xxx, object: chat.completion, created: 1735000000, model: deepseek-chat, choices: [ { index: 0, message: { role: assistant, content: DeepSeek API 提供了 OpenAI 兼容的接口通过替换 Base URL 和 API Key 即可接入。 }, finish_reason: stop } ], usage: { prompt_tokens: 20, completion_tokens: 30, total_tokens: 50 } }这个响应的结构非常接近 OpenAI 的 Chat Completions因此大部分现有的 OpenAI 封装代码都可以复用。3.2 用 Python requests 调用 DeepSeek 推理模型先安装依赖pip install requests然后新建文件deepseek_demo.pyimport requests API_KEY sk-xxxxxxxxxxxxxxxx url https://api.deepseek.com/chat/completions headers { Authorization: fBearer {API_KEY}, Content-Type: application/json, } payload { model: deepseek-reasoner, messages: [ {role: system, content: 你是资深代码评审专家。}, {role: user, content: 这段 Python 代码有什么性能问题\n\npython\ndef find_duplicates(lst):\n result []\n for i in range(len(lst)):\n for j in range(i1, len(lst)):\n if lst[i] lst[j]:\n result.append(lst[i])\n return result\n} ], stream: False } resp requests.post(url, headersheaders, jsonpayload) data resp.json() if resp.status_code ! 200: print(请求失败, data) else: message data[choices][0][message] reasoning_content message.get(reasoning_content) content message.get(content) print( 推理过程 ) print(reasoning_content) print( 最终回答 ) print(content)运行脚本python deepseek_demo.py这里有一个容易被忽略的重点deepseek-reasoner模型的响应里会包含reasoning_content字段它代表模型在给出最终答案前的思考过程。如果你把历史上下文保存在业务系统里并且后续还想继续多轮对话那么reasoning_content也需要原样保存并传回给 API否则某些版本的接口会直接返回 400。3.3 用 OpenAI Python SDK 调用 DeepSeek如果你的项目已经在用 OpenAI SDK迁移起来非常方便from openai import OpenAI client OpenAI( api_keysk-xxxxxxxxxxxxxxxx, base_urlhttps://api.deepseek.com ) resp client.chat.completions.create( modeldeepseek-chat, messages[ {role: system, content: 你是一个乐于助人的助手。}, {role: user, content: 写一段 Python 二分查找代码。} ], streamFalse, ) print(resp.choices[0].message.content)这种方式的好处是团队里已有 OpenAI 封装层时基本只需要改配置不用改业务逻辑。不过要注意OpenAI SDK 不同版本对扩展字段的处理方式不同有些版本能直接访问resp.choices[0].message.reasoning_content有些版本则因为 Pydantic 模型校验导致拿不到。遇到这种情况最稳定的方式是回到 requests 原始请求直接打印data查看完整字段。4. 实战Codex 与 Claude Code 接入 DeepSeek最近搜索热度最高的几个场景都是把 DeepSeek 接进现有 AI 编程工具。这里先说一个底层原则Codex 原本面向 OpenAI 接口Claude Code 原本面向 Anthropic 接口而 DeepSeek 提供的是 OpenAI 兼容接口。所以接入时主要解决的是“把请求路由到 DeepSeek”和“把协议格式对齐”这两个问题。4.1 Codex 接入 DeepSeek 的思路Codex 是由 OpenAI 推出的编程 Agent 工具很多开发者希望把它接到 DeepSeek 上原因是 DeepSeek 的 API 成本更低而且在代码任务上的表现也很不错。官方 SDK 或 CLI 通常会读取环境变量最典型的两个变量是OPENAI_API_KEY鉴权凭证。OPENAI_BASE_URL接口服务地址。在终端里切换export OPENAI_API_KEYsk-xxxxxxxxxxxxxxxx export OPENAI_BASE_URLhttps://api.deepseek.com然后启动codex。不同版本适配程度不同有的 CLI 允许通过--model参数指定模型有的则需要修改配置文件。整体配置思路就三件事把api_key设为 DeepSeek 的 Key。把base_url指向https://api.deepseek.com。把model设为deepseek-chat或deepseek-reasoner。需要提醒的是Codex CLI 本身可能出现针对特定模型的功能开关比如对某些模型启用“思考模式”。如果 DeepSeek 侧返回 400很可能是客户端发送了一些 DeepSeek 不支持的扩展参数或者模型名不匹配。4.2 用 ccswitch 之类的工具管理多 provider 配置社区里出现了不少用于切换不同模型提供方的工具比如 ccswitch 等。它们在本质上是配置管理器把多个 provider 的 base_url、api_key、model 集中保存切换时只需要执行一条命令。如果你使用这类工具配 DeepSeek 时重点检查三个字段provider deepseek base_url https://api.deepseek.com model deepseek-chat这里不推荐去记忆某个工具的具体配置文件路径因为这类工具迭代很快。真正值得记住的是任何供应商切换都是base_url api_key model三要素的替换。把这套思维掌握了无论界面怎么变你都能快速定位。4.3 Claude Code 接入 DeepSeekClaude Code 默认走 Anthropic 协议而 DeepSeek 并没有原生暴露 Anthropic 兼容接口所以直接设置环境变量往往不够。社区通常的做法是增加一个本地代理层把 Anthropic 请求转换成 OpenAI 格式后再转发给 DeepSeek。这种架构大致如下Claude Code | v 本地代理协议转换 | v DeepSeek API本地代理可以做哪些事接收 Claude Code 发来的/v1/messages请求。转换成/chat/completions请求。把 DeepSeek 的choices[0].message.content转换回 Anthropic 格式。这部分不同项目实现方式差异很大配置方式也不统一。如果你在跑这类代理建议先单独用 curl 验证代理能不能成功请求 DeepSeek再接入 Claude Code。不要同时改代理配置、API Key、模型三个变量否则出问题很难定位。4.4 VSCode 与企业微信等扩展场景VSCode 接入 DeepSeek通常是通过 Continue、Cline 等插件。插件里设置 provider 为 OpenAI Compatible然后填写 DeepSeek 的 Base URL、API Key 和模型名即可。企业微信接入 DeepSeek则是写一个后端机器人服务接收企微消息后调用 DeepSeek API再把回答返回。这两类场景的核心仍然是第三节里的 API 调用只是外层协议不同。5. 本地部署 DeepSeek从 API 到自建推理服务有些团队因为数据安全或网络限制不愿意把业务数据发送到外部 API于是会考虑本地部署 DeepSeek。下面讲清楚本地部署的边界和思路。5.1 本地部署适合什么场景本地部署的优势是数据不出内网、可离线使用、没有按 token 计费的后顾之忧。但代价也很明显需要自己准备 GPU 服务器。需要自己拉模型、做推理优化。需要维护模型版本、监控推理服务稳定性。小参数量模型的推理能力可能明显弱于云端满血版本。所以我的建议是先根据业务场景判断。如果只是个人学习可以先用量化版小模型如果是企业内部生产至少要准备对应的 GPU 资源和运维方案。5.2 常见本地推理框架目前比较常见的方式有 Ollama、vLLM、SGLang 等。Ollama 偏个人开发安装简单适合快速体验。比如ollama run deepseek-r1具体可用的模型标签以你当前 Ollama 版本显示的模型列表为准不同时间点可拉取的模型和 tag 可能不一样。个人电脑上通常适合跑蒸馏量化版本更大参数的模型则需要更高显存。vLLM 更适合生产环境它可以加载模型后暴露一个 OpenAI 兼容的服务接口。一个典型的启动思路如下vllm serve deepseek-ai/DeepSeek-R1-Distill-Qwen-7B \ --served-model-name deepseek-local \ --port 8000启动后本地服务地址就是http://localhost:8000/v1然后你可以在 Codex 或自定义脚本里这样配置export OPENAI_BASE_URLhttp://localhost:8000/v1 export OPENAI_API_KEYnot-needed这里我不写死具体的模型名和参数因为 vLLM 的模型支持列表、Hugging Face 仓库命名都会随版本变化。你要做的是先确认已下载的模型路径再照着官方文档启动。这条链路的思路比命令本身更重要本地推理框架启动 OpenAI 兼容服务然后让外部工具直接指向这个服务。5.3 本地部署后的模型选择策略如果你在本地同时部署了小模型和中等模型建议根据不同任务分流简单的文本分类、关键词抽取、格式转换交给小模型速度快成本低。复杂代码重构、逻辑推理、长文档分析交给更大的模型质量更稳定。线上服务要做好超时控制和限流因为本地推理的并发能力通常不如云端 API 弹性扩展。6. 常见报错与排查思路接入过程中最劝退人的不是概念而是一堆看不懂的英文报错。下面整理几个高频问题全部来自实际踩坑场景。问题现象常见原因解决思路401 Authentication FailsAPI Key 错误、环境变量没生效重新复制 Key确认没有多余空格重启终端或重新 source 环境变量402 Insufficient Balance账户余额不足登录开放平台查看额度充值后再试400 Invalid model模型名不存在或未开通去开放平台查询当前可用模型不要盲信第三方教程里的模型名400 reasoning_content 相关报错思考模式下历史上下文没有把reasoning_content原样传回多轮对话时把上一轮的reasoning_content保存并回传429 Rate Limit / Insufficient Quota并发超限或当日额度用尽降低并发增加指数退避重试必要时提升账户限额local proxy failed while handling codex endpoint /responses本地代理配置与目标接口不兼容或请求参数里带了不支持的字段先单独测 DeepSeek API确认可用后再查代理配置去掉与 DeepSeek 不兼容的扩展参数这里重点解释一下reasoning_content报错。下面是一个典型的错误提示片段upstream_status: http 400 cause: the reasoning_content in the thinking mode must be passed back to the api这个报错的意思是你的请求启用了 thinking/推理模式但下一次请求时没有把上一轮模型返回的reasoning_content完整带回给 API。要解决它需要在前端或服务端保存完整的消息记录包括message.reasoning_content并在后续请求中放到 messages 数组里。另外如果你用的是本地代理转发代理可能丢弃了reasoning_content这时要在代理层也保留这个字段。遇到这类问题最直接的办法是打印原始请求和原始响应一步一步确认字段有没有丢。在排查时可以按下面的顺序走先用 curl 直接请求 DeepSeek API排除工具链问题。检查 API Key 是否有效、账户是否有余额。检查模型名是否在官方可用列表中。检查是否开启了流式输出流式输出时对字段处理方式不同。检查本地代理是否把reasoning_content透传。最后才考虑 SDK 版本兼容问题。7. 最佳实践与工程建议跑通一个 API 请求很容易但要在生产环境长期稳定使用 DeepSeek还需要一些工程层面的设计。7.1 密钥管理不要在前端代码里暴露 DeepSeek API Key。正确做法是让后端服务保存 Key前端请求统一走后端网关。如果只是在个人电脑上跑脚本也要至少用环境变量保存。在 CI/CD 或云服务器上可以使用密钥管理服务把 Key 从代码和配置文件中移除。这样即使代码仓库泄露也不会直接暴露云端模型账户。7.2 模型选择与成本控制DeepSeek 的 API 按 token 计费推理模型的输出 token 可能较长。为了控制成本建议普通任务优先用deepseek-chat。复杂推理任务再用deepseek-reasoner。设置max_tokens限制输出长度。不需要实时流式输出时不要盲目开启 stream。在日志中记录每次请求的usage字段定期统计成本。7.3 异常处理与重试网络请求总有失败的可能。接入 DeepSeek API 时要考虑以下异常场景网络超时设置合理的超时时间不要无限等待。429 限流采用指数退避重试避免短时间疯狂重试。5xx 服务端错误可以重试但也要设置重试次数上限。4xx 参数错误不要重试先修复请求参数。使用openaiPython SDK 时可以通过max_retries参数控制重试次数不过生产环境一般还是建议在最外层封装统一的错误处理逻辑。7.4 日志与可观测性凡是经过 API 的请求建议记录以下信息请求时间、模型名、token 数。响应状态码和耗时。是否触发重试。错误信息分类。注意日志里不要记录完整的 API Key也不要随意存储用户输入的敏感内容。如果业务需要保存消息记录做审计要对敏感字段做脱敏处理。7.5 生产环境变更规范无论你是接入云端 API还是切换本地部署服务变更前都要做好回滚方案。比较推荐的做法是先用一个低流量环境验证模型名、参数和服务稳定性。在配置中心或环境变量中预留多个 provider 配置。切换时先小流量灰度观察错误率和响应耗时。如果出现异常能立即切回原配置。DeepSeek 的接入成本低但也不能因此省略灰度验证尤其是涉及金融、医疗、法律等对内容准确性要求较高的场景。8. 写在最后动手跑通一次才是最有效的学习这篇文章从 DeepSeek API 的基础调用一直讲到 Codex、Claude Code 接入和本地部署核心始终围绕三条主线接口地址、模型名、鉴权方式。你只要把这三件事弄清楚无论用什么工具都能快速定位问题。如果你手里正好有 Codex 或 Claude Code建议不要急着安装各种来路不明的第三方桌面端先把 Base URL、API Key、Model 这三个变量搞清楚再回到终端里跑一次带思考模式的任务。DeepSeek 这波高光时刻真正留下的是更低的调用成本和更开放的模型选择空间。现在要做的不是继续刷帖而是打开终端把你的第一个 DeepSeek 请求发出去。