从 404 到 402 再到「通了」：蓝耘元生代 MaaS 接入排障全记录

从 404 到 402 再到「通了」蓝耘元生代 MaaS 接入排障全记录写给第一次用 OpenAI SDK 接蓝耘的人。全文错误码、模型名、usage 字段均来自2026-07-30 本机实跑不是抄文档。平台蓝耘元生代 MaaS ·base_urlhttps://maas-api.lanyun.net/v10. 先给结论忙的人只看这里我用官方文档里的示例模型名跑通「第一次调用」结果连栽两跤顺序报错真实原因一句话处理1404 model .../DeepSeek-V3 not found文档示例模型已下架/更名调GET /v1/models用当前列表里的 id2402 Insufficient account balanceKey 有效账户没额度控制台充值/领资源包充完可能有短暂延迟3正常返回 usage链路已通再上streamTrue做聊天体感选型上我最后落在deepseek-v4-flash列表里有、能聊、带reasoning_tokens适合当日常默认模型。蓝耘这边真正省事的点一个 Key、一套base_url模型广场里 DeepSeek / Qwen / Kimi / GLM 都能换model字段切换——排障时你至少不用在五家控制台之间来回跳。下面按时间线写。你可以对照着复现。1. 我本来只想做一件很简单的事场景很土给一个本地小工具接大模型做接口报错解释和简单问答。自己部署满血模型不划算本地小模型又不够稳于是选了蓝耘元生代 MaaS——OpenAI 兼容、模型多、按 Token 计费。最小目标只有三个Python 官方openaiSDK 非流式对话能回文看懂usage知道钱花在哪流式输出能在终端「一个字一个字蹦」以后好接聊天框。环境macOSPython 3.9openai新版 SDKchat.completions.createKey 放环境变量LANYUN_API_KEY文中一律打码为sk-xxxx2. 第一枪照着旧文档写直接 404第一版代码几乎是「文档复读」importosfromopenaiimportOpenAI clientOpenAI(api_keyos.getenv(LANYUN_API_KEY,sk-xxxx),base_urlhttps://maas-api.lanyun.net/v1,)respclient.chat.completions.create(model/maas/deepseek-ai/DeepSeek-V3,# 文档示例里的名字messages[{role:system,content:你是一个简洁的中文技术助手。},{role:user,content:用三句话介绍什么是 MaaS。},],temperature0.3,max_tokens512,streamFalse,)print(resp.choices[0].message.content)终端原话关键信息未改openai.NotFoundError: Error code: 404 - { error: { message: model /maas/deepseek-ai/DeepSeek-V3 not found, type: api_error, param: None, code: None } }2.1 这一步其实说明了三件「好消息」很多人一见红字就怀疑人生。其实404 在这里信息量很大DNS / 网络通了——请求打到了蓝耘网关Key 大概率有效——鉴权失败通常是 401不是「model not found」路径大致正确——/v1/chat/completions被正确路由了只是model 字符串平台不认。也就是说你的 SDK 写法没大问题问题集中在模型名过期。2.2 正确姿势先问平台「你现在有什么货」不要猜不要死背旧博客。OpenAI 兼容接口几乎都有模型列表fromopenaiimportOpenAIimportos clientOpenAI(api_keyos.getenv(LANYUN_API_KEY,sk-xxxx),base_urlhttps://maas-api.lanyun.net/v1,)forminclient.models.list().data:print(m.id)我当天拉到的 DeepSeek 相关 id以你账号实时列表为准会变deepseek-v4-pro deepseek-v4-flash /maas/deepseek-ai/DeepSeek-V3.2注意两件事旧名DeepSeek-V3/DeepSeek-R1已不在列表命名风格不统一有的是deepseek-v4-flash这种短 id有的仍是/maas/...路径风格。以models.list和模型详情页「API 调用模型名」为准不要混用。这是我愿意长期用蓝耘统一网关的原因之一换模型 换一个字符串排障脚本、业务代码、压测脚本共用同一套 client。3. 第二枪模型名对了变成 402把 model 改成列表里的deepseek-v4-flash再跑openai.APIStatusError: Error code: 402 - { error: { message: Insufficient account balance., type: api_error, ... } }3.1 402 和 404 的分工一定要分清状态码平台在说什么你该动哪401你是谁我不知道Key / Bearer404 model我认识你但不卖这个型号model 字符串402 balance型号有钱包空充值 / 资源包 / 免费额度429你手太快限流、退避5xx我这边晃了重试、换时段、看状态页很多人把 402 当「Key 坏了」——错。402 是商业结果不是技术配置错误。Key 能 list models说明身份已过。3.2 我实际怎么处理的登录蓝耘控制台 → 看余额 / 资源包完成充值或领取活动/新手资源包稍等再请求——我这边出现过充值完成后极短时间内仍 402再跑就 200。更像是计费侧同步延迟而不是代码偶发 bug。小坑有的平台是「先建 Key 再充值」有的是余额为 0 时 Key 表现异常。蓝耘这条链路上我的体感是list models 可以chat 要扣费才严格查余额。排障时用「能 list 不能 chat」快速定位到钱而不是改代码。4. 第三枪通了——非流式最小闭环充值生效后同一份脚本直接出结果内容每次会略有不同结构稳定MaaS模型即服务是一种将机器学习模型以API形式提供给用户调用的云服务模式。 ... --- usage: CompletionUsage( completion_tokens115, prompt_tokens20, total_tokens135, completion_tokens_detailsCompletionTokensDetails(..., reasoning_tokens47, ...), prompt_tokens_detailsPromptTokensDetails(..., cached_tokens0) )4.1 别只看 contentusage 才是「会不会算账」的证据对接入方usage至少要会读这几项字段含义我为什么在意prompt_tokens输入系统提示 历史越长越贵completion_tokens输出max_tokens设太大容易浪费total_tokens合计对账用reasoning_tokens思维链消耗v4 等模型「先想后说」时钱会藏在这里cached_tokens缓存命中Agent / 多轮重发大 system 时降本关键开关当天另一次短请求提示词用一句话解释 Prompt Caching。modeldeepseek-v4-flash指标本机观测单次非压测端到端耗时约3.26s含网络 推理非正式 benchmarkprompt / completion / total11 / 78 / 89reasoning_tokens42cached_tokens0短 prompt、首次合理声明延迟受本机网络、时段、是否命中缓存影响极大。对外写文章或对内选型时请用平台日志 / AI Ping / 自己的 p95 脚本复核不要把单次 3 秒当成 SLA。4.2 可直接粘贴的「今天能跑」版本importosfromopenaiimportOpenAI clientOpenAI(api_keyos.getenv(LANYUN_API_KEY,sk-xxxx),base_urlhttps://maas-api.lanyun.net/v1,)respclient.chat.completions.create(modeldeepseek-v4-flash,# 以 models.list 为准messages[{role:system,content:你是一个简洁的中文技术助手。},{role:user,content:用三句话介绍什么是 MaaS。},],temperature0.3,max_tokens512,streamFalse,)print(resp.choices[0].message.content)print(---)print(usage:,resp.usage)5. 第四枪流式——聊天框体感的分水岭非流式适合批处理、脚本、评测做人机对话几乎必须streamTrue。蓝耘走 OpenAI 兼容 SSESDK 里把streamTrue然后迭代chunk。当前deepseek-v4-flash仍可能带思维链字段reasoning_content不一定每轮都有代码要用getattr防崩。importosfromopenaiimportOpenAI clientOpenAI(api_keyos.getenv(LANYUN_API_KEY,sk-xxxx),base_urlhttps://maas-api.lanyun.net/v1,)streamclient.chat.completions.create(modeldeepseek-v4-flash,messages[{role:user,content:解释一下什么是智能路由尽量通俗。}],streamTrue,)print( 输出开始 )forchunkinstream:ifnotchunk.choices:continuedeltachunk.choices[0].delta reasoninggetattr(delta,reasoning_content,None)ifreasoning:print(reasoning,end,flushTrue)contentgetattr(delta,content,None)ifcontent:print(content,end,flushTrue)print(\n 输出结束 )5.1 我跑出来的体感定性可复现先出现一段「思考」风格的reasoning_content解释怎么打比方、怎么组织结构再进入正式回答content快递/导航类比讲智能路由终端是持续刷字而不是干等 3 秒突然整段弹出。对产品经理说人话就是总时长未必更短但「进度可见」会显著降低等待焦虑。做 Web 聊天框时把 reasoning 折叠成「思考中」content 做主气泡体验会接近主流 AI 产品。5.2 流式排障多看一眼现象可能原因一直没输出代理缓冲、没flush、外层又包了一层非流式 HTTP只有 reasoning 没有 contentmax_tokens太小思维链把额度吃光我短测里就见过 content 空、finish_reasonlength中文乱码终端编码不是 API 问题中途断开超时、网络业务侧要做断线重连与已输出暂存6. 一张表收掉从红字到上线的检查清单把我两小时踩的坑收成可执行清单——建议你接任何一家 MaaS 都走一遍A. 连通性5 分钟base_url是否精确到/v1不要自己再拼出/v1/v1Authorization: Bearer sk-...client.models.list()能否 200从列表复制完整 model id禁止凭记忆B. 计费2 分钟控制台余额 / 资源包 0充值后若仍 402等 1几分钟再试确认 Key 所属账号就是你充值的那个账号子账号/多团队最容易混C. 调用质量10 分钟非流式能打印 content usage看reasoning_tokens/cached_tokens是否按预期出现流式reasoning / content 分离渲染用业务真实 prompt 打 1 次而不是只发「你好」D. 和蓝耘强相关的加分项接入期就能感到统一网关业务只维护一个base_url 一个 Key模型可切换DeepSeek 不够就换 Qwen / Kimi改配置不改架构usage 透明缓存命中、思维链消耗暴露在字段里后面做成本看板才有数据OpenAI SDK 零迁移成本原 OpenAI 项目改两行就能指过来这不是广告句式是我排障时的真实路径依赖如果每换一个模型都要换 SDK、换鉴权头、换 usage 结构404/402 这种事会在每家平台重复学一遍。蓝耘把「学一遍 OpenAI 兼容」的成本摊薄了。7. 模型怎么选别再死磕已经下架的名字结合2026-07-30我账号可见列表一个很务实的默认策略需求更建议先试备注日常对话 / 教程 / 客服草稿deepseek-v4-flash我本次主测模型更重推理 / 复杂任务deepseek-v4-pro更贵按任务开要路径风格旧 id/maas/deepseek-ai/DeepSeek-V3.2列表里仍在V3 无后缀已 404代码 Agent / 工具调用控制台看 Qwen 等 agentic 向型号换 model 即可client 不动千万别把 2025 年博客里的DeepSeek-V3/DeepSeek-R1当永恒真理在文章/代码里写死模型名却不写「以控制台为准」用单次延迟给平台判死刑或发奖状。8. 安全与投稿都要注意的三句话Key 不要进 Git。用环境变量泄露就控制台作废重建。数据论断要写来源。本文延迟与 usage 均标注「本机单次 / 非正式压测」。和产品的关联要具体。「好用」三个字没有信息量「404 换 list models、402 查余额、usage 能看 cached_tokens」才是可核对的使用经验。9. 结尾我真正学到的不是「蓝耘能调通」调通一家 API本来就该是半小时内的事。我多花的时间几乎全耗在过期文档和余额状态上——这俩都不在 SDK 文档的快乐路径里。所以如果让我送给下一个接入者三句口诀先 list 再 chat先余额再调参先 usage 再优化。先 list 再 chat避免 404 模型名陷阱先余额再调参避免把 402 当代码 bug 通宵先 usage 再优化后面做缓存、切模型、控max_tokens才有依据。蓝耘元生代 MaaS 在这条链路上的角色很清楚把多模型收成一个 OpenAI 兼容入口让你把精力留在业务和成本结构上而不是留在「每家一套 SDK」上。我的两个可运行脚本就放在本地 demo 目录非流式lanyun_maas_demo.py流式lanyun_maas_stream_demo.py你要是复现时卡在别的状态码把完整 error JSON 是否能 models.list两样贴出来基本就能定位到是网、是 Key、是模型还是钱。附录本文涉及的平台信息便于审核/复现项值产品蓝耘元生代 MaaSBase URLhttps://maas-api.lanyun.net/v1协议OpenAI 兼容 Chat Completions主测模型deepseek-v4-flash实测日期2026-07-30典型错误404 model not found402 Insufficient account balance数据来源本机 Python 3.9 官方 openai SDK 实跑注册与控制台入口以蓝耘官网 / 活动页最新链接为准文中不放个人 Key。