Skip to content

Commit

Permalink
Add: FAQ を追加
Browse files Browse the repository at this point in the history
  • Loading branch information
@tsukumijima
tsukumijima committed Oct 28, 2024
1 parent 7ced0a7 commit 54b6c6c
Showing 1 changed file with 26 additions and 25 deletions.
51 changes: 26 additions & 25 deletions Readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@

💠 **aivmlib**: **Ai**vis **V**oice **M**odel File (.aivm/.aivmx) Utility **Lib**rary

**AIVM** (**Ai**vis **V**oice **M**odel) / **AIVMX** (**Ai**vis **V**oice **M**odel for ONN**X**) は、学習済みモデル・ハイパーパラメータ・スタイルベクトル・話者メタデータ（名前・概要・ライセンス・アイコン・ボイスサンプル など）を 1 つのファイルにギュッとまとめた、AI 音声合成モデル用オープンファイルフォーマットです。
**AIVM** (**Ai**vis **V**oice **M**odel) / **AIVMX** (**Ai**vis **V**oice **M**odel for ONN**X**) は、**学習済みモデル・ハイパーパラメータ・スタイルベクトル・話者メタデータ（名前・概要・ライセンス・アイコン・ボイスサンプル など）を 1 つのファイルにギュッとまとめた、AI 音声合成モデル用オープンファイルフォーマット**です。

> [!NOTE]
> **「AIVM」は、AIVM / AIVMX 両方のフォーマット仕様・メタデータ仕様の総称でもあります。**
Expand All @@ -12,12 +12,12 @@
[AivisSpeech](https://github.com/Aivis-Project/AivisSpeech) / [AivisSpeech-Engine](https://github.com/Aivis-Project/AivisSpeech-Engine) をはじめとした AIVM 仕様に対応するソフトウェアに AIVM / AIVMX ファイルを追加することで、AI 音声合成モデルを簡単に利用できます。

**aivmlib では、AIVM / AIVMX ファイル内のメタデータを読み書きするためのユーティリティを提供します。**
この Readme の後半では、aivmlib で対応している各 AIVM 仕様についても説明しています。
**aivmlib / [aivmlib-web](https://github.com/aivis-project/aivmlib-web) では、AIVM / AIVMX ファイル内のメタデータを読み書きするためのユーティリティを提供します。**
この Readme の後半では、aivmlib / aivmlib-web で対応している各 AIVM 仕様についても説明しています。

> [!TIP]
> **[AIVM Generator](https://aivm-generator.aivis-project.com/) では、ブラウザ上の GUI で AIVM / AIVMX ファイルを生成・編集できます。**
> 機能的には aivmlib の上位互換です。手動で AIVM / AIVMX ファイルを生成・編集する際は AIVM Generator の利用をおすすめします。
> **[AIVM Generator](https://aivm-generator.aivis-project.com/) では、ブラウザ上の GUI でかんたんに AIVM / AIVMX ファイルを生成・編集できます。**
> 手動で AIVM / AIVMX ファイルを生成・編集する際は AIVM Generator の利用をおすすめします。
- [aivmlib](#aivmlib)
- [Installation](#installation)
Expand Down Expand Up @@ -184,8 +184,8 @@ $ aivmlib show-metadata ./output.aivmx
> **ライブラリとしての使い方は、[`__main__.py`](aivmlib/__main__.py) に実装されている CLI ツールの実装を参照してください。**
> [!IMPORTANT]
> **aivmlib は、AIVM ファイルフォーマットの読み込み/書き込み機能のみを有するライブラリです。**
> 各モデルアーキテクチャごとの AI 音声合成モデルの推論ロジックや、aivmlib から取得したデータをどのようにユーザーに提示するかは、すべてライブラリの利用者に委ねられています。
> **aivmlib / [aivmlib-web](https://github.com/aivis-project/aivmlib-web) は、AIVM ファイルフォーマットの読み込み/書き込み機能のみを有するライブラリです。**
> 各モデルアーキテクチャごとの AI 音声合成モデルの推論ロジックや、aivmlib / aivmlib-web から取得したデータをどのようにユーザーに提示するかは、すべてライブラリの利用者に委ねられています。
## License

Expand Down Expand Up @@ -416,7 +416,7 @@ class AivmManifestVoiceSample(BaseModel):
- 一般に、NVIDIA GPU での高速推論に特化しています (CUDA / TensorRT など) 。
- PyTorch には .pth (pickle) 形式もありますが、Python コードをそのままシリアライズする pickle の特性上、任意コードの実行が可能な脆弱性があります。したがって、AIVM 仕様では対応予定はありません。
- **AIVMX (.aivmx): 様々な環境で高速な推論が可能な [ONNX](https://onnx.ai/) 形式をベースとしたフォーマットです。**
- 特に CPU での推論や、エッジデバイスでの利用に適しています。
- 特に CPU での推論や、エッジデバイスでの利用に適しています。また Web ブラウザでも推論可能です。
- 2024 年時点では、一般的な PC ユーザーの多くは NVIDIA GPU や NPU を搭載していない PC を使用しています。
- ONNX 形式は CPU での推論性能に優れているため、GPU や NPU がなくても快適に音声合成を実行できます。
- さらに ONNX 形式は DirectML 推論をサポートしており、Windows では AMD Radeon / Intel Arc GPU でも高速推論が可能です。
Expand All @@ -427,25 +427,25 @@ class AivmManifestVoiceSample(BaseModel):

**A. はい、可能です。**

AIVM は Safetensors 形式の、AIVMX は ONNX 形式の拡張仕様として設計されているため、それぞれ通常の Safetensors ファイル・ONNX ファイルとして読み込むことができます。

AIVM は Safetensors 形式の、AIVMX は ONNX 形式の拡張仕様として設計されているため、それぞれ通常の Safetensors ファイル・ONNX ファイルとして読み込むことができます。
AIVM メタデータは既存のモデルフォーマット仕様で定められたメタデータ領域に格納されているため、既存のツールの動作に影響を与えることはありません。

### Q. 既存の AI 音声合成モデルを AIVM / AIVMX に変換するにはどうすればよいですか？

**A. 以下の2つの方法があります。**

1. **[AIVM Generator](https://aivm-generator.aivis-project.com/) (推奨)**: ブラウザ上の GUI で簡単に AIVM / AIVMX ファイルを生成・編集できます。
2. **aivmlib**: このライブラリが提供する CLI ツールを使用して、コマンドラインから AIVM / AIVMX ファイルを生成できます。
2. **aivmlib**: このライブラリが提供する CLI ツールを使用して、コマンドラインから最低限のメタデータが設定された AIVM / AIVMX ファイルを生成できます。
- ハイパーパラメータなどから変換した最低限のメタデータのみ設定されているため、実際に配布する際は別途メタデータを編集する必要があります。

なお、変換元のモデルは単一の Safetensors または ONNX 形式で保存されている必要があります。

### Q. AIVM マニフェストのバージョン管理はどのように行われますか？

**A. AIVM マニフェストのバージョン管理は以下の方針で行われます。**

- マイナーバージョンアップ (ex: 1.0 -> 1.1) : 新しいフィールドの追加など、後方互換性が保たれた変更
- メジャーバージョンアップ (ex: 1.1 -> 2.0) : 既存フィールドの削除や構造変更など、後方互換性のない変更
- **マイナーバージョンアップ (ex: 1.0 -> 1.1)**: 新しいフィールドの追加など、後方互換性が保たれた変更
- **メジャーバージョンアップ (ex: 1.1 -> 2.0)**: 既存フィールドの削除や構造変更など、後方互換性のない変更

現在は 1.0 が最新です。

Expand All @@ -457,33 +457,33 @@ AIVM メタデータは既存のモデルフォーマット仕様で定められ
- その際、なるべく同時に `generate_aivm_metadata()` 関数に新しいモデルアーキテクチャのサポートを追加してください。
2. **モデルアーキテクチャ固有のメタデータの追加が必要な場合**: `aivm_style_vectors` フィールドのように、AIVM マニフェストとは別のメタデータキーを新設する仕様を策定した上で、プルリクエストを送信してください。
- なるべく aivmlib (Python) と [aivmlib-web](https://github.com/Aivis-Project/aivmlib-web) (TypeScript Web) の両方でサポートできる仕様が望ましいです。
- 当該モデルアーキテクチャが Python での推論しか対応していない場合、推論時のみ必要なメタデータに関しては、aivmlib-web で対応可能な仕様である必要はありません。
- 当該モデルアーキテクチャが Web で推論可能な ONNX 形式に対応していない場合、推論時のみ必要なメタデータに関しては、aivmlib-web で対応可能な仕様である必要はありません。
- AIVM マニフェストに追加するメタデータは、aivmlib-web でもサポートできるものでなければなりません（後述）。

> [!IMPORTANT]
> [!IMPORTANT]
> **提出される AIVM マニフェスト仕様は、技術的に aivmlib (Python) と [aivmlib-web](https://github.com/Aivis-Project/aivmlib-web) (TypeScript Web) の両方でサポートできるものでなければなりません。**
> AIVM Generator の内部では aivmlib-web が利用されています。
> **aivmlib にサポートを追加したら、aivmlib-web にも同様にサポートを追加してください。**
> [!NOTE]
> **AIVM マニフェストは、モデルアーキテクチャに依存しない共通のメタデータのみを定義する設計としています。**
> 実装固有のハイパーパラメータは、`aivm_hyper_parameters` フィールドに格納してください。
> ハイパーパラメータの Pydantic スキーマ定義の追加も受け付けます。現在は `Style-Bert-VITS2` 系アーキテクチャのハイパーパラメータのスキーマのみが定義されています。
> [!IMPORTANT]
> **AIVM 仕様のリファレンスライブラリには、aivmlib だけでなく [aivmlib-web](https://github.com/Aivis-Project/aivmlib-web) もあることに注意が必要です。** AIVM Generator の内部では aivmlib-web が利用されています。
> **提出される AIVM マニフェスト仕様は、技術的に aivmlib (Python) と aivmlib-web (TypeScript Web) の両方でサポートできるものでなければなりません。**
> aivmlib にサポートを追加したら、aivmlib-web にも同様にサポートを追加してください。
> [!NOTE]
> 当然ですが、AIVM / AIVMX への変換元モデルは単一の Safetensors または ONNX 形式で保存されている必要があります。
> **したがって、複数のモデルファイルにまたがるモデルアーキテクチャはサポートされていません。**
> モデルファイルを一つに結合する、不要なモデルファイルを削るなどの対応をご検討ください。
### Q. ライセンス情報はどのように記述すべきですか？

**A. ライセンス情報は Markdown 形式またはプレーンテキストで、ライセンスの全文を AIVM / AIVMX ファイルに直接埋め込む形で設定します。**
**A. ライセンス情報は Markdown 形式またはプレーンテキストで、ライセンスの全文のコピーを AIVM / AIVMX ファイルに直接埋め込む形で設定します。**

URL 指定ではなくライセンス全文を埋め込む理由は以下の通りです。

- URL の永続性が保証できない
- URL だとライセンス名が分からない
- カスタムライセンスを規定するのが難しい
- URL だけだとライセンス名が分からない
- カスタムライセンスの規定が難しい
- AIVM 仕様対応ソフトウェアでライセンス情報を直接表示できる必要がある

### Q. 画像・音声データのサイズ制限はありますか？
Expand All @@ -493,13 +493,14 @@ URL 指定ではなくライセンス全文を埋め込む理由は以下の通
- 画像ファイル: 512×512 の JPEG または PNG (JPEG を推奨)
- 音声ファイル: WAV (PCM 16bit) または M4A (AAC-LC) (M4A を推奨)

リファレンス実装である [AIVM Generator](https://aivm-generator.aivis-project.com/) では、これらのガイドラインに従って適切なサイズ最適化を行っています。
> [!TIP]
> リファレンス実装である [AIVM Generator](https://aivm-generator.aivis-project.com/) では、これらのガイドラインに従って適切なサイズ最適化を行っています。
### Q. メタデータは手動で編集できますか？

**A. メタデータは直接バイナリに埋め込まれるため、手動編集は推奨されません。**
エンドユーザーの方は [AIVM Generator](https://aivm-generator.aivis-project.com/) をご利用ください。

> [!TIP]
> 開発者は、aivmlib / [aivmlib-web](https://github.com/Aivis-Project/aivmlib-web) を使用して独自のアプリケーションを作成できます。
> **開発者は、aivmlib / [aivmlib-web](https://github.com/Aivis-Project/aivmlib-web) を使用して独自のアプリケーションを作成できます。**
> aivmlib CLI は、最低限のメタデータを持つ AIVM / AIVMX ファイルの生成と、メタデータの確認機能のみを提供します。

0 comments on commit 54b6c6c

Please sign in to comment.