第一次成功调通接口,打印出来的却不是一句回答,而是一整块带着 id、object、choices、usage 的结构。有人把整块内容直接显示给用户,有人取错层级拿到一个空值,于是以为调用失败了。其实每个字段都在回答「这次调用发生了什么」的一个具体问题:结果有几条、正文放在哪、为什么停下来、用了多少额度。把这几层拆开看,读返回值就不再靠猜。
第一层:choices 是候选列表,不是答案本身
choices 是数组,因为接口允许一次生成多个候选。默认配置只返回一个,所以日常取第一条就够了;数组里每个元素都带 index(候选序号)和 finish_reason(这次为什么停)。请求里如果设了多个候选,就会拿到多条,此时要按业务需要挑选,别习惯性只取第一条。空数组通常意味着请求被拦截或上游异常,先看状态码和错误信息,不要当成正常回答处理。
还有一点容易误会:choices 里装的是「这一次生成的结果」,不是聊天记录。上下文不会自动存在里面,多轮对话要自己把历史消息重新带上,这也是新手常问「AI 怎么不记得上一句」的技术原因。想让对话连起来,改的是请求里的消息列表,而不是去翻返回值。
choices 是容器,message 才是内容。取答案前先确认数组非空,比写完代码再回头排查省事得多。
第二层:message 里放正文、角色和工具调用
message 通常有 role 和 content 两个字段。role 说明这条消息是谁说的,assistant 表示来自模型;content 就是你要的正文。要注意 content 并不总是字符串:多模态或分段内容时它是数组,直接拼接前先判断类型。开启流式输出时,返回的更是一小段一小段的增量片段,需要自己按顺序累积,最后才得到完整正文。
如果请求里带了工具定义,message 里可能没有 content,而是出现 tool_calls,告诉你模型想调用哪个函数、参数是什么。这时候别急着显示空白,先看有没有工具调用要执行。把「有正文」和「有工具调用」当成两种正常返回分别处理,代码会稳很多,也不会把一次正常的函数调用误判成接口故障。
正文为空不一定是失败。先看 finish_reason 和 tool_calls,再决定是展示、拼接还是继续执行函数。
第三层:finish_reason 与 usage 各管一件事
finish_reason 说明这次为什么停:stop 是自然说完,length 是碰到长度上限被截断,content_filter 是内容被策略拦截,tool_calls 是在等你执行函数。同样的正文,取值不同,后续处理应该完全不同。看到 length 就去调整长度参数或让模型分段续写,而不是把原请求反复重发;看到 tool_calls 就走函数执行分支,别把它当成一次没答完的普通回复。
再往外一层是 usage:prompt_tokens、completion_tokens 和 total_tokens 分别对应输入、输出与合计,它是核对用量与费用的依据,也是排查「为什么这次贵」的第一手材料。通过 https://api.aigcbreeze.cn 调用时,建议把 usage 连同请求参数一起留档,后期对账、定位异常调用都靠这份记录。返回值最外层的 id 和 created 也别丢,出问题时它们能帮支持方快速定位到具体那一次请求。
常见问题
为什么我取到的 content 是空的
按顺序查三处:是否开了流式输出(片段在增量字段而不是完整的 message)、是否存在 tool_calls、finish_reason 是不是 length 或内容策略拦截。绝大多数空正文都属于这三类,跟模型「会不会回答」没有关系,改提示词通常也解决不了。
choices 真的会有多个吗
会。请求里设置多个候选时,choices 就有多条,每条带自己的 index 和 finish_reason。默认配置只有一条,所以很多人用了很久也没见过第二条。需要做多方案对比时再开启,同时留意用量会随候选数量增加,别在批量任务里无意打开。
返回值里的 id 和 created 有用吗
有用,主要用于留痕与排障。id 是这次调用的唯一标识,created 是时间戳。页面上不用展示,但日志里建议保留;反馈问题时把这两个值一起给出,比描述「刚才那次好像不太对」有效得多。养成记录习惯后,偶发问题也能复盘。