トラブルシューティング

MiniPrem トラブルシューティングガイド

ミニプレム（MiniPrem）プラットフォーム運用時によく発生する問題の解決方法

本ページの内容はデジタルヒューマン株式会社の正式サポート対象外です。参考情報としてご利用ください。

トラブルシューティングを初めて行う方へ：サポートに問い合わせる前の診断情報収集について、初心者の方にもわかりやすく解説した 問題診断ガイド からお読みください。

Audio2Face 関連エラーが表示された場合：現行の MiniPrem は Audio2Face を使用していません。Container audio2face_with_emotion Error などのメッセージが出る環境は旧バージョンのため、サポート窓口 までご連絡ください。アップグレード対応をご案内します。

目次

• 一般的なトラブルシューティング手順

• Renny に関する問題

• Audio2Face に関する問題

• リソースに関する問題

• パフォーマンスに関する問題

• ネットワークに関する問題

• Flowise に関する問題

• モニタリングに関する問題

• vLLM に関する問題

• インストールに関する問題

• ドライバー・OS に関する問題

• ライセンス

• 著作権

一般的なトラブルシューティング手順

1. サービスのステータス確認：

   ./miniprem.sh status

2. サービスログの確認：

   ./miniprem.sh logs
   # または特定のサービスのみ
   ./miniprem.sh logs renny

3. サービスの再起動：

   ./miniprem.sh restart

4. Docker リソースの確認：

   docker stats

Renny に関する問題

Renny のヘルスチェック失敗

症状：レンダラー（開発コード：Renny）のコンテナが unhealthy ステータスを返す

解決方法：

1. Renny のログを確認します：

   docker logs renny

2. デジタルヒューマン プラットフォームへの接続性を確認します：

   curl -I $DHOP_ADDRESS

3. 内部の音声処理を確認します：

   docker logs renny | grep -i speech

4. configuration.dat ファイルを確認します：

   cat docker/configuration.dat

音声処理に関する問題

症状：表情アニメーションや音声が正しく動作しない

原因：TTS（音声合成）プロバイダー（Azure / Eleven Labs / RIME）の認証情報誤り、コーディネーターの不整合、Renny 内部の音声サービス停止などが考えられます。

対処：

1. 音声処理の設定を確認します：

   docker logs renny | grep -i "speech\|audio"

2. コーディネーターの問題が疑われる場合は、USE_V2_COORDINATOR が設定されているか確認します：

   docker exec -it renny env | grep USE_V2_COORDINATOR

3. Renny 内部の音声システムのステータスを確認します：

   curl -s http://localhost:8081/health | grep -i speech

デジタルヒューマンが表示されるが発話しない

症状：デジタルヒューマンの映像は表示されるが音声を発しない

原因：TTS プロバイダーへの接続失敗、API キー誤り、TTS モデル ID 不一致などが疑われます。複数プロバイダー（Azure / Eleven Labs / RIME）を切り替えて運用している場合に発生しやすい問題です。

対処：

1. Renny のコンテナ ID を取得します：

   docker ps

2. ログを TTS キーワードで追い、該当行の前後 5 行程度を確認して切り分けます。[CONTAINER_ID] は Renny のコンテナ ID に置き換えてください：

   docker logs -f [CONTAINER_ID] 2>&1 | grep -B 5 -A 5 -i "TTS"

3. docker-compose.env の TTS 関連変数（AZURE_REGION / AZURE_SPEECH_KEY / ELEVEN_LABS_API_KEY / ELEVEN_LABS_MODEL_ID / RIME_API_KEY）が、選択中のプロバイダーに合っているか確認します。

Audio2Face に関する問題

Audio2Face のヘルスチェック失敗

症状：起動時に audio2face_with_emotion や audio2face_controller のヘルスチェックが失敗し、コンテナが unhealthy のまま起動しない

原因：環境によっては HTTP ヘルスチェック（curl http://localhost:50000/health）が安定せず、TCP ポート疎通のみで判定する方が確実なケースがあります。

対処： ./docker/docker-compose.default.yml のヘルスチェックを TCP ベースに書き換えます。

  audio2face_with_emotion:
    healthcheck:
      # test: ["CMD-SHELL", "curl -s http://localhost:50000/health | grep -q '\"status\":\"ok\"' || exit 1"]
      test: ["CMD-SHELL", "timeout 2 bash -c '</dev/tcp/localhost/50000' || exit 1"]

  audio2face_controller:
    healthcheck:
      # test: ["CMD-SHELL", "curl -s http://localhost:52000/health | grep -q '\"status\":\"ok\"' || exit 1"]
      test: ["CMD-SHELL", "timeout 2 bash -c '</dev/tcp/localhost/52000' || exit 1"]

書き換え後は ./miniprem.sh restart でサービスを再起動して反映します。

Audio2Face コンテナエラー（現行版での扱い）

症状：MiniPrem 起動時に次のような Audio2Face 関連エラーが表示される

Container audio2face_with_emotion  Error

原因：現行の MiniPrem は Audio2Face を使用しません。当該エラーが出る環境は旧バージョンを運用している可能性があります。

対処：サポート窓口 までご連絡ください。アップグレード作業をご案内します。

リソースに関する問題

メモリ不足

症状：サービスが OOM（メモリ不足）エラーでクラッシュする

解決方法：

1. メモリ使用量を確認します：

   free -h
   docker stats

2. ホストのスワップ領域を増やします：

   sudo fallocate -l 8G /swapfile
   sudo chmod 600 /swapfile
   sudo mkswap /swapfile
   sudo swapon /swapfile

3. Docker のメモリ上限を調整します：

   deploy:
     resources:
       limits:
         memory: 8G

GPU メモリに関する問題

症状：GPU のメモリ不足エラーが発生する

原因：フルインストール（Full Install）では vLLM・Renny・Audio2Face など複数サービスが同時に GPU を確保するため、単一カード運用では同時起動でメモリ枯渇が起きやすくなります。

対処：

1. GPU の使用状況を監視します：

   nvidia-smi -l 1

2. より小さなモデルを使用します：

   docker exec -it vllm python3 -m vllm.entrypoints.openai.api_server --model tinyllama

3. MiniPrem の稼働中は他のアプリケーションが GPU を使用しないようにします。

4. フルインストール（Full Install）で GPU メモリが慢性的に不足する場合は、サービスを段階的に起動して負荷ピークを分散します：

   # 1) vLLM を先に起動して LLM 用 VRAM を確保
   docker compose up -d vllm
   
   # 2) Redis / Grafana / Prometheus / Flowise を起動
   docker compose up -d redis grafana prometheus flowise
   
   # 3) Audio2Face 系を最後に起動
   docker compose up -d audio2face_with_emotion audio2face_controller

パフォーマンスに関する問題

フレームレート低下・コマ落ち

症状：セッション中にフレームレートが低下する、映像にコマ落ちが発生する

原因：CPU・メモリ・GPU いずれかのリソース不足、または他プロセスとの GPU 競合が一般的な要因です。低スペック機材で運用している場合や、MiniPrem ホストに他アプリケーションを同居させている場合に発生しやすくなります。

対処：

1. CPU・メモリの使用状況を確認します：

   top

2. セッション実行中に GPU 利用率と GPU メモリを継続観察します：

   watch nvidia-smi

3. 慢性的にリソース不足が確認される場合は、推奨ハードウェア要件を満たしているかを はじめに で再確認してください。下回るとコマ落ち・フリーズ・再接続が発生します。

ネットワークに関する問題

ポートの競合

症状：ポートがすでに使用中のためサービスが起動しない

解決方法：

1. そのポートを使用しているプロセスを特定します：

   sudo lsof -i :PORT_NUMBER

2. 競合しているプロセスを停止するか、該当する compose ファイル（docker-compose.base.yml または docker-compose.extras.yml）でポートを変更します。

3. ファイアウォール設定を確認します：

   sudo ufw status

Docker ネットワークの問題

症状：サービス間の通信ができない

解決方法：

1. Docker ネットワークを確認します：

   docker network inspect uneeq-miniprem_default

2. コンテナ間の接続性を確認します：

   docker exec -it flowise ping vllm

3. Docker を再起動します：

   sudo systemctl restart docker

Flowise に関する問題

Flowise UI にアクセスできない

症状：http://localhost:3000 で Flowise にアクセスできない

原因：コンテナの起動失敗、ポート 3000 の競合、ホスト OS のローカルファイアウォール（ufw）、または EDR / アンチウイルス等のエンドポイントセキュリティ製品によるブロックが考えられます。日本のエンタープライズ環境では EDR / AV が未承認ポートを遮断するケースがあります。

対処：

1. コンテナが稼働しているか確認します：

   docker ps | grep flowise

2. コンテナのログを確認します：

   docker logs flowise

3. ポートが利用可能か確認します：

   curl -I http://localhost:3000

4. ローカルファイアウォール、組織のファイアウォール、EDR / アンチウイルス等のセキュリティソフトがポート 3000 をブロックしていないか確認します：

   sudo ufw status

Chatflow の作成失敗

症状：Chatflow を作成または保存できない

解決方法：

1. データベースへの接続性を確認します：

   docker exec -it flowise ls -la /usr/src/.flowise/database.sqlite

2. ボリュームのパーミッションを確認します：

   docker exec -it flowise ls -la /usr/src/.flowise/

3. セットアップスクリプトを手動で実行してみます：

   ./docker/setup-chatflow-post-deployment-fixed.sh

API 認証に関する問題

症状：API アクセス時に Unauthorized エラーが発生する

解決方法：

1. 正しい API キーを使用しているか確認します：

   Authorization: Bearer miniprem_demo_secret_key

2. API キーをリセットします：

   docker exec -it flowise node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

   その後、該当する compose ファイル（インストール種別に応じて docker-compose.base.yml または docker-compose.extras.yml）の FLOWISE_SECRETKEY_OVERWRITE を更新します。

モニタリングに関する問題

Prometheus がメトリクスを収集しない

症状：Grafana ダッシュボードにメトリクスが表示されない

解決方法：

1. Prometheus が稼働しているか確認します：

   docker ps | grep prometheus

2. Prometheus のターゲットを確認します：

   curl http://localhost:9090/api/v1/targets

3. Prometheus の設定を確認します：

   cat docker/prometheus.yml

Grafana のログインに関する問題

症状：Grafana にログインできない

解決方法：

1. デフォルトの認証情報（admin/admin）を使用します

2. admin パスワードをリセットします：

   docker exec -it grafana grafana-cli admin reset-admin-password admin

3. Grafana のログを確認します：

   docker logs grafana

vLLM に関する問題

vLLM コンテナが起動しない

症状：vLLM コンテナが起動直後に停止する

解決方法：

1. GPU が利用可能か確認します：

   nvidia-smi

2. NVIDIA ランタイムが正しく設定されているか確認します：

   docker info | grep -i runtime

3. ポートの競合を確認します：

   sudo lsof -i :8000

4. vLLM のログを確認します：

   docker logs vllm

モデル読み込みの問題

症状：モデル使用時にエラーメッセージが表示される

解決方法：

1. モデルがダウンロードされているか確認します：

   docker exec -it vllm ls /root/.cache/huggingface

2. モデルを再取得します：

   docker exec -it vllm python3 -m vllm.entrypoints.openai.api_server --model facebook/opt-125m

3. GPU メモリが十分か確認します：

   nvidia-smi

4. テスト用により小さなモデルを試します：

   docker exec -it vllm python3 -m vllm.entrypoints.openai.api_server --model tinyllama

サービスを追加したい、またはインストール種別を変更したい場合は、インストーラーを再実行し、希望するオプションを選択してください。

インストールに関する問題

重複インストールの検出

症状：インストーラー実行時に「既存の MiniPrem インストールを検出しました」といった警告が表示される

原因：同一ホスト上に MiniPrem が複数インストールされている、または旧インストールが残置されています。複数の MiniPrem が並行稼働すると、ポート競合・GPU 競合・docker-compose.env の不整合が発生します。

対処：

• 検証目的で複数バージョンを並べたい場合でも、稼働は常に 1 つに限定してください。

• 旧インストールが不要であれば、停止のうえディレクトリごと削除してから新規インストールを進めます。

• どちらが現行か判断できない場合は、各ディレクトリ直下の .miniprem_install_type ファイルでインストール種別（default / custom）を確認できます：

  cat .miniprem_install_type

ドライバー・OS に関する問題

GPU が検出されない

症状：nvidia-smi が「command not found」を返す、または GPU が一覧に表示されない、コンテナが GPU エラーで起動しない

解決方法：

1. NVIDIA プロプライエタリドライバーがロードされているか確認します（nouveau には対応していません）：

   lsmod | grep nvidia
   # 「nouveau」が表示される場合は、オープンソース版ドライバーがロードされています
   lsmod | grep nouveau

2. NVIDIA プロプライエタリドライバーをインストールします：

   sudo apt install nvidia-driver-580
   sudo reboot

3. 再起動後に確認します：

   nvidia-smi

詳しいインストール手順とトラブルシューティングについては、NVIDIA ドライバーガイド を参照してください。

Secure Boot による NVIDIA モジュール読み込み失敗

症状：sudo modprobe nvidia 実行時に次のメッセージが表示され、ドライバーをインストール済みでも nvidia-smi が動作しない

ERROR: could not insert 'nvidia': Key was rejected by service

原因：Secure Boot / UEFI が有効になっており、署名されていないカーネルモジュールの読み込みを拒否しています。Dell / HP / Lenovo の BTO ワークステーションやサーバー機は Secure Boot がデフォルトで有効な場合が多く、典型的なハマりどころです。

対処：

1. 再起動時に BIOS 設定画面（DEL / F2 / F12 等、ベンダーごとに異なります）に入り、Secure Boot を無効化します。

2. 起動後にモジュールが読み込まれているか確認します。出力がなければまだロードされていません：

   lsmod | grep nvidia

3. カーネル更新後に同じ症状が再発することがあります。詳しい手順と MOK 署名による回避策は、NVIDIA ドライバーガイド を参照してください。

NVENC エラー / ピクセルストリーミング失敗

症状：ピクセルストリーミングの初期化に失敗する、Renny ログに NVENC エンコーダーのエラーが出る、画面が真っ黒または映像が出ない、セッション接続直後に切断される

580.126.x は NVENC を破壊します（L4、A10G、T4、RTX を含むすべての GPU タイプで発生）。このバージョンを使用している場合は、580.82.x または 580.142 にダウングレードしてください。

推奨ドライバーバージョン：

バージョン	インストール方法	推奨用途
580.82.07	apt（Ubuntu パッケージマネージャー）	大半のデプロイ（L4、A10G、T4）
580.82.09	.run インストーラー（NVIDIA 公式）	Blackwell / RTX PRO 6000
580.142	apt または .run	サポート対象バージョン

解決方法：

1. ドライバーバージョンを確認します：

   nvidia-smi | head -3

2. バージョンが 580.126.x と表示された場合、580.82 にダウングレードします：

   # 不具合のあるドライバーを削除
   sudo apt remove --purge nvidia-driver-580
   # 正常動作するバージョンをインストール
   sudo apt install nvidia-driver-580=580.82.07-0ubuntu1
   sudo reboot

3. アクティブセッション中に NVENC が動作しているか確認します：

   nvidia-smi dmon -s u -d 1
   # ストリーミング中は「enc」列に値（0% 以外）が表示されるはずです

サポート対象ドライバーバージョンの詳細については、NVIDIA ドライバーガイド を参照してください。

WSL / Docker のネットワークに関する問題

WSL はサポート対象外です。 MiniPrem はネイティブの Ubuntu 24.04 LTS 以降が必要です。WSL（Windows Subsystem for Linux）では、MiniPrem に必要な完全な GPU パススルーや Docker のネットワーク機能を提供できません。WSL 上で動作させている場合は、Ubuntu をネイティブにインストールするか、専用の Linux マシンをご利用ください。