工作区推理返回与流式协议

普通对话结果

字段

类型

说明

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

计费准入分支可选恢复动作代码。

最后更新于