应用执行与流式对话

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

应用开放接口

应用接口已有发布版本时执行发布快照，首次发布前使用草稿。对话形式便于接入聊天客户端，原生执行形式直接提交开始节点变量，并返回执行结果与节点运行态。

一、接入准备

在应用工作区保存、调试并发布版本，开启 API，签发应用的资源密钥。以已发布版本验证结果后再接入程序，操作见应用调试与版本发布。

接口	用途
`GET /app/{id}/v1/models`	获取应用模型标识
`POST /app/{id}/v1/chat/completions`	对话格式调用
`POST /app/{id}/v1/execute`	原生变量调用

模型列表返回 bladex@app_id:{id} 形式的标识，可直接用作对话请求的 model。

二、对话形式

curl "$AI_API_BASE/app/$AI_APP_ID/v1/chat/completions" \
  -H "Authorization: Bearer $AI_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
    "model":"bladex@app_id:<应用主键>",
    "messages":[{"role":"user","content":"介绍宿主集成入口。"}],
    "stream":true
  }' -N

URL 与模型标识使用同一个应用主键。其他业务输入使用 extraParams 时，同时填写 app_id 与 params：

{
  "extraParams": {
    "app_id": "<应用主键>",
    "params": {"topic": "知识检索"}
  }
}

请求配置的应用标识必须与预期调用资源一致；后端会校验密钥是否覆盖最终执行的资源。对话续接使用返回的会话标识。

三、原生形式

咨询受理流程的开始字段为 message，可直接提交：

curl "$AI_API_BASE/app/$AI_APP_ID/v1/execute" \
  -H "Authorization: Bearer $AI_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"message":"如何配置知识库的召回参数？","stream":false}'

请求字段必须与发布定义中的开始输入一致。同步响应 FlowExecuteResult 包含：

字段	类型	内容
`id`	string	响应标识
`created`	integer	秒级 Unix 时间戳
`variables`	object	流程执行变量；可能包含各节点的产出
`result`	object / string	最终输出，类型取决于应用定义
`runs`	array	节点运行态：`nodeId`、`nodeType`、`nodeName`、`step`、`status`、`input`、`output`、`durationMs`、`tokens`、`error` 等
`progress`	string	流式过程文本
`executed`	string	执行状态
`error`	string	执行错误，无错误时可省略或为空
`duration`	integer	总耗时，毫秒
`totalTokens`	integer	总 token 用量

模板流程的成功响应如下。示例仅保留一个节点运行项，完整响应包含该次执行的全部 runs 与 variables。

{
  "id": "demo-flow-response",
  "created": 1793577600,
  "executed": "SUCCESS",
  "result": {"answer": "已收到您的咨询：\n如何配置知识库的召回参数？\n请补充使用场景、当前环境和预期结果，便于进一步处理。"},
  "runs": [{
    "nodeId": "start",
    "nodeType": "start",
    "nodeName": "开始",
    "step": 1,
    "status": "SUCCESS",
    "input": {"message": "如何配置知识库的召回参数？"},
    "output": {"message": "如何配置知识库的召回参数？"},
    "durationMs": 1,
    "tokens": 0
  }],
  "variables": {"start.message": "如何配置知识库的召回参数？"},
  "duration": 12,
  "totalTokens": 0
}

输出协议

原生执行的流式帧使用执行结果结构；对话接口使用对话响应结构。应用工作区的节点命名事件又是另一条调试协议，客户端应按所用入口解析。

四、验证结果

比较同一输入在草稿调试、发布运行页和 API 中的结果。结果不一致时先检查发布版本、资源主键与输入字段，再定位运行记录。

资源密钥到期后，请求返回 HTTP 401（请求未授权）。密钥类型与有效期管理见超级密钥。

原生流的中间进度帧可能尚无 runs 和 result。客户端持续读取，以最终执行结果判定流程是否完成，进度帧中的 executed 不作为完成依据。

可运行客户端与完整 SSE 示例见响应协议与异常处理。

配置教程见应用接口与密钥管理。