大模型应用开发教程,怎么从零跑通 1 次调用

20分钟前发布

跑通第一次大模型调用只要 4 步:注册拿 API Key、装 1 个 SDK、写 20 行脚本、读返回的 usage。整个流程在 1 台普通笔记本上 40 分钟能走完,不需要显卡,也不需要训练。真正的门槛在参数填错和额度耗尽这两件事上。

我 9 月带过 3 个刚转行的同学,2 个人卡在 401 错误上,1 个人卡在 429 上。两处都在代码写完之后,报错信息很短,不容易看出原因。下面按「准备—跑通—填参—排错—验证」的顺序写,每一步标明界面位置和耗时。

先准备这 4 样

  1. 1 个能收验证码的手机号,用来注册开放平台账号。
  2. 1 个 API Key,在开放平台的「API keys」页点「创建」,只显示 1 次,复制下来存进环境变量。
  3. Python 3.9 以上环境,装 openai 或官方 SDK,1 条命令。
  4. 账户里有余额或免费额度,新账号一般有几百次调用的试用额度。

第 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 无效。

第二步:写 15 行代码

核心就是 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 install1 分钟pip show 能查到版本
写脚本本地编辑器15 分钟无语法报错
跑通终端执行2 分钟打印出回答和 usage

参数怎么填

字段填什么常见错填
modeldeepseek-chat写成 DeepSeek-V3 或带版本号
temperature事实类 0 到 0.3,创意类 0.8 到 1.2一律填 1,回答飘
max_tokens按场景 300 到 2000不填,长回答把额度吃光
stream交互开、批处理关开了流式还按普通对象取值
messagesrole 加 content 的数组直接传字符串

表里第 2 行最值得改。做合同条款抽取这类任务,temperature 填 1.0 会让同 1 份合同跑 2 次出 2 个结果,验收时对不上。填 0 之后结果稳定,代价是偶尔会卡在同 1 种表述上。

max_tokens 填太小会把回答截断,截断的回答不带结束标记,代码里看 finish_reason 字段,值是 length 就说明被截了。这个字段很多人不看,出现了半句话的回答还以为模型能力不行。

双显示器与键盘

报错怎么排查

  1. 401 认证失败。查 Key 有没有空格、有没有带 Bearer 前缀重复、环境变量有没有读到。打印 Key 的前 6 位和后 4 位对比。
  2. 402 余额不足。去开放平台的充值页看余额,试用额度用完也会报这个。
  3. 429 请求过多。并发或频率超限,加 1 个 1 秒的重试等待,别立即重发。
  4. 400 参数错误。看报错里的字段名,多半是 model 拼错或 messages 结构不对。
  5. 超时。默认超时 600 秒,网络差的环境调到 60 秒并加重试。
  6. 连接被拒。代理或防火墙拦了 api.deepseek.com,用 curl 测 1 次就知道。

第 3 条有个细节:429 分两种,每分钟请求数超限和每分钟 token 数超限。前者把并发降到 5 以下就能过,后者要把单次请求的输入压小,光降并发不够。报错信息里带 limit 字样,看清楚是哪一个。

第 6 条我遇到过 1 次。公司内网出口没放行这个域名,代码报「connection reset」,看着像服务端问题。让运维加 1 条白名单,2 分钟解决。

排错的顺序建议从简到繁:先 curl 打 1 次接口,能通就说明域名和网络没问题,问题在代码;再把 Key 打印前后各 4 位,确认没被引号或空格污染;最后看 messages 数组的实际 JSON,用 1 行 print 打出来对着文档比。3 步走完,8 成问题能定位。

怎么验证成功

  1. 看 choices[0].finish_reason,值是 stop 表示正常结束。
  2. 看 usage.total_tokens 大于 0,说明计费链路通了。
  3. 同 1 个问题连跑 3 次,回答结构一致,说明参数稳定。

第 3 条用来做验收。跑通 1 次只能证明网络通,跑 3 次结构一致,才说明 prompt 和参数配好了。做产品之前把这条跑完,后面改 prompt 才有对照。

多轮对话怎么拼 messages

多轮不靠服务端记状态,客户端每轮把历史全部带上去。第 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