第06章开放接口

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

开放接口

开放接口用于将模型、应用、智能体、知识和 MCP 能力接入业务系统。本章给出当前接口路径、认证方式、请求字段与响应处理方法。

接入前准备

由管理员签发对应作用域的开放密钥；应用和知识资源需完成发布或开放配置。示例中的服务地址、资源主键和模型名称应替换为当前环境的实际值。

服务地址

将对外提供的 AI 服务根地址保存为 AI_API_BASE，例如：

export AI_API_BASE='https://ai.example.com/blade-ai'
export AI_API_KEY='<开放接口密钥>'

示例根地址包含 /blade-ai。网关另有前缀时按实际路由补齐。浏览器开发代理的 /api 前缀在转发时去除，接口路径以控制器映射为准。

集成目标	方法与路径	返回内容
模型目录	`GET /v1/models`	当前密钥可访问的模型
模型对话	`POST /v1/chat/completions`	模型回答与用量，支持流式输出
图像生成	`POST /v1/images/generations`	图像地址或 Base64 内容
应用对话	`POST /app/{id}/v1/chat/completions`	已发布应用的 OpenAI 兼容对话结果
应用执行	`POST /app/{id}/v1/execute`	应用原生执行结果与节点运行信息
外部智能体	`POST /agent/{id}/v1/chat/completions`	外部智能体的对话结果
知识检索	`POST /v1/rag/search`、`/v1/rag/lite-search`	命中内容及检索信息
知识问答	`POST /v1/rag/chat`	基于知识资料的回答
MCP 工具	`POST /v1/mcp/tools`、`/v1/mcp/call`	工具清单或指定工具的执行结果

同步请求返回完整结果，流式请求以 SSE 分段返回内容或执行事件。连续对话保留服务端返回的会话标识并在后续请求中传入：会话组织消息历史，运行记录描述一次业务执行，用量记录描述其中的模型调用。

网页交互与嵌入使用独立部署在 /share/ai/ 的分享入口，见分享与嵌入。