mirror of
https://github.com/farion1231/cc-switch.git
synced 2026-05-01 16:42:56 +08:00
docs: restructure user manual for i18n and add EN/JA translations
Reorganize docs/user-manual/ from flat structure to language subdirectories (zh/, en/, ja/) with shared assets/. Move existing Chinese docs into zh/, fix image paths, add multilingual navigation README, and translate all 23 markdown files (~4500 lines each) to English and Japanese.
This commit is contained in:
Jason
222
docs/user-manual/ja/4-proxy/4.1-service.md
Normal file
222
docs/user-manual/ja/4-proxy/4.1-service.md
Normal file
@@ -0,0 +1,222 @@
|
||||
# 4.1 プロキシサービス
|
||||
|
||||
## 機能説明
|
||||
|
||||
プロキシサービスは、ローカルで HTTP プロキシを起動し、すべての API リクエストをプロキシ経由で転送します。
|
||||
|
||||
**主な用途**：
|
||||
- リクエストログの記録
|
||||
- API 使用量の統計
|
||||
- フェイルオーバーのサポート
|
||||
- 複数アプリのリクエストを一元管理
|
||||
|
||||
## プロキシの起動
|
||||
|
||||
### 方法 1：メイン画面のスイッチ
|
||||
|
||||
メイン画面上部の **プロキシスイッチ** ボタンをクリックします。
|
||||
|
||||
スイッチの状態：
|
||||
- 白：プロキシ停止中
|
||||
- 緑：プロキシ実行中
|
||||
|
||||
|
||||
|
||||
### 方法 2：設定ページ
|
||||
|
||||
1. 「設定 → 詳細 → プロキシサービス」を開く
|
||||
2. 右上のスイッチをクリック
|
||||
|
||||
|
||||
|
||||
## プロキシ設定
|
||||
|
||||
### 基本設定
|
||||
|
||||
| 設定項目 | 説明 | デフォルト値 |
|
||||
|--------|------|--------|
|
||||
| リスニングアドレス | プロキシがバインドする IP アドレス | `127.0.0.1` |
|
||||
| リスニングポート | プロキシがリスニングするポート | `15721` |
|
||||
| ログを有効化 | リクエストログを記録するかどうか | オン |
|
||||
|
||||
### 設定の変更
|
||||
|
||||
1. **プロキシサービスを停止**（先に停止する必要あり）
|
||||
2. リスニングアドレスまたはポートを変更
|
||||
3. 「保存」をクリック
|
||||
4. プロキシを再起動
|
||||
|
||||
> アドレス/ポートの変更には、先にプロキシサービスの停止が必要です
|
||||
|
||||
### リスニングアドレスの説明
|
||||
|
||||
| アドレス | 説明 |
|
||||
|------|------|
|
||||
| `127.0.0.1` | ローカルマシンのみアクセス可能（推奨） |
|
||||
| `0.0.0.0` | LAN からのアクセスを許可 |
|
||||
|
||||
## 実行状態
|
||||
|
||||
プロキシ実行中、パネルには以下の情報が表示されます：
|
||||
|
||||
### サービスアドレス
|
||||
|
||||
```
|
||||
http://127.0.0.1:15721
|
||||
```
|
||||
|
||||
「コピー」ボタンでアドレスをコピーできます。
|
||||
|
||||
### 現在のプロバイダー
|
||||
|
||||
各アプリが現在使用しているプロバイダーを表示：
|
||||
|
||||
```
|
||||
Claude: PackyCode
|
||||
Codex: AIGoCode
|
||||
Gemini: Google 公式
|
||||
```
|
||||
|
||||
### 統計データ
|
||||
|
||||
| 指標 | 説明 |
|
||||
|------|------|
|
||||
| アクティブ接続 | 現在処理中のリクエスト数 |
|
||||
| 総リクエスト数 | 起動以来の総リクエスト数 |
|
||||
| 成功率 | リクエスト成功の割合（>90% 緑、≤90% 黄） |
|
||||
| 実行時間 | プロキシの稼働時間 |
|
||||
|
||||
### フェイルオーバーキュー
|
||||
|
||||
プロキシパネルにはアプリタイプごとにフェイルオーバーキューが表示されます：
|
||||
|
||||
```
|
||||
Claude
|
||||
├── 1. PackyCode [使用中] ●
|
||||
├── 2. AIGoCode ●
|
||||
└── 3. バックアップ ○
|
||||
|
||||
Codex
|
||||
├── 1. AIGoCode [使用中] ●
|
||||
└── 2. バックアップ ●
|
||||
```
|
||||
|
||||
キューの説明：
|
||||
- 数字は優先順位を示す
|
||||
- 「使用中」ラベルは現在使用しているプロバイダーを示す
|
||||
- ヘルスバッジはプロバイダーの状態を示す：
|
||||
- 緑：健康（連続失敗 0 回）
|
||||
- 黄：低下（連続失敗 1-2 回）
|
||||
- 赤：不健康（連続失敗 ≥3 回）
|
||||
|
||||
## 動作原理
|
||||
|
||||
### リクエストフロー
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant CLI as CLI ツール (Claude)
|
||||
participant Proxy as ローカルプロキシ (CC Switch)
|
||||
participant API as API プロバイダー (Anthropic)
|
||||
participant DB as データストレージ (Logger)
|
||||
|
||||
CLI->>Proxy: API リクエストを送信
|
||||
Proxy->>DB: リクエストログの記録/使用量の統計
|
||||
Proxy->>API: リクエストを転送
|
||||
API-->>Proxy: レスポンスを返却
|
||||
Proxy-->>CLI: レスポンスを返却
|
||||
```
|
||||
|
||||
### 設定の変更
|
||||
|
||||
プロキシを起動してアプリケーション接管を有効にすると、CC Switch はアプリの設定を変更します：
|
||||
|
||||
**Claude**：
|
||||
```json
|
||||
{
|
||||
"env": {
|
||||
"ANTHROPIC_BASE_URL": "http://127.0.0.1:15721"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Codex**：
|
||||
```toml
|
||||
base_url = "http://127.0.0.1:15721/v1"
|
||||
```
|
||||
|
||||
**Gemini**：
|
||||
```
|
||||
GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:15721
|
||||
```
|
||||
|
||||
## プロキシの停止
|
||||
|
||||
### 方法 1：メイン画面のスイッチ
|
||||
|
||||
プロキシスイッチボタンをクリックしてオフにします。
|
||||
|
||||
### 方法 2：設定ページ
|
||||
|
||||
プロキシサービスパネルでスイッチをオフにします。
|
||||
|
||||
### 停止後の処理
|
||||
|
||||
プロキシの停止時、CC Switch は以下を実行します：
|
||||
|
||||
1. アプリの設定を元の状態に復元
|
||||
2. リクエストログを保存
|
||||
3. すべての接続を閉じる
|
||||
|
||||
## ログ記録
|
||||
|
||||
### ログの有効化
|
||||
|
||||
プロキシパネルの「ログを有効化」スイッチをオンにします。
|
||||
|
||||
### ログの内容
|
||||
|
||||
各リクエスト記録には以下が含まれます：
|
||||
|
||||
| フィールド | 説明 |
|
||||
|------|------|
|
||||
| 時間 | リクエスト時刻 |
|
||||
| アプリ | Claude / Codex / Gemini |
|
||||
| プロバイダー | 使用されたプロバイダー |
|
||||
| モデル | リクエストされたモデル |
|
||||
| Token | 入力/出力の Token 数 |
|
||||
| レイテンシ | リクエストにかかった時間 |
|
||||
| ステータス | 成功/失敗 |
|
||||
|
||||
### ログの表示
|
||||
|
||||
「設定 → 使用量」タブでリクエストログを表示できます。
|
||||
|
||||
## よくある質問
|
||||
|
||||
### ポートが使用中
|
||||
|
||||
エラーメッセージ：`Address already in use`
|
||||
|
||||
解決方法：
|
||||
1. ポートを変更する（例：5001）
|
||||
2. またはそのポートを使用しているプログラムを終了する
|
||||
|
||||
### プロキシの起動に失敗する
|
||||
|
||||
確認事項：
|
||||
- ポートが使用中でないか
|
||||
- 十分な権限があるか
|
||||
- ファイアウォールがブロックしていないか
|
||||
|
||||
### リクエストがタイムアウトする
|
||||
|
||||
考えられる原因：
|
||||
- ネットワークの問題
|
||||
- プロバイダーのサーバーの問題
|
||||
- プロキシ設定のエラー
|
||||
|
||||
解決方法：
|
||||
- ネットワーク接続を確認
|
||||
- プロバイダーの API に直接アクセスを試みる
|
||||
- プロバイダーの設定を確認
|
||||
195
docs/user-manual/ja/4-proxy/4.2-takeover.md
Normal file
195
docs/user-manual/ja/4-proxy/4.2-takeover.md
Normal file
@@ -0,0 +1,195 @@
|
||||
# 4.2 アプリケーション接管
|
||||
|
||||
## 機能説明
|
||||
|
||||
アプリケーション接管とは、CC Switch のプロキシが特定アプリの API リクエストを接管することです。
|
||||
|
||||
接管を有効にすると：
|
||||
- アプリの API リクエストがローカルプロキシ経由で転送される
|
||||
- リクエストログと使用量の統計を記録できる
|
||||
- フェイルオーバー機能を使用できる
|
||||
|
||||
## 前提条件
|
||||
|
||||
アプリケーション接管機能を使用する前に、プロキシサービスを起動する必要があります。
|
||||
|
||||
## 接管の有効化
|
||||
|
||||
### 操作場所
|
||||
|
||||
設定 → 詳細 → プロキシサービス → アプリケーション接管エリア
|
||||
|
||||
### 操作手順
|
||||
|
||||
1. プロキシサービスが起動していることを確認
|
||||
2. 「アプリケーション接管」エリアを見つける
|
||||
3. 必要なアプリのスイッチをオンにする
|
||||
|
||||
### 接管スイッチ
|
||||
|
||||
| スイッチ | 作用 |
|
||||
|------|------|
|
||||
| Claude 接管 | Claude Code のリクエストを接管 |
|
||||
| Codex 接管 | Codex のリクエストを接管 |
|
||||
| Gemini 接管 | Gemini CLI のリクエストを接管 |
|
||||
|
||||
複数のアプリの接管を同時に有効にできます。
|
||||
|
||||
## 接管の仕組み
|
||||
|
||||
### 設定の変更
|
||||
|
||||
接管を有効にすると、CC Switch はアプリの設定ファイルを変更し、API エンドポイントをローカルプロキシに向けます。
|
||||
|
||||
**Claude 設定の変更**：
|
||||
|
||||
```json
|
||||
// 接管前
|
||||
{
|
||||
"env": {
|
||||
"ANTHROPIC_BASE_URL": "https://api.anthropic.com"
|
||||
}
|
||||
}
|
||||
|
||||
// 接管後
|
||||
{
|
||||
"env": {
|
||||
"ANTHROPIC_BASE_URL": "http://127.0.0.1:15721"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Codex 設定の変更**：
|
||||
|
||||
```toml
|
||||
# 接管前
|
||||
base_url = "https://api.openai.com/v1"
|
||||
|
||||
# 接管後
|
||||
base_url = "http://127.0.0.1:15721/v1"
|
||||
```
|
||||
|
||||
**Gemini 設定の変更**：
|
||||
|
||||
```bash
|
||||
# 接管前
|
||||
GOOGLE_GEMINI_BASE_URL=https://generativelanguage.googleapis.com
|
||||
|
||||
# 接管後
|
||||
GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:15721
|
||||
```
|
||||
|
||||
### リクエストの転送
|
||||
|
||||
プロキシがリクエストを受信すると：
|
||||
|
||||
1. リクエスト元を識別（Claude/Codex/Gemini）
|
||||
2. そのアプリで現在有効なプロバイダーを検索
|
||||
3. プロバイダーの実際のエンドポイントにリクエストを転送
|
||||
4. リクエストログを記録
|
||||
5. アプリにレスポンスを返却
|
||||
|
||||
## 接管ステータスの表示
|
||||
|
||||
### メイン画面の表示
|
||||
|
||||
接管を有効にすると、メイン画面に以下の変化があります：
|
||||
|
||||
- **プロキシ Logo の色**：無色から緑に変化
|
||||
- **プロバイダーカード**：現在アクティブなプロバイダーに緑の枠が表示
|
||||
|
||||
### プロバイダーカードの状態
|
||||
|
||||
| 状態 | 枠の色 | 説明 |
|
||||
|------|----------|------|
|
||||
| 現在有効 | 青 | 設定ファイル内のプロバイダー（非プロキシモード） |
|
||||
| プロキシアクティブ | 緑 | プロキシが実際に使用しているプロバイダー |
|
||||
| 通常 | デフォルト | 使用されていないプロバイダー |
|
||||
|
||||
## 接管の無効化
|
||||
|
||||
### 操作手順
|
||||
|
||||
1. プロキシパネルで対応するアプリの接管スイッチをオフにする
|
||||
2. またはプロキシサービスを直接停止
|
||||
|
||||
### 設定の復元
|
||||
|
||||
接管を無効にすると、CC Switch は以下を実行します：
|
||||
|
||||
1. アプリの設定を接管前の状態に復元
|
||||
2. 現在のリクエストログを保存
|
||||
|
||||
## 接管とプロバイダーの切り替え
|
||||
|
||||
### 接管モードでのプロバイダー切り替え
|
||||
|
||||
接管モードでプロバイダーを切り替える場合：
|
||||
|
||||
1. メイン画面でプロバイダーの「有効化」ボタンをクリック
|
||||
2. プロキシが新しいプロバイダーを使用してリクエストを即座に転送
|
||||
3. **CLI ツールの再起動は不要**
|
||||
|
||||
これが接管モードの大きなメリットです：プロバイダーの切り替えが即座に反映されます。
|
||||
|
||||
### 非接管モードでのプロバイダー切り替え
|
||||
|
||||
非接管モードでプロバイダーを切り替える場合：
|
||||
|
||||
1. 設定ファイルを変更
|
||||
2. CLI ツールの再起動が必要
|
||||
|
||||
## 複数アプリの接管
|
||||
|
||||
複数のアプリを同時に接管でき、それぞれ独立して管理されます：
|
||||
|
||||
- 独立したプロバイダー設定
|
||||
- 独立したフェイルオーバーキュー
|
||||
- 独立したリクエスト統計
|
||||
|
||||
## 使用シーン
|
||||
|
||||
### シーン 1：使用量の監視
|
||||
|
||||
接管 + ログ記録を有効にして、API の使用状況を監視します。
|
||||
|
||||
### シーン 2：素早い切り替え
|
||||
|
||||
接管を有効にすると、プロバイダーの切り替えに CLI ツールの再起動が不要になります。
|
||||
|
||||
### シーン 3：フェイルオーバー
|
||||
|
||||
接管の有効化はフェイルオーバー機能を使用するための前提条件です。
|
||||
|
||||
## 注意事項
|
||||
|
||||
### パフォーマンスへの影響
|
||||
|
||||
プロキシにより少量のレイテンシ（通常 < 10ms）が追加されますが、ほとんどのシーンでは無視できます。
|
||||
|
||||
### ネットワーク要件
|
||||
|
||||
接管モードでは、CLI ツールがローカルプロキシアドレスにアクセスできる必要があります。
|
||||
|
||||
### 設定のバックアップ
|
||||
|
||||
接管を有効にする前に、CC Switch は元の設定をバックアップし、無効化時に復元します。
|
||||
|
||||
## よくある質問
|
||||
|
||||
### 接管後にリクエストが失敗する
|
||||
|
||||
確認事項：
|
||||
- プロキシサービスが正常に実行されているか
|
||||
- プロバイダーの設定が正しいか
|
||||
- ネットワークが正常か
|
||||
|
||||
### 接管を無効にしても設定が復元されない
|
||||
|
||||
考えられる原因：
|
||||
- プロキシの異常終了
|
||||
- 設定ファイルが他のプログラムに変更された
|
||||
|
||||
解決方法：
|
||||
- プロバイダーを手動で編集して保存し直す
|
||||
- または接管を再度有効にしてから無効にする
|
||||
232
docs/user-manual/ja/4-proxy/4.3-failover.md
Normal file
232
docs/user-manual/ja/4-proxy/4.3-failover.md
Normal file
@@ -0,0 +1,232 @@
|
||||
# 4.3 フェイルオーバー
|
||||
|
||||
## 機能説明
|
||||
|
||||
フェイルオーバー機能は、メインプロバイダーのリクエストが失敗した場合に、自動的にバックアッププロバイダーに切り替えてサービスの中断を防ぎます。
|
||||
|
||||
**適用シーン**：
|
||||
- プロバイダーのサービスが不安定な場合
|
||||
- 高可用性が必要な場合
|
||||
- 長時間実行するタスク
|
||||
|
||||
## 前提条件
|
||||
|
||||
フェイルオーバー機能を使用するには：
|
||||
|
||||
1. プロキシサービスを起動
|
||||
2. アプリケーション接管を有効化
|
||||
3. フェイルオーバーキューを設定
|
||||
4. 自動フェイルオーバーを有効化
|
||||
|
||||
## フェイルオーバーキューの設定
|
||||
|
||||
### 設定ページを開く
|
||||
|
||||
設定 → 詳細 → フェイルオーバー
|
||||
|
||||
### アプリの選択
|
||||
|
||||
ページ上部に 3 つのタブがあります：
|
||||
- Claude
|
||||
- Codex
|
||||
- Gemini
|
||||
|
||||
設定するアプリを選択します。
|
||||
|
||||
### バックアッププロバイダーの追加
|
||||
|
||||
1. 「フェイルオーバーキュー」エリアで
|
||||
2. 「プロバイダーを追加」をクリック
|
||||
3. ドロップダウンリストからプロバイダーを選択
|
||||
4. プロバイダーがキューの末尾に追加
|
||||
|
||||
### 優先順位の調整
|
||||
|
||||
プロバイダーをドラッグして順序を調整：
|
||||
- 番号が小さいほど優先度が高い
|
||||
- メインプロバイダーが失敗すると、順番にバックアッププロバイダーを試行
|
||||
|
||||
### プロバイダーの削除
|
||||
|
||||
プロバイダーの右側にある「削除」ボタンをクリックします。
|
||||
|
||||
## メイン画面でのクイック操作
|
||||
|
||||
プロキシとフェイルオーバーがどちらも有効な場合、プロバイダーカードにフェイルオーバースイッチが表示されます。
|
||||
|
||||
### キューに追加
|
||||
|
||||
1. プロバイダーカードを見つける
|
||||
2. フェイルオーバースイッチをオンにする
|
||||
3. プロバイダーが自動的にキューに追加
|
||||
|
||||
### キューから削除
|
||||
|
||||
1. プロバイダーカードのフェイルオーバースイッチをオフにする
|
||||
2. プロバイダーがキューから削除
|
||||
|
||||
## 自動フェイルオーバーの有効化
|
||||
|
||||
### 操作手順
|
||||
|
||||
1. フェイルオーバー設定ページで
|
||||
2. 「自動フェイルオーバー」スイッチをオンにする
|
||||
|
||||
### スイッチの説明
|
||||
|
||||
| 状態 | 動作 |
|
||||
|------|------|
|
||||
| オフ | 失敗を記録するのみ、自動切り替えなし |
|
||||
| オン | 失敗時に自動的に次のプロバイダーに切り替え |
|
||||
|
||||
## フェイルオーバーのフロー
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Start[リクエストがプロキシに到達] --> Send[現在のプロバイダーに送信]
|
||||
Send --> CheckSuccess{成功？}
|
||||
CheckSuccess -- はい --> Return[レスポンスを返却]
|
||||
CheckSuccess -- いいえ --> LogFail[失敗を記録]
|
||||
LogFail --> CheckCircuit{サーキットブレーカーの状態確認}
|
||||
CheckCircuit -- 発動中 --> Skip[このプロバイダーをスキップ]
|
||||
CheckCircuit -- 未発動 --> IncFail[失敗カウントを増加]
|
||||
Skip --> Next{キューに次がある？}
|
||||
IncFail --> Next
|
||||
Next -- あり --> Switch[プロバイダーを切り替え]
|
||||
Switch --> Retry[リクエストをリトライ]
|
||||
Retry --> Send
|
||||
Next -- なし --> Error[エラーを返却]
|
||||
```
|
||||
|
||||
## サーキットブレーカーの設定
|
||||
|
||||
サーキットブレーカーは、失敗したプロバイダーへの頻繁なリトライを防止します。
|
||||
|
||||
### 設定項目
|
||||
|
||||
アプリごとに独立したデフォルト設定があります。以下は共通のデフォルト値で、Claude には独自の緩やかな設定があります。
|
||||
|
||||
| 設定 | 説明 | 共通デフォルト | Claude デフォルト | 範囲 |
|
||||
|------|------|--------|--------|------|
|
||||
| 失敗閾値 | 連続何回失敗でサーキットブレーカーが発動 | 4 | 8 | 1-20 |
|
||||
| 復旧成功閾値 | ハーフオープン状態で何回成功したら閉じるか | 2 | 3 | 1-10 |
|
||||
| 復旧待機時間 | サーキットブレーカー発動後の復旧試行までの時間（秒） | 60 | 90 | 0-300 |
|
||||
| エラー率閾値 | この値を超えるとサーキットブレーカーが発動 | 60% | 70% | 0-100% |
|
||||
| 最小リクエスト数 | エラー率計算前の最小リクエスト数 | 10 | 15 | 5-100 |
|
||||
|
||||
> Claude はリクエストに時間がかかるため、デフォルト設定はより緩やかで、多くの失敗を許容します。
|
||||
|
||||
### タイムアウト設定
|
||||
|
||||
| 設定 | 説明 | 共通デフォルト | Claude デフォルト | 範囲 |
|
||||
|------|------|--------|--------|------|
|
||||
| ストリーム初バイトタイムアウト | 最初のデータチャンクの最大待機時間（秒） | 60 | 90 | 1-120 |
|
||||
| ストリームサイレントタイムアウト | データチャンク間の最大間隔（秒） | 120 | 180 | 60-600（0 で無効化） |
|
||||
| 非ストリームタイムアウト | 非ストリームリクエストの総タイムアウト時間（秒） | 600 | 600 | 60-1200 |
|
||||
|
||||
### リトライ設定
|
||||
|
||||
| 設定 | 説明 | 共通デフォルト | Claude デフォルト | 範囲 |
|
||||
|------|------|--------|--------|------|
|
||||
| 最大リトライ回数 | リクエスト失敗時のリトライ回数 | 3 | 6 | 0-10 |
|
||||
|
||||
> Gemini のデフォルト最大リトライ回数は 5 です。
|
||||
|
||||
### サーキットブレーカーの状態
|
||||
|
||||
| 状態 | 説明 |
|
||||
|------|------|
|
||||
| 閉（Closed） | 正常状態、リクエストを許可 |
|
||||
| 開（Open） | サーキットブレーカー発動中、このプロバイダーをスキップ |
|
||||
| 半開（Half-Open） | 復旧試行中、探査リクエストを送信 |
|
||||
|
||||
### 状態遷移
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> Closed: 初期化
|
||||
Closed --> Open: 失敗回数 >= 閾値
|
||||
Open --> HalfOpen: サーキットブレーカー期間満了
|
||||
HalfOpen --> Closed: 探査成功 (>= 復旧閾値)
|
||||
HalfOpen --> Open: 探査失敗
|
||||
```
|
||||
|
||||
## ヘルスステータスの表示
|
||||
|
||||
### プロバイダーカード
|
||||
|
||||
カードにヘルスステータスバッジが表示されます：
|
||||
|
||||
| バッジ | 状態 | 説明 |
|
||||
|------|------|------|
|
||||
| 緑 | 健康 | 連続失敗回数 0 |
|
||||
| 黄 | 警告 | 失敗はあるがサーキットブレーカー未発動 |
|
||||
| 赤 | サーキットブレーカー発動 | 一時的にスキップ |
|
||||
|
||||
### キューリスト
|
||||
|
||||
フェイルオーバーキューにも各プロバイダーのヘルスステータスが表示されます。
|
||||
|
||||
## フェイルオーバーログ
|
||||
|
||||
各フェイルオーバーの記録内容：
|
||||
|
||||
| 情報 | 説明 |
|
||||
|------|------|
|
||||
| 時間 | 発生時刻 |
|
||||
| 元のプロバイダー | 失敗したプロバイダー |
|
||||
| 新しいプロバイダー | 切り替え先のプロバイダー |
|
||||
| 失敗理由 | エラー情報 |
|
||||
|
||||
使用量統計のリクエストログで確認できます。
|
||||
|
||||
## ベストプラクティス
|
||||
|
||||
### キュー設定のアドバイス
|
||||
|
||||
1. **メインプロバイダー**：最も安定で高速なプロバイダー
|
||||
2. **第 1 バックアップ**：次善の選択
|
||||
3. **第 2 バックアップ**：最後の手段
|
||||
|
||||
### サーキットブレーカー設定のアドバイス
|
||||
|
||||
| シーン | 失敗閾値 | サーキットブレーカー期間 |
|
||||
|------|----------|----------|
|
||||
| 高可用性要件 | 2 | 30 秒 |
|
||||
| 一般的なシーン | 3 | 60 秒 |
|
||||
| 偶発的な失敗を許容 | 5 | 120 秒 |
|
||||
|
||||
### 監視のアドバイス
|
||||
|
||||
定期的に確認：
|
||||
- 各プロバイダーのヘルスステータス
|
||||
- フェイルオーバーの発生頻度
|
||||
- サーキットブレーカーの発動状況
|
||||
|
||||
## よくある質問
|
||||
|
||||
### フェイルオーバーがトリガーされない
|
||||
|
||||
確認事項：
|
||||
1. プロキシサービスが実行中か
|
||||
2. アプリケーション接管が有効か
|
||||
3. 自動フェイルオーバーが有効か
|
||||
4. キューにバックアッププロバイダーがあるか
|
||||
|
||||
### フェイルオーバーが頻繁にトリガーされる
|
||||
|
||||
考えられる原因：
|
||||
- メインプロバイダーが不安定
|
||||
- ネットワークの問題
|
||||
- 設定のエラー
|
||||
|
||||
解決方法：
|
||||
- メインプロバイダーの状態を確認
|
||||
- サーキットブレーカーのパラメータを調整
|
||||
- メインプロバイダーの変更を検討
|
||||
|
||||
### すべてのプロバイダーがサーキットブレーカー発動中
|
||||
|
||||
サーキットブレーカー期間満了後に自動復旧を待つか、以下を実行：
|
||||
1. プロキシサービスを手動で再起動
|
||||
2. サーキットブレーカーの状態をリセット
|
||||
291
docs/user-manual/ja/4-proxy/4.4-usage.md
Normal file
291
docs/user-manual/ja/4-proxy/4.4-usage.md
Normal file
@@ -0,0 +1,291 @@
|
||||
# 4.4 使用量統計
|
||||
|
||||
## 機能説明
|
||||
|
||||
使用量統計機能は、API リクエストデータを記録・分析して、以下をサポートします：
|
||||
|
||||
- API の使用状況の把握
|
||||
- 費用支出の見積もり
|
||||
- 使用パターンの分析
|
||||
- 問題のトラブルシューティング
|
||||
|
||||
## 前提条件
|
||||
|
||||
使用量統計機能を使用するには：
|
||||
|
||||
1. プロキシサービスを起動
|
||||
2. アプリケーション接管を有効化
|
||||
3. ログ記録を有効化
|
||||
|
||||
## 使用量統計を開く
|
||||
|
||||
設定 → 使用量 タブ
|
||||
|
||||
## 統計概要
|
||||
|
||||
### 集計カード
|
||||
|
||||
ページ上部に主要指標が表示されます：
|
||||
|
||||
| 指標 | 説明 |
|
||||
|------|------|
|
||||
| 総リクエスト数 | 統計期間内のリクエスト総数 |
|
||||
| 総 Token | 入力 + 出力 Token の合計 |
|
||||
| 推定費用 | 料金設定に基づいて計算された費用 |
|
||||
| 成功率 | 成功したリクエストの割合 |
|
||||
|
||||
### 期間
|
||||
|
||||
統計の期間を選択できます：
|
||||
|
||||
| オプション | 範囲 |
|
||||
|------|------|
|
||||
| 今日 | 当日 00:00 から現在まで |
|
||||
| 過去 7 日間 | 直近 7 日間 |
|
||||
| 過去 30 日間 | 直近 30 日間 |
|
||||
|
||||
|
||||
|
||||
## トレンドグラフ
|
||||
|
||||
### リクエストトレンド
|
||||
|
||||
折れ線グラフでリクエスト数の変化傾向を表示：
|
||||
|
||||
- X 軸：時間
|
||||
- Y 軸：リクエスト数
|
||||
- 時間単位/日単位で表示可能
|
||||
- ズームとドラッグに対応
|
||||
|
||||
### Token トレンド
|
||||
|
||||
Token 使用量の変化を表示：
|
||||
|
||||
- 入力 Token（青）- ユーザーが送信した prompt の内容
|
||||
- 出力 Token（緑）- AI が生成した回答の内容
|
||||
- キャッシュ作成 Token（オレンジ）- 初回キャッシュ作成で消費された Token
|
||||
- キャッシュヒット Token（紫）- キャッシュ再利用で節約された Token
|
||||
- コスト（赤い破線、右側 Y 軸）- 推定費用
|
||||
|
||||
> **キャッシュ Token の説明**：Anthropic API は Prompt Caching 機能をサポートしています。キャッシュ作成時は高い料金（通常、入力価格の 1.25 倍）がかかりますが、その後のキャッシュヒット時は 0.1 倍の価格のみで、繰り返しリクエストのコストを大幅に削減できます。
|
||||
|
||||
### 時間粒度
|
||||
|
||||
- **今日**：時間単位で表示（24 データポイント）
|
||||
- **7 日間/30 日間**：日単位で表示
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## 詳細データ
|
||||
|
||||
ページ下部に 3 つのデータタブがあります：
|
||||
|
||||
### リクエストログ
|
||||
|
||||
各リクエストの詳細記録：
|
||||
|
||||
| フィールド | 説明 |
|
||||
|------|------|
|
||||
| 時間 | リクエスト時刻 |
|
||||
| プロバイダー | 使用されたプロバイダー名 |
|
||||
| モデル | リクエストされたモデル（課金モデル） |
|
||||
| 入力 Token | 入力の Token 数 |
|
||||
| 出力 Token | 出力の Token 数 |
|
||||
| キャッシュ読取 | キャッシュヒットの Token 数 |
|
||||
| キャッシュ作成 | キャッシュ作成の Token 数 |
|
||||
| 総費用 | 推定費用（ドル） |
|
||||
| 所要時間情報 | リクエスト時間、初回 Token 時間、ストリーム/非ストリーム |
|
||||
| ステータス | HTTP ステータスコード |
|
||||
|
||||
#### 所要時間情報の説明
|
||||
|
||||
所要時間情報列には複数のバッジが表示されます：
|
||||
|
||||
| バッジ | 説明 | 色のルール |
|
||||
|------|------|----------|
|
||||
| 総所要時間 | リクエストの総時間（秒） | ≤5s 緑、≤120s オレンジ、>120s 赤 |
|
||||
| 初回 Token | ストリームリクエストの最初の Token 時間 | ≤5s 緑、≤120s オレンジ、>120s 赤 |
|
||||
| ストリーム/非ストリーム | リクエストタイプ | ストリーム：青、非ストリーム：紫 |
|
||||
|
||||
#### 詳細の表示
|
||||
|
||||
リクエスト行をクリックすると詳細情報を表示：
|
||||
|
||||
- 完全なリクエストパラメータ
|
||||
- レスポンス内容のサマリー
|
||||
- エラー情報（失敗した場合）
|
||||
|
||||
#### ログのフィルタリング
|
||||
|
||||
以下の条件でフィルタリングできます：
|
||||
|
||||
| フィルタ項目 | オプション |
|
||||
|--------|------|
|
||||
| アプリタイプ | すべて / Claude / Codex / Gemini |
|
||||
| ステータスコード | すべて / 200 / 400 / 401 / 429 / 500 |
|
||||
| プロバイダー | テキスト検索 |
|
||||
| モデル | テキスト検索 |
|
||||
| 期間 | 開始時刻 - 終了時刻（日時ピッカー） |
|
||||
|
||||
操作ボタン：
|
||||
- **検索**：フィルタ条件を適用
|
||||
- **リセット**：デフォルトに戻す（過去 24 時間）
|
||||
- **更新**：データを再読み込み
|
||||
|
||||
|
||||
|
||||
### プロバイダー統計
|
||||
|
||||
プロバイダー別の集計データ：
|
||||
|
||||
| フィールド | 説明 |
|
||||
|------|------|
|
||||
| プロバイダー | プロバイダー名 |
|
||||
| リクエスト数 | そのプロバイダーの総リクエスト数 |
|
||||
| 成功数 | 成功したリクエスト数 |
|
||||
| 失敗数 | 失敗したリクエスト数 |
|
||||
| 成功率 | 成功の割合 |
|
||||
| 総 Token | Token 使用量の合計 |
|
||||
| 推定費用 | そのプロバイダーの費用 |
|
||||
|
||||
|
||||
|
||||
### モデル統計
|
||||
|
||||
モデル別の集計データ：
|
||||
|
||||
| フィールド | 説明 |
|
||||
|------|------|
|
||||
| モデル | モデル名 |
|
||||
| リクエスト数 | そのモデルの総リクエスト数 |
|
||||
| 入力 Token | 入力 Token の合計 |
|
||||
| 出力 Token | 出力 Token の合計 |
|
||||
| 平均レイテンシ | 平均応答時間 |
|
||||
| 推定費用 | そのモデルの費用 |
|
||||
|
||||
|
||||
|
||||
## 料金設定
|
||||
|
||||
### 料金設定を開く
|
||||
|
||||
設定 → 詳細 → 料金設定
|
||||
|
||||
### モデル価格の設定
|
||||
|
||||
各モデルの価格を設定（100 万 Token あたり）：
|
||||
|
||||
| フィールド | 説明 |
|
||||
|------|------|
|
||||
| モデル ID | モデル識別子（例：claude-3-sonnet） |
|
||||
| 表示名 | カスタム表示名 |
|
||||
| 入力価格 | 100 万入力 Token あたりの価格 |
|
||||
| 出力価格 | 100 万出力 Token あたりの価格 |
|
||||
| キャッシュ読取価格 | 100 万キャッシュヒット Token あたりの価格 |
|
||||
| キャッシュ作成価格 | 100 万キャッシュ作成 Token あたりの価格 |
|
||||
|
||||
### 操作
|
||||
|
||||
- **追加**：「追加」ボタンで新しいモデル価格を追加
|
||||
- **編集**：行末の編集アイコンで変更
|
||||
- **削除**：行末の削除アイコンで削除
|
||||
|
||||
|
||||
|
||||
### プリセット価格
|
||||
|
||||
CC Switch は一般的なモデルの公式価格（100 万 Token あたり）をプリセットしています：
|
||||
|
||||
**Claude シリーズ（ドル）**：
|
||||
|
||||
| モデル | 入力 | 出力 | キャッシュ読取 | キャッシュ作成 |
|
||||
|------|------|------|----------|----------|
|
||||
| **Claude 4.5 シリーズ** | | | | |
|
||||
| claude-opus-4-5 | $5 | $25 | $0.50 | $6.25 |
|
||||
| claude-sonnet-4-5 | $3 | $15 | $0.30 | $3.75 |
|
||||
| claude-haiku-4-5 | $1 | $5 | $0.10 | $1.25 |
|
||||
| **Claude 4 シリーズ** | | | | |
|
||||
| claude-opus-4 | $15 | $75 | $1.50 | $18.75 |
|
||||
| claude-opus-4-1 | $15 | $75 | $1.50 | $18.75 |
|
||||
| claude-sonnet-4 | $3 | $15 | $0.30 | $3.75 |
|
||||
| **Claude 3.5 シリーズ** | | | | |
|
||||
| claude-3-5-sonnet | $3 | $15 | $0.30 | $3.75 |
|
||||
| claude-3-5-haiku | $0.80 | $4 | $0.08 | $1.00 |
|
||||
|
||||
**OpenAI シリーズ / Codex（ドル）**：
|
||||
|
||||
| モデル | 入力 | 出力 | キャッシュ読取 |
|
||||
|------|------|------|----------|
|
||||
| **GPT-5.2 シリーズ** | | | |
|
||||
| gpt-5.2 | $1.75 | $14 | $0.175 |
|
||||
| **GPT-5.1 シリーズ** | | | |
|
||||
| gpt-5.1 | $1.25 | $10 | $0.125 |
|
||||
| **GPT-5 シリーズ** | | | |
|
||||
| gpt-5 | $1.25 | $10 | $0.125 |
|
||||
|
||||
> 注：Codex プリセットには low/medium/high などの変種が含まれており、価格はベースモデルと同一です。
|
||||
|
||||
**Gemini シリーズ（ドル）**：
|
||||
|
||||
| モデル | 入力 | 出力 | キャッシュ読取 |
|
||||
|------|------|------|----------|
|
||||
| **Gemini 3 シリーズ** | | | |
|
||||
| gemini-3-pro-preview | $2 | $12 | $0.20 |
|
||||
| gemini-3-flash-preview | $0.50 | $3 | $0.05 |
|
||||
| **Gemini 2.5 シリーズ** | | | |
|
||||
| gemini-2.5-pro | $1.25 | $10 | $0.125 |
|
||||
| gemini-2.5-flash | $0.30 | $2.50 | $0.03 |
|
||||
|
||||
**中国メーカーのモデル（人民元）**：
|
||||
|
||||
| モデル | 入力 | 出力 | キャッシュ読取 |
|
||||
|------|------|------|----------|
|
||||
| **DeepSeek** | | | |
|
||||
| deepseek-v3.2 | ¥2.00 | ¥3.00 | ¥0.40 |
|
||||
| deepseek-v3.1 | ¥4.00 | ¥12.00 | ¥0.80 |
|
||||
| deepseek-v3 | ¥2.00 | ¥8.00 | ¥0.40 |
|
||||
| **Kimi (月之暗面)** | | | |
|
||||
| kimi-k2-thinking | ¥4.00 | ¥16.00 | ¥1.00 |
|
||||
| kimi-k2 | ¥4.00 | ¥16.00 | ¥1.00 |
|
||||
| kimi-k2-turbo | ¥8.00 | ¥58.00 | ¥1.00 |
|
||||
| **MiniMax** | | | |
|
||||
| minimax-m2.1 | ¥2.10 | ¥8.40 | ¥0.21 |
|
||||
| minimax-m2.1-lightning | ¥2.10 | ¥16.80 | ¥0.21 |
|
||||
| **その他** | | | |
|
||||
| glm-4.7 | ¥2.00 | ¥8.00 | ¥0.40 |
|
||||
| doubao-seed-code | ¥1.20 | ¥8.00 | ¥0.24 |
|
||||
| mimo-v2-flash | 無料 | 無料 | - |
|
||||
|
||||
### カスタム価格
|
||||
|
||||
中継サービスを使用する場合、価格が異なる場合があります：
|
||||
|
||||
1. 「編集」ボタンをクリック
|
||||
2. 価格を変更
|
||||
3. 保存
|
||||
|
||||
## よくある質問
|
||||
|
||||
### 統計データが空
|
||||
|
||||
確認事項：
|
||||
- プロキシサービスが実行中か
|
||||
- アプリケーション接管が有効か
|
||||
- ログ記録が有効か
|
||||
- プロキシ経由でリクエストがあったか
|
||||
|
||||
### 費用の見積もりが不正確
|
||||
|
||||
考えられる原因：
|
||||
- 料金設定が実際と異なる
|
||||
- 中継サービスの特別な料金体系を使用
|
||||
|
||||
解決方法：
|
||||
- 料金設定を更新
|
||||
- プロバイダーの実際の請求書を参照
|
||||
|
||||
### Token 数がプロバイダーと一致しない
|
||||
|
||||
CC Switch は独自の方法で Token 数を推定しており、プロバイダーの計算方法と若干の差異が生じる場合があります。プロバイダーの請求書を基準にしてください。
|
||||
156
docs/user-manual/ja/4-proxy/4.5-model-test.md
Normal file
156
docs/user-manual/ja/4-proxy/4.5-model-test.md
Normal file
@@ -0,0 +1,156 @@
|
||||
# 4.5 モデルテスト
|
||||
|
||||
## 機能説明
|
||||
|
||||
モデルテスト機能は、プロバイダーに設定されたモデルが使用可能かどうかを確認するために、実際の API リクエストを送信してテストします：
|
||||
|
||||
- モデルが存在するか
|
||||
- API Key が有効か
|
||||
- エンドポイントが正常に応答するか
|
||||
- 応答レイテンシが正常か
|
||||
|
||||
## 設定を開く
|
||||
|
||||
設定 → 詳細 → モデルテスト
|
||||
|
||||
## テストモデルの設定
|
||||
|
||||
各アプリのテスト用モデルを設定します：
|
||||
|
||||
| アプリ | 設定項目 | デフォルト値 | 説明 |
|
||||
|------|--------|--------|------|
|
||||
| Claude | Claude モデル | システムデフォルト | Haiku シリーズの使用を推奨（低コスト・高速） |
|
||||
| Codex | Codex モデル | システムデフォルト | mini シリーズの使用を推奨 |
|
||||
| Gemini | Gemini モデル | システムデフォルト | Flash シリーズの使用を推奨 |
|
||||
|
||||
### モデル選択のアドバイス
|
||||
|
||||
テストモデルを選択する際の考慮事項：
|
||||
|
||||
1. **コスト**：低価格のモデルを選択（例：Haiku、Mini、Flash）
|
||||
2. **速度**：応答が速いモデルを選択
|
||||
3. **可用性**：プロバイダーがサポートしているモデルを選択
|
||||
|
||||
## テストパラメータの設定
|
||||
|
||||
### タイムアウト時間
|
||||
|
||||
| パラメータ | 説明 | デフォルト値 | 範囲 |
|
||||
|------|------|--------|------|
|
||||
| タイムアウト時間 | 1 回のリクエストのタイムアウト | 45 秒 | 10-120 秒 |
|
||||
|
||||
短すぎると誤判定の可能性があり、長すぎると障害検出が遅れます。
|
||||
|
||||
### リトライ回数
|
||||
|
||||
| パラメータ | 説明 | デフォルト値 | 範囲 |
|
||||
|------|------|--------|------|
|
||||
| 最大リトライ | 失敗時のリトライ回数 | 2 回 | 0-5 回 |
|
||||
|
||||
ネットワークが不安定な場合はリトライ回数を増やすことを推奨します。
|
||||
|
||||
### デグレード閾値
|
||||
|
||||
| パラメータ | 説明 | デフォルト値 | 範囲 |
|
||||
|------|------|--------|------|
|
||||
| デグレード閾値 | この時間を超えるとデグレードとマーク | 6000ms | 1000-30000ms |
|
||||
|
||||
閾値を超えたプロバイダーは「デグレード」状態としてマークされますが、引き続き使用可能です。
|
||||
|
||||
## モデルテストの実行
|
||||
|
||||
### 手動テスト
|
||||
|
||||
プロバイダーカードの「テスト」ボタンをクリックします：
|
||||
|
||||
1. 設定されたエンドポイントにテストリクエストを送信
|
||||
2. 設定されたテストモデルを使用
|
||||
3. レスポンスまたはタイムアウトを待機
|
||||
4. テスト結果を表示
|
||||
|
||||
### テスト内容
|
||||
|
||||
テストリクエストは：
|
||||
- 短い prompt（例："Hi"）を送信
|
||||
- 最大出力 Token を制限（通常 10-50）
|
||||
- ストリームレスポンスで初バイト時間を検出
|
||||
|
||||
## テスト結果
|
||||
|
||||
### ヘルスステータス
|
||||
|
||||
| ステータス | アイコン | 説明 |
|
||||
|------|------|------|
|
||||
| 健康 | 緑 | レスポンス正常、レイテンシが閾値内 |
|
||||
| デグレード | 黄 | レスポンス正常だが、レイテンシが閾値超過 |
|
||||
| 利用不可 | 赤 | リクエスト失敗またはタイムアウト |
|
||||
|
||||
### 結果情報
|
||||
|
||||
テスト完了後に表示：
|
||||
- 応答レイテンシ（ミリ秒）
|
||||
- 初バイト時間（TTFB）
|
||||
- エラー情報（失敗した場合）
|
||||
|
||||
## フェイルオーバーとの連携
|
||||
|
||||
モデルテストはフェイルオーバー機能と連携して使用します：
|
||||
|
||||
### ヘルスチェック
|
||||
|
||||
プロキシサービスを有効にすると、システムはフェイルオーバーキュー内のプロバイダーに対して定期的にヘルスチェックを実行します：
|
||||
|
||||
1. 設定されたテストモデルでリクエストを送信
|
||||
2. レスポンスに基づいてヘルスステータスを更新
|
||||
3. 不健康なプロバイダーは一時的にスキップ
|
||||
|
||||
### サーキットブレーカーからの復旧
|
||||
|
||||
プロバイダーがサーキットブレーカー状態から復旧する際：
|
||||
|
||||
1. モデルテストで可用性を確認
|
||||
2. テスト合格後、正常状態に復旧
|
||||
3. テスト不合格の場合、サーキットブレーカーを継続
|
||||
|
||||
## よくある質問
|
||||
|
||||
### テストは失敗するが実際には使用可能
|
||||
|
||||
**考えられる原因**：
|
||||
- テストモデルと実際に使用するモデルが異なる
|
||||
- プロバイダーが設定されたテストモデルをサポートしていない
|
||||
|
||||
**解決方法**：
|
||||
- テストモデルをプロバイダーがサポートするモデルに変更
|
||||
- プロバイダーのモデルリストを確認
|
||||
|
||||
### レイテンシが高すぎる
|
||||
|
||||
**考えられる原因**：
|
||||
- ネットワークレイテンシ
|
||||
- プロバイダーのサーバー負荷が高い
|
||||
- モデルの応答が遅い
|
||||
|
||||
**解決方法**：
|
||||
- より高速なテストモデルを使用
|
||||
- デグレード閾値を調整
|
||||
- ミラーエンドポイントの使用を検討
|
||||
|
||||
### 頻繁にタイムアウトする
|
||||
|
||||
**考えられる原因**：
|
||||
- タイムアウト時間の設定が短すぎる
|
||||
- ネットワークが不安定
|
||||
- プロバイダーのサービスが不安定
|
||||
|
||||
**解決方法**：
|
||||
- タイムアウト時間を延長
|
||||
- リトライ回数を増加
|
||||
- ネットワーク接続を確認
|
||||
|
||||
## 注意事項
|
||||
|
||||
- モデルテストは少量の API 枠を消費します
|
||||
- テストには低コストのモデルの使用を推奨
|
||||
- テスト頻度は高すぎないように、枠の浪費を避けてください
|
||||
- プロバイダーごとにサポートするモデルが異なる場合があります
|
||||
Reference in New Issue
Block a user