README.md

---
language:
- ja
base_model:
- webbigdata/VoiceCore
---

# VoiceCore GGUF - 次世代 日本語Voice AI Agent用モデル（gguf量子化版）

[webbigdata/VoiceCore](https://huggingface.co/webbigdata/VoiceCore)はAIが自然な日本語を発声可能にする商用利用可能なVoice AI Agentモデルです。  
本リポジトリはVoiceCoreのGGUF（量子化）版です。Mac環境や低スペックPCでも手軽に動作させることができるように最適化されています。  

## GGUFとは？

GGUF（GPT-Generated Unified Format）は、大規模言語モデルを効率的に配布・実行するためのファイルフォーマットです。  
元々は「NvidiaのGPUがない環境でもCPUでLLMを動かすための純粋なC++ツール」として開発がスタートした[llama.cpp](https://github.com/ggml-org/llama.cpp)というプロジェクト用のフォーマットでしたが、移植性が高いため、Macやスマートフォン、GPU環境にも移植されています。  

### 主な特徴
- **軽量化**: モデルサイズを大幅に削減（元の50%以下に）
- **高速起動**: モデルの読み込みが高速
- **メモリ効率**: RAM使用量を削減
- **互換性**: CPU/GPU両方で動作可能
- **簡単実行**: 様々な環境に移植されており特別な環境構築が不要

### 量子化について
量子化とは、モデルの重みを低精度（例：32bit→4bit）に変換する技術です。これにより：
- ファイルサイズが削減
- 必要メモリが減少
- 推論速度が向上
- わずかな精度低下と引き換えに実用性が向上

## 提供モデル

| モデル名 | サイズ | 特徴 | 推奨用途 |
|---------|--------|------|----------|
| VoiceCore-BF16.gguf | 6.61 GB | 最高品質、元モデルと同等の精度 | 高品質が必要な場合 |
| VoiceCore-Q4_K-f16.gguf | 2.66 GB | バランス型、実用的な精度 | 通常使用（要注意） |

⚠️ **重要な注意事項**: VoiceCoreは量子化に敏感なモデルです。ベースモデルであるorpheus-3bはQ4_K-f16以下の量子化レベルで[音声ファイルの作成に失敗するケース](https://huggingface.co/dahara1/orpheus-3b-0.1-ft_gguf)がある事がわかっています。  
自作ggufに挑戦する場合は、音声品質や文字誤り率だけでなく発声失敗率にも注目する事を推奨します。  

量子化手順を更に改善した結果、現在のVoiceCore-Q4_K-f16.ggufはVoiceCore-BF16.ggufより音声品質や文字誤り率が改善しているという評価が内製ベンチマークで示されており、これについてはオペレーションミスの可能性も踏まえて、判断が保留されています。  

## システム概要

```
[ユーザー入力]
    ↓
[llama.cpp サーバー]
    ↓
[VoiceCore GGUF]
    ↓
[音声トークン生成]
    ↓
[SNACデコーダー]
    ↓
[音声ファイル/リアルタイム再生]
```

VoiceCoreは直接WAVファイルを生成するのではなく、SNACというニューラルコーデック用の音声トークンを出力します。そのため、SNACも動かす必要があります。  
SNACは[C#実装 DillionLowry/NeuralCodecs](https://github.com/DillionLowry/NeuralCodecs)を公開してくれている方がいるので、参考にすればスマートフォン等で動作させる事も可能と思われます  
また、オリジナルの[pytorchモデル hubertsiuzdak/snac_24khz](https://huggingface.co/hubertsiuzdak/snac_24khz)以外に[ONNXに移植したモデル onnx-community/snac_24khz-ONNX](https://huggingface.co/onnx-community/snac_24khz-ONNX)も存在しますが、自然さがやや落ちるという評価も目にしているので留意してください  

## セットアップガイド（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のセットアップ

以下は基本的なセットアップ方法です。  
[llama.cppのセットアップ方法は多様なため各環境用の文書は公式サイトを参照](https://github.com/ggml-org/llama.cpp/blob/master/docs/build.md)してください  
[Docker](https://github.com/ggml-org/llama.cpp/blob/master/docs/docker.md)や[各種環境向けにコンパイル済のバイナリファイル](https://github.com/ggml-org/llama.cpp/releases)も用意されています。  

```bash
# llama.cppのクローン
git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp

# ビルド（Macの場合）
make

# Metal（Mac GPU）を使用する場合
make LLAMA_METAL=1
```

### 3. モデルのダウンロード

[webbigdata/VoiceCore_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  
nglは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,
        "repeat_penalty": 1.1,
        "repeat_last_n": 70
    }
    
    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動作は未チェックです。
- SNACと組み合わせる仕組みを別途構築する必要があります
- カスタムトークナイザーで問題(頻繁な異常な発声や反復出力)が発生する可能性があります。  

### LM Studio
[LM Studio](https://lmstudio.ai/)は、GUIベースでLLMを実行できるツールです。

**特徴:**
- 直感的なGUIインターフェース
- モデルの自動ダウンロード機能
- チャット履歴の管理

**使用方法:**
1. LM Studioをダウンロード・インストール
2. モデルファイル（.gguf）をインポート
3. 設定でコンテキストサイズを2048に設定
4. APIサーバーモードで起動

**注意:** 現時点でLM Studio動作は未チェックです。
- SNACと組み合わせる仕組みを別途構築する必要があります
- カスタムトークナイザーで問題(頻繁な異常な発声や反復出力)が発生する可能性があります。  

### llama.cpp Python バインディング
```bash
pip install llama-cpp-python
```

Pythonから直接モデルを使用できます。詳細は[公式ドキュメント](https://github.com/abetlen/llama-cpp-python)を参照してください。

## トラブルシューティング

### よくある問題と解決方法

1. **音声生成に失敗する**
   - Q4_K量子化版を使用している場合は、BF16版に切り替えてください
   - お使いのツールがカスタムトークナイザーに対応しているか確認してください
   - メモリ不足の場合は、コンテキストサイズ(-c)を小さくしてください

2. **サーバーが起動しない**
   - ポート8080が使用中でないか確認してください
   - モデルファイルのパスが正しいか確認してください

3. **生成速度が遅い**
   - CPU環境での推論実行は時間がかかります。Colabは無料でGPUが利用可能なので[webbigdata/VoiceCore](https://huggingface.co/webbigdata/VoiceCore)のサンプルColabスクリプトの利用も検討してください
   - GPU（Metal）を有効にしているか確認してください
   - `-ngl`パラメータを調整してください

## ライセンス

- モデル: 元モデル[webbigdata/VoiceCore](https://huggingface.co/webbigdata/VoiceCore)のライセンスに準じます。
- 音声データ: 各音声提供者様のライセンスに従ってください（[元モデルのライセンス情報](https://huggingface.co/webbigdata/VoiceCore#ディフォルト利用可能な音声の提供元とそのライセンス-default-voice-providers-and-their-licenses)を参照）