> 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/services/whisper.md).

# Whisper

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

{% hint style="info" %}
**Fast Whisper:** faster-whisper をベースにした GPU アクセラレーション対応の音声認識サービスです。リアルタイム文字起こしには WebSocket エンドポイント `ws://localhost:9000/ws`、ファイルアップロードによる文字起こしには REST API `http://localhost:9000/transcribe` を利用します。
{% endhint %}

ミニプレム（MiniPrem）は、OpenAI の Whisper 音声認識モデルを最適化した実装である faster-whisper を統合し、高精度なリアルタイム文字起こし機能を提供します。本ガイドでは、MiniPrem プラットフォーム内で Fast Whisper サービスを利用および設定する方法を説明します。

## 概要

Fast Whisper は、オリジナルの Whisper 実装よりもパフォーマンスを向上させた自動音声認識（ASR）機能を提供します。主な機能は以下のとおりです。

* WebSocket によるリアルタイム音声文字起こし
* ファイルベースの文字起こし用 REST API
* 多言語音声認識
* 高速処理のための GPU アクセラレーション
* ダークモード対応のテスト用インターフェース

## Web インターフェース

Fast Whisper には、以下の URL からアクセス可能なブラウザベースのテスト用インターフェースが付属しています。

```
http://localhost:9000/static/index.html
```

このインターフェースでは以下の操作が可能です。

* マイク入力のリアルタイムテスト
* 発話中の文字起こし結果の確認
* 文字起こし履歴のクリア
* 接続状態のモニタリング

## API の利用

### ベース URL

Fast Whisper API は以下の URL で利用できます。

```
http://localhost:9000
```

### WebSocket によるリアルタイム文字起こし

リアルタイム音声認識を行うには、以下の WebSocket エンドポイントに接続してください。

```
ws://localhost:9000/ws
```

音声データは、以下の形式で base64 エンコードしたチャンクとして送信します。

```json
{
  \"type\": \"audio\",
  \"data\": \"<base64-encoded-audio-data>\"
}
```

文字起こし結果は、処理が完了次第以下の形式で受信できます。

```json
{
  \"type\": \"transcription\",
  \"text\": \"The transcribed text will appear here.\",
  \"language\": \"en\"
}
```

### ファイル文字起こし API

POST リクエストを送信することで、音声ファイルを文字起こしできます。

```bash
curl -X 'POST' \\
  'http://localhost:9000/transcribe' \\
  -H 'accept: application/json' \\
  -H 'Content-Type: multipart/form-data' \\
  -F 'file=@your-audio-file.wav' \\
  -F 'language=en'
```

### API パラメータ

| パラメータ            | 説明                        | デフォルト |
| ---------------- | ------------------------- | ----- |
| `file`           | 文字起こし対象の音声ファイル            | 必須    |
| `language`       | 言語コード（例: `en`、`fr`）       | 自動検出  |
| `initial_prompt` | 文字起こしをガイドするためのオプションのプロンプト | なし    |

## 設定

Fast Whisper サービスは、`docker-compose.yml` ファイルで以下のオプションを使って設定されます。

```yaml
fastwhisper:
  build:
    context: ./fast-whisper
    dockerfile: Dockerfile
  container_name: fastwhisper
  runtime: nvidia
  environment:
    - NVIDIA_VISIBLE_DEVICES=all
    - MODEL_SIZE=tiny.en
    - COMPUTE_TYPE=float16
    - NUM_WORKERS=1
    - CPU_THREADS=4
  ports:
    - \"9000:9000\"
  volumes:
    - ./fast-whisper/app:/app/app
    - ./fast-whisper/models:/app/models
```

### 環境変数

| 変数             | 説明                                          | デフォルト     |
| -------------- | ------------------------------------------- | --------- |
| `MODEL_SIZE`   | Whisper モデルサイズ（tiny.en、base.en、small.en など） | `tiny.en` |
| `COMPUTE_TYPE` | GPU 演算タイプ（float16、float32、int8）             | `float16` |
| `NUM_WORKERS`  | ワーカースレッド数                                   | `1`       |
| `CPU_THREADS`  | CPU スレッド数（CPU フォールバック時）                     | `4`       |

## モデルサイズの変更

デフォルト設定では `tiny.en` モデルが使用されており、適度な精度で高速な処理が可能です。`MODEL_SIZE` 環境変数を更新することで、モデルサイズを変更できます。

```yaml
environment:
  - MODEL_SIZE=base.en
```

利用可能なモデルサイズ:

* `tiny.en`: 最速・最低精度（VRAM 約 1GB）
* `base.en`: 高速で妥当な精度（VRAM 約 1GB）
* `small.en`: 速度と精度のバランス（VRAM 約 2GB）
* `medium.en`: 良好な精度（VRAM 約 5GB）
* `large-v3`: 最高精度（VRAM 約 10GB）

## 他サービスとの連携

### デスクトップ音声入力

以下のスクリプト例のように、Fast Whisper を音声入力（Voice-to-Text）の入力手段として利用できます。

```bash
#!/bin/bash
# Record audio with silence detection
sox -d -r 16000 -c 1 -b 16 /tmp/dictation.wav silence 1 0.1 3% 1 1.0 3%

# Send to Fast Whisper for transcription
TEXT=$(curl -s -X POST \"http://localhost:9000/transcribe\" \\
  -H \"accept: application/json\" \\
  -H \"Content-Type: multipart/form-data\" \\
  -F \"file=@/tmp/dictation.wav\" | jq -r .text)

# Type the text at the current cursor position
xdotool type \"$TEXT\"
```

### Flowise との連携

HTTP リクエストノードから文字起こし API を呼び出すか、リアルタイム文字起こし用のカスタム WebSocket ノードを作成することで、Fast Whisper を Flowise ワークフローに統合できます。

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

### WebSocket 接続の問題

インターフェース上で WebSocket 接続エラーが表示される場合は、以下を確認してください。

1. Fast Whisper サービスが稼働しているかを確認: `docker ps | grep fastwhisper`
2. サービスを再起動: `docker restart fastwhisper`
3. ログでエラーを確認: `docker logs fastwhisper`
4. ご利用のブラウザが WebSocket に対応しているかを確認

### サービスが起動しない

Fast Whisper サービスの起動に失敗する場合は、以下を確認してください。

1. 利用可能な GPU メモリが十分にあるかを確認
2. Docker 用に NVIDIA ランタイムが適切に設定されているかを確認
3. `MODEL_SIZE` 環境変数をより小さいモデルに変更して試行

### 文字起こし品質が低い

文字起こしの品質が低い場合は、以下を試してください。

1. より大きなモデル（例: `MODEL_SIZE=medium.en`）を使用する
2. 音声入力の品質が良好で、背景ノイズが最小限であることを確認する
3. 専門用語のコンテキストを与えるために `initial_prompt` パラメータを利用する

### ログの確認

Fast Whisper サービスのログを確認するには、以下を実行してください。

```bash
docker logs fastwhisper
```

または、ドキュメントポータルのログビューアーをご利用ください。