🧠 模型自定义接入-简易接入

需要掌握 python 开发能力

模型接入推荐使用 aigcpanel-server-demo 示例项目的方式：将 python 环境打包到同一个目录（如 _aienv），然后通过 python run.py ./config.json 的方式启动模型。

模型进程启动后进入队列模式：先处理启动时传入的任务，随后持续轮询 aigcpanel-queue/ 目录中的 *.queue.json 新任务，并通过标准输出返回结果。进程在任务之间保持存活，因此模型只需加载一次即可服务所有队列任务。

项目结构

• run.py：主程序入口（队列循环逻辑）
• aigcpanelserver.py：轻量 SDK（appPrepare / watchNext / result / resultEnd 等）
• config.json：模型配置文件（mode.type = watch 开启队列模式）
• example-config/：任务配置示例
• aigcpanel-queue/：任务队列目录（放入 *.queue.json 文件即提交任务）

run.py 主程序示例

import os
import shutil
import time

import aigcpanelserver

def run():
    # 读取启动配置，初始化环境，返回 (config, ROOT_DIR)
    config, ROOT_DIR = aigcpanelserver.appPrepare('server-demo')
    modelConfig = config['modelConfig']

    # 在循环外加载模型，队列任务之间复用，避免重复加载
    # model = load_model(...)

    # watchNext()：首轮返回启动配置，之后持续轮询队列中的新任务
    while config := aigcpanelserver.watchNext():
        modelConfig = config['modelConfig']
        # 每个任务输出一次设备信息（设备类型、设备名称、显存等）
        aigcpanelserver.resultEnv()

        # 语音合成
        # config = { "id": "SoundTts_999", "modelConfig": { "type": "soundTts", "param": {}, "text": "你好" } }
        if modelConfig.get('type') == 'soundTts':
            text = aigcpanelserver.filterText(modelConfig['text'])
            # 模型推理，得到结果文件路径
            resultPath = aigcpanelserver.localCacheRandomPath('wav')
            # 输出结果：AigcPanelRunResult[id][base64]
            aigcpanelserver.result({'url': aigcpanelserver.urlForResult(resultPath)})
            aigcpanelserver.resultEnd()
            continue

        # 语音克隆
        # config = { "id": "SoundClone_999", "modelConfig": { "type": "soundClone", "param": {}, "text": "你好", "promptAudio": "/path/to/audio/xxxxx.wav", "promptText": "参考音频提示文字" } }
        if modelConfig.get('type') == 'soundClone':
            # 参考音频为远程 URL 时会自动下载缓存到 _cache/_file/
            promptAudio = aigcpanelserver.localCache(modelConfig['promptAudio'])
            resultPath = aigcpanelserver.localCacheRandomPath('wav')
            aigcpanelserver.result({'url': aigcpanelserver.urlForResult(resultPath)})
            aigcpanelserver.resultEnd()
            continue

        raise Exception('未知的模型类型: {}'.format(modelConfig.get('type')))

    # 队列无新任务且超过 watchDelay 秒后退出
    aigcpanelserver.end()

if __name__ == '__main__':
    run()

SDK 核心接口说明

• appPrepare(name)：读取 sys.argv[1] 传入的任务配置，初始化全局状态，返回 (config, ROOT_DIR)
• watchNext()：首轮返回启动配置；当 config.json 中 mode.type = watch 时，持续轮询 aigcpanel-queue/*.queue.json，按文件名顺序消费任务；超过 mode.watchDelay 秒无新任务则返回 None，循环结束
• result(data)：向标准输出输出 AigcPanelRunResult[id][base64]，由软件 / launcher 解析
• resultEnd()：清理临时文件并输出任务结束标记
• resultEnv()：输出当前设备信息（设备类型、设备名称、显存等）
• localCache(pathOrUrl)：远程 URL 自动下载缓存到 _cache/_file/，本地路径原样返回
• localCacheRandomPath(ext)：在 _cache/_file/ 中生成随机结果文件路径
• urlForResult(url)：根据配置模式处理结果路径（如 schedule 模式加 urlForResult:// 前缀）
• filterText(text)：过滤文本中的 emoji 与不可见字符
• end()：清理并退出进程

aigcpanelserver.py 为轻量自包含实现，函数签名与官方完整 SDK（_aigcpanel.lib）保持一致，接入实际模型后可无缝迁移。

config.json 文件示例

{
    "name": "server-xxx",          // 模型名称
    "version": "1.0.0",            // 模型版本
    "title": "语音模型",            // 模型标题
    "description": "模型描述",      // 模型描述
    "deviceDescription": "设备描述",
    "platformName": "win",         // 支持系统，win, osx, linux
    "platformArch": "x86",         // 支持架构，x86, arm64
    "serverRequire": ">=0.5.0",    // 对 AigcPanel 版本的要求，如 >=0.5.0
    "mode": {                      // 运行模式
        "type": "watch",           // watch=队列模式，进程常驻轮询队列
        "watchDelay": 60           // 空闲保活秒数，超时无新任务则退出
    },
    "entry": "__EasyServer__",     // 固定值，不需要修改
    "easyServer": {
        // python 运行入口
        // Windows      ".\\_aienv\\python.ext"
        // MacOS/Linux  "./_aienv/bin/python"
        "entry": "./_aienv/bin/python",
        "entryArgs": [
            "run.py",
            "${CONFIG}"
        ],
        // 环境变量
        "envs": [
            "FOO=BAR"
        ]
    },
    "functions": [
        "videoGen",                // 支持视频生成
        "soundTTS",                // 支持语音合成
        "soundClone"               // 支持语音克隆
    ],
    "settings": []
}

队列任务投递

将任务配置以 .queue.json 结尾放入 aigcpanel-queue/ 目录即可完成投递：

cp example-config/soundTts.json aigcpanel-queue/001.queue.json
cp example-config/soundClone.json aigcpanel-queue/002.queue.json

服务端会按文件名顺序消费并删除这些文件，每个任务输出一行 AigcPanelRunResult[id][base64] 结果。

运行模式

测试导入

完成开发之后，在软件中尝试选择模型文件夹中的 config.json 导入。