> 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
```

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.digitalhumans.jp/dev/miniprem/services/whisper.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.