响应协议与异常处理

BladeX大约 4 分钟开放接口开发指南

响应与事件流

开放接口包含统一业务响应、对话响应与应用执行响应。客户端先检查 HTTP 状态和内容类型，再按所调用入口的响应结构处理同步结果或 SSE。

一、响应分类

入口	主要结构
模型目录、检索、工具列表	该端点声明的目录或统一业务响应
模型、应用、智能体对话	`choices`、`usage`、`result`、`extra` 等对话字段
应用原生执行	`result`、`runs`、`executed`、`error` 等执行字段
工作区流程调试	带节点、进度和类型的命名事件

鉴权失败通常在事件流建立前以 HTTP 401 返回。流已开始后的执行失败，需要继续读取业务结束状态或错误内容。

二、对话事件流

请求体设置 stream: true，客户端持续消费 text/event-stream。一次网络读取不一定是一条完整事件，应缓冲文本，按空行分割事件，再处理 event: 与 data: 行。

以下为 chat/completions 的协议示例，依次展示会话、文本与业务结束。每条事件后有一个空行，JSON 中省略了与示例无关的字段。

data: {"id":"demo-chat","object":"chat.completion.chunk","extra":{"conversationId":"<会话主键>"}}

data: {"id":"demo-chat","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":"资料齐备后"}}]}

data: {"id":"demo-chat","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"提交受理。"}}]}

data: {"id":"demo-chat","object":"chat.completion.chunk","choices":[{"index":0,"finish_reason":"stop"}],"usage":{"promptTokens":18,"completionTokens":9,"totalTokens":27},"result":{"done":true}}

正文按 choices[].delta.content 追加。思维增量来自 reasoning_content，单独保存或渲染。平台以 result.done 标记业务结束、以 result.error 传达异常，客户端据此判定结束状态；供应商的 [DONE] 不作为统一结束条件。

正文与思维

对话增量中的正文与 reasoning_content 分别渲染；finish_reason 作为结束原因处理。内容过滤、失败和停止按各自状态展示，与正常完成区分。

三、原生流程事件流

/app/{id}/v1/execute 的每条 data 为 FlowExecuteResult。以下为简化的结构示例：

data: {"id":"demo-flow","executed":"SUCCESS","progress":"开始节点执行中"}

data: {"id":"demo-flow","executed":"SUCCESS","runs":[{"nodeId":"start","nodeType":"start","nodeName":"开始","step":1,"status":"SUCCESS"}],"variables":{"start.message":"查询受理时间"},"result":{"answer":"已收到您的咨询：查询受理时间"},"duration":12,"totalTokens":0}

首条过程帧尚无完整节点运行态。流程客户端持续接收，最终以包含节点运行态和耗时的执行对象核对结果；任一帧含错误时按失败处理。对话编排和专家团优先通过对话接口接入。

四、可运行的 Node.js 客户端

下载 SSE 客户端，使用 Node.js 22.18 及以上版本。客户端处理 UTF-8 分块、LF/CRLF/CR 行结束、连续 data: 行、注释心跳、HTTP 异常、业务错误与 Ctrl+C 停止，不依赖额外包。

调用原生变量输出流程，将请求文件保存为 app-stream-request.json：

export AI_API_URL="$AI_API_BASE/app/$AI_APP_ID/v1/execute"
export AI_API_PROTOCOL=flow
node sse-client.mjs app-stream-request.json

调用模型对话，将请求文件中的 model 替换为当前目录名称：

export AI_API_URL="$AI_API_BASE/v1/chat/completions"
export AI_API_PROTOCOL=chat
node sse-client.mjs chat-stream-request.json

两种调用均从环境变量 AI_API_KEY 读取凭证。对话正文写入标准输出，完成状态写入标准错误；流程模式输出最终执行 JSON。应用对话与知识问答可复用 chat 解析方式，分别使用对应 URL 和请求体。

示例边界

flow 示例面向含节点运行态的流程编排。连接关闭但没有收到业务完成结果时，客户端报告未完成；已输出的部分文字不作为成功标记。

五、流程工作区事件

节点通道的事件包含 workflow_started、node_started、node_finished、node_skipped、node_interrupt、text_chunk、workflow_finished 和 ping。

开始事件初始化运行与执行计划。
节点事件更新轨迹；跳过表示未走到该分支。
人工中断表示等待后续输入。
文本增量按输出来源和正文/思维类型进入对应区域。
结束事件统一处理成功、失败或停止；心跳不写入正文。

这些命名事件属于工作区调试接口，结构与应用开放原生执行的每帧结果对象不同。

六、异常定位

先保存 HTTP 状态、业务错误、响应标识和资源主键，再查询同一时间的运行记录。401 检查密钥；资源不可用检查开放与发布状态；模型或工具错误回到对应配置和执行节点。

客户端主动停止或关闭连接后，可保留已收到的部分文本，并标记本次交互的停止或中断状态。业务是否成功以结束状态判定，与网络连接是否正常关闭无关。

前端实现参考对话与可视化引擎。