Update: Readme.md

Aivis-Project · Oct 28, 2024 · 14eaecf · 14eaecf
1 parent 328181e
commit 14eaecf
Show file tree

Hide file tree

Showing 2 changed files with 53 additions and 3 deletions.
diff --git a/Readme.md b/Readme.md
@@ -1,8 +1,15 @@
 
 # aivmlib
 
+![PyPI version](https://badge.fury.io/py/aivmlib.svg)
+![Python Versions](https://img.shields.io/pypi/pyversions/aivmlib.svg)
+![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)
+
 💠 **aivmlib**: **Ai**vis **V**oice **M**odel File (.aivm/.aivmx) Utility **Lib**rary
 
+-----
+<br>
+
 **AIVM** (**Ai**vis **V**oice **M**odel) / **AIVMX** (**Ai**vis **V**oice **M**odel for ONN**X**) は、**学習済みモデル・ハイパーパラメータ・スタイルベクトル・話者メタデータ（名前・概要・ライセンス・アイコン・ボイスサンプル など）を 1 つのファイルにギュッとまとめた、AI 音声合成モデル用オープンファイルフォーマット**です。
 
 > [!NOTE]  
@@ -39,19 +46,31 @@
     - [Q. AIVM / AIVMX ファイルを既存のツールで読み込むことはできますか？](#q-aivm--aivmx-ファイルを既存のツールで読み込むことはできますか)
     - [Q. 既存の AI 音声合成モデルを AIVM / AIVMX に変換するにはどうすればよいですか？](#q-既存の-ai-音声合成モデルを-aivm--aivmx-に変換するにはどうすればよいですか)
     - [Q. AIVM マニフェストのバージョン管理はどのように行われますか？](#q-aivm-マニフェストのバージョン管理はどのように行われますか)
+    - [Q. aivmlib と aivmlib-web の違いはなんですか？](#q-aivmlib-と-aivmlib-web-の違いはなんですか)
     - [Q. 新しいモデルアーキテクチャのサポートを追加するにはどうすればよいですか？](#q-新しいモデルアーキテクチャのサポートを追加するにはどうすればよいですか)
     - [Q. ライセンス情報はどのように記述すべきですか？](#q-ライセンス情報はどのように記述すべきですか)
     - [Q. 画像・音声データのサイズ制限はありますか？](#q-画像音声データのサイズ制限はありますか)
     - [Q. メタデータは手動で編集できますか？](#q-メタデータは手動で編集できますか)
 
 ## Installation
 
-pip でインストールすると、コマンドラインツール `aivmlib` も自動的にインストールされます。
+pip でインストールすると、コマンドラインツール `aivmlib` も自動的にインストールされます。  
+Python 3.11 以上が必要です。
 
 ```bash
 pip install aivmlib
 ```
 
+開発時は Poetry を利用しています。
+
+```bash
+pip install poetry
+git clone https://github.com/Aivis-Project/aivmlib.git
+cd aivmlib
+poetry install --with dev
+poetry run aivmlib --help
+```
+
 ## Usage
 
 以下に CLI ツール自体の使い方を示します。
@@ -157,6 +176,8 @@ $ aivmlib create-aivmx --help
 ╰───────────────────────────────────────────────────────────────────────────────────╯
 ```
 
+以下にコマンドの実行例を示します。
+
 ```bash
 # Safetensors 形式で保存された "Style-Bert-VITS2 (JP-Extra)" モデルアーキテクチャの学習済みモデルから AIVM ファイルを生成
 # .safetensors と同じディレクトリに config.json と style_vectors.npy があることが前提
@@ -207,8 +228,12 @@ $ aivmlib show-metadata ./output.aivmx
 
 学習済み AI 音声合成モデルと、その利用に必要な各種メタデータを単一ファイルにまとめることで、**ファイルの散逸や混乱を防ぎ、モデルの利用や共有を容易にすることを目的としている。**
 
+> [!TIP]
+> 単一ファイルにまとめることで、AIVM / AIVMX ファイルをダウンロードして所定のフォルダに配置するだけで、対応ソフトウェアですぐに音声合成モデルを利用できるようになるといった、シンプルな運用が可能になる。  
+> 圧縮ファイルではないため、展開の必要がないのもメリット。
+
 **AIVM 仕様は、音声合成モデルのモデルアーキテクチャに依存しない。**  
-異なるモデルアーキテクチャの音声合成モデルを共通のファイルフォーマットで扱えるよう、拡張性や汎用性を考慮して設計されている。
+異なるモデルアーキテクチャの音声合成モデルを共通のファイルフォーマットで扱えるよう、将来的な拡張性や汎用性を考慮して設計されている。
 
 大元の学習済みモデルが単一の Safetensors または ONNX 形式で保存されているならば、原則どのようなモデルアーキテクチャであっても、メタデータを追加して AIVM / AIVMX ファイルを生成できる。  
 設計にあたっては、変換処理を挟むことなく通常の Safetensors ファイルや ONNX ファイルとしてロードできるよう、既存エコシステムとの互換性を重視した。
@@ -413,7 +438,7 @@ class AivmManifestVoiceSample(BaseModel):
 
 - **AIVM (.aivm): PyTorch などの機械学習フレームワークで直接利用できる [Safetensors](https://huggingface.co/docs/safetensors/index) 形式をベースとしたフォーマットです。**
   - 研究開発やモデルの Fine-Tuning 、モデルマージによる新たな声質生成などに適しています。
-  - 一般に、NVIDIA GPU での高速推論に特化しています (CUDA / TensorRT など) 。
+  - 一般に、NVIDIA GPU (CUDA / TensorRT など) での高速推論に特化しています。
   - PyTorch には .pth (pickle) 形式もありますが、Python コードをそのままシリアライズする pickle の特性上、任意コードの実行が可能な脆弱性があります。したがって、AIVM 仕様では対応予定はありません。
 - **AIVMX (.aivmx): 様々な環境で高速な推論が可能な [ONNX](https://onnx.ai/) 形式をベースとしたフォーマットです。**
   - 特に CPU での推論や、エッジデバイスでの利用に適しています。また Web ブラウザでも推論可能です。
@@ -449,6 +474,29 @@ AIVM メタデータは既存のモデルフォーマット仕様で定められ
 
 現在は 1.0 が最新です。
 
+### Q. aivmlib と [aivmlib-web](https://github.com/Aivis-Project/aivmlib-web) の違いはなんですか？
+
+**A. aivmlib と aivmlib-web は、同じ AIVM 仕様を異なる言語/動作環境向けに実装したライブラリになります。**
+
+- **aivmlib**: Python 実装。デスクトップアプリケーションやサーバーサイドでの利用を想定しています。
+  - NVIDIA GPU 搭載の高火力サーバーで運用するケースでは、モデルアーキテクチャにもよりますが、AIVMX (ONNX) 形式よりも AIVM (Safetensors) 形式の方が高速な可能性もあります。
+  - aivmlib は aivmlib-web のリファレンス実装でもあります。
+    - 新しい仕様を実装する際は、まず aivmlib に実装してから、aivmlib-web に移植する形をとっています。
+- **aivmlib-web**: TypeScript 実装。Web ブラウザ上での利用を想定しています。
+  - [AIVM Generator](https://aivm-generator.aivis-project.com/) や Web ブラウザ上で音声合成を行うサービスで使うことを前提に設計・開発されています。
+  - AIVM と AIVMX 両方のファイルを扱えます（主に AIVM Generator 向け）。
+    - Web ブラウザで推論可能なモデルフォーマットは基本的に ONNX 形式に限られるため、実運用上は AIVMX ファイルのみ扱うケースがほとんどのはずです。
+  - Python の `BinaryIO` が JavaScript Web API の `File` (Blob) になるなど、Web ブラウザの特性に応じた実装の違いはありますが、基本的な API 設計は aivmlib と同様です。
+    - Node.js や Deno などのサーバーサイド JavaScript 環境への対応予定はありません。
+
+> [!TIP]
+> 現時点で、aivmlib / [aivmlib-web](https://github.com/Aivis-Project/aivmlib-web) 以外に公式でメンテナンスされる AIVM 仕様対応ライブラリはありません。  
+> 今後、サードパーティーの他言語向けライブラリが登場する可能性はあります。
+
+> [!IMPORTANT]
+> **新しいモデルアーキテクチャのサポートを追加する際は、aivmlib と [aivmlib-web](https://github.com/Aivis-Project/aivmlib-web) の両方に実装を追加する必要があります。**  
+> AIVM Generator は aivmlib-web を使用しているため、エンドユーザーに新機能を提供するためには両方のライブラリをアップデートする必要があります。
+
 ### Q. 新しいモデルアーキテクチャのサポートを追加するにはどうすればよいですか？
 
 **A. AIVM 仕様はモデルアーキテクチャの実装詳細を規定しないため、比較的容易に新しいモデルアーキテクチャを追加できます。**

diff --git a/pyproject.toml b/pyproject.toml
@@ -15,6 +15,8 @@ python = ">=3.11"
 pydantic = ">=2.4.0"
 typer = {extras = ["all"], version = ">=0.9.0"}
 
+[tool.poetry.group.dev.dependencies]
+
 [tool.poetry.scripts]
 aivmlib = "aivmlib.__main__:app"