跑通第一次大模型调用只要 4 步:注册拿 API Key、装 1 个 SDK、写 20 行脚本、读返回的 usage。整个流程在 1 台普通笔记本上 40 分钟能走完,不需要显卡,也不需要训练。真正的门槛在参数填错和额度耗尽这两件事上。
我 9 月带过 3 个刚转行的同学,2 个人卡在 401 错误上,1 个人卡在 429 上。两处都在代码写完之后,报错信息很短,不容易看出原因。下面按「准备—跑通—填参—排错—验证」的顺序写,每一步标明界面位置和耗时。
第 2 条要提醒:Key 只显示 1 次,页面刷新就看不到全串。丢了不用找回,直接删掉重建。把 Key 写进代码里提交到仓库是最常见的泄露方式,改成读环境变量 DEEPSEEK_API_KEY,多写 1 行就能避开。
第 3 条注意版本。SDK 1.0 之后的写法和 0.28 差别很大,网上抄来的代码跑不通,多半是版本对不上。用 pip show openai 看版本号,低于 1.0 就先升级。
DeepSeek 的接口地址是 https://api.deepseek.com,兼容 OpenAI 的调用格式,所以可以直接用 openai 的 SDK,只改 base_url。模型名填 deepseek-chat(对话)或 deepseek-reasoner(推理),名字写错会返回 400,报错里带 model not found。
这一步花 2 分钟。很多教程漏了 base_url 这一行,代码跑起来会去连 OpenAI 的地址,报认证失败,看着像 Key 无效。
核心就是 1 个 client 和 1 次 chat.completions.create。三个必填项:model、messages。messages 是 1 个数组,每条带 role 和 content,role 取 system、user、assistant 三种。
system 放角色设定,user 放这次的问题。第一次跑通时 messages 只放 1 条 user,把变量减到最少,出错好定位。跑通之后再往里加 system。
返回对象里取两个位置:choices[0].message.content 是回答正文,usage 是这次的 token 明细。把 usage 打印出来,是养成本意识的第 1 步,后面查成本全靠它。
打印时顺手把 request_id 也打出来。开放平台的响应头里有 x-request-id,出了问题拿这个号去工单里查,比描述现象快。
加 1 个参数 stream=True,返回从 1 个对象变成 1 个迭代器,逐块吐字。网页上那种一个字一个字冒出来的效果就是它。流式下 usage 在最后 1 个数据块里,前面几块没有,别在循环里读。
流式适合交互场景,批处理场景用不上。做批量任务时关掉流式,代码简单一半。
| 步骤 | 在哪操作 | 耗时 | 成功标志 |
|---|---|---|---|
| 拿 Key | 开放平台 API keys 页 | 3 分钟 | 页面出现 sk- 开头的串 |
| 装 SDK | 本地终端 pip install | 1 分钟 | pip show 能查到版本 |
| 写脚本 | 本地编辑器 | 15 分钟 | 无语法报错 |
| 跑通 | 终端执行 | 2 分钟 | 打印出回答和 usage |
| 字段 | 填什么 | 常见错填 |
|---|---|---|
| model | deepseek-chat | 写成 DeepSeek-V3 或带版本号 |
| temperature | 事实类 0 到 0.3,创意类 0.8 到 1.2 | 一律填 1,回答飘 |
| max_tokens | 按场景 300 到 2000 | 不填,长回答把额度吃光 |
| stream | 交互开、批处理关 | 开了流式还按普通对象取值 |
| messages | role 加 content 的数组 | 直接传字符串 |
表里第 2 行最值得改。做合同条款抽取这类任务,temperature 填 1.0 会让同 1 份合同跑 2 次出 2 个结果,验收时对不上。填 0 之后结果稳定,代价是偶尔会卡在同 1 种表述上。
max_tokens 填太小会把回答截断,截断的回答不带结束标记,代码里看 finish_reason 字段,值是 length 就说明被截了。这个字段很多人不看,出现了半句话的回答还以为模型能力不行。
第 3 条有个细节:429 分两种,每分钟请求数超限和每分钟 token 数超限。前者把并发降到 5 以下就能过,后者要把单次请求的输入压小,光降并发不够。报错信息里带 limit 字样,看清楚是哪一个。
第 6 条我遇到过 1 次。公司内网出口没放行这个域名,代码报「connection reset」,看着像服务端问题。让运维加 1 条白名单,2 分钟解决。
排错的顺序建议从简到繁:先 curl 打 1 次接口,能通就说明域名和网络没问题,问题在代码;再把 Key 打印前后各 4 位,确认没被引号或空格污染;最后看 messages 数组的实际 JSON,用 1 行 print 打出来对着文档比。3 步走完,8 成问题能定位。
第 3 条用来做验收。跑通 1 次只能证明网络通,跑 3 次结构一致,才说明 prompt 和参数配好了。做产品之前把这条跑完,后面改 prompt 才有对照。
多轮不靠服务端记状态,客户端每轮把历史全部带上去。第 3 轮的 messages 是 5 条:1 条 system,加前 2 轮的 2 问 2 答,再加这次的问题。漏掉 assistant 那几条,模型就失忆。
顺序不能乱。system 放第 1 条,user 和 assistant 交替往后排,最后 1 条必须是 user。把 assistant 放在末尾,多数实现会返回 400,报错写 messages 格式不合法。
历史长了要截断。1 个 8 轮的对话,按每轮 300 字算,输入接近 3000 token。做法是保留 system 加最近 4 轮,更早的用 1 段 150 字摘要代替,摘要让模型自己写,成本比传原文低 6 成。
开放平台的「用量信息」页有 2 个数:账户余额和今日消耗。余额低于 10 元时调用仍能成功,只是会在响应头里带余额提醒。余额归零返回 402,代码里要单独处理这个状态码,别当成网络错误重试。
新账号的试用额度一般按 token 计,用完就停。有人第 1 天跑了 300 次就没了,原因是每次带 2000 字的 system 提示,300 次等于 60 万 token。把 system 压到 300 字,同样的额度能跑 2000 次以上。
做预算按 3 个数估:日均调用次数、单次平均 token、输出占比。3 个数乘出来就是日消耗量,乘 30 得月度。我们内部按这个法子估过 12 个项目,误差在 20% 以内,够用来判断要不要换模型。
第一次调用跑通,接下来 3 个方向按需要选:多轮对话要自己维护 messages 数组,把历史拼进去;结构化输出用 JSON 模式,在参数里指定 response_format;批量任务写 1 个队列,控制并发在 5 到 10 之间,别一次发 1000 条。
我们给 1 家做设备的客户搭过工单分类,1 天 2400 条,用 8 并发跑完 40 分钟。第 1 版没限并发,直接被限流打了 200 多条 429,加了队列之后稳定下来。这一步的经验是:先把单条跑准,再谈跑量。
还有 1 个常被忽略的点:把 prompt 存成独立文件,别写死在代码里。改 1 句话就要发版,测试成本比改文件高 10 倍。我们现在的做法是 prompts 目录下按场景放 txt,加载时读文件,调整不用动代码,回滚只要换文件。
本文信息核对时间:2026-11