MULTI_MODEL_DESIGN.md

# マルチモデル対応設計案

## 概要
現在のLLMViewはLlama 3.2 3B（transformers）のみ対応していますが、他のTransformersモデル（Qwen、Mistral、Gemma等）にも対応できるように拡張します。

**重要**: Hugging Face Spacesでの使用を前提とする場合、**APIを使う必要はありません**。
Transformersライブラリでローカルにモデルをロードする方法（TransformersAI）を使用してください。
これにより、完全なトークン確率情報が取得でき、コストもかかりません。

外部API（OpenAI、Anthropic、Google）のサポートは、ローカル環境やテスト目的でのみ使用することを想定しています。

## アーキテクチャ設計

### 1. アダプターパターンの導入

```
AI (基底クラス/インターフェース)
├── TransformersAI (現在の実装 - Llama等のローカルモデル)
├── OpenAIAI (ChatGPT API)
├── AnthropicAI (Claude API)
├── GoogleAI (Gemini API)
└── HuggingFaceInferenceAI (Hugging Face Inference API)
```

### 2. 統一インターフェース

すべてのモデルアダプターが実装すべきメソッド：

```python
class BaseAI:
    def get_token_probabilities(self, text: str, k: int = 5) -> List[Tuple[str, float]]:
        """
        テキストから次のトークン候補と確率を取得
        
        Returns:
            List[Tuple[str, float]]: (トークン, 確率)のリスト
        """
        raise NotImplementedError
    
    def build_chat_prompt(self, user_content: str, system_content: str = "") -> str:
        """
        モデル固有のチャットプロンプト形式に変換
        """
        raise NotImplementedError
```

### 3. モデルタイプの識別

環境変数または設定ファイルでモデルタイプを指定：

```python
MODEL_TYPE = os.getenv("MODEL_TYPE", "transformers")  # transformers, openai, anthropic, google, hf_inference
MODEL_PATH = os.getenv("HF_MODEL_REPO", "meta-llama/Llama-3.2-3B-Instruct")  # モデル識別子（Hugging FaceリポジトリID）
```

**Hugging Face Spacesでの推奨設定**:
```python
# 環境変数例（Hugging Face Spaces用）
MODEL_TYPE=transformers
HF_MODEL_REPO=Qwen/Qwen2.5-3B-Instruct  # または他のモデル
HF_TOKEN=your_hf_token  # プライベートモデルの場合
```

### 4. 各モデルの特徴と実装方針

#### 4.1 TransformersAI (現在の実装)
- **特徴**: ローカルでモデルをロード、logitsから直接確率を取得可能
- **利点**: 完全なトークン確率情報が利用可能
- **実装**: 現在の`AI`クラスを`TransformersAI`にリネーム

#### 4.2 OpenAIAI (ChatGPT)
- **特徴**: API経由、`logprobs`パラメータでトークン確率を取得可能
- **API**: `openai.ChatCompletion.create()` の `logprobs=True`
- **制約**: 
  - トークン確率は`logprobs`で取得可能（GPT-4以降）
  - リクエストごとにAPIコールが必要
  - レート制限とコストが発生
- **実装方針**:
  ```python
  response = openai.ChatCompletion.create(
      model="gpt-4",
      messages=[...],
      logprobs=True,
      top_logprobs=5
  )
  # logprobsから確率を計算
  ```

#### 4.3 AnthropicAI (Claude)
- **特徴**: API経由、`logprobs`パラメータでトークン確率を取得可能（Claude 3.5以降）
- **API**: `anthropic.Anthropic().messages.create()` の `logprobs=True`
- **制約**: 
  - トークン確率は`logprobs`で取得可能
  - リクエストごとにAPIコールが必要
- **実装方針**:
  ```python
  response = client.messages.create(
      model="claude-3-5-sonnet-20241022",
      messages=[...],
      logprobs=True,
      top_logprobs=5
  )
  ```

#### 4.4 GoogleAI (Gemini)
- **特徴**: API経由、`logprobs`パラメータでトークン確率を取得可能
- **API**: `google.generativeai.GenerativeModel.generate_content()` の `logprobs=True`
- **制約**: 
  - トークン確率は`logprobs`で取得可能
  - リクエストごとにAPIコールが必要
- **実装方針**:
  ```python
  response = model.generate_content(
      prompt,
      generation_config={"logprobs": True, "top_k": 5}
  )
  ```

#### 4.5 HuggingFaceInferenceAI
- **特徴**: Hugging Face Inference API経由、一部のモデルでlogits取得可能
- **API**: `huggingface_hub.InferenceClient.text_generation()` の `details=True`
- **制約**: 
  - すべてのモデルでlogitsが利用可能とは限らない
  - リクエストごとにAPIコールが必要
  - 無料プランにはレート制限あり

#### 4.6 Hugging Face Spacesで利用可能なモデル（Transformers経由）

Hugging Face Spacesでは、以下のモデルをTransformersライブラリで直接利用可能：

##### 4.6.1 日本語対応モデル（推奨）

| モデル | リポジトリID | サイズ | 特徴 | トークン確率取得 | HF_TOKEN必要 |
|--------|------------|--------|------|----------------|-------------|
| **Llama 3.2 3B Instruct** | `meta-llama/Llama-3.2-3B-Instruct` | 3B | 多言語対応、現在使用中 | ✅ 完全対応 | ⚠️ **必要**（gatedモデル） |
| **Qwen 2.5** | `Qwen/Qwen2.5-3B-Instruct` | 3B | 日本語に強い、高性能 | ✅ 完全対応 | ❌ 不要 |
| **Mistral 7B Instruct** | `mistralai/Mistral-7B-Instruct-v0.2` | 7B | 高性能、多言語対応 | ✅ 完全対応 | ❌ 不要 |
| **Gemma 2B/7B** | `google/gemma-2b-it`, `google/gemma-7b-it` | 2B/7B | Google製、軽量 | ✅ 完全対応 | ❌ 不要 |
| **Phi-3** | `microsoft/Phi-3-mini-4k-instruct` | 3.8B | 軽量、高性能 | ✅ 完全対応 | ❌ 不要 |
| **TinyLlama** | `TinyLlama/TinyLlama-1.1B-Chat-v1.0` | 1.1B | 超軽量 | ✅ 完全対応 | ❌ 不要 |

##### 4.6.2 日本語特化モデル

| モデル | リポジトリID | サイズ | 特徴 | トークン確率取得 | HF_TOKEN必要 |
|--------|------------|--------|------|----------------|-------------|
| **ELYZA-japanese-Llama-2** | `elyza/ELYZA-japanese-Llama-2-7b-instruct` | 7B | 日本語特化 | ✅ 完全対応 | ⚠️ **必要**（Llama-2ベースのため） |
| **japanese-stablelm** | `stabilityai/japanese-stablelm-base-gamma-7b` | 7B | 日本語特化 | ✅ 完全対応 | ❌ 不要 |
| **weblab-10b** | `rinna/weblab-10b-instruction-sft` | 10B | 日本語特化、大規模 | ✅ 完全対応 | ❌ 不要 |

##### 4.6.3 その他の主要モデル

| モデル | リポジトリID | サイズ | 特徴 | トークン確率取得 | HF_TOKEN必要 |
|--------|------------|--------|------|----------------|-------------|
| **Falcon** | `tiiuae/falcon-7b-instruct` | 7B | オープンソース | ✅ 完全対応 | ❌ 不要 |
| **MPT** | `mosaicml/mpt-7b-instruct` | 7B | 商用利用可能 | ✅ 完全対応 | ❌ 不要 |
| **StarCoder** | `bigcode/starcoder2-7b` | 7B | コード生成特化 | ✅ 完全対応 | ⚠️ **必要**（gatedモデルの可能性あり） |

##### 4.6.4 Hugging Face Inference APIで利用可能なモデル

**注意**: Inference APIでは、すべてのモデルでトークン確率（logits）が取得できるわけではありません。
以下のモデルはInference API経由でも利用可能ですが、トークン確率の取得はモデルによって異なります：

- **無料プラン**: 制限あり、一部モデルのみ
- **有料プラン**: より多くのモデルにアクセス可能

**推奨アプローチ**: 
- Hugging Face Spacesでは、**Transformersライブラリで直接モデルをロード**する方法を推奨
- これにより、完全なトークン確率情報が取得可能
- Inference APIは、モデルをローカルにロードできない場合の代替手段

### 5. プロンプトフォーマットの統一

各モデルに適したプロンプト形式に変換する`build_chat_prompt`メソッドを実装：

```python
# Llama 3.2形式
"<|start_header_id|>system<|end_header_id|>\n{system}\n<|eot_id|>..."

# OpenAI形式
[
    {"role": "system", "content": system},
    {"role": "user", "content": user}
]

# Claude形式
[
    {"role": "user", "content": f"{system}\n\n{user}"}
]

# Gemini形式
f"{system}\n\n{user}"
```

### 6. 設定管理の拡張

`config.py`または環境変数で管理：

```python
# Hugging Face Spaces用（推奨）
MODEL_TYPE=transformers
HF_MODEL_REPO=Qwen/Qwen2.5-3B-Instruct  # または meta-llama/Llama-3.2-3B-Instruct
HF_TOKEN=your_hf_token  # プライベートモデルの場合のみ

# OpenAI API用
MODEL_TYPE=openai
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4

# Anthropic API用
MODEL_TYPE=anthropic
ANTHROPIC_API_KEY=sk-ant-...
ANTHROPIC_MODEL=claude-3-5-sonnet-20241022

# Google API用
MODEL_TYPE=google
GOOGLE_API_KEY=...
GOOGLE_MODEL=gemini-pro

# Hugging Face Inference API用（オプション）
MODEL_TYPE=hf_inference
HF_INFERENCE_API_KEY=hf_...
HF_INFERENCE_MODEL=meta-llama/Llama-3.2-3B-Instruct
```

**Hugging Face Spacesでの推奨設定**:
- `MODEL_TYPE=transformers`を使用（ローカルでモデルをロード）
- `HF_MODEL_REPO`でモデルを指定（デフォルト: `meta-llama/Llama-3.2-3B-Instruct`）
- 他のモデルに切り替える場合は、`HF_MODEL_REPO`を変更するだけ

### 7. 実装の優先順位

#### Phase 1: 基盤整備（最優先）
- `BaseAI`インターフェースの定義
- 現在の`AI`クラスを`TransformersAI`にリファクタリング
- モデルタイプの識別とファクトリーパターンの実装
- **Hugging Face Spacesでの複数モデル対応**（Llama 3.2以外のモデル選択可能に）

#### Phase 2: Hugging Faceモデルの拡張対応
- **Qwen 2.5対応**: 日本語に強い、高性能
- **Mistral 7B対応**: 多言語対応、高性能
- **Gemma対応**: Google製、軽量
- 各モデルのプロンプトフォーマット対応

#### Phase 3: OpenAI対応
- `OpenAIAI`クラスの実装
- `logprobs`パラメータの活用
- プロンプトフォーマット変換

#### Phase 4: Anthropic対応
- `AnthropicAI`クラスの実装
- Claude固有のプロンプト形式対応

#### Phase 5: Google/Gemini対応
- `GoogleAI`クラスの実装

#### Phase 6: その他
- Hugging Face Inference API対応（オプション）
- カスタムモデルエンドポイント対応

### 8. 課題と解決策

#### 課題1: APIコストとレート制限
- **解決策**: 
  - キャッシュ機能の実装
  - リクエスト間隔の制御
  - ローカルモデルとの併用推奨

#### 課題2: トークン確率の取得方法の違い
- **解決策**: 
  - 各APIの`logprobs`パラメータを活用
  - 確率の正規化処理を統一

#### 課題3: プロンプト形式の違い
- **解決策**: 
  - 各モデル用の`build_chat_prompt`メソッドを実装
  - 統一された入力インターフェースを提供

#### 課題4: エラーハンドリング
- **解決策**: 
  - 各APIのエラーレスポンスを統一形式で処理
  - フォールバック機能の実装

### 9. ファイル構成

```
package/
├── ai/
│   ├── __init__.py          # ファクトリー関数
│   ├── base.py              # BaseAIインターフェース
│   ├── transformers_ai.py   # TransformersAI (現在のAIクラス)
│   ├── openai_ai.py         # OpenAIAI
│   ├── anthropic_ai.py      # AnthropicAI
│   ├── google_ai.py         # GoogleAI
│   └── hf_inference_ai.py   # HuggingFaceInferenceAI
├── config.py                # 設定管理（拡張）
└── ...
```

### 10. 使用例

#### 10.1 Hugging Face Spacesでの使用（推奨）

```python
# 環境変数でモデルを指定
# HF_MODEL_REPO=Qwen/Qwen2.5-3B-Instruct python app.py
# HF_MODEL_REPO=mistralai/Mistral-7B-Instruct-v0.2 python app.py

from package.ai import get_ai_model

# ファクトリー関数で適切なモデルを取得
ai_model = get_ai_model()  # MODEL_TYPE=transformers（デフォルト）

# 統一されたインターフェースで使用
tokens = ai_model.get_token_probabilities("こんにちは", k=5)
```

#### 10.2 OpenAI APIでの使用

```python
# MODEL_TYPE=openai OPENAI_API_KEY=sk-... python app.py

from package.ai import get_ai_model

ai_model = get_ai_model()  # MODEL_TYPE=openai
tokens = ai_model.get_token_probabilities("こんにちは", k=5)
```

#### 10.3 モデルの動的切り替え

```python
# アプリ起動時に環境変数で指定
# または、設定ファイルで管理

import os
os.environ["HF_MODEL_REPO"] = "Qwen/Qwen2.5-3B-Instruct"

from package.ai import get_ai_model
ai_model = get_ai_model()
```

### 11. Hugging Face Spacesでのモデル選択ガイド

#### 11.1 モデル選択の基準

1. **日本語対応**: 日本語処理が必要な場合
   - 推奨: `Qwen/Qwen2.5-3B-Instruct`, `meta-llama/Llama-3.2-3B-Instruct`

2. **軽量性**: リソース制約がある場合
   - 推奨: `TinyLlama/TinyLlama-1.1B-Chat-v1.0`, `google/gemma-2b-it`

3. **高性能**: 品質を重視する場合
   - 推奨: `mistralai/Mistral-7B-Instruct-v0.2`, `Qwen/Qwen2.5-3B-Instruct`

4. **日本語特化**: 日本語タスクに特化
   - 推奨: `elyza/ELYZA-japanese-Llama-2-7b-instruct`, `rinna/weblab-10b-instruction-sft`

#### 11.2 モデル切り替え手順

1. Hugging Face Spacesの環境変数で`HF_MODEL_REPO`を設定
2. アプリを再起動
3. モデルが自動的にロードされる（初回はダウンロード時間がかかる場合あり）

#### 11.3 注意事項

- **ストレージ制約**: Hugging Face Spacesのストレージ制限に注意
- **モデルサイズ**: 大きなモデル（7B以上）はメモリとロード時間がかかる
- **トークン確率**: すべてのTransformersモデルで完全なトークン確率が取得可能
- **APIコスト**: Transformersモデルは無料（ローカルロード）、APIモデルは有料

## まとめ

この設計により、以下のメリットが得られます：

1. **拡張性**: 新しいモデルを簡単に追加可能
2. **互換性**: 既存のコードを最小限の変更で維持
3. **柔軟性**: ユーザーが好みのモデルを選択可能
4. **統一性**: すべてのモデルが同じインターフェースを使用