跳转到内容

AIGoCode API 返回文字就算完成吗:四种协议的非流式结束字段怎么记录

AIGoCode发布于 更新于

四类协议响应汇入独立检查记录

给一次调用留下四个独立结果

应用已经收到一段文字,后台任务就能标为完成吗?如果你正在把 AIGoCode 的不同协议接到同一个任务系统,建议至少分别保留 HTTP 结果、正文提取结果、协议结束字段,以及业务校验结果。

这四项回答的问题不同。HTTP 层是否成功,不等于已经确认正文结构;提取到文字,也不等于文字满足你的业务要求。本文面向普通 JSON 非流式响应,整理官方示例已经展示的结束字段与记录位置,不把示例中的值扩展成全部模型、全部场景的成功保证。

如果你还没有拿到文字,先看响应文字解析指南。这里继续解决的是:同一任务系统怎样保留不同协议的结束信息,避免在统一转换时丢掉线索。

先保留协议,再读取相应位置

四种文档的示例层级不同:

本次实际协议需要保留的位置官方非流式示例展示的值记录范围
Responses顶层 statuscompleted整份响应上的状态
Chat Completionschoices 中相应项的 finish_reasonstop对应 choice 的结束原因
Anthropic Messages顶层 stop_reasonend_turn消息生成结束原因
Gemini generateContentcandidates 中相应项的 finishReasonSTOP对应 candidate 的结束原因

这些值来自官方页面的展示样例,不是一张完整原因枚举表。不要把大小写不同的字符串直接当同一个协议字段,也不要只抽出一列叫「success」后删除原始字段。

例如,Chat 的字段在 choice 中,Gemini 的字段在 candidate 中。如果程序选取其中一项来展示,就同时记录选中项的位置和该项的结束原值;不要把某项原因脱离位置后,当成整个数组的共同结论。

一个适合任务日志的最小记录结构

可以在自己的应用里设计以下记录项。这些是日志设计建议,不是 AIGoCode 新增的 API 字段:

自定义记录项记录内容
协议与接口本次实际请求使用哪一种格式
HTTP 结果应用实际取得的状态码或请求异常
文本提取结果已提取、未找到,或当前结构不支持
结束字段位置例如 status,或所选 choice 的 finish_reason
结束原值保留真实返回的字符串;缺失时明确记为缺失
业务核对输出是否满足本任务的格式、完整性与人工验收要求

业务侧若还要一个统一状态,可在保留这些原始观察后再计算。这样,后续发现适配器规则有误时,可以从记录还原判断依据,而不必重新发送请求寻找原来的信息。

缺失与陌生值都要留下来

官方示例不是每次请求的完整契约。读取前检查目标对象、数组及字段是否存在;未取得结束字段时,记录「未观察到」,不要用样例值补齐。

同样,遇到尚未在程序中处理的原值,先保留原值及协议,再进入明确的待核对分支。不要只因它不是表中的样例就断言发生某种具体故障,也不要先把未知值改成正常完成。

日志中还应区分没有选择到候选,与选到了候选但字段缺失。这些是给自己解析器设计的检查条件,不表示平台承诺会返回某种特定的异常结构。

把结束字段和正文内容分开验收

假设任务要求输出三条检查意见,应用确实提取出了文字,也取得了官方示例中的结束值。接下来仍要检查是否真的有三条、内容是否与输入有关,以及是否包含任务要求的必要信息。

结束字段提供协议层面的观察;业务规则由你的任务定义。不要把「生成结束」写成「结论一定正确」或「可以直接执行」。代码修改、对外答复等需要人工验收的结果,继续保留原来的审核步骤。

对 Chat Completions,还应注意工具调用内容需要按 tool_calls 处理;Anthropic 也明确要求工具调用等内容块按各自 type 处理。本文的纯文本核对不替代工具执行协议,不能把工具调用对象直接显示成最终文字交付。

先用本地样本检验记录逻辑

可以分别使用四页官方非流式示例,检查日志是否选对字段层级,并保留示例原值。再准备人为构造的缺字段、空数组及陌生值样本,确认它们进入明确的待核对状态。

这些人为样本仅用于测试自己的适配器,不是平台故障实测。样本通过后,再按你实际使用的分组与模型核对真实响应;不要把一个模型的结果推广为所有模型的保证。

流式处理需要另一套事件边界。若请求开启了 stream,就应转到相应协议的 SSE 文档,而不是等待最终出现本表中的完整普通 JSON。

提交排查材料时保留什么

需要协助时,可以整理协议、接口路径、所选项位置、结束字段原值及脱敏后的必要结构。移除认证头、真实 Key 与不必要的用户内容。能解释是哪一步尚未确认,比单写「返回成功但结果不对」更容易继续排查。

各字段以本次真实返回和官方资料为准:Responses、Chat Completions、Anthropic Messages、Gemini。需要重新核对服务入口时,可从 AIGoCode 主站进入。