> For the complete documentation index, see [llms.txt](https://docs.digitalhumans.jp/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digitalhumans.jp/dev/miniprem/troubleshooting.md).

# トラブルシューティング

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

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

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

{% hint style="warning" %}
**トラブルシューティングを初めて行う方へ**：サポートに問い合わせる前の診断情報収集について、初心者の方にもわかりやすく解説した [問題診断ガイド](/dev/miniprem/first-steps.md) からお読みください。
{% endhint %}

{% hint style="warning" %}
**Audio2Face 関連エラーが表示された場合**：現行の MiniPrem は Audio2Face を使用していません。`Container audio2face_with_emotion Error` などのメッセージが出る環境は旧バージョンのため、[サポート窓口](https://support.digitalhumans.jp/) までご連絡ください。アップグレード対応をご案内します。
{% endhint %}

### 目次

* [一般的なトラブルシューティング手順](#general-troubleshooting-steps)
* [Renny に関する問題](#renny-issues)
* [Audio2Face に関する問題](#audio2face-issues)
* [リソースに関する問題](#resource-issues)
* [パフォーマンスに関する問題](#performance-issues)
* [ネットワークに関する問題](#network-issues)
* [Flowise に関する問題](#flowise-issues)
* [モニタリングに関する問題](#monitoring-issues)
* [vLLM に関する問題](#vllm-issues)
* [インストールに関する問題](#install-issues)
* [ドライバー・OS に関する問題](#driver-os-issues)
* [ライセンス](#license)
* [著作権](#copyright)

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

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

   ```bash
   ./miniprem.sh status
   ```
2. **サービスログの確認**：

   ```bash
   ./miniprem.sh logs
   # または特定のサービスのみ
   ./miniprem.sh logs renny
   ```
3. **サービスの再起動**：

   ```bash
   ./miniprem.sh restart
   ```
4. **Docker リソースの確認**：

   ```bash
   docker stats
   ```

### Renny に関する問題

#### Renny のヘルスチェック失敗

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

**解決方法**：

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

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

   ```bash
   curl -I $DHOP_ADDRESS
   ```
3. 内部の音声処理を確認します：

   ```bash
   docker logs renny | grep -i speech
   ```
4. configuration.dat ファイルを確認します：

   ```bash
   cat docker/configuration.dat
   ```

#### 音声処理に関する問題

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

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

**対処**：

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

   ```bash
   docker logs renny | grep -i "speech\|audio"
   ```
2. コーディネーターの問題が疑われる場合は、`USE_V2_COORDINATOR` が設定されているか確認します：

   ```bash
   docker exec -it renny env | grep USE_V2_COORDINATOR
   ```
3. Renny 内部の音声システムのステータスを確認します：

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

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

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

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

**対処**：

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

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

   ```bash
   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 ベースに書き換えます。

```yaml
  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 関連エラーが表示される

```bash
Container audio2face_with_emotion  Error
```

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

**対処**：[サポート窓口](https://support.digitalhumans.jp/) までご連絡ください。アップグレード作業をご案内します。

### リソースに関する問題

#### メモリ不足

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

**解決方法**：

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

   ```bash
   free -h
   docker stats
   ```
2. ホストのスワップ領域を増やします：

   ```bash
   sudo fallocate -l 8G /swapfile
   sudo chmod 600 /swapfile
   sudo mkswap /swapfile
   sudo swapon /swapfile
   ```
3. Docker のメモリ上限を調整します：

   ```yaml
   deploy:
     resources:
       limits:
         memory: 8G
   ```

#### GPU メモリに関する問題

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

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

**対処**：

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

   ```bash
   nvidia-smi -l 1
   ```
2. より小さなモデルを使用します：

   ```bash
   docker exec -it vllm python3 -m vllm.entrypoints.openai.api_server --model tinyllama
   ```
3. MiniPrem の稼働中は他のアプリケーションが GPU を使用しないようにします。
4. フルインストール（Full Install）で GPU メモリが慢性的に不足する場合は、サービスを段階的に起動して負荷ピークを分散します：

   ```bash
   # 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・メモリの使用状況を確認します：

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

   ```bash
   watch nvidia-smi
   ```
3. 慢性的にリソース不足が確認される場合は、推奨ハードウェア要件を満たしているかを [はじめに](/dev/miniprem/getting-started.md) で再確認してください。下回るとコマ落ち・フリーズ・再接続が発生します。

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

#### ポートの競合

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

**解決方法**：

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

   ```bash
   sudo lsof -i :PORT_NUMBER
   ```
2. 競合しているプロセスを停止するか、該当する compose ファイル（docker-compose.base.yml または docker-compose.extras.yml）でポートを変更します。
3. ファイアウォール設定を確認します：

   ```bash
   sudo ufw status
   ```

#### Docker ネットワークの問題

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

**解決方法**：

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

   ```bash
   docker network inspect uneeq-miniprem_default
   ```
2. コンテナ間の接続性を確認します：

   ```bash
   docker exec -it flowise ping vllm
   ```
3. Docker を再起動します：

   ```bash
   sudo systemctl restart docker
   ```

### Flowise に関する問題

#### Flowise UI にアクセスできない

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

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

**対処**：

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

   ```bash
   docker ps | grep flowise
   ```
2. コンテナのログを確認します：

   ```bash
   docker logs flowise
   ```
3. ポートが利用可能か確認します：

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

   ```bash
   sudo ufw status
   ```

#### Chatflow の作成失敗

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

**解決方法**：

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

   ```bash
   docker exec -it flowise ls -la /usr/src/.flowise/database.sqlite
   ```
2. ボリュームのパーミッションを確認します：

   ```bash
   docker exec -it flowise ls -la /usr/src/.flowise/
   ```
3. セットアップスクリプトを手動で実行してみます：

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

#### API 認証に関する問題

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

**解決方法**：

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

   ```
   Authorization: Bearer miniprem_demo_secret_key
   ```
2. API キーをリセットします：

   ```bash
   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 が稼働しているか確認します：

   ```bash
   docker ps | grep prometheus
   ```
2. Prometheus のターゲットを確認します：

   ```bash
   curl http://localhost:9090/api/v1/targets
   ```
3. Prometheus の設定を確認します：

   ```bash
   cat docker/prometheus.yml
   ```

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

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

**解決方法**：

1. デフォルトの認証情報（admin/admin）を使用します
2. admin パスワードをリセットします：

   ```bash
   docker exec -it grafana grafana-cli admin reset-admin-password admin
   ```
3. Grafana のログを確認します：

   ```bash
   docker logs grafana
   ```

### vLLM に関する問題

#### vLLM コンテナが起動しない

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

**解決方法**：

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

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

   ```bash
   docker info | grep -i runtime
   ```
3. ポートの競合を確認します：

   ```bash
   sudo lsof -i :8000
   ```
4. vLLM のログを確認します：

   ```bash
   docker logs vllm
   ```

#### モデル読み込みの問題

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

**解決方法**：

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

   ```bash
   docker exec -it vllm ls /root/.cache/huggingface
   ```
2. モデルを再取得します：

   ```bash
   docker exec -it vllm python3 -m vllm.entrypoints.openai.api_server --model facebook/opt-125m
   ```
3. GPU メモリが十分か確認します：

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

   ```bash
   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`）を確認できます：

  ```bash
  cat .miniprem_install_type
  ```

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

#### GPU が検出されない

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

**解決方法**：

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

   ```bash
   lsmod | grep nvidia
   # 「nouveau」が表示される場合は、オープンソース版ドライバーがロードされています
   lsmod | grep nouveau
   ```
2. NVIDIA プロプライエタリドライバーをインストールします：

   ```bash
   sudo apt install nvidia-driver-580
   sudo reboot
   ```
3. 再起動後に確認します：

   ```bash
   nvidia-smi
   ```

詳しいインストール手順とトラブルシューティングについては、[NVIDIA ドライバーガイド](/dev/miniprem/nvidia-drivers.md) を参照してください。

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

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

```bash
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. 起動後にモジュールが読み込まれているか確認します。出力がなければまだロードされていません：

   ```bash
   lsmod | grep nvidia
   ```
3. カーネル更新後に同じ症状が再発することがあります。詳しい手順と MOK 署名による回避策は、[NVIDIA ドライバーガイド](/dev/miniprem/nvidia-drivers.md) を参照してください。

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

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

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

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

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

**解決方法**：

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

   ```bash
   nvidia-smi | head -3
   ```
2. バージョンが **580.126.x** と表示された場合、580.82 にダウングレードします：

   ```bash
   # 不具合のあるドライバーを削除
   sudo apt remove --purge nvidia-driver-580
   # 正常動作するバージョンをインストール
   sudo apt install nvidia-driver-580=580.82.07-0ubuntu1
   sudo reboot
   ```
3. アクティブセッション中に NVENC が動作しているか確認します：

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

サポート対象ドライバーバージョンの詳細については、[NVIDIA ドライバーガイド](/dev/miniprem/nvidia-drivers.md) を参照してください。

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

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