你在项目里要接国内的大模型，同事丢过来一句「用千帆吧」，结果打开控制台一堆概念：应用、鉴权、在线接口、批量任务，不知道先点哪个。这篇按开发者的动手顺序走一遍，从注册到跑通第一条请求，再到接入前该核对什么。它不教你选哪个模型，也不比价格，只解决「怎么用起来、怎么不踩坑」这一件事。
你在项目里要接国内的大模型，同事丢过来一句「用千帆吧」，结果打开控制台一堆概念：应用、鉴权、在线接口、批量任务，不知道先点哪个。这篇按开发者的动手顺序走一遍，从注册到跑通第一条请求，再到上线前该核对什么。
它不教你选哪个模型，也不比价格，只解决「怎么用起来、怎么不踩坑」这一件事。想横向比一比各家中转与直连渠道的差别，可以顺手到 /sites 和 /rankings 看当时的整理，但那是另一件事，本篇先把调用链路走通。
开通与拿到第一把钥匙：账号、应用与鉴权
千帆控制台里有两层东西容易混：一层是账号级的访问凭证，代表「你这个人/这个账号」；另一层是应用级的调用入口，代表「这次调用算在哪个业务上、走哪套限流」。刚上手时先把这两层分清，后面报错时才知道该去哪个页面找原因。
- 账号级凭证
- 证明调用方身份，通常用于开通、查看用量和创建应用
- 应用级 Key
- 真正写进代码的那把钥匙，决定调用归属、可用模型范围和限流池
- 模型范围
- 创建应用时勾选哪些模型可用，范围越窄，出问题时定位越快
- 创建应用时别一上来把所有模型全勾上，按当前任务只放一到两个，排查问题时变量少很多
- Key 不要硬写进代码，用环境变量或密钥管理服务；本地调试临时放可以，提交前扫一遍仓库和提交记录
- 团队协作就分开建应用，按业务或环境（开发/预发/生产）隔离，别几个人共用一个 Key
- Key 一旦怀疑泄露，先在控制台禁用再重新生成，别指望「应该没人看到」
跑通第一条请求：从在线接口到流式输出
第一次调用别急着把所有参数堆上去。先用最简的同步请求确认连通性和返回结构，知道响应体里哪个字段是正文、哪个字段是用量、出错时错误码放在哪，再往上加东西。
- 发一条最小请求只带必需参数，打印完整响应体而不是只打印正文。验证标准：能稳定拿到返回，且你看得懂每个字段的含义
- 改成流式把同步改成流式，逐片打印。验证标准：能正确拼接分片，且知道哪一片代表结束，不会把中间片当最终结果
- 自己维护上下文对话类任务把历史消息拼成列表一起发。验证标准：多轮追问时模型能接上前文，且你能说清这条列表在哪个变量里
- 压一下长度故意发一段超长输入，看截断或报错行为。验证标准：你知道超限时是报错还是被截断，业务侧不会静默丢内容
流式输出能明显改善等待体感，但要处理分片拼接和中断重连。业务代码里别把「收到第一片」当成「已完成」，否则用户看到的可能是半句话就被写进数据库了。
参数、限流与额度：别等报错才去翻文档
温度、最大输出长度这类参数决定风格和成本。稳妥做法是先按默认值跑一版基线，把结果存下来，之后一次只改一个参数，改完和基线对比，否则你分不清是哪个参数起的作用。
| 现象 | 大概率原因 | 先做什么 |
|---|---|---|
| 请求变慢、偶发超时 | 触到并发或 QPS 上限 | 降并发、加队列和退避重试，别用 for 循环硬怼 |
| 返回内容为空或被拦 | 内容安全策略命中 | 看错误码和返回体，确认是策略拦截而不是网络问题 |
| 突然全部失败 | 额度用尽或 Key 失效 | 先看用量与账单页，再确认 Key 状态 |
| 结果格式不对 | 参数或提示词写法问题 | 回退到基线参数，单独调提示词 |
- 批量任务走队列加指数退避，重试要有上限，别把限流错误无限重试成雪崩
- 错误码要先分类：限流、参数错误、内容拦截、鉴权失败，处理方式完全不同
- 额度用超和请求失败是两回事，前者看账单和用量页，后者看返回体，分不清会浪费大量排查时间
- 压测请在独立应用上做，别拿生产 Key 冲，免得影响线上真实流量
想对各家渠道的实际可用性和价格走势心里有数，可以去 /price-watch 看追踪记录，再决定主备怎么配。具体的数字别记在脑子里，那会变。
接入生产前的自查清单
从「能跑通」到「能上线」中间隔着一段工程活。模型接口不是本地函数，偶发慢和偶发失败是常态，下面这几项没配齐，上线后大概率要半夜被叫起来。
- 超时、重试、熔断三件套先配上，重试只针对可重试的错误，参数错误重试一百次也没用
- 日志记请求耗时、状态码和 token 用量，方便回溯；但别把用户原文整段打进日志，注意脱敏
- 准备降级路径：换备用模型、换备用渠道，或直接返回兜底文案，别让整个功能卡在一个接口上
- 上线前用真实流量比例做一轮灰度，观察错误率和延迟，再全量
备用渠道和模型对应关系，建议直接落到配置里而不是写死在代码里，具体怎么配可以参考站内大模型平台目录里的对照整理。切的时候改配置就行，不用重新发版。
什么情况下这套流程不适用
上面讲的是「调在线接口」这条路。有两种常见情况它直接不适用，提前判断能省掉很多无用功。
- 要往模型里塞自家私有数据做定制，走的是微调或知识库那条路，不是本文的调用流程
- 数据完全不能出内网，那要评估私有化部署，控制台调用这条路直接用不了
- 只是想做一次性的离线批量处理，用批量任务更合适，不用按在线接口那套来设计
- 需求还停留在「先看看效果」，那先用控制台的试用能力验证，别急着写工程代码
判断标准很简单：数据要不要出内网、模型要不要吃你的私有数据、调用是实时还是离线。三条里任一条答案变了，路线就得换。
下一步想对比各渠道的实际可用性、速度和价格走势，再去 /rankings 和 /price-watch 核对当时的数字，比拍脑袋选渠道靠谱得多。→常见问题
一定要先在控制台建应用才能调吗？
多数情况下是的，调用要绑定到一个应用上，额度、限流和统计都跟着应用走。建之前先想清楚这个应用给谁用、放哪几个模型，后面换模型或拆服务时改动会小很多。
本地能跑通，上线就报错，一般是哪里的问题？
先看三类：环境变量或密钥没带上去、出网被限制或代理没配、并发一上来就撞限流。按这个顺序查，比直接改代码快得多，具体错误码含义对照官方文档逐条核。
怎么知道调用花了多少、贵不贵？
用量按 token 算，长短跟你的提示词、历史消息和输出长度直接相关。先压掉没用的历史消息，再去站内价格与模型页面核对当时的单价口径，别拿旧记忆估账。
