audio-flamingo-next-env

NVIDIA Audio Flamingo Next の推論環境を DevContainer で構築するリポジトリです。
NVIDIA GPU を使用した高速推論に対応しています。 再現性のある DevContainer 構成と uv ベースの依存管理を中心に整理しています。

Python 依存は requirements.txt ではなく pyproject.toml と uv.lock を正本として管理します。

Hugging Face のモデルキャッシュは /workspace/.cache/huggingface に保存するため、コンテナを作り直してもワーキングディレクトリが残っている限り再ダウンロードを避けられます。

このリポジトリでできること

• NVIDIA Audio Flamingo Next の単発推論
• Streamlit UI: ブラウザから音声ファイルをアップロードして推論（モデルは常駐）
• 常駐サーバーモード: モデルを一度ロードして HTTP 経由で繰り返し推論（重みの再ロードなし）
• GPU 対応 DevContainer 上での再現可能な実行環境構築

必要条件

• Docker（GPU サポート付き）
• NVIDIA Container Toolkit
• CUDA 12.8 を利用できる NVIDIA ドライバー
• VS Code + Dev Containers 拡張機能

クイックスタート

1. DevContainer を起動する

VS Code でこのリポジトリを開き、コマンドパレット（Ctrl+Shift+P / Cmd+Shift+P）から
「Dev Containers: Reopen in Container」 を選択します。

コンテナのビルドには CUDA 12.8 ベースイメージと uv による依存解決を含むため、
初回は数分かかることがあります。

2. GPU が認識されていることを確認する

uv run python -c "import torch; print(torch.cuda.is_available(), torch.cuda.get_device_name(0))"

3. 推論を実行する

Streamlit UI（ブラウザ操作）

uv run streamlit run app.py

ブラウザで http://localhost:8501 が開きます。音声ファイルをアップロードして質問を入力するだけで推論できます。モデルは st.cache_resource でセッション中に常駐します。

単発実行（毎回モデルをロード）

uv run python inference.py --audio path/to/audio.wav --question "この音声は何ですか？"

常駐サーバーモード（モデルを一度だけロード）

サーバーを起動するとモデルが一度だけロードされ、以降は HTTP 経由で高速に推論できます。

uv run python server.py --device cuda --host 127.0.0.1 --port 8000

推論リクエストの送信例:

curl -s -X POST http://127.0.0.1:8000/infer \
  -H "Content-Type: application/json" \
  -d '{"audio": "/abs/path/to/audio.wav", "question": "この音声は何ですか？"}' \
  | python -m json.tool

ヘルスチェック:

curl http://127.0.0.1:8000/health

4. 依存を更新する

uv lock
uv sync

5. 必要に応じて Hugging Face 認証を設定する

モデル取得時のレート制限や警告を避けたい場合は、事前に HF_TOKEN を設定してください。

export HF_TOKEN=your_huggingface_token

6. 軽量チェックを実行する

python -m unittest discover -s tests -v

ファイル構成

.
├── .devcontainer/
│   ├── devcontainer.json   # DevContainer 設定（GPU アクセス含む）
│   └── Dockerfile          # CUDA 12.8 + uv + 非 root ユーザー設定
├── app.py                  # Streamlit UI（ブラウザから推論）
├── inference.py            # 単発推論 CLI
├── server.py               # 常駐 HTTP 推論サーバー（モデルを一度だけロード）
├── pyproject.toml          # Python 依存定義
├── tests/                  # 軽量ユニットテスト
├── uv.lock                 # uv ロックファイル
├── requirements.txt        # 互換用の旧依存一覧
└── README.md

環境詳細

推論スクリプトのオプション

uv run python inference.py \
  --audio <音声ファイルパス>        # WAV / MP3 / FLAC など
  --question "質問テキスト"         # （省略時: "What do you hear in this audio?"）
  --model nvidia/audio-flamingo-next-hf  # HuggingFace モデル ID
  --device cuda                     # cuda または cpu
  --max-new-tokens 512              # 生成トークン数上限

存在しないファイルや未対応拡張子を指定した場合は、モデルをロードする前に明示的にエラー終了します。

モデルについて

• モデル: nvidia/audio-flamingo-next-hf
• タスク: 音声理解・音声質問応答（AQA）
• 推奨 VRAM: 24GB 以上（bfloat16 使用時）

注意事項

• Audio Flamingo Next は通常の AutoModelForCausalLM ではなく、モデルカードの推奨どおり AutoModel と chat template ベースで読み込みます。
• 一部の PyPI 版 transformers では audioflamingonext が未対応なため、このリポジトリでは uv の source 設定で Audio Flamingo Next 対応ビルドを固定しています。
• DevContainer は root ではなく vscode ユーザーで起動し、Python 仮想環境は /workspace/venv に作成されます。
• Hugging Face のキャッシュ先は /workspace/.cache/huggingface に固定してあり、ワークスペースが残る限りモデルキャッシュも維持されます。

トラブルシューティング

ｗ

• ERROR: Audio file not found: 指定した音声ファイルのパスを確認してください。
• WARNING: CUDA is not available. Falling back to CPU.: GPU が見えていないため CPU 実行に切り替わっています。DevContainer を GPU 付きで起動しているか確認してください。
• The installed transformers build does not support Audio Flamingo Next: uv sync --frozen --no-dev を再実行し、README 記載の依存構成を使ってください。
• Hugging Face の未認証アクセス警告が出る: 必要に応じて HF_TOKEN を設定してください。

ライセンス

MIT License を採用しています。詳細は LICENSE を参照してください。