Author: a1027986420

把 SDK 的 base_url 换成另一个地址，通常可以让最简单的聊天请求跑起来，但这不代表应用已经兼容。不同供应商可能对模型别名、系统消息、工具参数、流式事件、错误结构和 token 限制有不同解释。真正的迁移成本往往在边界条件，而不是第一条成功响应。

先测请求和响应的基本形状

检查鉴权头、组织或项目字段、模型名、消息角色、空内容、图片输入和最大 token 参数。响应侧要记录 id、created、model、choices、finish_reason、usage 和错误字段是否存在，类型是否稳定。不要因为客户端没有报错就认为字段可用，很多业务逻辑会依赖这些字段做计费和状态判断。

流式和工具调用最容易出现差异

流式接口可能使用不同事件类型、结束标记和 usage 位置；有的实现会把工具调用参数拆成增量片段，有的则一次性返回。客户端如果只按文本 delta 拼接，遇到工具事件就可能丢失参数。测试时要覆盖普通文本、并行工具、工具错误、拒答和主动取消。

工具调用还要检查 schema 是否严格执行、未知字段如何处理、工具结果角色是否被接受，以及模型是否会在没有必要时调用工具。兼容接口的“能发出去”不等于“行为相同”，尤其不能把一个供应商的安全策略推断到另一个供应商。

错误与计费也要放进矩阵

至少制造鉴权失败、限流、超时、模型不存在、上下文过长、内容拒答和上游暂时不可用六类错误。记录 HTTP 状态、内部错误码、是否建议重试和是否已经产生费用。对重试策略来说，429 和参数错误的处理完全不同；对账单来说，响应失败也可能已经消耗 token。

在统一入口上，网关可以把供应商差异映射成内部错误分类、模型别名和 usage 结构。使用 top-api.cc 做迁移测试时，建议保留原始响应摘要和映射后的响应，方便判断是上游行为变化还是适配层改写造成的问题。

一份最小兼容矩阵

• 鉴权、组织字段和模型别名；
• 文本、多模态和空内容请求；
• 流式事件、结束原因和 usage；
• 工具 schema、参数增量和工具错误；
• 限流、超时、拒答和上下文超限；
• token 计数、价格字段和账单关联；
• 最大输出、温度、采样和未知参数处理。

兼容性报告最好给出“完全兼容、需要适配、明确不支持”三种结论，并附最小复现请求。这样开发者迁移时知道哪些功能可以直接切换，哪些需要 feature flag 或专用适配器。

参考资料：各供应商的 OpenAI-compatible API 文档、LiteLLM Proxy 和 Portkey Gateway 的适配说明。接口文档会更新，测试结果应标注日期、模型和 SDK 版本。

如果你需要同时管理多个兼容接口和回退策略，可以从 top-api.cc 统一 base_url 开始，但仍要保留自己的兼容矩阵和回归样本。

AI Agent 最容易让用户不安的不是它不会回答，而是它可能在用户还没看清参数时就执行了动作。删除文件、修改配置、创建资源或发送消息，都应该把“计划做什么”和“已经做了什么”分成两个阶段。预演模式就是在真正提交前生成一份可审查的变更计划。

预演结果要具体到参数和影响范围

一个合格的预演结果至少包含工具名、调用参数、目标资源、预计影响、风险等级、所需权限和过期时间。对于更新动作，最好展示差异；对于批量动作，展示数量、筛选条件和示例。只显示一句“即将执行操作”没有帮助，用户无法判断 Agent 是否理解正确。

风险分级决定谁能提交

读取、搜索和计算类动作可以自动执行；写入、外发和权限变化类动作需要确认；删除、付款、生产发布和跨租户操作应进入更严格的审批。风险级别不能只由工具名称决定，还要结合参数、目标环境、资源数量和用户身份。

预演结果应有短时效。用户确认后，系统再次检查参数哈希、权限和资源状态，避免“先预览、后被别人修改、仍按旧计划提交”。如果状态已经变化，应让用户重新确认，而不是静默套用旧计划。

网关和工具服务各负其责

网关可以统一记录请求、模型、工具名、参数摘要和审批结果，但真正的权限校验必须在工具服务侧完成。工具服务要拒绝客户端伪造的“已审批”字段，并对提交动作提供幂等键和结果查询。对于多模型场景，应该把同一份工具 schema 和风险策略应用到不同上游。

使用 top-api.cc 作为统一调用入口时，可以先把模型输出的工具调用转成待确认事件，再由业务系统提交。这样既能比较不同模型的调用意图，也能避免某个供应商的 SDK 默认行为绕过审批。

测评预演模式的六个问题

• 预演是否展示真实的目标和影响范围；
• 参数被修改后是否要求重新确认；
• 模型切换后风险级别是否仍然生效；
• 审批人是否能看到足够的上下文但不接触多余隐私；
• 提交失败或部分成功时是否有明确回执；
• 重复提交是否会重复产生副作用。

预演模式不是给 Agent 加一层漂亮的确认弹窗，而是把意图、授权、提交和结果拆成可审计的状态机。高风险工具宁愿多一次确认，也不要把用户只能事后发现的动作当成“自动化效率”。

参考资料：OWASP 对过度代理权限和不安全工具调用的风险说明，以及各 Agent 框架关于 human-in-the-loop 的公开文档。产品实现仍需结合自己的权限模型。

如果要在不同模型之间对比工具调用的风险，可以通过 top-api.cc 固定 schema 和策略，把模型差异留在意图生成层，把最终提交留在业务审批层。

AI 工具可以生成 PDF、表格、演示文稿、压缩包和代码文件。文件看起来像普通附件，但其中可能包含宏、外部链接、隐藏脚本、错误权限或不应交给另一个租户的内容。把“模型生成”误当成“文件可信”，会让下载和协作链路失去最后一道检查。

先检查真实类型而不是文件名

上传或生成后，服务端应通过魔数和解析器判断真实 MIME 类型，再限制允许的扩展名。压缩包要检查嵌套层级、解压大小和路径穿越；文档要检查宏、外部引用、嵌入对象和超链接；图片要检查元数据和异常尺寸。文件名由用户或模型生成时，不能直接拼接到磁盘路径。

扫描分为静态和策略两层

静态扫描负责病毒、脚本、宏和格式异常；策略扫描负责内容分类、敏感信息、外部链接和是否允许下载。代码文件还应经过语言和依赖检查，不能只因为文件是文本就跳过安全处理。扫描结果要和文件版本绑定，重新生成或修改内容后必须重新扫描。

临时链接也需要权限边界

下载链接应使用短时效、单文件、单租户的授权，并在服务端再次校验用户身份和项目权限。不要把对象存储的永久公开 URL 直接写进 AI 回复。下载、预览、分享和删除都应有审计事件；如果用户撤回或文件被判定为高风险，旧链接应立即失效。

文件处理常常跨越模型、网关、对象存储和前端。使用 top-api.cc 这类统一入口时，可以把文件元数据、生成请求和租户标识关联起来，但原始文件仍应放在独立的受控存储中，不要把大文件和敏感正文长期写入网关日志。

发布前的检查表

• 真实 MIME 类型和扩展名是否一致；
• 是否扫描宏、脚本、嵌套压缩和外部链接；
• 是否限制文件大小、解压比和目录穿越；
• 是否按租户和项目隔离存储与下载；
• 临时链接是否短时效且可撤销；
• 扫描结果是否绑定文件版本；
• 高风险文件是否进入人工复核而非直接下载。

生成文件的安全目标不是阻止所有文件，而是让“可预览、可下载、可执行、可分享”成为不同的权限级别。尤其是代码、脚本和带宏文档，默认应当按高风险内容处理。

参考资料：OWASP LLM 应用风险项目、OWASP 文件上传安全建议，以及对象存储的临时授权文档。具体扫描器应在隔离环境中验证，不要把单一产品的检测结果当作完整保证。

如果需要把多模型生成、文件元数据和成本记录串起来，可以先让 top-api.cc 处理调用统一性，再把文件扫描与存储权限放在独立的安全服务中。

长上下文宣传常常只强调最大 token 数，但业务真正遇到的是：历史消息太长后哪些内容被丢掉，检索片段重复后模型是否忽略关键证据，超出限制时网关如何处理，以及长输入带来的成本和延迟是否还能接受。

先确认谁在截断

可能截断请求的地方有客户端、Agent 框架、网关、供应商 SDK 和模型服务。每一层的方向也不同：从最早消息开始删、从检索结果末尾删，或只保留摘要。测试时应记录发送前 token 数、网关改写后的 token 数、供应商返回的 usage 和最终保留的消息摘要。否则出现错误时，团队很容易把问题归咎于模型。

用位置测试发现“看见但没用上”

把同一个关键事实分别放在上下文开头、中间、结尾和工具结果中，再用相同问题询问。加入相似但错误的干扰内容，检查模型是否能按来源和优先级选择正确事实。对多轮对话，要测试旧指令、用户撤回和最新约束的冲突，避免单轮样本给出过于乐观的结果。

预算应该按任务管理

可以把上下文拆成系统规则、用户输入、历史摘要、检索证据和工具结果五个预算区。每个区有上限，超出后采用可解释策略：摘要、去重、降级为标题，或要求用户确认。比起把所有内容塞进最大窗口，明确预算更容易控制成本和延迟，也方便排查回答为什么发生变化。

如果请求经常需要在不同模型之间回退，统一网关可以在路由前计算 token 预算，选择能容纳当前上下文的模型，并保留“删掉了什么”的摘要记录。使用 top-api.cc 这类入口时，最好把上下文裁剪策略放在自己的业务层或显式配置中，不要依赖某家上游的隐式行为。

测评结果至少包含这些项

• 发送前、改写后和响应后的 token 数；
• 不同位置的关键信息准确率；
• 检索重复、冲突和过期信息下的表现；
• 截断后是否给出明确标记；
• 上下文长度增长带来的 P95 延迟和成本；
• 模型切换后摘要和指令优先级是否保持。

长上下文不是免费存储。它会增加隐私暴露面、提示注入入口和账单波动。对于高风险应用，应把信息最小化、来源标记和人工确认放在“扩大窗口”之前。

参考资料：各模型上下文窗口与 token 计费文档、OWASP 对提示注入和敏感信息暴露的风险说明。模型限制和价格变化很快，正式报告应记录版本和日期。

需要在多家上游之间比较相同上下文的保留和裁剪行为时，可以通过 top-api.cc 统一请求格式，再把每次裁剪摘要保存为回归证据。

Embedding API 看起来比聊天模型简单：输入文本，返回向量。但向量质量会直接影响搜索、推荐和知识库回答，真正的差异往往要经过检索链路才能看出来。只比较维度和价格，很容易选到“单价便宜、业务召回差”的方案。

先建立带难例的检索集

测试集至少包括同义表达、错别字、缩写、跨语言、长文档、数字和权限标签。每个查询需要有人工确认的相关文档，才能计算 Recall@K、MRR 或 nDCG。不要只用随机切分的训练文档，因为那会掩盖真正的难例。还要专门放入“看起来相似但权限不同”的样本。

质量之外的四项指标

第一是批量吞吐。生产系统经常需要离线切片和重建索引，单条延迟并不能代表批处理效率。第二是尾延迟，P95 和 P99 直接影响在线问答。第三是成本，包括输入字符、token、批处理折扣和重复重建的费用。第四是版本稳定性，模型升级后向量空间可能变化，旧索引是否需要重建必须提前验证。

多语言系统还要比较不同语言之间的相似度是否可用；中文、英文、代码和混合文本不要用同一条结论。对于长文档，要测试切片长度、重叠窗口和标题保留对召回的影响，而不是把问题归咎于模型。

把租户边界放入测试

向量检索最大的安全问题之一不是“搜不到”，而是搜到了不该看到的内容。每条向量都应带租户、项目、来源和权限元数据，检索过滤必须在向量库或网关的受控层执行。测试集需要包含同文档不同租户副本，确认相似度排序不会绕过过滤条件。

统一 API 入口可以让不同 Embedding 供应商共享鉴权、配额和账单。通过 top-api.cc 做对照时，建议固定文本清洗、切片和批量大小，只替换 embedding 模型，否则测到的是整个数据处理流程的差异。

推荐的评测表

• Recall@5、Recall@10 和 MRR；
• 中文、英文、代码和混合文本分组结果；
• 单条与批量的 P50、P95、P99 延迟；
• 每百万字符或 token 的实际成本；
• 模型升级后旧索引的兼容性；
• 过滤条件下的跨租户误召回率。

最终选择不一定是分数最高的模型。一个质量略低但延迟稳定、价格可预测、版本策略透明的 API，可能更适合生产；一个离线检索很强却无法稳定批处理和隔离租户的服务，则需要谨慎使用。

参考资料：各供应商 Embedding API 文档、向量检索基准的 Recall/MRR 定义，以及 OpenTelemetry 对生成式 AI 调用指标的讨论。价格和模型版本应在发布前重新确认。

如果需要把多个 embedding 上游放入相同的鉴权和成本框架，可用 top-api.cc 做一层实验性统一入口，再把最终结果回写到自己的检索评测平台。

很多 AI 搜索和知识库产品会在回答底部放几个链接，于是测评报告容易写成“支持引用”。但链接存在只是形式，真正重要的是它是否支持当前结论。一个与问题相关却没有包含关键证据的页面，不能因为被列出来就算作高质量引用。

先测来源是否真的支撑结论

把回答拆成可验证的事实单元，再检查每个事实是否有对应来源。引用可以分成直接证据、间接证据和背景材料三类。直接证据包含结论所需的原文或数据；间接证据只能说明相关主题；背景材料则不能独立支撑结论。测评时应记录覆盖率，而不是只统计引用数量。

证据片段决定可复核程度

只展示一个标题和链接，用户仍然需要重新翻页。如果产品能给出段落、页码、时间戳或字段路径，复核成本会低很多。对于动态页面，要保存抓取时间和内容版本；对于 API 文档，要记录版本号。引用片段过短会丢失限定条件，过长又会让用户找不到重点，因此应该同时保留上下文范围。

处理过期和冲突来源

同一个问题可能有多个版本、公告和社区讨论。工具应优先展示更新时间、来源类型和版本范围，不能简单用最新页面覆盖旧规则。发现冲突时，答案应该明确指出“来源之间不一致”，而不是把两段内容拼成一个确定结论。

可以准备一套包含日期、版本和否定条件的测试集，观察工具是否会忽略“仅适用于某地区”“已在某版本废弃”这类限制语句。对企业知识库，还要检查用户是否能访问被引用的原文，避免引用了权限之外的内容。

中转网关能帮什么

引用质量主要由检索和生成流程决定，但统一入口可以帮助记录模型、提示版本、检索耗时和响应摘要。通过 top-api.cc 这类中转站做多模型对照时，可以固定同一份检索结果，比较不同模型是否选择了同样的证据，避免把检索差异误判为模型差异。

五项评分指标

• 事实覆盖率：可验证事实中有多少得到直接证据；
• 证据准确率：引用内容是否真正支撑对应句子；
• 新鲜度：来源更新时间是否满足问题要求；
• 冲突识别率：多个来源不一致时能否显式提示；
• 复现成本：用户能否打开来源并重建结论。

引用不是装饰，而是 AI 工具输出的一部分。测评报告最好提供失败样本，例如“链接相关但没有支撑”“引用过期版本”“把背景页面当作事实证据”，这样产品团队才能修检索、提示词或权限策略。

参考资料：OWASP 关于知识边界和不当输出的风险说明，以及各知识库产品对来源和检索结果的公开文档。不同产品的引用格式不应直接横比，先统一评分定义。

如果你希望比较多个模型在同一检索证据下的引用行为，可以用 top-api.cc 统一调用并保存最小化测试记录，再把失败样本加入回归集。

“跑一遍攻击提示词”不能证明模型安全。不同工具的探测器、判断器、输入格式和报告方式都不同，模型还可能因为温度、系统提示和工具权限变化而得到完全不同的结果。红队工具测评应该比较它能否稳定发现问题、复现问题并推动修复。

Garak 更像探测器集合

Garak 的定位接近 LLM 漏洞扫描器，适合批量运行多类 probes，对越狱、提示泄露、错误信息和不安全输出做初筛。它的优势是可以把已知攻击模式组织成可重复的扫描任务；局限是通用探测器不一定理解你的业务规则，结果还需要人工或业务评测器复核。

Promptfoo 更适合把评测接入开发流程

Promptfoo 常用于把多个模型、提示词和测试断言放在同一个配置中比较，也适合做红队、回归和模型切换前后的差异检查。它更接近“可编排的测试框架”，但配置质量决定了结果质量。只增加攻击提示词，不定义通过标准、严重性和人工复核流程，最终仍然只是一个漂亮的报告。

自建用例不能被通用工具替代

企业真正关心的常常是业务特有风险：客服是否泄露内部订单、代码助手是否越过仓库边界、工具调用是否绕过审批、知识库回答是否混入其他租户内容。这些问题需要用真实的权限、数据分类和业务动作建模，通用扫描器只能提供补充。

建议用三层流程

第一层是快速扫描，使用 Garak 或类似工具覆盖常见风险。第二层是配置化回归，用 Promptfoo 或自建 harness 固定系统提示、模型参数和断言。第三层是业务红队，使用脱敏数据和隔离环境验证真实权限、工具和数据边界。每层都要保存输入版本、模型版本、响应摘要、判定依据和复现命令。

在网关侧，把 top-api.cc 作为测试流量入口可以减少供应商差异：同一组用例通过统一鉴权和路由发往不同模型，再比较拒答、改写、工具调用和延迟。测试环境要单独使用密钥和配额，避免红队样本污染生产账单或触发真实动作。

工具选型清单

• 能否接入 OpenAI 兼容接口和自定义 HTTP 服务；
• 能否固定模型、系统提示和随机参数；
• 判定器是否支持规则、分类器和人工复核；
• 是否能重跑单条失败样本；
• 报告能否关联修复提交和回归结果；
• 是否可以限制请求速率、数据范围和工具权限。

不要把“通过率”直接当安全分数。安全评测的结果应该回答：哪类输入触发了什么行为、影响范围是什么、修复后是否仍然复现，以及这项风险是否在模型或提示词更新后重新出现。

参考资料：OWASP GenAI Security Project、NVIDIA Garak 项目和 Promptfoo 项目文档。工具版本与探测器会变化，发布文章时应注明测试日期。

完成基础扫描后，可以用 top-api.cc 做多模型对照测试，把红队发现变成可重复的网关回归样本。

AI 应用的慢请求通常不是单点故障：用户请求先经过 Web 服务，再进入 Agent、工具、队列和模型网关，最后才到供应商。如果每一层只写一行“调用失败”，排查时就不知道延迟发生在哪里，也无法判断是路由策略、网络还是模型本身造成的。

一条模型调用至少要有三层信息

第一层是链路关联信息：trace_id、span_id、父级 span、租户或项目的内部标识，以及请求开始和结束时间。第二层是模型信息：供应商、模型名、模型版本或别名、路由决策和是否发生回退。第三层是结果信息：输入和输出 token、首字节时间、总延迟、状态、结束原因、重试次数和错误分类。

这些字段应尽量使用稳定的枚举和内部 ID。不要把完整提示词、文件内容、API Key 或用户邮箱直接当成 span 属性。需要排障时，可以保存经过脱敏的摘要、版本号或内容哈希，再通过受控的日志系统查询原始证据。

不要把 token 当成唯一成本指标

token 数量是重要的资源指标，但它不能解释所有成本。图像、音频、工具调用、缓存命中和供应商计费规则可能使用不同单位。网关可以同时记录 usage 原值、内部成本估算、计费版本和报价表版本，并在账单对账时标记“估算”和“已确认”两种状态。

延迟也要拆开：排队时间、鉴权时间、上游连接时间、首字节时间、生成时间和后处理时间。对于流式请求，平均延迟常常掩盖长尾，至少要看 P50、P95 和 P99。对失败请求，记录最后一个协议事件和是否已经产生 token，比单个 500 状态码更有用。

让网关成为统一观测边界

如果每个应用自己接入不同厂商 SDK，字段很快会失控。把 top-api.cc 这类中转入口作为统一边界，可以在不改动业务代码的情况下补充路由、模型、成本和重试字段。应用只需要传递业务 trace 和项目标识，网关负责把上游响应映射到统一的内部事件。

但统一入口不等于无限采集。建议按租户和环境设置采样率，开发环境可保存更多调试信息，生产环境只保留必要摘要。对高风险工具调用，增加审批结果、执行状态和回滚标识；对普通文本请求，则不必保存完整内容。

落地顺序

1. 先统一 trace 传播和请求状态；
2. 再增加模型、路由、延迟和 token 字段；
3. 通过错误分类区分限流、超时、拒答和协议错误；
4. 把遥测数据与账单、发布版本和回放样本关联；
5. 最后再决定哪些脱敏片段值得保留。

OpenTelemetry 的价值在于可移植的链路基础，而不是替代所有 AI 专用指标。接入前先明确谁能看原始内容、保留多久、如何删除，避免为了“可观测”把敏感数据复制到更多系统。

参考资料：OpenTelemetry Semantic Conventions 的 GenAI 方向、LiteLLM Proxy 与 Portkey Gateway 的观测能力说明。标准字段仍在演进，生产环境应锁定自己的字段版本。

如果你的应用已经有多家模型供应商，先把请求统一经过 top-api.cc，再在网关边界上建立一套可迁移的 trace 和成本字段，通常比逐个改 SDK 更容易控制范围。

超时并不等于上游没有处理请求。客户端可能已经发出请求，上游也已经扣费，只是响应没有及时回来。如果网关收到超时就重新发送，最终可能得到两次模型调用、两次账单，甚至把“创建订单”“发邮件”这样的工具动作执行两遍。

幂等键不是随便生成的 request_id

一个可用的幂等键必须代表“同一次业务意图”，而不是每次网络重试都重新生成。网关可以要求客户端传入业务键，也可以根据租户、会话、动作编号和请求版本生成。键需要绑定模型、工具参数和关键请求选项，避免同一个键被错误复用于完全不同的任务。

服务端要保存幂等键的状态：处理中、已完成、已失败但可重试、结果未知。遇到相同键时，不能简单返回“重复请求”，而应根据状态返回原结果、告知仍在处理，或要求人工确认。保存时间也要和客户端可能的重试窗口匹配，太短会留下重复执行的空档，太长则会阻塞合法的新任务。

把请求重试和工具重试分开

纯文本生成通常可以在明确失败后重试，但工具调用要看副作用。查询、读取和校验类工具可以通过相同幂等键安全重放；写入、删除、付款和发送类工具必须由工具服务自己提供幂等约束，不能把责任全部推给 AI 网关。

一个实用做法是把模型响应中的工具调用先放入“待执行”状态。工具执行器检查动作键、租户和权限后再提交；提交结果写回后，重复请求只返回原执行结果。对“响应已丢失”的情况，网关还需要提供状态查询接口，让客户端先查结果，再决定是否重试。

测评时故意制造不确定性

测试不能只模拟明确的 500。还要制造这些情况：上游已经接收但网关读不到响应、响应在工具调用后断开、客户端在超时后立刻重试、队列重复投递、数据库写入成功但回包失败。每种场景都要对照调用次数、上游账单、工具执行记录和客户端最终状态。

在统一入口上做多供应商测试时，可以让 top-api.cc 负责鉴权、路由和调用记录，再把幂等键贯穿网关、队列和业务服务。这样能区分“同一个业务请求切换了上游”与“同一个请求被重复提交”这两类问题。

最小实现清单

• 幂等键由业务意图生成，重试不改变；
• 记录处理中、完成、失败和结果未知四种状态；
• 对工具副作用使用工具侧幂等键；
• 保存原始响应摘要和账单关联 ID；
• 设置明确的幂等键过期时间；
• 给客户端提供查询未知结果的接口；
• 日志中隔离租户、密钥和敏感参数。

幂等设计的目标不是让所有请求都可以无限重试，而是让系统在“不知道上游到底做没做”的时候仍然能收敛到一个可解释状态。只要业务动作可能产生费用或副作用，就应把幂等当成网关的基本能力，而不是出了重复扣费再补数据库脚本。

参考资料：HTTP 方法幂等语义、主流支付 API 的 Idempotency-Key 设计，以及 Portkey Gateway 的重试配置说明。实际字段以目标供应商 API 为准。

如果需要先统一不同上游的鉴权、路由和账单关联，再逐步补齐幂等策略，可在 top-api.cc 上用低风险查询和测试模型验证完整链路。

很多 AI API 的演示只测“最后有没有返回完整答案”。但在聊天、代码生成和 Agent 场景里，用户先看到什么、网络中断后能不能恢复、已经返回的部分是否有用，同样决定体验。流式输出应该被当成一条持续变化的连接来测，而不是普通的 200 响应。

先把五个时间点记下来

第一项是首字节时间，也就是请求发出到第一个有效事件抵达的时间。它反映鉴权、排队、模型准备和网关转发的总开销。第二项是令牌间隔，平均值不够，还要看 P95、P99 是否出现长停顿。第三项是完整结束时间，应该和输出长度一起记录，避免把“回答更短”误判为“接口更快”。

第四项是断流位置。断在开头、中间或工具调用事件之后，恢复策略并不相同。第五项是取消后的行为：客户端停止读取后，上游是否仍然继续消耗额度，网关是否及时关闭连接，都要通过账单和日志核对。

用故障样本代替单次体验

至少准备四组样本：短回答、长回答、包含工具调用的回答，以及主动取消的回答。每组重复多次，记录状态码、事件类型、最后一个合法事件、usage 字段和连接关闭原因。不要只看文本是否完整，因为有些 SDK 会把协议错误吞掉，最终只留下一个看似正常的字符串。

断线恢复也要分级。若协议支持事件 ID，可以从最后一个已确认事件继续；如果不支持，就应该把重试标记为新请求，避免客户端把两段内容无条件拼接。对有副作用的工具调用，重连前必须确认工具是否已经执行，不能仅凭文本判断。

网关层应该做什么

网关可以统一补充 request_id、stream_id、首字节时间和结束原因，同时限制单次连接时长、输出速率和最大缓冲区。日志不必保存全部提示词和答案，保留事件计数、哈希、错误类型和必要的脱敏片段即可。对不同上游使用同一套样本，就能比较真实的流式稳定性。

如果需要同时测试多个模型，可以在 top-api.cc 这类统一入口上复用同一套请求和样本，重点对比首字节、断流率和取消后的资源消耗，而不是只比较最终文案。统一入口的价值是让协议、鉴权和采样方式保持一致。

一份可执行的检查清单

• 是否记录首字节和令牌间隔的分位数；
• 是否能识别正常结束、主动取消、上游错误和网络断开；
• 断流后是否会重复执行工具；
• usage 和账单是否包含被取消的部分请求；
• 长连接是否有超时、限速和最大输出保护；
• 日志是否做到可排障但不把敏感正文长期落盘。

流式 API 的测评结果应该最终落到“什么情况下可恢复、什么情况下必须人工介入”。在生产环境中，部分结果、断流和取消都是正常事件，真正的风险是系统把它们伪装成成功，或者在恢复时重复执行了用户动作。

参考资料：OpenAI Cookbook 的流式响应示例、Portkey Gateway 的可靠路由说明。发布前应以实际供应商协议为准。

需要把多家上游放在同一套样本下比较时，可从 top-api.cc 的统一 API 入口开始，再把流式指标接入自己的监控系统。