Project Files
README.ja.md
RAG-Flex
LM Studio 用の柔軟な RAG（Retrieval-Augmented Generation）プラグインで、動的な埋め込みモデル選択、インテリジェントなコンテキスト管理、多言語サポートを提供します。
✨ 特徴
- 🔄 動的モデル選択: 4つの主要な埋め込みモデルから選択、ローカルモデルの自動検出
- 🧠 スマートコンテキスト管理: ファイルサイズに基づいて全文挿入または RAG 検索を自動決定
- 🌏 多言語サポート: 英語、繁体字中国語、日本語の完全な UI とメッセージ
- ⚙️ 柔軟な設定: 検索制限、類似度しきい値、コンテキスト使用率を調整可能
- 🛡️ 堅牢なエラー処理: AI フレンドリーなエラーメッセージでユーザーを解決に導く
- 🔧 開発者ツール: トラブルシューティングと開発のためのオプションのデバッグログ機能
🚀 クイックスタート
前提条件
- LM Studio（v0.2.9 以降）をインストール
- 少なくとも1つの埋め込みモデルをダウンロード:
- 推奨:
nomic-ai/nomic-embed-text-v1.5-GGUF（内蔵、高速） - 中国語/多言語:
lm-kit/bge-m3-gguf（遅いがより正確）
- 推奨:
インストール
LM Studio プラグインページからインストール（推奨）
- https://lmstudio.ai/yongwei/rag-flex にアクセス
- Run in LM Studio をクリック
- LM Studio が自動的に開き、プラグインをインストールします
GitHub からインストール（開発モード）
git clone https://github.com/henrychen95/rag-flex.git cd rag-flex lms dev
プラグインは自動的に LM Studio にロードされます。ターミナルに「Register with LM Studio」と表示されれば成功です。
📖 使用方法
基本的なワークフロー
- プラグインを有効化: LM Studio の設定で有効化（Plugins タブ）
- ドキュメントをアップロード: ファイル（PDF、DOCX、TXT、MD）をチャットにアップロード
- 質問する: RAG-Flex が自動的に:
- ファイルサイズとコンテキスト使用率を分析
- 全文挿入（小ファイル）または RAG 検索（大ファイル）を選択
- 関連チャンクを引用と共に返す
会話例
小ファイル（全文挿入モード）
📎 アップロード: 会議メモ.txt（5 KB） 💬 あなた: 「会議のアクションアイテムは何ですか？」 🤖 AI: [ドキュメント全体を確認] 「アクションアイテムは以下の通りです: 1. John が金曜日までに Q4 レポートを準備 2. Sarah がフォローアップ会議をスケジュール...」
大ファイル（RAG 検索モード）
📎 アップロード: 技術マニュアル.pdf（2 MB） 💬 あなた: 「SSL 証明書の設定方法は？」 🤖 AI: [関連セクションを検索] 「引用 1 と引用 3 に基づくと: SSL 証明書を設定するには...」 引用 1:（45 ページ）「SSL 設定には...」 引用 3:（89 ページ）「証明書インストール手順...」
⚙️ 設定オプション
LM Studio → Plugins → RAG-Flex でプラグイン設定にアクセス
| パラメータ | デフォルト | 範囲 | 説明 |
|---|---|---|---|
| メッセージ言語 | 自動検出 | EN/ZH-TW/JA | 実行時メッセージの言語 |
| 埋め込みモデル | nomic-ai/nomic-embed-text-v1.5 | 4つのプリセット | プリセットの埋め込みモデルから選択 |
| カスタム埋め込みモデル | （空欄） | テキスト入力 | 上記の選択を上書き。モデルキー（例：text-embedding-bge-m3）、識別子（例：lm-kit/bge-m3-gguf）、または完全パスを入力 |
| コンテキスト使用しきい値 | 0.7 | 0.1 - 1.0 | RAG 検索のトリガーポイント（低い = より精密） |
| 検索リミット | 5 | 1 - 15 | 検索時に返すチャンク数 |
| 検索親和性しきい値 | 0.4 | 0.0 - 1.0 | 類似度のしきい値（BGE-M3: 0.4-0.6 推奨） |
| デバッグログを有効化 | オフ | オン/オフ | デバッグログを有効化（開発者向け） |
| デバッグログのパス | ./logs/lmstudio-debug.log | カスタムパス | デバッグログファイルのパス |
埋め込みモデル比較
| モデル | サイズ | 速度 | 最適な用途 | 言語サポート |
|---|---|---|---|---|
| nomic-ai/nomic-embed-text-v1.5-GGUF | 84 MB | ⚡⚡⚡ 高速 | 英語、一般用途 | 英語 |
| NathanMad/sentence-transformers_all-MiniLM-L12-v2-gguf | 133 MB | ⚡⚡⚡ 高速 | 軽量タスク | 英語 |
| groonga/gte-large-Q4_K_M-GGUF | 216 MB | ⚡⚡ 中速 | バランス型 | 多言語 |
| lm-kit/bge-m3-gguf | 1.16 GB | ⚡ 低速 (F16) / ⚡⚡ 中速 (Q4) | 中国語、多言語、高精度 | 100+ 言語 |
注意: SDK の制限により、ドロップダウンにはプリセットモデルのみが表示されます。カスタム埋め込みモデルフィールドを使用して、モデルキー（例：text-embedding-qwen3-embedding-8b）、識別子、または完全パスを入力し、任意のダウンロード済みモデルを指定できます。
💡 ユースケースと例
📚 技術ドキュメント分析
シナリオ: ソフトウェア開発者が API ドキュメントを必要とする アップロード: FastAPI-documentation.pdf（3.2 MB） 質問: 「FastAPI がサポートする認証方法は？」 結果: RAG 検索モードが起動 ✓ 5つの関連引用を取得 ✓ JWT、OAuth2、API Key のセクションを発見 ✓ ドキュメントからコード例を提供 設定のヒント: - コンテキストしきい値: 0.7（デフォルト） - 検索リミット: 5-7（包括的なカバレッジ） - 親和性しきい値: 0.5（技術コンテンツ）
📄 法的文書レビュー
シナリオ: 弁護士が契約条件をレビュー アップロード: 商業リース契約.docx（250 KB） 質問: 「テナントのメンテナンス責任は？」 結果: 全文挿入モード（ファイルがしきい値内） ✓ ドキュメント全体がコンテキストとして挿入 ✓ AI が複数の条項を相互参照可能 ✓ 正確な条項番号付きの包括的な回答 設定のヒント: - コンテキストしきい値: 0.8（全文挿入を許可） - 言語: 繁體中文（中国語契約の場合）
💻 コード理解と分析
シナリオ: データベーススキーマの理解 アップロード: database-schema.sql（450 KB） 質問: 「users テーブルと orders テーブルの関係を説明して」 結果: RAG 検索（しきい値を下げる） ✓ 関連する CREATE TABLE ステートメントを取得 ✓ 外部キー制約を発見 ✓ 結合テーブルを識別 設定のヒント: - 親和性しきい値: 0.3-0.4（コード/SQL には低めの値） - 検索リミット: 8-10（関連テーブルをキャプチャ） - モデル: bge-m3（中国語コメント付きコードに適している）
🏛️ 政府文書処理
シナリオ: 公務員が申請を処理 アップロード: 補助金申請ガイドライン-2024.pdf（1.8 MB） 質問: 「申請資格の制限条件は何ですか？」 結果: 多言語 RAG 検索 ✓ 言語が繁体字中国語として自動検出 ✓ 資格基準セクションを取得 ✓ ページ番号と条項参照を含む引用 設定のヒント: - 言語: 繁體中文 - モデル: bge-m3（繁体字中国語に最適） - 親和性しきい値: 0.5-0.6
📊 研究論文分析
シナリオ: 大学院生が文献レビュー アップロード: 機械学習サーベイ論文-2024.pdf（4.5 MB） 質問: 「Transformer アーキテクチャの現在の課題は？」 結果: 精密 RAG 検索 ✓「課題」と「今後の課題」セクションを取得 ✓ 方法論セクションと相互参照 ✓ ページ番号付きの引用を提供 設定のヒント: - コンテキストしきい値: 0.6（大規模論文には RAG を強制） - 検索リミット: 10-15（多様な視点をキャプチャ） - モデル: gte-large（学術コンテンツに良好なバランス）
🔧 高度な設定ガイド
コンテキスト使用しきい値の理解
しきい値は、全文挿入から RAG 検索への切り替えタイミングを決定します:
利用可能なコンテキスト = 残りのコンテキスト × しきい値 if (ファイルトークン数 + プロンプトトークン数) > 利用可能なコンテキスト: → RAG 検索を使用（精密モード） else: → 全文挿入を使用（包括的モード）
調整するタイミング:
| しきい値 | 動作 | ユースケース |
|---|---|---|
| 0.3-0.5 | RAG をより頻繁に強制 | 大規模ドキュメント、メモリ制約 |
| 0.6-0.7 | バランス（デフォルト） | 一般用途 |
| 0.8-0.9 | より多くの全文挿入を許可 | 小規模ドキュメント、完全なコンテキストが必要 |
検索親和性しきい値の最適化
コンテンツタイプごとに異なる類似度しきい値が必要です:
| コンテンツタイプ | 推奨しきい値 | 理由 |
|---|---|---|
| 自然言語テキスト | 0.5-0.7 | 明確な意味的マッチング |
| 技術ドキュメント | 0.4-0.6 | 技術用語が変化する |
| コード/SQL | 0.3-0.4 | 構文が多く、意味的類似度が低い |
| 混合言語 | 0.4-0.5 | 言語切り替えを考慮 |
多言語設定
プラグインはシステム言語を自動的に検出し、UI を設定します:
- Windows: Intl API を使用してロケールを検出
- Linux/macOS:
LANG、LANGUAGE、LC_ALL環境変数を確認 - 手動上書き: プラグイン設定で「メッセージ言語」を変更
サポート言語:
- 🇬🇧 English (en)
- 🇹🇼 繁體中文 (zh-TW)
- 🇯🇵 日本語 (ja)
📖 開発者向け: 国際化システムの技術詳細、新しい言語の追加方法、翻訳ガイドラインについては I18N.ja.md を参照してください。English および 繁體中文 版もあります。
開発者モード: デバッグログ
トラブルシューティングまたは開発のためにデバッグログを有効化:
- LM Studio → Plugins → RAG-Flex 設定を開く
- 「デバッグログを有効化」を有効にする
- （オプション）カスタム「デバッグログのパス」を設定
- ログには以下が含まれます:
- システムロケール検出
- モデル読み込みイベント
- ファイル処理ステップ
- 検索結果
- エラースタックトレース
デフォルトのログ場所: ./logs/lmstudio-debug.log
🐛 トラブルシューティング
よくある問題
「❌ 埋め込みモデルが見つかりません」
原因: 選択したモデルが LM Studio でダウンロードされていない
解決方法:
- LM Studio → Search（🔍）を開く
- モデル名を検索（例:
bge-m3） - Download をクリック
- ダウンロードが完了するまで待つ
- チャットを再起動するか、プラグインをリロード
代替案: プラグイン設定で別のモデルを選択
「関連する引用が見つかりませんでした（しきい値: 0.4）」
原因: 検索親和性しきい値がコンテンツに対して高すぎる
解決方法:
- コード/SQL ファイル: しきい値を 0.3-0.4 に下げる
- 混合言語ドキュメント: 0.4-0.5 を試す
- 技術用語: 0.35-0.45 に下げる
調整方法: LM Studio → Plugins → RAG-Flex → 検索親和性しきい値
ファイル処理が遅い
原因: 大規模ファイルで高精度埋め込みモデルを使用
解決方法:
- より高速なモデルに切り替え:
bge-m3の代わりにnomic-embed-text-v1.5を使用- 英語コンテンツで 10-20倍 高速
- 検索リミットを下げる:
- 5 から 3 チャンクに削減
- 処理は高速だがコンテキストは少ない
- 大規模ファイルを分割:
-
5MB のファイルを章/セクションに分割
-
ランタイムメッセージの言語が正しくない
原因: システム言語の自動検出結果が設定と一致していない
解決方法:
- プラグイン設定を開く
- 「メッセージ言語」を手動で選択
- 選択: English (en) / 繁體中文 (zh-TW) / 日本語 (ja)
注意: この設定はプラグインのランタイムメッセージ（エラーメッセージ、ステータス更新など）のみに影響します。LM Studio の UI 言語は LM Studio 自体で制御されます。
デバッグログが作成されない
考えられる原因:
- 設定でデバッグログが有効になっていない
- ファイル書き込み権限が不足
- ログパスが無効
解決方法:
- プラグイン設定で「デバッグログを有効化」を有効にする
- ログパスが存在し、書き込み可能であることを確認
- デフォルトパスを試す:
./logs/lmstudio-debug.log - Windows では、パスが
\\または/を使用していることを確認
💡 プロのヒント: すべてのエラーメッセージは AI フレンドリー形式です - LLM チャットに直接貼り付けて自動トラブルシューティングできます！
📦 サポートされているファイル形式
| 形式 | 拡張子 | 処理方法 | 備考 |
|---|---|---|---|
.pdf | テキスト抽出 | テキストベースの PDF をサポート（スキャン画像は不可） | |
| Word ドキュメント | .docx | 完全なドキュメント解析 | 構造とフォーマットを保持 |
| プレーンテキスト | .txt | 直接読み取り | UTF-8 エンコーディング推奨 |
| Markdown | .md | Markdown 解析 | 見出し構造を維持 |
サポートされていない: 画像、音声、動画、Excel スプレッドシート、OCR なしのスキャン PDF
🆚 RAG-v1 からの改善点
| 機能 | RAG-v1 | RAG-Flex (v1.2.0) |
|---|---|---|
| 埋め込みモデル | ❌ ハードコード（nomic のみ） | ✅ 4つ選択可能 + 自動検出 |
| 多言語サポート | ❌ 英語のみ | ✅ English, 繁體中文, 日本語 |
| エラーメッセージ | ❌ 技術的な英語 | ✅ ユーザーフレンドリー、ローカライズ済み |
| コンテキスト管理 | ⚙️ 基本的なしきい値 | ✅ スマートしきい値ベース戦略 |
| 親和性しきい値 | ❌ 0.5 で固定 | ✅ 設定可能（0.0-1.0） |
| 結果なしの処理 | ❌ システムプロンプトを露出 | ✅ 優雅な劣化 |
| モデル検出 | ❌ 手動設定 | ✅ ローカルモデルを自動検出 |
| デバッグツール | ❌ なし | ✅ オプションのデバッグログ |
| 設定 UI | ⚙️ 英語のみ | ✅ 多言語（システム言語） |
🤝 貢献
貢献を歓迎します！以下の方法でお手伝いできます:
問題の報告
- GitHub Issues でバグを報告
- デバッグログを含める（最初にデバッグログを有効化）
- ファイルタイプ、サイズ、使用した設定を提供
コードの提出
- リポジトリをフォーク
- 機能ブランチを作成（
git checkout -b feature/amazing-feature） - 既存のコードスタイルに従う（適切な型の TypeScript）
- 複数の埋め込みモデルでテスト
- 必要に応じてドキュメントを更新
- 変更をコミット（
git commit -m 'Add amazing feature'） - ブランチにプッシュ（
git push origin feature/amazing-feature） - プルリクエストを開く
翻訳の追加
新しい言語を追加するには:
src/locales/types.tsに言語コードを追加- 翻訳ファイルを作成:
src/locales/[lang].ts src/locales/index.tsを更新src/config.tsの言語オプションを更新README.[lang].mdを作成
📝 ライセンス
MIT License - 詳細は LICENSE ファイルを参照
これは以下を意味します:
- ✅ 商用利用可能
- ✅ 修正と配布可能
- ✅ 私的利用可能
- ✅ サブライセンス可能
要件:
- ⚖️ 元のライセンスと著作権表示を含める
🙏 謝辞
- LM Studio チーム - 優れた SDK とプラグインエコシステム
- オリジナル RAG-v1 プラグイン - インスピレーションと基盤
- 埋め込みモデル作者:
- Nomic AI - nomic-embed-text-v1.5
- Sentence Transformers - all-MiniLM-L12-v2
- Groonga - gte-large
- 北京智源人工智能研究院 - BGE-M3
- Hugging Face コミュニティ - モデルホスティングと配布
- すべての貢献者 - 改善とフィードバックをありがとうございます！
📧 連絡先とリンク
作者: Henry Chen GitHub: @henrychen95 リポジトリ: rag-flex LM Studio プラグインページ: lmstudio.ai/yongwei/rag-flex
コミュニティ
- 🐛 バグ報告: GitHub Issues
- 💡 機能リクエスト: GitHub Discussions
- 📖 ドキュメント: Wiki
⭐ RAG-Flex がワークフローに役立つ場合は、リポジトリにスターをお願いします！
LM Studio コミュニティのために ❤️ を込めて作成