大模型应用开发教程,先装环境再跑通第1个接口

大模型应用开发的第一步只有两件事：把本地环境装起来，跑通一个能返回结果的接口调用。做到这两步大概 40 分钟，需要 1 台能上网的电脑、1 个已实名的平台账号、1 个编辑器。

我带的 3 个新人都是零基础起步，最快的一个 32 分钟跑通，最慢的卡了 2 天。卡住的地方全部出现在环境上：Python 版本不对、虚拟环境没激活、依赖包装错了名字。接口本身反倒是最顺利的一段。

先想清楚做的是哪一类应用

分类决定后面选什么接口、要不要流式、要不要存对话。同一套环境，三类应用的写法差得很远。

1. 对话壳。一个输入框加一段结果，给人直接问问题用。重点是流式输出和上下文保留，功能可以很少。
2. 批处理。一次处理 100 份文档，抽字段、写摘要、做分类。重点是失败重试和结果落盘，界面可以没有。
3. 嵌进业务系统。客服工单自动分类、合同条款比对。重点是接口稳定性和超时控制，一次失败不能拖垮整条流程。

三类里最先做的是第二类。批处理没有交互，出错了能重跑，适合拿来摸清接口脾气。做对话壳容易被界面细节牵着走，一周过去还在调输入框。

选哪一类还决定了成本结构。批处理的钱花在输入，一份长文档进去就是几千 token；对话壳的钱花在输出，用户一直追问，输出量翻倍。先算清哪头大，再决定压缩哪里。

先准备：4 项环境，缺一项都跑不起来

1. Python 3.10 或以上。命令行敲 python --version 看版本，低于 3.9 的直接装新版，别在旧版本上折腾兼容。
2. 一个独立的虚拟环境。在项目目录里执行 python -m venv .venv，激活后再装包，避免污染系统环境。
3. 兼容 OpenAI 格式的 SDK。国内几家平台的接口都能用同一个包调用，装 1 次够用，换平台只改 base_url 和模型名。
4. 一个能看 JSON 的编辑器。返回体是多层嵌套结构，纯文本编辑器读起来费劲。

虚拟环境这一步最容易漏。没激活就 pip install，包会装到系统目录，换个项目又冲突。判断有没有激活，看命令行前面有没有出现 (.venv) 字样，没有就是没进。

我习惯在项目根目录放 1 个 config 文件写 base_url 与模型名，Key 放环境变量。这样把代码发给同事时不会连 Key 一起发出去，换平台也只改 1 行。

跑通第 1 个接口的 6 步

第 1 步，建 Key。登平台控制台，在 API keys 页面点创建，完整 Key 只显示 1 次，复制到密码管理器。没做实名认证的账号建出来的 Key 调不通。

第 2 步，把 Key 写进环境变量。Windows 用 setx，macOS 用 export，写进 shell 配置文件再重开终端。写进代码里是最常见的错误，代码一提交就等于公开。

第 3 步，写 8 行调用代码。初始化客户端时传 base_url 与 api_key，调用对话补全方法，把消息数组和模型名传进去，打印返回里第一个选项的内容。

第 4 步，跑起来看输出。第一次不要在 IDE 里点运行，用命令行跑，报错信息完整。成功时屏幕上会出现一段模型生成的中文。

第 5 步，打开流式。加 1 个 stream 参数，用循环逐块拼接内容，屏幕上会一个字一个字出。这一步做完，界面上的「等待中」感觉就没有了。

第 6 步，把结果写进文件。按时间戳命名，存成 json，里面保留输入、输出、模型名、耗时 4 个字段。后面排查问题全靠它。

整个流程下来 40 分钟左右。第 3 步到第 4 步之间的报错最多，多数是 Key 或模型名写错，报错文本里会直接指出是哪一项。

参数怎么填：5 个字段的对照

提示词写在哪

固定不变的说明放 system 角色，随用户输入变化的内容放 user 角色。两段混在一起写，改一次提示词就要重测全部用例。

我做过一个合同条款抽取，system 里固定写输出格式与 3 条禁止事项，user 里只放合同正文。改格式只动 system，200 条测试用例的输入完全不用碰。

输出怎么存

存原始返回，别只存解析后的字段。模型返回里带 usage 和 finish_reason，这两个值后面核对成本、判断有没有截断都要用。

文件名用 日期加序号，例如 20261110-001.json。存 1000 条也就几十兆，比事后回想「当时它到底怎么答的」省事得多。

报错怎么排查：5 类高频

1. 模块找不到。现象是 import 报错。原因在虚拟环境没激活。重新激活再装一遍。
2. 连接被拒绝。现象是请求发不出去。原因多是代理或防火墙拦了。临时关掉代理试一次，能通就是代理配置问题。
3. 返回 401。现象是每次都失败。Key 里有空格或已失效，重新复制 1 次。
4. 返回 429。现象是并发上来就报。把并发降到 2 到 3，请求之间加 200 毫秒间隔，跑通再逐步加。
5. 输出被截断。现象是最后一句突然没了。看 finish_reason 是不是 length，命中就把 max_tokens 加大。

排查顺序固定：先看状态码，再看返回体里的 message 字段，最后看自己的参数。跳过前两步直接改代码，多数时候是在改一段本来没毛病的代码。

怎么验证成功了

1. 连发 10 次同样的请求，10 次都有输出，没有一次空返回。这一步排除偶发失败。
2. 看每次返回的 usage 里 total_tokens 是否稳定在同一个量级，波动超过 3 倍说明输入有问题。
3. 把耗时记下来，单次 5 到 30 秒属于正常区间。超过 60 秒要查是不是超时设置太宽或者网络绕路。

三步都过，本地这一段就算完成。接下来是把它塞进一个能给别人用的壳里，那部分工作量和调接口差不多。

还有一项容易漏的验证：换个网络环境跑一遍。公司内网能通、家里宽带不通的情况不少见，原因是代理设置只在一台机器上生效。上线前在 2 个不同网络下各测 3 次。

从 demo 到能用还差 2 件事

第一件是错误兜底。接口会超时、会被限流、会返回空内容，每种都要有对应的提示语，不能让页面一直转圈。第二件是成本可见，每天统计一次消耗，超预算要能收到提醒。

我见过一个内部工具上线 2 周花了 4 位数，原因是每次刷新页面都重新调一次接口，没有缓存。加上 5 分钟缓存后，消耗降了八成。

上线前必查的 4 项

1. Key 在后端。用浏览器开发者工具看网络请求，请求头里不该出现 Key，出现就是泄露。
2. 超时与重试都设了。重试 3 次、间隔递增，失败后给用户明确提示。
3. 输入长度做了限制。前端限制字数，后端再校验一次，超长的直接拒绝，别让它打到接口上烧钱。
4. 日志里不存敏感内容。用户贴的身份证号、手机号在入库前脱敏。

这 4 项里第 1 项最要命。Key 泄露之后，别人用你的额度跑自己的业务，账单上只看到消耗，看不到是谁在用。

入门阶段最容易犯的错是把教程当成品。教程跑通只代表链路通了，离能用还差兜底、限流、日志这三块。这三块加起来的工作量，通常比写主流程多 2 倍。

本文信息核对时间：2026-11