Create README.md

README.md

@@ -0,0 +1,280 @@
+---
+language:
+- ja
+base_model:
+- webbigdata/VoiceCore
+---
+
+# VoiceCore GGUF - 次世代 日本語Voice AI Agent用モデル（量子化版）
+
+これは[webbigdata/VoiceCore](https://huggingface.co/webbigdata/VoiceCore)のGGUF（量子化）版です。  
+Mac環境や低スペックPCでも手軽に動作させることができるように最適化されています。  
+
+## GGUFとは？
+
+GGUF（GPT-Generated Unified Format）は、大規模言語モデルを効率的に配布・実行するためのファイルフォーマットです。
+llama.cppというGPUがない環境でもCPU環境でもLLMを動かすため純粋なC++プログラムとして開発がスタートしましたが、移植性が高いため、Macやスマートフォンなどでも動作するようになっています。  
+
+### 主な特徴
+- **軽量化**: モデルサイズを大幅に削減（元の50%以下に）
+- **高速起動**: モデルの読み込みが高速
+- **メモリ効率**: RAM使用量を削減
+- **互換性**: CPU/GPU両方で動作可能
+- **簡単実行**: 様々な環境に移植されており特別な環境構築が不要
+
+### 量子化について
+量子化とは、モデルの重みを低精度（例：32bit→4bit）に変換する技術です。これにより：
+- ファイルサイズが削減
+- 必要メモリが減少
+- 推論速度が向上
+- わずかな精度低下と引き換えに実用性が向上
+
+## 提供モデル
+
+| モデル名 | サイズ | 特徴 | 推奨用途 |
+|---------|--------|------|----------|
+| VoiceCore-BF16.gguf | 6.61 GB | 最高品質、元モデルと同等の精度 | 高品質が必要な場合 |
+| VoiceCore-Q4_K-f16.gguf | 2.66 GB | バランス型、実用的な精度 | 通常使用（要注意） |
+
+⚠️ **重要な注意事項**: VoiceCoreは量子化に敏感なモデルです。Q4_K-f16以下の量子化レベルでは音声ファイルの作成に失敗する事がある事がわかっています。安定性を重視する場合はBF16版の使用を推奨します。
+
+## システム概要
+
+```mermaid
+graph LR
+    A[ユーザー入力] --> B[llama.cpp サーバー]
+    B --> C[VoiceCore GGUF]
+    C --> D[音声トークン生成]
+    D --> E[SNACデコーダー]
+    E --> F[音声ファイル/リアルタイム再生]
+```
+
+## セットアップガイド（Mac/初心者向け）
+
+### 1. 必要なツールのインストール
+
+```bash
+# Homebrewのインストール（まだの場合）
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+
+# 必要なパッケージのインストール
+brew install cmake
+brew install python@3.11
+
+# Pythonライブラリのインストール
+pip3 install torch snac numpy httpx pyaudio scipy
+```
+
+### 2. llama.cppのセットアップ
+
+```bash
+# llama.cppのクローン
+git clone https://github.com/ggerganov/llama.cpp
+cd llama.cpp
+
+# ビルド（Macの場合）
+make
+
+# Metal（Mac GPU）を使用する場合
+make LLAMA_METAL=1
+```
+
+### 3. モデルのダウンロード
+
+[dahara1/orpheus-3b-0.1-ft_gguf](https://huggingface.co/webbigdata/VoiceCore_gguf)から必要なモデルをダウンロードしてください。
+
+### 4. サーバーの起動
+
+```bash
+# 基本的な起動方法
+.//llama-server \
+  -m path/to/VoiceCore-BF16.gguf \
+  --prio 3 \
+  -c 2048 \
+  -e \
+  -n -2 \
+  -fa \
+  -ngl 99 \
+  -v \
+  --port 8080 \
+  --host 0.0.0.0 \
+  --no-webui  
+nblはgpu環境でgpuメモリに収まる範囲で指定  
+faはフラッシュアテンション有りでコンパイルした時のみ利用  
+
+# Macでメタル（GPU）を使用する場合
+./llama-server \
+  -m path/to/VoiceCore-BF16.gguf \
+  --prio 3 \
+  -c 2048 \
+  -e \
+  -n -2 \
+  -fa \
+  -ngl 1 \  # Macの場合は1を推奨
+  -v \
+  --port 8080 \
+  --host 0.0.0.0 \
+  --no-webui
+```
+
+### 5. 音声生成の実行
+
+シンプルなサンプルスクリプト（simple_voice.py）:
+
+```python
+import asyncio
+import httpx
+import json
+import re
+import torch
+from snac import SNAC
+import scipy.io.wavfile as wavfile
+import numpy as np
+
+async def generate_voice(prompt, output_file="output.wav"):
+    """シンプルな音声生成関数"""
+    
+    # SNACモデルの読み込み
+    print("SNACモデルを読み込んでいます...")
+    snac_model = SNAC.from_pretrained("hubertsiuzdak/snac_24khz")
+    snac_model.to("cpu")
+    
+    # サーバーにリクエスト送信
+    payload = {
+        "prompt": prompt,
+        "temperature": 0.8,
+        "top_p": 0.95,
+        "n_predict": 2048
+    }
+    
+    collected_tokens = []
+    
+    async with httpx.AsyncClient(timeout=None) as client:
+        response = await client.post(
+            "http://localhost:8080/completion",
+            json=payload,
+            headers={"Accept": "application/x-ndjson"}
+        )
+        
+        # トークンの収集
+        async for line in response.aiter_text():
+            if line.strip():
+                try:
+                    data = json.loads(line)
+                    if "content" in data:
+                        matches = re.findall(r'<custom_token_(\d+)>', data["content"])
+                        for match in matches:
+                            token_id = 128256 + int(match)
+                            collected_tokens.append(token_id)
+                except:
+                    pass
+    
+    # 音声の生成
+    if collected_tokens:
+        # 7の倍数に調整
+        code_length = (len(collected_tokens) // 7) * 7
+        tokens = collected_tokens[:code_length]
+        
+        # コードの再分配
+        codes = redistribute_codes(tokens)
+        
+        # 音声デコード
+        with torch.inference_mode():
+            audio_hat = snac_model.decode(codes)
+        
+        audio_np = audio_hat.detach().squeeze().cpu().numpy()
+        
+        # WAVファイルとして保存
+        wavfile.write(output_file, 24000, audio_np)
+        print(f"音声を {output_file} に保存しました。")
+
+def redistribute_codes(tokens):
+    """トークンをSNACコード形式に変換"""
+    code_list = [t - 128266 for t in tokens]
+    
+    layer_1, layer_2, layer_3 = [], [], []
+    
+    for i in range(len(code_list) // 7):
+        layer_1.append(code_list[7*i])
+        layer_2.append(code_list[7*i+1]-4096)
+        layer_3.append(code_list[7*i+2]-(2*4096))
+        layer_3.append(code_list[7*i+3]-(3*4096))
+        layer_2.append(code_list[7*i+4]-(4*4096))
+        layer_3.append(code_list[7*i+5]-(5*4096))
+        layer_3.append(code_list[7*i+6]-(6*4096))
+    
+    return [
+        torch.tensor(layer_1).unsqueeze(0),
+        torch.tensor(layer_2).unsqueeze(0),
+        torch.tensor(layer_3).unsqueeze(0)
+    ]
+
+# 使用例
+async def main():
+    # 松風さんの声で挨拶
+    prompt = "<custom_token_3><|begin_of_text|>matsukaze_male[neutral]: こんにちは！よろしくお願いします！<|eot_id|><custom_token_4><custom_token_5><custom_token_1>"
+    await generate_voice(prompt, "greeting.wav")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## その他のツールでの利用方法
+
+### Ollama
+[Ollama](https://ollama.ai/)は、大規模言語モデルをローカルで簡単に実行できるツールです。
+
+**特徴:**
+- ワンコマンドでモデルの実行が可能
+- Docker風のシンプルなインターフェース
+- 自動的な量子化対応
+
+**注意:** 現時点でOllamaはカスタムトークナイザーに対応していないため、VoiceCoreの音声生成機能は制限される可能性があります。
+
+### LM Studio
+[LM Studio](https://lmstudio.ai/)は、GUIベースでLLMを実行できるツールです。
+
+**特徴:**
+- 直感的なGUIインターフェース
+- モデルの自動ダウンロード機能
+- チャット履歴の管理
+
+**使用方法:**
+1. LM Studioをダウンロード・インストール
+2. モデルファイル（.gguf）をインポート
+3. 設定でコンテキストサイズを2048に設定
+4. APIサーバーモードで起動
+
+### llama.cpp Python バインディング
+```bash
+pip install llama-cpp-python
+```
+
+Pythonから直接モデルを使用できます。詳細は[公式ドキュメント](https://github.com/abetlen/llama-cpp-python)を参照してください。
+
+## トラブルシューティング
+
+### よくある問題と解決方法
+
+1. **音声生成に失敗する**
+   - Q4_K量子化版を使用している場合は、BF16版に切り替えてください
+   - メモリ不足の場合は、コンテキストサイズを小さくしてください
+
+2. **サーバーが起動しない**
+   - ポート8080が使用中でないか確認してください
+   - モデルファイルのパスが正しいか確認してください
+
+3. **生成速度が遅い**
+   - CPU環境での推論実行は時間がかかります。[webbigdata/VoiceCore](https://huggingface.co/webbigdata/VoiceCore)のサンプルColabスクリプトの利用も検討してください
+   - GPU（Metal）を有効にしているか確認してください
+   - `-ngl`パラメータを調整してください
+
+## ライセンス
+
+- モデル: [LLAMA 3.2 COMMUNITY LICENSE](https://huggingface.co/meta-llama/Llama-3.2-1B/blob/main/LICENSE.txt)または[Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0)
+- 音声データ: 各音声提供者のライセンスに従ってください（[元モデルのライセンス情報](https://huggingface.co/webbigdata/VoiceCore#ディフォルト利用可能な音声の提供元とそのライセンス-default-voice-providers-and-their-licenses)を参照）
+
+## 謝辞
+
+- オリジナルモデル: [webbigdata/VoiceCore](https://huggingface.co/webbigdata/VoiceCore)
+- ベースモデル: [canopylabs/orpheus-tts](https://huggingface.co/collections/canopylabs/orpheus-tts-67d9ea3f6c05a941c06ad9d2)