企业官网建设流程全解析

上周帮一个做客服工单系统的朋友看需求，他们每天要处理三千多条用户反馈，想做个自动归类加摘要的小工具。聊到模型选型时他第一反应是"肯定用最强的那个"，结果我把成本表拉出来一算，光是把三千条工单全量过一遍旗舰档模型，一个月的账单就够他招半个实习生了。后来换成 Haiku 这个轻量档跑了一遍，准确率掉了不到四个点，延迟从三秒多降到一秒内，成本直接砍到零头。这件事让我意识到，很多人对 Haiku 5.5 这类轻量模型的认知还停留在"便宜但不太行"的阶段，实际上它在高频、短文本、结构固定的任务上表现相当够用。

这篇就把 Haiku 5.5 的上手路径完整走一遍：从零基础的环境准备，到第一次 API 调用跑通，再到参数怎么调、场景怎么落地、账单怎么压。文章里的 SDK 包名、模型 ID、端点地址我都做成了占位符，你按自己控制台里显示的实际值替换就行，不影响照着做。适合两类人看——一类是没接触过模型 API、想找个便宜档位练手的开发者；另一类是已经在用大模型、想把一部分流量迁到轻量档来降本的技术负责人。

1. 先搞清楚 Haiku 5.5 在模型梯队里的位置

选模型这件事，本质上和选车差不多。你不会开着一辆重卡去市区送外卖，也不会骑电动车去拉建材。同一个厂商通常会按能力从低到高铺开几档产品，Haiku 这一档长期定位在"响应快、单价低、上下文够用"的区间，5.5 这个版本号意味着它在保持轻量特性的前提下又做了一轮能力刷新。理解这一点，比记住任何跑分都重要。

1.1 轻量档不是"缩水版"，而是另一种取舍

很多人第一次接触轻量模型时会下意识觉得它是旗舰款的降级产物，能省的都省了。这个理解方向就偏了。轻量档真正做的取舍是：牺牲一部分复杂推理深度，换取数量级的延迟和成本优势。它背后往往是更小的参数量、更激进的推理优化，以及针对短输出场景做的专门调校。

这个取舍在实际业务里意味着什么？我给你拆开说。当你让模型做"把这段三百字的用户反馈归纳成一句话"这类任务时，模型需要的是语义压缩能力，不是多步逻辑推演。这种活旗舰模型能做九十五分，Haiku 5.5 大概能拿九十分出头，但它的单次耗时可能只有对方的三分之一，单价可能只有五分之一。在每天几万次调用的量级下，这五分差距换来的是账单上少一个零。

反过来，如果你要模型做的是"读完这份四十页的合同，找出其中互相矛盾的三处条款并解释冲突点"，那这就是典型的多步推理加长上下文交叉验证，轻量档容易在中间步骤漏掉细节。这类活老老实实交给高档位，或者在流程里做拆分——先用 Haiku 做初筛定位相关段落，再把筛出来的部分丢给旗舰款做深度分析。这种"两级流水线"是我目前最常用的架构，成本能压到全量走旗舰的三成左右，效果几乎无损。

还有一个容易被忽略的点：轻量档在指令遵循的稳定性上往往比大模型更"听话"。大模型见得多、想得多，有时候会自作主张给你补一些你没要求的内容；轻量档反而更倾向于严格按你给的格式输出。做结构化抽取的时候，这个特性是加分项。

1.2 一张表看清什么活该交给它

我把自己踩过的场景整理成了下面这张表，判断标准就三条：输入长度、是否需要多步推理、输出是否结构化。你可以直接对着自己的需求往里套。

这张表不是绝对边界，是我在几十个项目里攒出来的经验值。判断的时候有个简单心法：如果这个任务你能用一句明确的指令描述清楚，且正确答案基本唯一，就放心交给轻量档；如果任务描述里出现"综合考虑""权衡""分析利弊"这类词，就往上升一档。

还有一类特殊场景值得单独提：作为流水线的第一道过滤器。比如内容审核，你可以先用 Haiku 5.5 把明显合规的九成内容快速放行，剩下的一成可疑内容再交给高档位模型人工复核。这种用法下，轻量档不需要判断得多准，只要保证"不漏放"就行，召回率优先于精确率，成本却能省下绝大部分。

2. 从零跑通第一次调用：环境、密钥与最小请求

真正卡住新手的从来不是"模型能力够不够"，而是第一步就跑不通。我见过太多人卡在密钥格式、请求头拼写、响应结构解析这些地方，折腾两小时还没看到第一句回复。这一节我把最小闭环拆到最细，你照着抄就能跑。

2.1 环境准备里最容易被忽略的三件事

先说环境。Python 3.9 以上、能正常访问外网、有一个装好包的虚拟环境，这三样是基础。虚拟环境这一步别省，我见过有人图省事直接全局装，结果跟已有的依赖版本打架，报了一堆看不懂的错，最后重装系统级别的包才解决。用python -m venv .venv建一个，激活之后再装东西，出问题直接删目录重来，成本极低。

第二件事是密钥不要写进代码。这条听起来是老生常谈，但我每年都能在各种代码仓库里翻到硬编码的密钥。正确做法是放进环境变量：

# macOS / Linux export MODEL_API_KEY="sk-xxxxxxxxxxxxxxxx" # Windows PowerShell $env:MODEL_API_KEY="sk-xxxxxxxxxxxxxxxx"

然后在代码里用os.environ.get("MODEL_API_KEY")读。这样做的好处不只是安全，切换测试环境和生产环境时也方便，不用改代码。如果你的项目要提交到版本库，记得把.env加进.gitignore。

第三件事是确认你的账户有可用额度。这个坑太常见了：代码写得没问题，请求发出去返回 401 或 403，人就开始怀疑人生，翻文档翻半天，最后发现是新注册账户没充值或者密钥被禁用了。我的建议是第一次调用前，先去控制台确认三件事：密钥状态是否为启用、账户余额是否大于零、当前密钥所属的项目是否有权限调用目标模型。这三项确认完，能省掉八成莫名其妙的鉴权报错。

至于 SDK，装官方提供的那套就行，包名以你所用平台的文档为准：

pip install <官方SDK包名>

装完用pip show <包名>确认版本，顺手看一眼版本号对应的文档，SDK 的接口在不同大版本之间偶尔会有变动，用老代码配新 SDK 也会报错。

2.2 用 HTTP 手搓一次请求，比 SDK 更能看清本质

我强烈建议第一次调用别用 SDK，直接用requests手写。原因很简单：SDK 把很多东西封装掉了，你根本不知道请求长什么样、响应里有什么。等你遇到线上问题时，排查全靠猜。手搓一次，后面所有问题你都能定位。

import os import requests API_KEY = os.environ.get("MODEL_API_KEY") ENDPOINT = "https://<你的服务端点>/v1/messages" headers = { "content-type": "application/json", "x-api-key": API_KEY, "anthropic-version": "2023-06-01", # 版本头字段名以官方文档为准 } payload = { "model": "<model-id>", # 填控制台里的实际模型 ID "max_tokens": 512, "messages": [ {"role": "user", "content": "用一句话解释什么是向量数据库。"} ], } resp = requests.post(ENDPOINT, headers=headers, json=payload, timeout=30) print(resp.status_code) print(resp.text)

这段代码有几个点值得说。timeout=30一定要加，不设超时的请求在网络上出问题时会把你的进程挂死，线上环境这是灾难。第一次跑建议先print(resp.text)把原始响应打出来，看看结构长什么样——通常是一个 JSON，里面有个content数组，每个元素有type和text字段，另外还有一个usage对象记录输入输出各用了多少 token。

看到usage里的数字时，你会对成本有非常直观的感受。我第一次跑的时候输入八十多个 token、输出四十多个，算下来一次调用不到一厘钱。这个体感很重要，它会让你在后面设计批量任务时不至于畏手畏脚。

如果返回 200 但你找不到文本，八成是解析姿势不对——content是数组不是字符串，可能有多个元素（比如中间夹了思考过程块），要遍历找出type == "text"的那些再拼接。这个坑我在第一次对接时踩过，直接resp.json()["content"]然后当成字符串用，结果打印出来是一个列表，愣了半天。

2.3 SDK 封装版：把重复劳动收进一个函数

手搓跑通之后，就可以上 SDK 了。SDK 的价值不在于让你少写几行请求代码，而在于它帮你处理了重试、流式解析、类型提示这些琐碎事情。我一般的做法是封装一个统一的调用函数，把模型 ID、超时、重试都收进去，业务代码只关心"传什么进去、拿什么出来"。

import os import time def ask(prompt: str, system: str = "", max_tokens: int = 1024, retries: int = 3) -> str: """统一入口：带重试与错误归一化""" last_err = None for attempt in range(retries): try: resp = client.messages.create( model=os.environ.get("MODEL_ID"), max_tokens=max_tokens, system=system or None, messages=[{"role": "user", "content": prompt}], timeout=60, ) return "".join(b.text for b in resp.content if b.type == "text") except Exception as e: last_err = e # 指数退避，别用固定间隔猛怼 time.sleep(2 ** attempt) raise RuntimeError(f"调用失败，已重试 {retries} 次: {last_err}")

这个函数里有几个设计决策值得解释。retries=3配合指数退避2 ** attempt，是因为限流类错误往往是瞬时的，隔一秒再试大概率就过了，但如果你固定每隔 100 毫秒猛怼一次，只会让情况更糟，甚至触发更长时间的封禁。timeout=60比手搓版的 30 秒长，因为 SDK 场景下通常处理的是稍长的文本，留足余量。

system or None这个写法是个小细节：有些平台对空字符串的 system 字段处理不一致，传None表示"不设置"，比传空串更稳妥。至于"".join(...)那段，就是前面说的多元素拼接问题，封装在函数里之后业务层就再也不用操心了。

3. 请求参数才是输出质量的总开关

跑通第一次调用只是开始，真正决定输出质量的是那几个参数。我发现新手最常见的误区是：输出不满意就换提示词，换来换去效果还是飘。其实很多时候问题出在参数上，提示词只占一半功劳。

3.1 max_tokens 与截断：最常见的"答到一半没了"

max_tokens是输出长度的硬上限，超过就直接截断。这个参数设小了，你会看到模型话说到一半戛然而止，而且不会有任何报错——响应正常返回 200，stop_reason字段的值会告诉你是正常结束还是因为长度被截断。

我第一次遇到这个问题是在做会议纪要总结，设了max_tokens=256，出来一段话最后半句是"因此我们建议在这个方向上"，然后就没了。当时还以为是模型能力问题，折腾了半天提示词，最后发现是长度限制。

所以有个铁律：处理完响应后必须检查stop_reason。如果是长度截断（通常是max_tokens这个值），要么调大上限，要么在提示词里明确要求"控制在多少字以内"。

text = "".join(b.text for b in resp.content if b.type == "text") if resp.stop_reason == "max_tokens": # 记录日志，方便后续统计有多少请求被截断 logger.warning("输出被截断，考虑调大 max_tokens 或压缩输入")

那max_tokens设多大合适？我的经验值是：按你期望输出长度的 1.5 倍设。比如你要一段两百字左右的摘要，设 400 到 500 就够。设太大有个隐性成本——虽然按实际用量计费，但过大的上限会让模型在某些情况下倾向于写得更啰嗦。设太小则频繁截断，重试反而更贵。

另外提醒一句，很多平台对输入加输出的总长度也有限制。如果你传了一段超长文本进去，即便max_tokens设得很小，也可能因为总长度超限直接报错。处理长文档的标准做法是分段，这个后面第 4 节会展开。

3.2 temperature 与 top_p：别同时拧两个旋钮

这两个参数控制的是输出的随机性。temperature越低，输出越确定、越保守；越高越发散、越有创意。top_p是另一种采样策略，控制候选词的累积概率阈值。

新手最喜欢干的事是两个一起调。这是错的。官方的建议一直是只调其中一个，另一个保持默认。原因是这两个参数作用在同一个环节上，同时拧会让你完全失去对输出的可预测性——出了问题你都不知道是哪个参数导致的。

我的实际用法很朴素：

有一次做商品标题生成，运营同学抱怨"每次生成的结果都差不多，没新鲜感"。我一看配置，temperature=0.1，当然每次一样。改到 0.8 之后问题解决。反过来也遇到过：做发票信息抽取，temperature默认 1.0，同样的图片转文字内容，十次里有两次把金额的小数点位置搞错。降到 0 之后，一百次测试零错误。这两个例子说明一件事——参数没有好坏，只有匹配不匹配。

还有一个隐藏细节：即使temperature=0，输出也不保证百分之百完全一致，因为底层推理的并行计算顺序可能有微小差异。所以如果你的业务需要严格可复现，别指望靠参数实现，要在应用层自己做缓存或者用结果哈希比对。

3.3 system 提示的写法差异，效果差一截

system字段是用来设定角色和全局约束的，它和用户消息不是一回事。很多人把所有要求都塞进用户消息里，能用，但效果不如分开写。

区别在哪？system 的内容在整个对话中优先级更高，模型会把它当作"行为准则"而不是"待处理的任务"。举个具体的对比：

# 写法 A：全塞在用户消息里 prompt = """你是一个专业的客服助手，回答要简洁，不要超过三句话， 不要用感叹号，遇到不知道的就说不确定。 用户问题：我的订单什么时候到？""" # 写法 B：拆开 system = """你是一名电商客服助手。回答规则： 1. 每次回答不超过三句话 2. 不使用感叹号，语气平实 3. 信息不足时明确说"我需要再确认一下"，不要编造""" prompt = "用户问题：我的订单什么时候到？"

实测下来，写法 B 的格式遵守率明显更高，尤其是规则条数多的时候。原因在于 system 被模型当作持续性约束，而用户消息里的要求容易被当成"这一轮的临时指令"，多轮对话里会逐渐衰减。

写 system 有几个我总结的小技巧。用编号列表而不是大段散文，模型对编号的遵循度更高。规则要写成"做什么"而不是"不要做什么"，因为否定式指令有时会起反效果。还有一点，规则别超过七条，超过之后模型的遵守率会明显下滑，该合并的合并，该挪到用户消息里的挪过去。

4. 三个能直接抄的场景：摘要、抽取、批量分类

光讲参数太虚，这一节直接上三个我反复用过的场景，代码能跑、思路能迁移。这三个场景覆盖了轻量模型最擅长的区间，你按自己的业务改改提示词就能用。

4.1 长文摘要：分段 + 二次归并

直接扔一篇一万字的文档进去，结果通常不理想——要么超长报错，要么模型只抓住了开头和结尾，中间的内容被稀释掉了。正确做法是"分而治之"。

第一轮，按段落或固定字数切块，每块控制在两千字以内，让模型对每块做一句摘要。第二轮，把所有小摘要拼起来，再让模型做一次归并，输出最终版本。

def chunk_text(text: str, size: int = 1800, overlap: int = 100): """带重叠的切块，避免在句子中间切断导致语义丢失""" chunks, start = [], 0 while start < len(text): end = min(start + size, len(text)) chunks.append(text[start:end]) start = end - overlap if end == len(text): break return chunks def summarize_long(text: str) -> str: chunks = chunk_text(text) partials = [] for i, c in enumerate(chunks): s = ask( prompt=f"请用一句话概括以下内容的要点：\n\n{c}", system="你是一名严谨的文档编辑，只提取事实，不做推测。", max_tokens=150, ) partials.append(f"[片段{i+1}] {s}") merged = "\n".join(partials) return ask( prompt=f"以下是同一份文档各部分的摘要，请合并成一段通顺的总结，" f"去除重复信息，保留关键数据：\n\n{merged}", system="你是一名严谨的文档编辑，输出控制在三百字以内。", max_tokens=600, )

这里有两个关键设计。重叠切块（overlap=100）是为了避免一句话被切成两半，"由于成本上升……因此我们决定涨价"这种因果句如果被切断，前后两块的摘要都会失真。片段编号加在中间结果里，是为了第二轮归并时模型能感知到顺序，否则它可能把结论和前提颠倒。

还有个细节：第一轮我用了很短的max_tokens，因为只要一句话。这不仅省钱，还能逼模型做真正的压缩，而不是把原文改几个字还回来。人的经验是，摘要任务里"限制输出长度"比"要求简洁"有效得多。

4.2 结构化抽取：用 JSON 约束输出

这是轻量模型性价比最高的场景。从一段自由文本里抽出姓名、金额、日期、编号这些字段，人工做要几十秒，模型做不到一秒。

关键是把输出格式约束死。我的做法是在 system 里给出完整的 JSON 结构示例，并明确"只输出 JSON，不要有任何解释文字"。

system = """你是一个信息抽取器。从用户提供的文本中抽取字段，严格按以下 JSON 结构输出， 不要输出任何解释、前后缀或 Markdown 代码块标记： { "order_id": "订单编号，找不到填 null", "amount": "金额数字，不带货币符号，找不到填 null", "date": "日期，格式 YYYY-MM-DD，找不到填 null", "contact": "联系人姓名，找不到填 null" } 规则：宁可填 null 也不要猜测。金额如果带千分位逗号要去掉。""" def extract(text: str) -> dict: raw = ask(prompt=text, system=system, max_tokens=300) raw = raw.strip() # 兜底：去掉可能被包上的代码块标记 if raw.startswith("```"): raw = raw.strip("`").lstrip("json").strip() try: return json.loads(raw) except json.JSONDecodeError: logger.warning("JSON 解析失败，原文: %s", raw[:200]) return {}

代码里那段"兜底清洗"不是为了偷懒，是实战必需品。即便你在提示词里千叮咛万嘱咐"不要加代码块标记"，实际跑几千条的时候，仍然会有那么一两个百分比不听话。多写这三行，能省掉后面一堆脏数据。

更要紧的是解析失败的处理策略。我一开始的做法是直接抛异常，结果批处理跑到一半崩了。后来改成两段式：先尝试解析，失败就重试一次并降低温度，再失败就记原始输出、填默认值、继续往下跑。整批跑完之后统计失败率，如果超过百分之二，说明提示词或者数据结构有问题，需要回去调整。

关于"宁可填 null 也不要猜测"这句，一定要写进去。不写的话模型遇到模糊信息会倾向于编一个看起来合理的值，这类错误最难发现，因为格式完全正确，数据却是错的。

4.3 批量分类：并发、限速与结果校验

单条调用和批量调用完全是两码事。批量场景下你会遇到三个新问题：跑得太慢、撞上限流、以及结果不可信。三个都得处理。

先说并发。纯串行跑一万条，按每条一秒算要将近三个小时。用线程池并发能压到几分钟，但并发数不是越高越好。我的经验是从 5 开始往上试，找到不触发限流的最大值再打个七折。因为并发跑满的时候，一旦有个请求卡住，整个池子的吞吐会骤降。

from concurrent.futures import ThreadPoolExecutor, as_completed def classify_batch(items, workers=5): results = {} with ThreadPoolExecutor(max_workers=workers) as pool: futures = {pool.submit(classify_one, it): it for it in items} for fut in as_completed(futures): item = futures[fut] try: results[item["id"]] = fut.result() except Exception as e: results[item["id"]] = {"label": "ERROR", "error": str(e)} return results

限流类的错误（通常是 429）必须单独处理，不能和普通错误混在一起重试。它的语义是"你请求太快了，等一会儿再来"，所以退避时间要更长，而且最好整个进程一起等，而不是各个线程各自等——各自等会让总请求速率依然很高，等于没退避。我一般用一个全局的时间戳共享，碰到 429 就把"下一次允许请求时间"往后推，所有线程都读这个值。

第三个问题最隐蔽：结果看起来都对，其实是模型在偷懒。做情感分类的时候，如果某个类别的样本量特别大，模型会倾向于全部判成那一类。我的应对办法是定期抽一批人工标注的样本做校验，算一下混淆矩阵。如果发现某一类的精确率异常高而召回率极低，说明模型有偏向，要么调整提示词做类别均衡，要么给每个类别加一句定义说明。

还有一个实用技巧：让模型输出理由。哪怕你最终只用标签，让它在 JSON 里多返回一个reason字段，你抽查的时候能快速看出它是不是在瞎猜。这个字段增加不了多少 token，但对调试帮助极大。上线稳定之后可以再把这个字段去掉，用两套提示词分别压测对比。

5. 成本与延迟：怎么在真实业务里压下来

前面所有内容最终都会落到两个数字上：一次调用花多少钱，一次调用等多久。这两个指标决定了你的方案能不能真正上线。这一节讲的全是实操里验证过的压降手段。

5.1 先把 token 账算明白

不算账就谈优化是耍流氓。token 的计费逻辑是输入和输出分开算，而且单价不同，通常输出贵于输入。所以一个常见的误区是只盯着输出长度，其实长文档场景里输入才是大头。

举个具体例子。假设你要处理一篇五千字的中文文档，大概对应三千五到四千个 token。输出三百字摘要大概两百多个 token。如果输入单价是输出的五分之一，那么成本构成大约是：输入占 75%，输出占 25%。这种情况下你优化提示词让输出更短，省下的只是那 25% 里的零头，意义不大。真正的优化空间在输入端。

输入端怎么压？三个方向。第一，去掉无用上下文。很多人在多轮对话里把完整历史一直传，几轮之后输入就膨胀了。实际上大部分场景只需要最近两三轮，更早的内容可以摘要成一句话放进 system。第二，把重复的 system 内容做缓存。不少平台支持提示词缓存，同样的前缀第二次调用时按低价计费，长 system 提示的场景能省一大笔。第三，能不用模型的地方别用模型。正则能抽的字段、关键词能匹配的分类，就别浪费 token 了。

我做过的对比测试很说明问题：一个工单分类任务，优化前平均每次输入 900 token，优化后压到 320 token，准确率没变。省下来的不是一次性的，是每天几万次乘以三十天的量。所以我的建议是，方案上线前一定先采样一百条真实数据跑一遍，把usage里的数字统计出来，算清楚单次成本和日成本，再决定要不要动手。

5.2 缓存、批量与重试策略

缓存这件事值得单独讲，因为它是最容易被低估的省钱手段。业务数据里重复率往往高得惊人——同一批用户反馈、同样的商品描述、同一份模板文档，改几个字就再来一遍。加一层结果缓存，命中率做到三四十个点很常见。

实现上最简单的是对输入做哈希：

import hashlib, json def cache_key(system: str, prompt: str, params: dict) -> str: raw = json.dumps({"s": system, "p": prompt, "t": params.get("temperature", 0)}, ensure_ascii=False, sort_keys=True) return hashlib.sha256(raw.encode()).hexdigest()

注意要把 system、prompt 和影响输出的参数一起算进哈希，只哈希 prompt 会导致参数变了但缓存没失效，出来一堆错的结果。这个 bug 我踩过一次，调试了一下午，因为缓存里的结果看起来完全正常，只是跟当前参数对不上。

缓存的有效期怎么定？我的做法是按业务性质分。事实类抽取结果基本不会变，缓存可以设很长，甚至不过期。创意类生成的缓存意义不大，因为用户本来就要多样性。分类任务居中，设个七天到三十天。

再说重试。前面提过指数退避，这里补一个容易被忽略的点：重试要区分错误类型。400 类错误（参数不对、格式错误）重试一万次也没用，纯浪费钱和时间，应该直接失败并记录。429 类要退避后重试。5xx 类通常是服务端临时问题，重试有效。我第一次做批量任务时没做区分，所有错误一律重试三次，结果一批格式错误的请求白白多花了两倍的钱。

5.3 流式输出什么时候真的有用

流式传输（每次返回一小段，边生成边推给前端）在演示里效果很炫，但很多人不区分场景就一律开流式，反而增加了复杂度。

它真正有价值的地方是用户需要等待结果的场景。比如客服对话、写作助手，用户盯着屏幕，首字返回时间从两秒降到三百毫秒，体感差别巨大。这种情况下流式是必需的，不是可选项。

反过来，批处理场景开流式纯属自找麻烦。你本来就要等全部输出才能做后续处理，流式只会让你多写一套拼接逻辑，还容易在中间出错时留下半截脏数据。我早期有个项目，为了"统一接口"在批处理里也开了流式，结果某次网络波动导致部分请求只拿到了前两个片段，拼起来的 JSON 缺了右括号，解析全崩。后来老老实实在批处理里改成非流式，问题消失。

还有个中间地带值得提：流式 + 提前中断。做内容审核时，如果前五十个 token 里已经出现了明确的违规信号，你可以主动断开连接，不用等它把剩下的内容生成完。这样既省了输出 token，又快了响应。实现上就是流式回调里检查关键字，命中就 break。我们做过测试，这个技巧在审核场景能省下三成左右的输出成本。

6. 零基础最容易卡住的六个报错与排查链路

真正的实战能力体现在出问题时你能不能快速定位。我把过去一年里被问到最多的报错整理了一遍，按现象、根因、排查路径三层拆开。你可以当速查表用。

6.1 鉴权类与限流类：401、403、429

这三个是最常见的，但处理思路完全不同。

401 未授权，本质上就是"我不认识你"。排查顺序应该是：环境变量读到了没有（先print一下长度，别看值）→ 密钥有没有多余的空格或换行（复制粘贴时特别容易带上）→ 密钥是不是被禁用或删除了 → 请求头字段名对不对。最后这条我是真踩过，把x-api-key写成了x-api_key，下划线换横线，肉眼扫三遍都没看出来，最后是逐字符比对才发现的。所以遇到 401，一定要逐字符核对请求头。

403 禁止访问，意思是"我认识你，但你没权限"。常见原因是密钥所属项目没有目标模型的调用权限，或者账户余额为零、账单异常。这种情况查代码没用，直接去控制台看账户状态和权限配置。

429 请求过多，这个最好排查也最容易处理不好。现象是间歇性失败，跑得慢的时候正常，一加压就报。处理方式前面说过：识别出来、指数退避、全局共享退避状态。这里补充一个坑——并发数不是唯一变量，输入长度也会触发限流。有些平台按 token 速率限流而不是按请求数，同样的并发下，处理长文档比处理短文本更容易触发。所以调整参数时要同时看请求速率和 token 速率两个维度。

400 参数错误最容易被忽略，因为它往往只在特定输入下出现。典型场景是长文档超过输入上限、max_tokens设成了负数或字符串、消息数组格式不对。我处理这类问题的固定套路是：把失败的请求体完整序列化成 JSON 打到日志里，然后拿去和文档里的示例逐字段比对。十次有九次能一眼看出问题。

6.2 输出类：JSON 解析失败、截断、空回复

这一类更麻烦，因为请求成功了，报错出现在你的应用层，很容易被误判成"模型能力不行"。

JSON 解析失败前面说过部分原因，这里补全排查链路。第一层看原始输出有没有被代码块标记包裹，这是最常见的。第二层看有没有多余的解释文字，模型有时候会在 JSON 后面附一句"以上是提取结果"。第三层看 JSON 本身是否合法，比如单个引号、尾随逗号、字段名没加引号。第四层才是怀疑模型理解错了结构。

我的处理顺序是：提示词里加"只输出 JSON" + 代码里做兜底清洗 + 失败重试一次（降低温度）+ 统计失败率。四层下来基本能压到百分之一以下。如果还是高，说明你给的结构太复杂了，字段超过十个就该考虑拆成两次调用。

截断的判断依据是stop_reason，前面讲过。这里补一句：截断在流式模式下更难发现，因为流式本来就是一段一段返回，你分不清"这一段结束了"和"整个生成结束了"。所以流式场景下一定要监听结束事件，而不是靠数据流关闭来判断。

空回复是最玄学的一种。请求 200，content数组是空的，或者只有一个空的文本块。常见原因有三个：max_tokens设得太小（比如设成 1），模型连第一个词都放不下；输入内容是空的或者全是空白字符；以及输入触发了某种内容过滤，平台选择返回空而不是报错。排查的时候先检查max_tokens有没有下限，再检查输入有没有实际内容，最后检查usage里的输出 token 数——如果是 0，基本就是前面几种情况之一。

还有一种"假成功"值得单独提醒：模型返回了内容，但和你要求的格式完全不符。比如你要 JSON，它给你一段自然语言描述，格式挑不出错，但没法用。这种情况我一般在提示词末尾加一句"如果无法按格式输出，请输出 {"error": "原因"}"，这样至少能结构化地捕获到失败，而不是在业务层抛一个看不懂的异常。

最后分享一个我一直在用的调试习惯：新建场景时，先拿五到十条典型样本跑一遍，把完整的请求体和响应体都存成本地文件。出了问题直接翻文件，比重新构造请求快得多。这十来个文件攒下来，就是你自己的案例库，下次遇到类似问题，翻一翻往往几分钟就定位了。

我个人在实际操作中的体会是，轻量模型的价值不在于它多聪明，而在于它让"把模型用起来"这件事的成本低到可以随手试。以前做一个想法要先算算预算，现在几十条样本跑下来花不了几分钱，试错速度完全不一样。真正的门槛从来不是模型能力，而是你有没有耐心把第一次调用跑通、把参数一个个摸清楚、把报错一条条搞清楚。这些事做完一遍，后面所有的场景都只是换个提示词而已。