ACE Linux RTX Sandbox

Linux RTX 上で NVIDIA ACE 系の digital human 構成を試すためのリポジトリです。現在の主経路は Tokkio 5.0 を使った browser-first / Kubernetes / multi-service 構成で、既存の Audio2Face + MetaHuman + ASR/LLM/TTS 直結サンドボックスは Unreal 中心の研究用サブパスとして残しています。

大きなキャッシュ、生成音声、Docker bind mount、UE の重い生成物は repo の外に置きます。Tokkio の作業ディレクトリは infra/tokkio/workspace に置きますが、Git 管理外です。既定の外部永続領域は /home2/ko66/ace-sandbox です。

Layout

• docs/architecture/tokkio-reference-stack.md: Tokkio 5.0 を主系にした構成メモ
• infra/tokkio: Tokkio one-click deployment 用の前提チェック、環境変数雛形、実行ラッパ
• docs/architecture/ace-sandbox.md: 全体アーキテクチャ、状態遷移、WebSocket プロトコル、運用前提
• infra/compose/docker-compose.yml: GPU1 に固定した ASR/TTS NIM 起動雛形
• services/orchestrator: FastAPI + asyncio ベースの half-duplex 会話オーケストレータ
• unreal/Plugins/ACEConversation: UE 5.6 プロジェクトへ組み込むための C++ コンポーネント雛形

Persistent Directories

初回に以下を作成します。

mkdir -p /home2/ko66/ace-sandbox/{nim-cache/{asr,tts},logs,audio,ue-ddc,docker}
mkdir -p infra/tokkio/workspace/{controller,logs,state}

Tokkio 5.0

Tokkio を主系で使う場合は、まず infra/tokkio を使って controller 側の準備を行います。ここで行うのは my-config.env 生成、永続ディレクトリの作成、envbuild.sh 実行ラッパの提供です。Tokkio 本体は NVIDIA 配布の NVIDIA/ACE repo 側にあります。

cp infra/tokkio/.env.example infra/tokkio/.env
python3 infra/tokkio/prepare_tokkio_workspace.py --env-file infra/tokkio/.env

その後、NVIDIA 公式 quickstart に沿って NVIDIA/ACE を infra/tokkio/workspace/NVIDIA-ACE に取得し、infra/tokkio/deploy_tokkio.sh で init-config と install を実行します。

infra/tokkio/deploy_tokkio.sh init-config --env-file infra/tokkio/.env
$EDITOR /home/kyano/workspace/ACE/infra/tokkio/workspace/controller/ace-app-config.yml
infra/tokkio/deploy_tokkio.sh install --env-file infra/tokkio/.env
python3 infra/tokkio/check_tokkio_endpoints.py --insecure --kubectl --ui-url https://<app-ip>:30111 --api-url https://<app-ip>:30888

詳細は infra/tokkio/README.md と docs/architecture/tokkio-reference-stack.md にまとめています。

Unreal-Centric Sandbox

以下は Tokkio ではなく、Unreal 直結の研究用サンドボックスです。

Speech NIM

1. infra/compose/.env.example を infra/compose/.env にコピーして、NGC とイメージ名を埋めます。
2. 起動します。

docker compose --env-file infra/compose/.env -f infra/compose/docker-compose.yml up -d

ASR は host の 50051/9000、TTS は 50052/9001 を使う前提です。

Orchestrator

cd services/orchestrator
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
cp .env.example .env
python3 tools/init_storage.py
uvicorn app.main:app --host 0.0.0.0 --port 8080

ACE_NIM_API_KEY、ACE_NIM_LLM_MODEL、Speech NIM の接続先を .env で調整してください。既定では起動時に /v1/models で LLM モデル存在確認を行います。

起動後は GET /status で外部依存を含む状態確認ができます。モックモードの疎通確認には services/orchestrator/tools/demo_client.py を使えます。

Unreal

unreal/README.md に組み込み手順をまとめています。重要なポイントは次のとおりです。

• UE 5.6 の C++ プロジェクトを作成する
• MetaHuman と ACE Unreal Plugin を入れる
• Face_AnimBP に Apply ACE Face Animations を追加する
• mh_arkit_mapping_pose_A2F を使う
• Mouth Close の既定カーブ干渉を無効化する
• ConversationBridgeComponent で WebSocket と PCM の受け渡しを接続する
• ACEAudioPlaybackComponent で受信 PCM を USoundWaveProcedural へ流す

Verification

Tokkio の確認は infra/tokkio/check_tokkio_endpoints.py を使います。Unreal 中心のサンドボックスを確認する場合は、依存が入った環境で以下を順に確認します。

python3 -m unittest discover -s services/orchestrator/tests
python3 services/orchestrator/tools/demo_client.py --url ws://127.0.0.1:8080/ws/session --mock-audio
curl -s http://127.0.0.1:8080/status