大模型应用开发教程写到「本地跑通 1 次调用」就结束,是最常见的一步之差。要让同事、客户或前端页面用上这个能力,还差 4 件事:把脚本包成 1 个 HTTP 接口、把密钥挪出代码、给请求加超时与重试、把服务放到有公网地址的机器上。这 4 步做完,1 个 200 行的脚本才算变成 1 个能用的服务。
我 2024 年给 1 家做设备的公司搭过 1 个内部问答接口,第 1 版只用了 40 行 Python,跑在自己电脑上,同事要用就得连我的热点。第 2 天上午接口被外部扫到,1 小时收到 3000 多次请求,余额掉了一半。那次之后我把这 4 步写成了固定清单,后面 6 个项目都按这个顺序走。
环境不齐就往下写,报错会出在莫名其妙的地方。4 项里最容易漏的是第 4 项:很多人本地能跑,一放到服务器就失败,差的就是那条出网规则。
端口这件事值得单独提。uvicorn 默认监听 127.0.0.1,只有本机能访问;写成 0.0.0.0 才对局域网开放。我见过 3 个人卡在这一步,症状都一样:本机 curl 能通,同事浏览器打不开,最后发现启动命令少写了 --host 参数。
改造的顺序从外往里:先定接口长什么样,再填里面的调用逻辑。先写调用逻辑的人,往往把参数写死在函数里,接前端时又要改一遍。
第 4 步决定接口好不好用。不包异常的接口,1 次超时就把整个请求挂住,前端等到 60 秒浏览器自己断,用户看到的是空白页。包了异常,前端能拿到「稍后重试」这类明确提示,体验差一个档次。
接口参数看着简单,错填集中在 3 处:超时设太长、重试次数设太多、max_tokens 不设上限。
| 字段 | 建议填什么 | 常见错填 |
|---|---|---|
| timeout | 30 秒,长文生成放 60 秒 | 不设,默认无限等 |
| max_tokens | 按业务定,问答 800,长文 2500 | 留空,模型写到上限才停 |
| retry | 最多 2 次,间隔 2 秒与 4 秒 | 写 5 次,失败时雪崩 |
| temperature | 问答 0.3,创意写作 0.8 | 全部填 1.0,答案飘 |
| Key 位置 | .env 文件,且加进 .gitignore | 直接写在代码第 3 行 |
表里第 3 行的重试要配退避。失败后立刻重发,等于把 1 次失败放大成 3 次;间隔 2 秒再发,绝大多数瞬时抖动都能过去。第 5 行的 Key 位置更硬:代码一旦推到公开仓库,Key 就等于公开,平台侧的风控会在几小时内标记,后续所有请求都被拒。
本地跑通之后有 2 条路。临时演示用内网穿透,10 分钟能拿到 1 个临时域名;长期使用放云主机,配 1 个域名加反向代理。2 条路的差别在稳定性和备案,演示用前者,上线用后者。
按使用人数分。3 人以内、用 1 到 2 周,内网穿透够用,成本 0 元;超过 5 人、要连续跑 1 个月以上,直接上云主机,1 台 2 核 4G 的入门配置能扛住每天 2000 次请求。
内网穿透的免费版有 1 个限制:域名每次重启都变,带宽也常被限到 1Mbps。演示时够,跑批量任务不够,1 个 2000 字的请求要等 20 秒以上。
云主机的配置顺序别乱:先开安全组端口,再装依赖,最后起服务。反过来做,服务起来了但端口没开,外部一直超时,很容易误判成代码问题。nginx 反代只写 3 行就够:监听 80、转发到 127.0.0.1:8000、带上 Host 头。
内网穿透的临时域名有 1 个坑:地址每次重启都变,前端写死就失效。做法是把地址放配置里,别写进代码。我们给客户演示时吃过这个亏,第 2 次演示前半小时才发现地址变了,现场临时改配置。
接口类故障的排查顺序是「先看状态码,再看日志,最后看代码」。跳过前两步直接改代码,改的往往是没坏的地方。我处理过 1 次连环故障,改了半天代码,最后发现是反代配置里的端口写错 1 位。
502 是反向代理找不到后端,责任在进程或端口;500 是后端自己抛了异常,责任在代码。看 1 个位置就能分开:nginx 的错误日志里,502 会写 connection refused,500 不会。
500 的定位靠堆栈。把异常信息写进日志文件,字段至少留 3 项:时间、请求路径、异常类型。没有堆栈的日志只能看到「出错了」,有堆栈的日志能直接跳到哪 1 行。
| 现象 | 原因 | 处理 |
|---|---|---|
| 502 Bad Gateway | 反代通了,后端进程已退出 | 看进程是否还在,启动日志报什么错 |
| 连接超时 | 端口没放行,或监听在 127.0.0.1 | 改 --host 0.0.0.0,加安全组规则 |
| 前端报 CORS | 浏览器跨域拦截,服务端没带响应头 | 加 1 个允许来源的中间件 |
| 偶发 500 | 模型返回结构变了,解析代码没兜住 | 解析前先判空,异常写进日志 |
| 请求越来越慢 | 单进程阻塞,1 个请求等 1 个 | 先加 workers=2,再拆异步调用 |
第 5 行是新手最容易忽略的性能问题。uvicorn 单进程跑,1 个 30 秒的长请求会把后面排队的请求全堵住。加 1 个 workers 参数,并发能力翻倍,代价是内存占用上升,2 核 4G 的机器上开 2 个刚好。
验证分 3 层,从单次到并发,逐层过。只做第 1 层就上线,等于没测。
第 2 层经常被跳过,后果是线上 1 个畸形请求把服务打挂。空问题要返回 422 这类明确的参数错误,不能让它进到模型调用那一步,白花 1 次 token。
第 1 件是限流。按 IP 或按 Key 设 1 个每分钟上限,例如 20 次,超了返回 429。没有限流,1 个脚本就能把余额刷空,我遇到的那次 3000 请求就是没设限流。
第 2 件是日志。每条请求记 5 个字段:时间、来源 IP、问题长度、耗时、token 数。5 个字段够定位 90% 的问题,字段再多也没人看。日志按天切分,留 30 天。
第 3 件是成本上限。在主账号设 1 个日消耗阀值,超了发邮件。阀值按「日均值乘 2」定,既能兜住异常,又不会天天报警。这 3 件事做完,1 个内部工具才算能交给别人用。
先跑 5 个工作日,记下每天的实际消耗,取中位数当基准,乘 2 就是阀值。样本少于 5 天不要设,设了也是拍脑袋,第 1 周就会误报 3 次以上。
阀值分 2 级:日阀值发邮件提醒,月阀值直接停用 Key。日阀值管异常,月阀值管预算,2 级都设,1 个 10 人团队 1 年的超支能压到 1 次以内。
回到教程本身:跑通 1 次调用是学习的终点,也是工程的起点。中间差的是 4 个固定动作,没有一样需要更难的算法。把这 4 个动作做成模板,第 2 个项目开始,从脚本到可访问的接口只要 1 个下午。本文信息核对时间:2026-11