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

## 普通对话结果

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| 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流

```text
data: {"choices":[{"delta":{"content":"你好"}}]}

data: [DONE]

```

按事件持续拼接delta，不能一次将整个流当JSON解码。已发送200后出错，handler无法再改HTTP状态，可能返回：

```text
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 | 计费准入分支可选恢复动作代码。 |
