QQ扫一扫联系
远程模型对外就是一个 HTTP 服务,由 launcher 提供。接口不多,七个,全部返回 JSON。这篇按调用顺序讲,最后给一段能直接跑通的 curl。
自己接一个远程模型、写自动化脚本、或者排查「为什么本机连不上」,都从这里看。
http://<服务端 ip>:<LAUNCHER_PORT>,端口由启动参数决定launcher-data/,上传和下载都只碰这个目录application/json,上传接口除外{"code": 0, "msg": "ok", "data": {}},code 非 0 就是失败| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /ping | 探活 |
| POST | /config | 取模型配置 |
| POST | /submit | 提交任务,返回 token |
| POST | /query | 按 token 取状态和增量日志 |
| POST | /cancel | 终止当前任务 |
| POST | /upload | 上传文件到 launcher-data/ |
| GET | /download/:file | 下载结果文件,下完即删 |
另外 /launcher-data/* 是静态目录,可以直接按文件名访问,不删除。
检查服务在不在。没有参数。
{ "code": 0, "msg": "ok", "data": {} }
返回模型目录里 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 要是对象形式({"能力名": {...}}),不能是数组。本机拿它直接渲染参数表单,数组形式会导致功能页表单空白。
提交一个任务。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。
拿 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())"
杀掉当前正在跑的进程,没有参数。没有任务在跑时调用也返回成功。
{ "code": 0, "msg": "ok", "data": {} }
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 就行。
按文件名下载 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,界面照样报「执行失败,请查看模型日志」。