工作区推理返回与流式协议¶
普通对话结果¶
字段 |
类型 |
说明 |
|---|---|---|
id |
string |
完成结果标识,是否存在取决于提供商适配。 |
model |
string |
返回的模型标识。 |
choices |
object(对象数组) |
提供商兼容的候选结果。 |
choices[].index |
integer |
候选序号。 |
choices[].message |
object |
回答消息,可含role/content及工具调用。 |
choices[].finish_reason |
string 或 null |
提供商给出的结束原因。 |
usage |
object |
提供商上报的用量,可能缺失;不能据缺失推断免费或零用量。 |
moi_context_budget |
object |
仅启用预算检查时由网关追加。 |
moi_context_budget.status |
string |
checked或unknown。 |
moi_context_budget.input_tokens |
integer |
checked时测量的输入token数。 |
moi_context_budget.context_window |
integer |
checked时测得的上下文容量。 |
moi_context_budget.reserved_output_tokens |
integer |
checked时预留的输出token数。 |
moi_context_budget.reason |
string |
unknown时的原因,如adapter_unsupported。 |
这是兼容形态,原始提供商和适配器可返回额外字段;不能把示例当统一的必返完整schema。普通返回没有产品code封套。
Embedding结果¶
字段 |
类型 |
说明 |
|---|---|---|
object |
string |
常规为list。 |
data |
object(对象数组) |
向量结果本身,不能再拆产品data封套。 |
data[].object |
string |
常规为embedding。 |
data[].embedding |
number(数值数组) |
数值向量,长度与模型有关。 |
data[].index |
integer |
输入关联序号。分批路径按返回条目重写为全局连续序号,不保证能恢复任意上游重排/缺失。 |
model |
string |
提供商模型标识,分批时取首批。 |
usage |
object |
提供商用量;分批合并可合计数值字段并保留其他元数据,形态依提供商。 |
当前普通公开Embedding调用未启用知识检索内部专用的条数/非空向量校验;收到200仍需核结果条数、index、维度和模型是否符合消费方要求。分批适配与编码形式的限制不可由单批成功代替。
SSE流¶
data: {"choices":[{"delta":{"content":"你好"}}]}
data: [DONE]
按事件持续拼接delta,不能一次将整个流当JSON解码。已发送200后出错,handler无法再改HTTP状态,可能返回:
event: error
data: {"error":{"message":"upstream failed"}}
SDK流入口返回可读取响应体,CLI写出原始SSE;它们不必自动解析event:error。需要识别错误事件与结束信号;只看HTTP200或CLI退出0不能判断回答完整。断连/取消时也可能只结束连接,缺少结束信号需按未完成处理,不盲目重试生成请求。
错误与结束条件¶
情况 |
HTTP/数字code |
说明 |
|---|---|---|
输入无效 |
400/2 |
无效model/JSON/预算与stream组合、Embedding输入等。 |
预算超限 |
422/2 |
context budget超过上下文容量,不等于已生成回答。 |
请求/资源限额 |
413/14 |
Embedding请求体、输入项数、上游读取/调用预算超限。 |
无可用路由 |
503/1 |
当前模型没有可用后端/端点。 |
预算或计费依赖不可用 |
503/15 |
不应当作成功后的缺少usage。 |
配置/适配器/对话提供商失败 |
500/1 |
可能有details.cause及details.upstream_status;上游状态用字符串诊断,不能代替当前HTTP状态。 |
Embedding提供商错误 |
上游4xx/5xx或500,code1 |
按可识别上游状态及脱敏原因返回,和Chat固定500映射分开。 |
计费准入拒绝 |
402/14、403/5或依赖503/15 |
详情含reason/retryable及可选action,错误消息可能本地化;不是提供商error标签。 |
接口错误是code/message及可选details,身份或运行证明边界可能另用string code/msg。不要把普通成功、错误、SSE错误事件和Genesis的error封套合并解析。已经完成的提供商响应与结算状态也不是同一件事;真实计费/补偿与环境配置仍需复测。
诊断字段 |
类型 |
说明 |
|---|---|---|
details.cause |
string |
可选脱敏原因,主要用于提供商错误。 |
details.upstream_status |
string |
可选上游HTTP状态诊断。 |
details.reason |
string |
计费准入拒绝的稳定原因代码。 |
details.retryable |
string |
计费准入分支的true/false字符串,不是JSON布尔。 |
details.action |
string |
计费准入分支可选恢复动作代码。 |