开放语音识别测试接口前，先写清音频契约、限流与故障语义

把语音识别能力开放给外部调用者时，最先暴露的往往不是模型准确率，而是接口边界。客户端可能上传空白录音、错误采样率、超长文件、双声道数据或被截断的容器；网络重试会重复提交同一段音频；测试流量也可能在短时间集中到一个节点。如果没有明确契约，服务端只能靠猜测修正输入，使用者则无法区分是录音、网络、配额还是识别本身出了问题。

请求合同应从字节一直写到业务结果

文档要同时说明容器与编码。例如WAV只是容器，内部仍可能是浮点、压缩或不同位深；只写“支持WAV”不足以保证解码一致。还需规定采样率、声道数、最大字节数、最长时长、是否接受URL拉取，以及服务端会不会重采样。若支持多种格式，应该在接收阶段完成探测，并在不支持时返回具体原因，而不是把解码失败伪装成空文本。

• 请求标识用于串联客户端日志、网关日志和推理任务。
• 语言、领域或热词参数要给出默认值、长度限制与转义规则。
• 同步接口应规定超时时间，长音频则更适合异步任务。
• 响应要区分最终文本、分段时间、置信信息和警告。
• 所有时间与大小限制都应以机器可校验的单位表达。

空文本也不是单一状态。它可能表示有效静音、音量过低、格式无法解码、语音不在支持语言范围内，或模型确实没有产生标签。返回结构可以把业务结果与诊断码分开，让客户端决定提示用户重新录音还是稍后重试。

同步与异步流程不要共享含糊的成功码

短音频同步识别可在一次响应内返回结果；长音频异步提交则先返回任务标识，随后查询状态或接收回调。任务状态至少应区分排队、处理中、成功、可重试失败、不可重试失败和过期。查询到成功时必须能拿到稳定结果，查询到未知任务时也要区分标识错误与保留期结束。

1. 客户端生成幂等键并提交音频，服务端先校验元数据与配额。
2. 同一账户在有效期内重复提交同一幂等键，返回原任务而非重复推理。
3. 队列记录接收时间和截止时间，超时任务不再无限等待。
4. 推理完成后保存结果摘要，并按保留策略删除原始音频。

限流需要同时保护入口、队列和模型

只限制每秒请求数会忽略音频时长差异。一个十分钟文件与一个两秒口令消耗不同，配额可结合请求数、音频秒数、并发任务和每日总量。入口令牌桶控制突发，账户并发限制避免单个调用者占满工作进程，队列上限则在系统已经饱和时尽早拒绝，而不是让所有请求最终超时。

公开测试版还应标明服务等级边界：是否承诺可用性，数据是否用于改进，结果保留多久，接口可能如何变更。免费并不意味着可以省略滥用防护。密钥要可撤销、可轮换并绑定最小权限；异常账户需要按音频秒数和错误比例识别，而不是只看来源地址。

可观测性要能回答一次请求去了哪里

关键指标包括接收与拒绝数量、音频总时长、解码失败率、排队时间、推理时间、端到端延迟、实时率、不同错误码和队列深度。延迟应按音频时长分桶，否则大量短音频会掩盖长音频积压。日志记录请求标识、账户匿名标识、模型版本和阶段耗时，但不应默认写入完整转写文本或原始音频路径。

模型版本是结果可追溯的一部分。升级后若输出变化，调用方需要知道差异来自输入、参数还是服务端模型，而不是把所有变化归因于随机波动。

隐私边界必须出现在默认流程里

上传语音可能包含身份、地址、健康或商业信息。传输应加密，存储采用最小保留期，运维访问受到审计。若任务只需在线推理，应尽量在结果确认后删除原始文件；若为了排错需要留样，应明确征得许可并做访问隔离。删除策略还要覆盖缓存、对象存储历史版本、队列死信与备份，不能只删数据库中的一条记录。

用一组故障注入替代“Demo能跑”的验收

测试至少覆盖零字节、纯静音、损坏头部、错误扩展名、超时上传、最大合法文件、超限文件、重复幂等键、凭据过期和队列已满。再模拟推理进程在任务中途退出，确认状态不会永久停留在处理中；模拟回调失败，确认重试有上限且签名可验证。客户端示例也要展示超时、退避和错误解析，而不是只有成功路径。

公共语音接口真正的产品边界由契约定义。输入能被确定地接受或拒绝，资源压力能提前反馈，重试不会制造重复任务，音频去向可追踪且按期删除，调用者才能把测试能力安全地接进自己的应用。模型效果仍然重要，但只有在这些工程条件成立后，效果才有稳定、可比较的载体。

版本演进还需要兼容策略。新增字段应允许旧客户端忽略，删除或改变语义的字段则通过新版本路径发布，并保留明确迁移期。服务端在灰度阶段比较新旧模型的延迟、错误类型与资源消耗；一旦回滚，任务状态和结果格式仍要保持可读取。把变更记录、弃用日期和客户端最低版本放进机器可读文档，能防止测试接口在一次升级后突然失去可用性。