大模型应用开发教程：从环境到界面的 5 步

从零做一个能对话的大模型应用，最短路径是 1 个 API Key、1 台装好 Python 的电脑、40 行代码、1 个网页界面，2 小时内能跑通第一个版本。下面按准备、动手、参数、报错、验证 5 段写，每步都注明在哪个文件里改哪一行。

我带过 6 个刚转行的同学走这一遍，卡在环境上的有 4 个，卡在代码上的只有 1 个。环境占的时间比写代码多，所以第 1 段值得慢一点做。

一、动手前准备 4 样东西

1. Python 3.10 或更高版本：命令行敲 python --version 看版本号，低于 3.10 先升级，后面 3 个库都会挑版本
2. 1 个模型平台的 API Key：国内可选 DeepSeek、通义、豆包，接口大多兼容 OpenAI 协议，换平台只改 base_url 与 model 这 2 个值
3. 1 个代码编辑器：VS Code 装 1 个 Python 插件就够，别在记事本里写，缩进错了很难查
4. 1 个能跑本地网页的端口：默认用 7860，被占用时换 7861，公司网络限制端口的话先问 1 次网管

第 2 条建议先选 1 家跑通再考虑换。同时申请 3 家平台会拿到 3 套文档、3 种报错码，第一周基本都在对照文档，做不出东西。

二、5 步做出第一个应用

1. 建目录：在磁盘上新建 1 个文件夹叫 mychat，进目录后执行 python -m venv venv 建虚拟环境，再把环境激活
2. 装 3 个库：pip install openai gradio python-dotenv，3 个包加起来 40MB 左右，国内源 30 秒装完
3. 写调用函数：新建 app.py，把 key 放进 .env 文件，用 1 个函数接收用户问题、返回模型答案，函数体 12 行
4. 加对话历史：用 1 个列表按 user、assistant 的顺序追加消息，每次请求把整个列表传回去，模型才有上下文
5. 套网页界面：用 gradio 的 ChatInterface 包 1 层，执行 python app.py，浏览器打开提示的本地地址就能对话

第 1 步为什么要单独建虚拟环境

同一台电脑上跑 2 个项目，库版本常常打架。A 项目要 openai 0.28，B 项目要 1.x，装在系统环境里只能留 1 个版本，另一个项目立刻报错。虚拟环境给每个项目 1 套独立的库，删掉文件夹就等于清理干净。

建环境只要 1 条命令，成本 3 秒。我以前图快直接在系统里装，1 年后系统 Python 里堆了 40 多个包，升级时崩了 1 次，重装花了 2 小时。

第 3 步的提示词放在哪

提示词写进 messages 的第 1 条，role 填 system。这段内容每次请求都会重复发送，所以别写太长，控制在 200 字内够用，写 1000 字等于每次多花 1 份输入 token。

我自己的模板固定 3 段：身份 1 句、输出格式 1 句、禁止事项 1 句。比如做客服场景时，身份写「你是售后客服」，格式写「回答不超过 3 句」，禁止事项写「不承诺赔付金额」。3 段都写具体，比写一堆形容词有用。

第 4 步历史怎么截断

对话轮数不加限制，第 30 轮之后就会顶到上下文上限，报错或答案开始丢前面的信息。处理办法有 3 种：按轮数截断，只保留最近 10 轮；按 token 数截断，超过 3000 就删最早 2 条；把早期对话压缩成 1 段摘要塞进 system。

我做内部工具时用第 1 种，成本可控、行为稳定。对外服务用第 3 种，用户感觉不到对话被剪过，代价是多 1 次总结调用。

三、参数怎么填

第 5 行是新手最容易漏的。默认超时偏短，1 次生成 2000 字要 40 秒以上，客户端先断开，服务端还在跑，账单照扣。我在第 1 个项目里就这样白花了一笔。

第一个版本不用追求参数最优。默认值跑出来的效果已经有 7 分，剩下 3 分靠提示词和后处理补，比反复试参数省时间。我通常让同学先跑 20 条真实问题，把不满意的 5 条挑出来，再针对性调 1 到 2 个参数。

参数不要一次改 5 个。每次只改 1 个，记下改动前后的输出差异，3 次之后你就知道这套模型对哪个旋钮最敏感。

四、报错怎么排查

ModuleNotFoundError 说明库没装进当前环境，多半是虚拟环境没激活。命令行前面没看到 (venv) 这个前缀，就先激活再装 1 次。

401 与 403 都指向 key，检查 3 处：.env 文件里有没有引号包住、key 前后有没有空格、代码里读的环境变量名是否一致。名字拼错时读到的值是空字符串，报的也是 401。

429 是频率限制，处理方式是加等待：第 1 次等 5 秒，第 2 次等 15 秒，第 3 次直接跳出循环并记日志。批量任务里我把并发压到 3，全天跑下来没再撞过墙。

ConnectionError 出现在公司网络里，先确认能不能打开平台官网。打不开就走代理，把代理地址写进环境变量 HTTP_PROXY，代码不用改。

输出乱码或返回半句，查 2 个地方：max_tokens 是否太小、messages 里是否有空内容。空内容一般在历史截断时产生，删到只剩最后 1 条 user 消息也能复现问题。

报错信息里出现 2 个不同平台的域名，说明环境变量里还留着上 1 个项目的配置。检查 3 个位置：系统环境变量、项目里的 .env、终端当前会话，逐个清掉旧值再试。

界面上点了没反应，看命令行窗口。gradio 的报错打在终端里，不弹到网页上，很多人以为是界面坏了，实际是后端抛异常。

五、怎么验证跑通了

1. 连问 3 轮相关的问题，第 3 轮答案能引用第 1 轮说过的内容，说明历史传递正常
2. 打印每次请求的 usage，输入 token 随轮数稳步增长，输出 token 在 max_tokens 以内
3. 把 key 临时改错 1 位，界面能给出可读的错误提示，说明异常分支也被处理了

第 3 条很多人跳过，上线后第一次 401 就看到一屏英文堆栈，用户直接卸载。我给所有对外工具都加 1 层错误映射，把 5 类常见错误翻译成 1 句中文提示。

验证完本地版本，再做 3 个改动就能给别人用：把 key 换成服务端环境变量、加 1 个每日调用上限、把对话记录写进 1 个文件。3 件事加起来半天，缺了任何 1 件都不适合放到公网。

六、从 demo 到能用的 3 个改动

第 1 个改动是给请求加超时与重试。重试 3 次封顶，间隔按 3 秒、8 秒、20 秒递增，这样偶发的网络抖动不会直接变成用户看到的失败。

第 2 个改动是把提示词挪到配置文件。改一次文案不用动代码，非技术同事也能维护，我现在的项目里提示词都放在 1 个 prompts 目录，按场景分 5 个文件。

提示词文件怎么组织

1 个场景 1 个 txt，文件名用业务名，比如 refund.txt、faq.txt，别用 prompt1 这类编号。文件开头写 1 行注释说明用途，第 2 行开始才是正文，读文件时跳过第 1 行即可。

我把这套结构用在了 5 个项目上，改动最频繁的那 1 个文件，1 个月改了 23 次，全部由运营同事自己动手，没让我改过 1 行代码。

第 3 个改动是留 1 个开关，能在不重启服务的情况下切换到备用平台。国内几家平台接口兼容，改 2 个变量就能切，遇到某家限流或故障时，30 秒内能切走。

大模型应用开发的难点集中在 3 处：环境、上下文管理、错误处理。代码本身 40 行就够，剩下的时间都花在这 3 处，把它们的边界想清楚，第二个应用能省一半时间。

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