远程模型接口

更新时间: 2026-01-30 09:26:51

远程模型对外就是一个 HTTP 服务,由 launcher 提供。接口不多,七个,全部返回 JSON。这篇按调用顺序讲,最后给一段能直接跑通的 curl。

自己接一个远程模型、写自动化脚本、或者排查「为什么本机连不上」,都从这里看。

基础信息

  • 地址:http://<服务端 ip>:<LAUNCHER_PORT>,端口由启动参数决定
  • 数据目录:launcher-data/,上传和下载都只碰这个目录
  • 请求体:application/json,上传接口除外
  • 统一响应:{"code": 0, "msg": "ok", "data": {}},code 非 0 就是失败
  • 无鉴权:接口不校验任何 key,靠网络层限制访问

接口总表

方法路径用途
GET/ping探活
POST/config取模型配置
POST/submit提交任务,返回 token
POST/query按 token 取状态和增量日志
POST/cancel终止当前任务
POST/upload上传文件到 launcher-data/
GET/download/:file下载结果文件,下完即删

另外 /launcher-data/* 是静态目录,可以直接按文件名访问,不删除。

GET /ping

检查服务在不在。没有参数。

{ "code": 0, "msg": "ok", "data": {} }

POST /config

返回模型目录里 config.json 的全文。本机添加远程模型时会读其中的 name、version、title;调用阶段读 description 和 functions。

{
"code": 0,
"msg": "ok",
"data": {
"name": "server-demo",
"version": "1.1.0",
"title": "示例模型",
"description": "模型描述",
"functions": {
"soundTts": { "param": [], "result": [] }
},
"launcher": {
"entry": "./_aienv/bin/python",
"entryArgs": ["-u", "-m", "run", "${CONFIG}"],
"envs": []
}
}
}

functions 要是对象形式({"能力名": {...}}),不能是数组。本机拿它直接渲染参数表单,数组形式会导致功能页表单空白。

POST /submit

提交一个任务。launcher 会用 launcher.entry 加 entryArgs 起一个进程,跑完就结束。

请求字段全部可选:

字段说明
entry覆盖 config.json 里的 launcher.entry
entryArgs覆盖 launcher.entryArgs
entryPlaceholders占位符替换表,把 entry 和 entryArgs 里的 ${KEY} 换成值
envs追加环境变量
root工作目录,默认是模型目录
{
"entryPlaceholders": {
"CONFIG": "launcher-data/ab12cd34ef56gh78.json"
}
}

CONFIG 放的是任务配置文件的远端路径,也就是 /upload 的返回值。本机提交时只传这一个字段,靠 launcher.entryArgs 里的 ${CONFIG} 把路径喂给模型进程。

任务配置文件的格式和本地模型完全一样:

{
"id": "SoundTts_1731234567890",
"mode": "local",
"modelConfig": {
"type": "soundTts",
"param": { "speed": 1 },
"text": "你好,欢迎使用 AIGCPanel"
},
"setting": {}
}

响应:

{ "code": 0, "msg": "ok", "data": { "token": "64 位随机字符串" } }

进程退出码为 0 记 success,非 0 记 error。进程环境里会带上 AIGCPANEL_SERVER_<KEY>,<KEY> 来自启动 launcher 时的 --env。

POST /query

拿 token 换状态和日志。

{ "token": "上一步拿到的 token" }
{
"code": 0,
"msg": "ok",
"data": {
"logs": "Base64 编码的日志",
"status": "running"
}
}

status 三个值:running、success、error。

两个必须知道的行为:logs 是增量,每次只给上次查询之后的新内容;状态不是 running 时,这次查询返回后 token 就被删了,再查会拿到 {"code": -1, "msg": "Token not found"}。

logs 里才有结果。模型进程把 AigcPanelRunResult[<id>][<base64>] 打到标准输出,launcher 原样收进日志,调用方解码后拼起来就是结果对象。解码:

curl -s -X POST $BASE/query -H "Content-Type: application/json" \
-d '{"token":"<token>"}' \
| python3 -c "import sys,json,base64; print(base64.b64decode(json.load(sys.stdin)['data']['logs']).decode())"

POST /cancel

杀掉当前正在跑的进程,没有参数。没有任务在跑时调用也返回成功。

{ "code": 0, "msg": "ok", "data": {} }

POST /upload

multipart/form-data,字段名固定是 file。

curl -X POST $BASE/upload -F "file=@/tmp/task.json"
{
"code": 0,
"msg": "ok",
"data": { "file": "launcher-data/ab12cd34ef56gh78.json" }
}

文件名会被换成 16 位随机串,扩展名保留。返回的路径不带前导斜杠,直接放进 entryPlaceholders.CONFIG 就行。

GET /download/:file

按文件名下载 launcher-data/ 下的文件,只认文件名,不能带路径。

curl -O $BASE/download/1731234567890.wav

成功返回 application/octet-stream,下载完服务端会把这个文件删掉。文件不存在返回 404。

一个完整的例子

假设 launcher 在本机 8888,launcher.entryArgs 里已经写了 ${CONFIG}。

BASE=http://127.0.0.1:8888

# 0. 探活
curl -s $BASE/ping

# 1. 准备任务配置
cat > /tmp/task.json <<'JSON'
{
"id": "SoundTts_1731234567890",
"mode": "local",
"modelConfig": { "type": "soundTts", "param": { "speed": 1 }, "text": "你好" },
"setting": {}
}
JSON

# 2. 上传,记下返回的 file
curl -s -X POST $BASE/upload -F "file=@/tmp/task.json"

# 3. 提交,记下 token
curl -s -X POST $BASE/submit -H "Content-Type: application/json" \
-d '{"entryPlaceholders":{"CONFIG":"launcher-data/ab12cd34ef56gh78.json"}}'

# 4. 轮询,直到 status 不是 running
curl -s -X POST $BASE/query -H "Content-Type: application/json" \
-d '{"token":"<上一步的 token>"}'

# 5. 下载结果
curl -O $BASE/download/1731234567890.wav

日志解码后会看到两行结果标记,中括号里是 Base64:

AigcPanelRunResult[SoundTts_1731234567890][<base64>]
AigcPanelRunResult[SoundTts_1731234567890][<base64>]

第一行的 Base64 解出来是 {"url":"launcher-data/1731.wav"},第二行是 {"End":true}。url 拿出来拼 $BASE/ 就是下载地址。

模型侧要注意

launcher 只负责转日志,不解析结果。结果行得由模型进程自己打,格式和本地模型一致。少了这一行,status 会变成 success,但拿不到 url,界面照样报「执行失败,请查看模型日志」。

相关

语言
QQ
微信客服
微信群
客服