CyberVerse 镜像使用说明

本镜像已预装 CyberVerse 源码、Go / Node / Python 依赖、CUDA 12.8、PyTorch 2.8 及 Avatar 相关包。 你只需完成：初始化本地配置 → 填写 config/env → 调整 config/cyberverse.yaml → 下载模型权重（仅本地 Avatar 需要）→ 启动三个服务。

---

快速开始

1. 进入项目并初始化本地配置

cd /root/CyberVerse

# 如果 config/ 不存在，先从镜像内置模板复制一份本地配置。
if [ ! -d config ]; then
  cp -r infra/config config
fi

如果镜像已经带有 config/，不要直接覆盖已有配置；优先对照 infra/config/ 合并新增项。

当前 CyberVerse 的配置入口是：

文件或目录	作用
config/env	API Key、服务端点、TURN 密码等环境变量
config/cyberverse.yaml	服务端口、pipeline、WebRTC、Avatar 开关等主配置
config/*_models/	omni、LLM、Embedding、TTS、ASR 等 provider 定义
config/avatar_models/	本地 Avatar 模型参数，每个模型一个 YAML 文件

---

2. 填写 config/env

编辑 config/env，按实际使用的供应商填写。模型定义中的 ${VAR_NAME} 会从这个文件加载。

cd /root/CyberVerse
vim config/env

常用变量：

变量	说明
DOUBAO_API_KEY	豆包新鉴权方式，优先用于 Doubao realtime / TTS
DOUBAO_ACCESS_TOKEN / DOUBAO_APP_ID	豆包旧鉴权方式
DASHSCOPE_API_KEY	阿里云 DashScope / Qwen / CosyVoice
OPENAI_API_KEY / OPENAI_BASE_URL	OpenAI 或 OpenAI-compatible 服务
GEMINI_API_KEY	Gemini Live
XAI_API_KEY	Grok
TURN_PASSWORD	Direct WebRTC 内嵌 TURN 密码
LIVEKIT_URL / LIVEKIT_API_KEY / LIVEKIT_API_SECRET	仅 streaming_mode: livekit 时需要
BAIDU_XILING_APP_ID / BAIDU_XILING_APP_KEY	百度曦灵 H5 数字人
XUNFEI_AVATAR_APP_ID / XUNFEI_AVATAR_API_KEY / XUNFEI_AVATAR_API_SECRET / XUNFEI_AVATAR_SCENE_ID	讯飞数字人

豆包语音获取方式见：火山引擎快速入门。

服务启动后，也可以在 Web UI 的 /settings 页面修改 API Key 和服务端点，不必只依赖编辑 config/env。

---

3. 配置纯语音模式或 Avatar 模式。

设置数字人Avatar

如果要使用 FlashHead 或 LiveAct，把 config/cyberverse.yaml 中的 Avatar 开关打开，并保留模型配置目录：

inference:
  avatar:
    enabled: true
    default: "live_act"        # 可选 "live_act" 或 "flash_head"
    idle_strategy: "silent_inference"
    runtime:
      cuda_visible_devices: 0  # 多卡可写 0,1
      world_size: 1
    model_config_dir: "avatar_models"

当前模型参数不再写在 config/cyberverse.yaml 的 inference.avatar.flash_head 或 inference.avatar.live_act 下，而是写在 config/avatar_models/ 下的独立文件中。

LiveAct 示例，编辑 config/avatar_models/live_act.yaml：

live_act:
  ckpt_dir: "./checkpoints/models/LiveAct"
  wav2vec_dir: "./checkpoints/models/chinese-wav2vec2-base"
  infer_params:
    size: "272*480"
    fps: 20

FlashHead 示例，编辑 config/avatar_models/flash_head.yaml：

flash_head:
  checkpoint_dir: "./checkpoints/SoulX-FlashHead-1_3B"
  wav2vec_dir: "./checkpoints/wav2vec2-base-960h"
  infer_params:
    height: 512
    width: 512
    tgt_fps: 20

这些模型参数之后也可以在 Web UI 中调整，并会写回对应的模型配置文件。

---

4. 下载本地 Avatar 模型权重

仅当 inference.avatar.enabled: true 且选择 FlashHead 或 LiveAct 时需要下载。若 ./checkpoints/... 已存在完整权重，可跳过本节。

# 中国大陆可选 Hugging Face 镜像：
# export HF_ENDPOINT=https://hf-mirror.com

FlashHead

组件	说明	下载
SoulX-FlashHead-1_3B	FlashHead 主权重	Hugging Face / ModelScope
wav2vec2-base-960h	音频特征提取器	Hugging Face / ModelScope

hf download Soul-AILab/SoulX-FlashHead-1_3B \
  --local-dir ./checkpoints/SoulX-FlashHead-1_3B

hf download facebook/wav2vec2-base-960h \
  --local-dir ./checkpoints/wav2vec2-base-960h

LiveAct

组件	说明	下载
LiveAct	LiveAct 主权重	Hugging Face / ModelScope
chinese-wav2vec2-base	中文 wav2vec	Hugging Face / ModelScope

hf download Soul-AILab/LiveAct \
  --local-dir./checkpoints/LiveAct

hf download TencentGameMate/chinese-wav2vec2-base \
  --local-dir ./checkpoints/chinese-wav2vec2-base

下载完成后，确认 config/avatar_models/*.yaml 中的路径与上述 --local-dir 一致。

---

5. 启动服务

需要 3 个终端，或 3 个 tmux / screen 窗口。

终端 1：Python 推理服务

cd /root/CyberVerse
conda activate cyberverse
make inference

终端 2：Go API 服务

cd /root/CyberVerse
make server

终端 3：前端

cd /root/CyberVerse
make frontend

就绪标志：

• 推理服务日志出现 CyberVerse Inference Server started on port 50051。
• 开启本地 Avatar 时，推理服务日志出现 Active avatar model initialized: 。
• API 服务监听 http://localhost:8080。
• 前端服务监听 http://localhost:5173。

---

6. 验证访问

curl -s http://localhost:8080/api/v1/health

期望返回 JSON 中包含 "status":"ok"。

浏览器打开：

• 前端：http://localhost:5173
• 设置页：http://localhost:5173/settings