CyberVerse

CyberVerse は、オープンソースのリアルタイム音声・映像 Agent プラットフォームです。WebRTC、ペルソナ記憶、ツール、RAG、任意のデジタルヒューマン映像機能を基盤に、音声インタラクションを中心とした AI Agent の構築を支援します。

English · 简体中文 · 日本語 · 한국어

たった一枚の写真から、息づくデジタルヒューマンへ。

あなたを本当に見て、聞いて、リアルタイムで話しかけてくれる、自分だけの J.A.R.V.I.S. のような AI を夢見たことはありませんか？

もう会えない大切な人に再び会い、その声を聞き、笑顔を見ることができたらどうでしょうか。

あるいは、ずっと命を吹き込みたかったキャラクターがいるかもしれません。

必要なのはたった一枚の写真。CyberVerse がその存在を動き出させます。

デジタルヒューマン Agent とは？

デモ

以下のキャラクターはデモ例です。CyberVerse に同梱されておらず、商用利用向けには提供されません。


Alice — YouTube で見る	Lina — YouTube で見る


Xiaolongnü — YouTube で見る

特長

リアルタイム音声 Agent

音声は CyberVerse のデフォルトのインタラクション方式であり、低遅延で長時間続けられるリアルタイム会話を想定しています。ユーザーはマイクで Agent と継続的に会話し、モデルの発話中にいつでも割り込み、同じ会話ターンで音声とテキスト入力を組み合わせられます。

各キャラクターには声、ウェルカムメッセージ、人格設定を個別に構成でき、音声クローンにも対応します。会話中のセッション中断と再開をサポートし、inference.avatar.enabled を false にすると、プラットフォームは純粋な音声モードで動作し、音声ストリームだけを配信します。ローカル Avatar GPU は不要で、コアの音声体験は変わりません。

WebRTC による音声・映像

セッション経路は WebRTC 上に構築され、デプロイ環境に応じて直接 P2P（組み込み TURN / NAT トラバーサル）または LiveKit SFU モードを選択できます。低遅延と複雑なネットワーク環境での接続性を両立します。

standard モードと対応する omni セッションでは、Agent がユーザーのカメラ映像や画面共有フレームを視覚入力として受け取ることもできます。純粋なテキスト文脈に限定されず、「聞ける、見られる」対面型のインタラクションを実現します。

PersonaAgent + SubAgent タスク

CyberVerse は multi-agent アーキテクチャを採用しています。PersonaAgent は常に前面にいて、ユーザーとの滑らかな会話、割り込みへの素早い応答、文脈切り替えを担当します。検索、調査、資料整理、要約、HTML レポート生成などの時間がかかる作業は、バックグラウンド SubAgent が非同期で実行します。

これにより複雑なタスクが音声ターンを遅くしません。ユーザーは話し続けたり、追加で質問したり、方向性を調整したりでき、SubAgent の完了後に結果が前面の会話へ返されます。

キャラクター記憶と RAG

各キャラクターの会話履歴はローカルディスクに永続化され、会話へ戻ると自動的に読み込まれるため、セッションをまたいだ連続性を保てます。キャラクター用の知識ベース、文書、人物の経歴素材も取り込めます。システムはそれらをインデックス化し、検索拡張生成に利用することで、回答をキャラクターの背景や設定により近づけます。

任意のデジタルヒューマン映像

GPU リソースがあり Agent を「見える」存在にしたい場合は、avatar inference を有効にします。1 枚のキャラクター参照画像だけで、FlashHead や LiveAct などの設定可能なバックエンドを通じて、リアルタイム表情アニメーション、リップシンク、キャッシュ済み待機動画の再生を駆動できます。GPU がない場合や、まだ映像が不要な場合は、この機能を無効にすれば純粋な音声 Agent に戻せます。同じキャラクターとペルソナ設定はそのまま使えます。

プラグインベースのスタック

頭脳、声、聴覚、ツール、記憶、顔はすべて差し替え可能なモジュールです。cyberverse_config.yaml で omni model、LLM、TTS、ASR、Embedding、RAG、ツール呼び出し、Avatar バックエンドを組み合わせ、Web UI の /settings で各ベンダーの API Key とサービスエンドポイントを設定できます。用途に応じてプロバイダーやモデル構成を自由に切り替えられます。

クイックスタート

前提条件

Node 18+
Go 1.25（必須: protoc-gen-go, protoc-gen-go-grpc）
Conda
Python 3.10+
FFmpeg
libopus-dev、libopusfile-dev、libsoxr-dev，pkg-config

純粋な音声セッションでは、ローカルの Avatar GPU は不要です。実行コストは、設定したリアルタイム音声 / omni / LLM / TTS / ASR プロバイダーに依存します。

確認には次を実行します:

node --version
go version
protoc --version
ffmpeg -version
conda --version

ステップ 1: クローンする

git clone https://github.com/dsd2077/CyberVerse.git
cd CyberVerse

ステップ 2: Python 環境を作成する

conda create -n cyberverse python=3.10
conda activate cyberverse

ステップ 3: 環境変数を設定する

cp infra/.env.example .env

.env を編集し、対応する API Key を入力します。

Alibaba Cloud Qwen シリーズモデル:

DASHSCOPE_API_KEY=your_dashscope_api_key

または Volcengine Doubao シリーズモデル:

DOUBAO_ACCESS_TOKEN=your_doubao_access_token
DOUBAO_APP_ID=your_doubao_app_id

Doubao Voice: Volcengine クイックスタートに従って App ID / API Key を取得し、DOUBAO_APP_ID / DOUBAO_ACCESS_TOKEN に設定します。

スタック起動後は、API キーやサービスエンドポイントを .env だけでなく Web UI の /settings から変更できます。

ステップ 4: ローカル設定を作成して voice-only モードを有効にする

cp infra/cyberverse_config.example.yaml cyberverse_config.yaml

cyberverse_config.yaml を編集します。

inference:
  avatar:
    enabled: false

enabled: false の場合、CyberVerse は純粋な音声 Agent アシスタントとして動作します。

ステップ 5: プロジェクト依存関係をインストールする

make setup

これにより、基本の editable package（[dev,inference]）のインストール、gRPC stubs の生成、フロントエンド依存関係のインストールが行われます。

デフォルト設定で使う音声 Agent extras をインストールします。

# すべての optional グループを一括でインストール
pip install -e ".[all]"

ステップ 6: サービスを起動する（3 つのターミナル）

ターミナル 1 — Python 推論サーバー:

conda activate cyberverse
make inference

ターミナル 2 — Go API サーバー:

make server

ターミナル 3 — フロントエンド:

make frontend

ステップ 7: 確認する

# API ヘルスを確認
curl -s http://localhost:8080/api/v1/health

ブラウザで http://localhost:5173 を開いてください。

任意: 完全なデジタルヒューマン映像

FlashHead または LiveAct でリアルタイム Avatar 映像を駆動したい場合は、以下の手順を実行してください。

追加要件

CUDA 12.8+ に対応した GPU
PyTorch 2.8（CUDA 12.8）
libvpx を含む FFmpeg（動画エンコード用）
Avatar モデル重み

PyTorch（CUDA 12.8）をインストールします。

pip3 install torch==2.8.0 torchvision==0.23.0 torchaudio==2.8.0 --index-url https://download.pytorch.org/whl/cu128

LiveAct を使う場合は vllm をインストールします。

pip install vllm==0.11.0

モデル重みをダウンロードする

CyberVerse は現在 FlashHead と LiveAct に対応しています。必要なものだけダウンロードしてください。今後もさらにモデルを追加していきます。

pip install "huggingface_hub[cli]"

FlashHead（SoulX-FlashHead）

モデルコンポーネント	説明	リンク
`SoulX-FlashHead-1_3B`	1.3B FlashHead 重み	Hugging Face, ModelScope
`wav2vec2-base-960h`	音声特徴抽出器	Hugging Face, ModelScope

# 中国本土から利用する場合は、先にミラーを設定できます:
# export HF_ENDPOINT=https://hf-mirror.com

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（SoulX-LiveAct）

モデル名	ダウンロード
SoulX-LiveAct	Hugging Face, ModelScope
chinese-wav2vec2-base	Hugging Face, ModelScope

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

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

Avatar Inference を設定する

enabled を true にし、モデルパスをローカルの checkpoint パスに合わせて更新します。

inference:
  avatar:
    enabled: true
    default: "flash_head"               # 起動するアバターモデルを指定。live_act を選ぶ場合は下の live_act 設定を記入
    runtime:
      cuda_visible_devices: 0      # 共有 GPU ID。マルチ GPU の場合は 0,1 など
      world_size: 1                # 共有 GPU 数。デュアル GPU なら 2
    flash_head:
      checkpoint_dir: "./checkpoints/SoulX-FlashHead-1_3B"  # ← ローカルのパス
      wav2vec_dir: "./checkpoints/wav2vec2-base-960h"        # ← ローカルのパス
      model_type: "lite"           # 高画質が必要なら "pro"（より多くの GPU が必要）
      compile_model: true
      compile_vae: true
      dist_worker_main_thread: true
      infer_params:
        frame_num: 33
        motion_frames_latent_num: 2
        tgt_fps: 20
        sample_rate: 16000
        sample_shift: 5
        color_correction_strength: 1.0
        cached_audio_duration: 8
        num_heads: 12
        height: 512
        width: 512
    live_act:
      ckpt_dir: "./checkpoints/LiveAct"                     # ← ローカルのパス
      wav2vec_dir: "./checkpoints/chinese-wav2vec2-base"   # ← ローカルのパス
      seed: 42
      fp8_gemm: true
      fp4_gemm: false
      compile_wan_model: false
      compile_vae_decode: false
      dist_worker_main_thread: true
      default_prompt: "一个人在说话"
      infer_params:
        size: "320*480"
        fps: 20
        audio_cfg: 1.0

これらのオプションは、あとで Web UI から調整することもできます。

LiveAct FP4 GEMM（任意）

FP4 アクセラレーションには LightX2V から lightx2v_kernel をビルド・インストールする必要があります。ビルド環境では PyTorch 2.7+ と CUTLASS のソースを用意してください。

準備

pip install scikit_build_core uv

whl のビルド

git clone https://github.com/NVIDIA/cutlass.git
git clone https://github.com/ModelTC/LightX2V.git
cd LightX2V/lightx2v_kernel
# /path/to/cutlass をローカルの cutlass クローンの絶対パスに置き換えてください。
MAX_JOBS=$(nproc) && CMAKE_BUILD_PARALLEL_LEVEL=$(nproc) \
uv build --wheel \
    -Cbuild-dir=build . \
    -Ccmake.define.CUTLASS_PATH=/path/to/cutlass \
    --verbose \
    --color=always \
    --no-build-isolation

whl のインストール

pip install dist/*.whl --force-reinstall --no-deps

CyberVerse で有効化

cyberverse_config.yaml（または Web UI）の inference.avatar.live_act で次を設定します：

fp8_gemm: false
fp4_gemm: true

これらのフラグを変更したあと、推論サービスを再起動してください。

SageAttention と FlashAttention（任意）

# SageAttention（ソースからビルド）
git clone https://github.com/thu-ml/SageAttention.git
cd SageAttention
export EXT_PARALLEL=4 NVCC_APPEND_FLAGS="--threads 8" MAX_JOBS=32 # Optional
python setup.py install

# FlashAttention (optional)
wget -O flash_attn-2.8.1+cu12torch2.8cxx11abiTRUE-cp312-cp312-linux_x86_64.whl \
  "https://github.com/Dao-AILab/flash-attention/releases/download/v2.8.1/flash_attn-2.8.1%2Bcu12torch2.8cxx11abiTRUE-cp312-cp312-linux_x86_64.whl"

pip install flash_attn-2.8.1+cu12torch2.8cxx11abiTRUE-cp312-cp312-linux_x86_64.whl

Avatar ハードウェアベンチマーク

リアルタイムのデジタルヒューマン映像には GPU アクセラレーションが必要です。以下は FlashHead と LiveAct アバターモデルのベンチマークです。

モデル	品質	GPU	枚数	解像度	FPS	リアルタイム可？
FlashHead 1.3B	Pro	RTX 5090	2	512×512	25+	✅ はい
FlashHead 1.3B	Pro	RTX 5090	1	464x464	20	✅ はい
FlashHead 1.3B	Pro	RTX PRO 6000	1	512×512	20	✅ はい
FlashHead 1.3B	Pro	RTX 4090	1	512×512	~10.8	❌ いいえ
FlashHead 1.3B	Lite	RTX 4090	1	512×512	25+	✅ はい
LiveAct 18B	—	RTX PRO 6000	2	320×480	20	✅ はい
LiveAct 18B	—	RTX PRO 6000	1	256×417	20	✅ はい

Pro は画質優先、Lite は速度優先です。表は代表的な 画質と計算資源のバランス の例です。余裕があれば画質を上げられ、不足なら解像度や Pro / Lite など画質側の設定を下げてリアルタイム性を確保してください。

avatar inference が有効な場合、make inference は cyberverse_config.yaml の inference.avatar.default を読み取り、現在の推論プロセスではその 1 つのアバターモデルだけを初期化します。次のログが出るまで待ちます。

Active avatar model initialized: <model_name>
CyberVerse Inference Server started on port 50051

よくある質問 — 自己チェック（QA）

アバター映像がカクつく、止まる、音声より遅れるときは、まず推論が再生に追いついているかを確認してください。

推論ログで RTP を確認する

RTP（リアルタイム性能係数）は、チャンクの生成にかかった時間と、そのチャンクを設定 FPS で再生するのに必要な時間の比です。

RTP = elapsed / (frames / fps)

RTP	意味
< 1	生成が再生より速い — リアルタイム配信に余裕あり
= 1	ちょうどリアルタイム
> 1	生成が再生より遅い — 産出が消費に追いつかないため、遅延やカクつきが起きやすい

キャラクターが話している間、推論ターミナル（make inference）のログで LiveAct または FlashHead の chunk 行を確認します。

LiveAct の例（RTP > 1 — リアルタイム不可）：

INFO:inference.plugins.avatar.live_act_plugin:LiveAct chunk: idx=2 frames=32 320x480 fps=20 iter=2 elapsed=1.870s is_final=False

この chunk の再生時間：32 / 20 = 1.6 秒
RTP：1.870 / 1.6 ≈ 1.17（> 1 — この GPU では 320×480 @ 20 fps に追いつかない）

FlashHead も同様に、elapsed と num_frames、fps から計算します。

INFO:...FlashHead video chunk generated: chunk_index=1 num_frames=33 512x512 fps=20 ... elapsed=2.100s

この例では RTP = 2.100 / (33/20) ≈ 1.27 で、リアルタイムを超えています。

RTP > 1 のときの対処

解像度または画質を下げる — 例：LiveAct の infer_params.size、FlashHead の height / width、または FlashHead を model_type: "lite" にする。
計算資源を増やす — GPU を増やす（runtime.world_size、cuda_visible_devices）、対応環境では FP8/FP4 GEMM やコンパイル加速を有効化、より高速な GPU を使う。
上のベンチマーク表に合わせる — Avatar ハードウェアベンチマークで リアルタイム？ が「はい」の解像度・FPS・GPU の組み合わせを選ぶ。

純粋な音声モード（inference.avatar.enabled: false）では Avatar の RTP は関係しません。音声のみでカクつく場合は、ネットワーク/WebRTC や上流の音声遅延を疑い、リモートアクセスメモを参照してください。

リモートアクセスメモ

streaming_mode: direct で組み込み TURN を使う場合、ブラウザはサーバーの 8443/TCP に到達できる必要があります。ページは開けるのに音声・映像がいつまでも接続されない、またはサーバーログに ICE connection state: failed や publish timeout waiting for connection が出る場合は、まず手元の端末からサーバーの 8443 ポートに疎通できるか確認してください。

nc -vz <server-ip> 8443

8443 に到達できない場合、原因はクラウドのセキュリティグループ、ファイアウォール、または NAT 制限であることが一般的です。その場合は、SSH トンネルでローカルの 8443 をサーバーへ転送できます。

ssh -L 8443:127.0.0.1:8443 user@host -p port

トンネル確立後、ブラウザはローカルの 127.0.0.1:8443 経由でリモート TURN サービスへ接続します。

SSH トンネルではなくブラウザからリモートサーバーへ直接接続したい場合は、cyberverse_config.yaml の pipeline.ice_public_ip にサーバーのグローバル IP またはドメインを設定してください。SSH トンネルを使う場合は、デフォルト値（127.0.0.1）のままで構いません。

ロードマップ

1. リアルタイム音声・映像 Agent プラットフォーム

音声ファーストのリアルタイム Agent を、実行・カスタマイズ・埋め込みしやすくします。

2. リアルタイムデジタルヒューマン通話

Avatar 用 GPU リソースがある場合、音声 Agent をリアルタイム映像通話に変えます。

参照画像から、設定可能な Avatar プラグイン（FlashHead、LiveAct など）でリアルタイムのアバター映像を駆動
キャラクター存在感のための待機動画キャッシュ再生
リアルタイム発話セグメントの音声・映像同期
画質、遅延、コストのトレードオフが異なる Avatar バックエンドを追加
コンシューマー GPU、ワークステーション GPU、クラウド GPU 向けのより良い Avatar デプロイプロファイル

3. エージェントネットワーク

複数のエージェントを接続し、相互にコミュニケーションし、協調し、ネットワークを形成できるようにします。

agent-to-agent 通信を有効化
マルチエージェント協調と委譲を有効化
エージェント間の共有メモリと共有知識を有効化
接続されたエージェントのオープンネットワークを構築

コミュニティ

QR コードの有効期限が切れた場合は、管理者の WeChat wx_dsd2077 に追加し、申請時に CyberVerse と備考してください。グループへ招待します。

Star History

ライセンス

GNU General Public License v3.0。詳細は LICENSE を参照してください。

謝辞

SoulX-FlashHead — Soul AI Lab によるアバターモデル
SoulX-LiveAct - Soul AI Lab によるアバターモデル
MuseTalk — TME Lyra Lab によるリアルタイムリップシンクモデル
Pion — Go の WebRTC 実装
Linux.do

FilesExpand file tree

README.ja.md

Latest commit

History