python+ai大模型应用开发

你可能已经会写 Python，pip install 也很熟，但一碰到大模型就懵：该用哪个 SDK、key 从哪来、为什么本地能跑线上报错、花了多少钱都不知道。这篇不聊原理，只按顺序给你一条能走通的路——先跑通一次调用，再决定用官方接口还是自建，再处理流式、上下文、重试和成本，最后按清单检查能不能上线。每一步都给判断标准和排查顺序，卡住了照着查。

你可能已经会写 Python，pip install 也很熟，但一碰到大模型就懵：该用哪个 SDK、key 从哪来、为什么本地能跑线上报错、花了多少钱都不知道。这篇不聊原理，只按顺序给你一条能走通的路——先跑通一次调用，再决定用官方接口还是自建，再处理流式、上下文、重试和成本，最后按清单检查能不能上线。

每一步都给判断标准和排查顺序，卡住了照着查就行。放心，不需要你先理解注意力机制，也不需要先把向量数据库学一遍，那些是后面的事。这一篇的目标只有一个：让你在今天的下班前，手上有一个能稳定跑起来、知道钱花在哪里的最小应用。

第一步：先跑通一次调用，别急着搭架构

这个阶段唯一的目标是看见一次成功的返回。选一家能立刻拿到 key 的平台，到 /ai-nav/category/ai-model-platform 对照各家计费与限制，先挑一个门槛最低的。不要在这个阶段纠结模型强弱，跑通比选对重要得多，反正后面换模型只需要改一行配置。

Python 侧只装一个官方 SDK 或直接 requests 发 POST，把 model、messages、max_tokens 三个参数写死，打印完整返回体和耗时。先确认三件事：key 有没有生效、请求走的是哪个地址、返回里 usage 字段长什么样。这三样不清楚，后面所有问题都查不下去。

python -c "import requests,os,json;r=requests.post('你的接口地址',headers={'Authorization':'Bearer '+os.environ['API_KEY']},json={'model':'你的模型名','messages':[{'role':'user','content':'你好'}],'max_tokens':64},timeout=30);print(r.status_code);print(json.dumps(r.json(),ensure_ascii=False)[:800])"

• 先确认 key 生效：换成 curl 发同一条请求，报错变化说明是客户端问题而不是网络问题
• 再确认地址：很多人把 base_url 和完整路径混着填，多一层少一层都会 404
• 最后看 usage 字段：输入输出分别有多少 token，这是你后面算成本的唯一依据
• 把这条成功的请求存成一个小脚本，之后所有排查都以它做对照

第二步：本地跑还是调接口，用一个判断标准分开

判断只看两条：数据能不能出本机，以及一天要跑多少次。数据要留在内网、调用量不大，就看 /models/deploy 做部署测算；调用量大、又不在意数据出网，就先按量调接口。别用「哪个效果好」来选，这个阶段两者的差距远小于你的业务逻辑本身。

本地跑的优势是断网也能用、没有按次计费的心理负担；代价是显存、并发和模型版本都要自己扛。想先从本地试，装一个推理工具跑个量化过的小模型是最省事的路子，先验证接口协议通不通，再回去调线上。

结论不要一次定死：先按量调接口验证产品逻辑，验证通了再评估要不要挪到本地，反过来做最容易白折腾。什么情况下这条不适用？如果业务从第一天就明确禁止数据出网，那就没有「先调接口试试」的选项，直接走本地路线，不要在中间反复。

第三步：把接口层的三件事写对——流式、上下文、错误处理

流式输出几乎一定会用上，写的时候注意两件事：分块返回的 JSON 可能被切断，必须做缓冲区拼接，遇到不完整的片段先攒着别解析；前端断连时要主动关闭上游请求，否则你在为没人看的输出付钱。这两条在演示时看不出问题，上线后一定出。

上下文管理要有明确的裁剪策略：留最近几轮、把长文档单独走检索、超出上限前先摘要。别指望模型自己记住，也别把整个对话历史无脑塞进去，那样成本会线性涨、效果还会掉。先想清楚「哪些信息下一轮真的会用到」，再决定留什么。

1. 给每个请求打日志记录时间、模型、输入输出 token 数、耗时、状态码。没有这条日志，出了问题和算成本你都只能猜。
2. 给重试设上限重试两到三次就够，超过就转人工或降级。写成死循环会在限流时把你的额度烧完。
3. 手动构造一次失败把 key 改错、把模型名改错、断网跑一次，看应用的反应是不是你想要的。这一步花十分钟，省后面几小时。

第四步：算清成本和延迟，别等账单来教你

成本按 token 算，输入和输出单价通常不一样。用站内的 /tools/model-cost-calculator 把你的真实调用量带进去算一遍，比拍脑袋靠谱。注意算的时候别只算平均情况，把峰值那一小时也带进去看，限流和额度往往是被峰值打穿的。

延迟分两段：首 token 时间和整体生成时间。前者决定用户觉不觉得卡，后者决定任务能不能按时完成。用 /tools/speed-test 先量出你自己环境里的基线，再谈优化。没测过就换模型，属于瞎换。

• 降本顺序一：先砍没必要的上下文，这一步通常不损失效果
• 降本顺序二：再换更便宜的档位，牺牲一点效果换明显下降的成本
• 降本顺序三：最后才考虑换模型，这一步影响最大所以要放到最后
• 别只看单价：限流阈值和并发上限一样是成本，到 /official-api 核对当时的规格说明，这些数字会变，以页面为准

没有量的优化都是猜，先把基线测出来再动手。

第五步：代码结构怎么摆，才不至于两周后推倒重来

把「调模型」和「业务逻辑」拆成两层：一层只负责发请求、解析返回、重试；另一层只负责业务判断。换模型时只动第一层，这是最值钱的一条约定。听起来简单，但绝大多数返工都来自这两层混在一起。

模型网关层

只管发请求、处理流式、重试、记日志，不含任何业务词

业务逻辑层

只管判断做什么、怎么拼 prompt，不直接碰 HTTP

配置文件

模型名、地址、key、超时时间都放这里，不硬编码

prompt 文件

prompt 单独放文件或数据库，改一句话不需要重新部署

先写同步版本跑通，确认逻辑对了再改异步。一上来就上异步和队列，调试成本会翻倍，而且你会在还没想清楚业务的时候先被并发问题拖住。什么情况下可以直接上异步？你们的业务本身就是长任务、必须排队处理的场景，那是另一回事。

第六步：什么时候该自己部署，什么时候别碰

该自己部署的信号：数据不能出内网、调用量大到按量计费明显不划算、需要固定版本长期不变。到 /compute/sizing 按模型算一遍几张卡够用，再决定。算的时候把冗余也算进去，只按理论值买机器，上线第一天就会排队。

不该碰的信号同样清楚：还在验证需求、团队没人管过服务器、模型要频繁换。这三种情况自建只会拖慢你。尤其是第一和第三条，自建会把「换个模型试试」从改一行配置变成一次部署工程，试错速度直接掉一个量级。

• 真要自建，先跑通一个最小闭环：一个模型、一个接口、一个调用方
• 跑通了再谈并发、监控、扩容，顺序别反
• 许可证在动手前看，不是上线前看：权重能不能商用、能不能改、要不要署名，这些条件决定方案能不能落地
• 准备一个降级路径：自建扛不住的时候能不能切回接口，别把鸡蛋放一个篮子

上线前的自查清单：按这个顺序过一遍

下面这五条按顺序过，哪条没过就先别上线。每条都是可以手动验证的，不需要额外的工具，也不依赖你用的是哪家平台。

1. 日志与计量每次调用有记录、能按用户或项目汇总用量。没有这个，收费和排障都做不了。
2. 失败路径限流、超时、返回格式异常、余额不足，四种情况都手动构造过一次，确认应用不会崩。
3. 成本上限设一个每日或每月的调用上限，到了就降级或拒绝，防止脚本跑飞。用两条测试请求验证拒绝逻辑真的生效。
4. 数据边界输入里会不会出现不该外发的字段，有没有做脱敏。这一条出问题的代价最大，别跳。
5. 回退方案现在用的模型如果当天不可用，能不能一键切到备选。切不了就先别上线。