AI Creative Studio (muc-vis-comp) — 项目总结

概述

Sonic Lab / AI Creative Studio 是一个集成式的 AI 创意内容生成平台，覆盖草图→图像、图像→3D、文字→音乐、音乐→音轨分离的完整创作管线。前端为 Vue 3 SPA，后端采用微服务架构（Flask），所有 GPU 推理通过统一的排队锁串行化。

---

整体架构

外部访问 (port 7979)
    │
    ├── serve.py (port 7979)        ← 静态文件服务 + 反向代理
    │      ├── 前端 dist/ (Vue 3 SPA)
    │      ├── /vis/ (音乐可视化页面)
    │      └── /api/* → main_server.py (port 5000)
    │
    └── main_server.py (port 5000)  ← API 网关 + GPU 排队锁
             │
             ├── /api/flux     → flux_server.py (port 5001)  [Qwen-Image-Edit-2509]
             ├── /api/sf3d     → sf3d_server.py (port 5002)  [Trellis2]
             ├── /api/acestep  → acestep_server.py (port 5003)  → upstream ACE-Step (port 8001)
             ├── /api/mucgen   → mucgen_server.py (port 5004)  [Demucs via subprocess]
             │
             ├── /api/polish      [DashScope Qwen-plus]
             ├── /api/glb2ply     [trimesh]
             ├── /api/save-tracks
             ├── /api/gpu-status  [nvidia-smi + queue state]
             └── /backups/        [JSON 元数据 + PLY 文件]

关键设计决策

---

前端代码（Vue 3 + Three.js）

目录结构

frontend/
├── src/
│   ├── main.js               # 入口：createApp(App).mount('#app')
│   ├── App.vue               # 唯一 SPA 组件（全部 UI + 逻辑）
│   └── style.css             # 基础样式
├── dist/                     # Vite 构建输出
├── index.html                # HTML 入口
├── serve.py                  # Flask 静态服务 + 反向代理（port 7979）
├── vite.config.js            # Vite 配置
└── package.json              # 依赖：vue ^3.5.30, three ^0.183.2

四步创作管线（App.vue）

前端关键特性

• GPU 状态指示灯：setInterval 每 2s 轮询 /api/gpu-status，显示实时 GPU 利用率、温度、队列状态
• WebGL 生命周期管理：dispose3DModel() 在加载新模型前销毁旧的 renderer/scene/RAF 循环，防止 WebGL 上下文泄漏
• 一键下载：每个生成结果（图像/GLB/音乐/分离音轨）均附带下载按钮
• 音乐可视化联动：openVis() 调用 /api/save-tracks 保存音轨分配，跳转到 /vis/index.html?ply=...&bass=...&drums=...
• Toast 通知系统：成功/错误/警告/信息四种类型的瞬态消息

serve.py 反向代理

超时 1200 秒（20 分钟），以容纳长时间的 AI 推理。

---

后端代码（Python Flask 微服务）

main_server.py（port 5000）— API 网关

• 路由：统一入口，将请求转发到各微服务
• GPU 排队：_GpuSlot（基于 threading.Lock + deque 队列），所有 GPU 请求串行执行
• GPU 状态：nvidia-smi 解析 + 内置队列状态，通过 /api/gpu-status 暴露
• 辅助功能：
  • POST /api/polish — DashScope Qwen-plus 润色提示词
  • POST /api/glb2ply — GLB → PLY 格式转换（trimesh）
  • POST /api/save-tracks — 保存可视化页面轨道分配
  • GET /backups/<path> — 备份文件服务
• 备份目录：backups/ 下按类别（models/, music/, images/, tracks/, ply/）存储 JSON 元数据

flux_server.py（port 5001）— 图像生成

• 模型：QwenImageEditPlusPipeline（diffusers），本地路径 /root/qwen_image_edit/models/Qwen-Image-Edit-2509
• 输入：Base64 草图 + 文本提示词
• 输出：Base64 PNG 数据 URL
• 依赖：torch, diffusers, PIL

sf3d_server.py（port 5002）— 3D 模型生成

• 模型：Trellis2ImageTo3DPipeline，模型缓存 /root/.cache/trellis2_dl
• 输入：Base64 图像
• 输出：Base64 GLB 数据 URL（full quality: remesh=True, decimation_target=1_000_000, texture_size=4096）
• 依赖：torch, trellis2.pipelines, o_voxel.postprocess
• 耗时：约 4-6 分钟（pipeline ~35s + export ~163s）

acestep_server.py（port 5003）— 音乐生成包装

• 上游：ACE-Step API 服务器（http://127.0.0.1:8001，FastAPI + uvicorn）
• 协议：POST /release_task 提交 → POST /query_result 轮询（最长 30 分钟）
• 输出：JSON（含音频代理 URL proxy-audio?path=...）
• 端点：
  • POST /api/acestep/generate
  • GET /api/acestep/status/<task_id>
  • GET /api/acestep/proxy-audio

mucgen_server.py（port 5004）— 音乐分离

• 模型：Facebook Research Demucs v4（HTDemucs），/root/musicB
• 执行方式：通过 subprocess 调用 /root/anaconda3/envs/demucs/bin/python -m demucs -n htdemucs
• 输入：Base64 音频数据 或 audio_url
• 输出：6 个音轨的 Base64 WAV（vocals, drums, bass, guitar, piano, other）

未使用的旧文件

---

客户端脚本

位于 clients/ 目录，依赖仅有 requests，可直接通过 SSH 从外部机器调用：

所有脚本内置 5 秒心跳线程，在等待时显示 GPU 队列状态。

---

集成的开源项目

Qwen-Image-Edit-2509（阿里巴巴/Qwen）

• 官网：https://huggingface.co/Qwen/Qwen-Image-Edit-2509
• 用途：草稿/参考图 → 照片级真实感图像
• 架构：基于 diffusers 的 instruction-based 图像编辑 pipeline
• 环境：qwen_image_edit conda 环境 | 端口：5001
• 本地路径：/root/qwen_image_edit/models/Qwen-Image-Edit-2509

TRELLIS.2（微软研究院）

• 官网：https://huggingface.co/microsoft/TRELLIS.2-4B
• 论文：https://arxiv.org/abs/2501.06155
• 用途：2D 图像 → 3D 模型（GLB + PBR 材质）
• 架构：4B 参数，基于 O-Voxel 稀疏体素 + DiT 的 field-free 3D 生成模型
• 环境：trellis2 conda 环境 | 端口：5002
• 本地路径：/root/Trellis2/

ACE-Step 1.5（ACEMusic / StepFun）

• 官网：https://github.com/ACEMusic/ACEMusic
• 用途：文本提示 → 多长度音乐生成（10s - 10min）
• 架构：混合 LM（planner）+ DiT（audio generator），支持 50+ 语言
• 环境：ace_step conda 环境 | 上游端口：8001（uvicorn），包装端口：5003
• 本地路径：/root/musicgen/

Demucs v4 / HTDemucs（Meta / Facebook Research）

• 官网：https://github.com/facebookresearch/demucs
• 用途：音乐源分离 → 人声/鼓/贝斯/吉他/钢琴/其他
• 架构：Hybrid Transformer Demucs (U-Net + Transformer cross-domain attention)
• 环境：demucs conda 环境（子进程调用） | 端口：5004
• 本地路径：/root/musicB/

DashScope Qwen-plus（阿里云）

• 用途：中文→英文翻译 + 提示词润色
• 方式：OpenAI 兼容 SDK（openai.OpenAI），base_url=https://dashscope.aliyuncs.com/compatible-mode/v1
• 集成点：POST /api/polish

---

启动与运维

启动脚本

/root/full/muc-vis-comp/start.sh

按顺序启动 6 个进程 + 1 个前端服务。每个服务用 setsid + disown 后台运行，日志输出到 /tmp/muc-vis-comp/*.log。

状态检查

# 健康检查
curl http://127.0.0.1:5000/health
curl http://127.0.0.1:7979/health

# GPU 状态
curl http://127.0.0.1:5000/api/gpu-status

外部访问

# Mac 上建立 SSH 隧道
ssh -fN -o GatewayPorts=yes \
    -L 0.0.0.0:7979:localhost:7979 \
    -p 30230 root@10.15.171.204

# 浏览器访问 http://你Mac的IP:7979

---

备份数据

/root/full/muc-vis-comp/backups/
├── images/   # 图像生成元数据 JSON
├── models/   # 3D 模型元数据 JSON
├── music/    # 音乐生成元数据 JSON（含 prompt, duration, audio_url, timestamp）
├── tracks/   # 音轨分配回放 JSON
└── ply/      # 导出的 PLY 文件

---

工作流总结

用户手绘草图 + 输入提示词
    │
    ▼
[01] Qwen-Image-Edit-2509 → 照片级图像 (PNG)
    │
    ▼
[02] Trellis2 → 3D 模型 (GLB) → GLB→PLY 转换
    │
    ▼
[03] ACE-Step → 音乐 (WAV)
    │
    ▼
[04] Demucs → 分离音轨 (人声/鼓/贝斯/吉他/钢琴/其他)
    │
    ▼
    音乐可视化页面 (Three.js 3D 场景 + 音轨播放)