# AAO から VibeVoice-ASR-Streaming を試す

## ASR サーバー

`https://gitea.example.com/swallow/asr-server` の main にある
`docs/vibevoice-streaming.md` に従い、GPU側の公式推論サービスと接続アダプターを起動します。
アダプターは `ASR_BACKEND=vibevoice-streaming`、`VIBEVOICE_URL=http://公式推論サービス:8001` を設定します。
AAO の接続先は **アダプター** の `/v1/audio/stream` です。

アダプターの compose は既定で localhost:8000 に公開します。AAO が別ホストなら、
AAO から届く内部アドレスへの公開、または内部リバースプロキシを設定してください。
ホストの通信制限を利用している場合は AAO→アダプターの通信を許可します。

## AAO の設定

1. この変更を含む AAO をビルドして起動します（通常の配布・起動手順）。
2. 管理者でログインし、設定 → メディア・文書を開きます。
3. 「リアルタイム文字起こし接続先」に `ws://ASR_HOST:8000/v1/audio/stream` を入力します。
4. 「保存して反映」を押します。再起動は不要です。
5. ワークスペースでチャットを開き、右側の文字起こしタブで、まずマイクのみの開始・停止を試します。
6. 次に PC 音声も有効にし、Windows Chrome/Edge の共有選択画面でシステム音声を含めます。

HTTPSでAAOを利用してください（localhostはブラウザの例外）。TLSをリバースプロキシで終端する場合は、
既存の `auth.secure_cookie: true` の構成を利用し、Hostを維持してWebSocket Upgradeを転送します。
ブラウザは同じAAO originにのみ接続し、ASRのURLや認証cookieを外部へ転送しません。

## 確認項目

- 入力元ごとのメーターと途中結果が動く。
- 他の AAO タブへ移動して戻っても録音を継続する。
- 停止すると末尾を確定して保存する。
- ブラウザ更新後、保存済みから開ける。本文を編集して保存できる。
- 別アカウントでは記録が見えない。
- 共有停止、ASR停止、ネットワーク切断時にエラーが表示され、未確定本文を回収できる。

両入力を有効にするとASR側では2接続を使います。複数ユーザーの利用時は
ASR側の `MAX_WS_CONNECTIONS` とGPU性能を確認してください。
録音の再開は新しいASRセッションになるため、話者番号は入力元・区間ごとの識別です。
公式モデルには会議長に応じたコンテキストと音声窓の上限があります。

## 今回の検証範囲

CPUのAPI・保存・WSテスト、模擬音声と模擬ASRを使ったChromiumの画面操作を実施しました。
GPU推論、日本語の精度、Windows実機のシステム音声共有は未実測です。

ローカルの統合チェックは、サーバーとUIのビルド後に `npm run check:transcription` で実行できます。
実際のブラウザと音声処理を使い、模擬ASRへの送信、設定変更、画面遷移、保存・再読込を確認します。
外部ASRへ音声を送信するテストではありません。

## TranslateGemma の逐次翻訳を追加する

翻訳は ASR とは別のサーバーです。未設定でも文字起こしを利用できます。
以下は [vLLM 公式 TranslateGemma recipe](https://docs.vllm.ai/projects/recipes/en/stable/Google/TranslateGemma.html)
の最適化モデルを使う構成例です。Google の元モデルを通常のチャットモデルとして起動する手順とは異なります。
GPU のドライバー・メモリー容量に適した vLLM バージョンを選び、必要なモデルの利用条件を確認してください。

```bash
docker run --rm --gpus all --ipc=host \
  -p 8002:8002 \
  -v "$HOME/.cache/huggingface:/root/.cache/huggingface" \
  vllm/vllm-openai:v0.14.1-cu130 \
  Infomaniak-AI/vllm-translategemma-4b-it \
  --served-model-name translategemma-4b-it \
  --host 0.0.0.0 --port 8002 \
  --gpu-memory-utilization 0.8
```

ASR と同じ GPU を使う場合は、両モデルの必要メモリーを合わせて調整してください。
例のポートは AAO が接続できる内部ネットワークへ公開し、必要に応じてサーバー側に API キー認証を設定します。

管理者は **設定 → メディア・文書 → 文字起こしの翻訳（TranslateGemma）** に入力して保存します。

| 設定 | 例 |
| --- | --- |
| 翻訳サーバー URL | `http://GPU_HOST:8002/v1` |
| 翻訳モデル | `translategemma-4b-it`（served-model-name と一致） |
| 翻訳 API キー | サーバーで認証を設定した場合のキー |
| 翻訳の送信形式 | **vLLM 向け区切り文字形式** |
| 翻訳のタイムアウト | `120` 秒 |

vLLM recipe の形式では、AAO が `/chat/completions` に以下の user メッセージを送信します。

```json
{"role":"user","content":"<<<source>>>en<<<target>>>ja<<<text>>>Hello."}
```

**公式モデル向け構造化形式** は、次の content 配列を受け付ける専用サーバーを用意した場合だけ選びます。
標準の vLLM/OpenAI チャット API がこの独自フィールドを扱えるとは限りません。

```json
{"role":"user","content":[{"type":"text","source_lang_code":"en","target_lang_code":"ja","text":"Hello."}]}
```

vLLM 向け形式では、モデル側テンプレートの予約文字列 `<<<custom>>>` を含む原文は、
意図せず通常プロンプトへ切り替わらないよう翻訳を拒否します。原文は保存でき、構造化形式ではこの制限はありません。

一般的なチャット用 system 指示は追加しません。ブラウザーから翻訳サーバーへ直接接続せず、
AAO の認証済み API を経由します。一般ユーザーには接続 URL と API キーを公開しません。

### 使い方と確認

1. 文字起こしで **逐次翻訳** を ON にし、原文言語と翻訳先言語を選びます。初期値は英語 → 日本語です。
2. 原文と訳文がブロックごとに対応し、翻訳待ち・翻訳中・翻訳済みが表示されることを確認します。
3. 原文を編集したとき、古い訳が更新待ちと表示され、最新の原文に対応する訳へ置き換わることを確認します。
4. 翻訳に失敗した場合は **翻訳を再試行** を使います。原文の保存・ダウンロードは引き続き利用できます。
5. 録音停止時は、その時点の原文と訳を保存します。停止後に届いた訳は未保存となるため、**保存 / 再試行** で保存してください。
6. 保存済みを開いて原文と訳を確認し、TXT / JSON に対応関係が含まれることを確認します。保存済みを開くだけでは翻訳を再開しません。

GPU 上の TranslateGemma 推論、翻訳精度、同時 ASR 利用時の速度とメモリー消費は未実測です。
模擬翻訳サーバーの検証結果と実機の性能を区別し、利用環境で確認してください。

逐次処理は同時1件・依頼開始の間隔は最低2.5秒です。途中原文は1.5秒変化しないブロックを対象にし、
録音停止時は安定待ちを省略します。ブロックは最大400文字、変更のない訳は再利用します。
設定識別子はDBに保持した秘密値で生成するため、AAOの再起動だけでは再翻訳しません。


## チャット保存の確認

文字起こしはグローバルナビゲーションではなく、各チャットの右側タブにあります。
`?page=transcription` の旧URLはワークスペースへ移動し、新しい入口を案内します。

- チャットAで開始し、Bや設定へ移動しても、上部の帯がAの録音中と示すことを確認します。
- 帯からAに戻って停止し、Aの履歴に保存され、Bの履歴に現れないことを確認します。
- Aのワークスペース内の `output/transcriptions/<記録ID>.txt` と `.json` に原文と訳が出力されることを確認します。
- 旧未関連の記録はチャットの文字起こしタブから開き、現在チャットへの保存で関連づけます。
- ファイル出力に失敗した場合は「履歴には保存済み」とファイル保存エラーが区別され、再試行できることを確認します。

ファイルはチャット／ワークスペースの既存アクセス権に従います。読み取り専用のチャットには保存できません。
録音中のチャットを切り替えても保存先は変わりません。この変更に音声コマンドやチャット自動送信は含まれません。