Dify統合

概要

Dify は、オープンソースの大規模言語モデル（LLM）アプリケーション開発プラットフォームです。バックエンド・アズ・サービス（Backend as Service）と LLMOps の理念を融合し、開発者がプロダクションレベルの生成AIアプリケーションを迅速に構築できるようにします。

SERVICEME が提供する serviceme-rag-dify プラグインは、SERVICEME の強力なエンタープライズ向け検索拡張生成（RAG）機能をツールとして Dify のワークフローやアプリケーションに提供し、ユーザーが Dify 内で安全にエンタープライズナレッジベースへアクセスし、コンテキスト検索やQ&Aを実行できるようにします。

主な機能は以下の通りです：

• SERVICEME ワークスペースに対してハイブリッド、ベクトル、またはキーワード検索を実行可能。
• 構造化された回答、メタデータ、ワークスペースコンテキストを返し、後続ノードでの処理が容易。
• ワークスペース範囲、類似度閾値、ハイブリッド重み、リランカーモデルの設定をサポートし、企業のガバナンスポリシーに適合。
• OAuth トークンの状態を自動管理し、トークン更新後もツールの呼び出しを保証。

最低バージョンと前提条件

• 最低サポートバージョン：Dify ≥ 1.9.0
• アクセス可能な SERVICEME 環境、および OpenAPI 権限が有効化されていること
• SERVICEME OpenAPI 認証ガイド に従って作成された OAuth2 クレデンシャル（client_id、client_secret、ユーザーアカウント）
• カスタムプラグインのインポートと設定が可能な Dify ワークスペース権限

プラグインのインストール

Marketplace からインストール

1. Dify コンソール右上の Plugins > Install plugin > Marketplace をクリックします。

2. 検索ボックスに SERVICEME RAG と入力し、Enter キーを押します。

   

3. 最初の結果（SERVICEME RAG）にマウスを合わせ、Install をクリックします。

4. インストールが完了すると成功メッセージが表示され、プラグインが Plugins リストに自動的に追加されます。

   

GitHub からインストール

1. Dify コンソール右上の Plugins > Install plugin > GitHub をクリックします。

   

2. serviceme-rag-dify リポジトリのアドレス：https://github.com/medalsoftchina/serviceme-rag-dify を入力し、次へ をクリックします。

3. 該当バージョンとプラグインファイルを選択し、次へ をクリックします。

   

4. インストール完了後、Plugins リストでプラグインが表示されていることを確認します。

   

ローカル difypkg からインストール

1. GitHub リポジトリの Release ページにアクセスし、最新の serviceme-rag-dify.difypkg をダウンロードします。

2. Dify コンソールで Plugins > Install plugin > Local Package Plugin を選択し、ダウンロードしたインストールパッケージをアップロードします。

3. 成功すると、インストール成功のポップアップ画面が表示されます。

   

いずれのインストール方法でも機能は同一です。デプロイ環境のネットワークポリシーに応じて適切な方法を選択してください。

OAuth2 認証の設定

SERVICEME プラグインは OAuth2 方式で SERVICEME OpenAPI リソースにアクセスします。以下の手順で設定してください：

1. SERVICEME 管理画面でスーパ―管理者インターフェースに入り、システム管理者がクライアント管理画面 {domain}#/super-admin/client-management でクレデンシャルを作成し、client_id と client_secret を生成します。

   

2. Dify コンソールでプラグインをクリックし、サイドバーで Use OAuth Authorization をクリックします。

   

3. Vendor Configuration で SERVICEME 環境情報を入力し、Save and Authorize をクリックします：

   • Base URL：SERVICEME ドメイン（プロトコル含む）、例：https://example.serviceme.com
   • Client Id / Client Secret：クライアント管理画面で取得したクレデンシャル
   • Account：OpenAPI 呼び出し用の SERVICEME ユーザー名

   

4. 保存後、すべて正しく設定されていれば緑色の認証済み表示となります。プラグインは /openapi/auth/client_with_account を呼び出してアクセストークンを取得し、トークンの有効期限切れ時に自動で更新します。

   

認可制御を簡素化するため、ユーザーのロールによる SERVICEME データの可視範囲で OAuth の認可範囲を制御します。詳細はOpenAPI 章を参照してください。

Dify で SERVICEME RAG ツールを呼び出す

1. Dify の Studio に移動し、Chatflow ワークフローを作成してTest SERVICEMEと命名します。

   

2. キャンバスでAdd Node > Tools > serviceme-rag をクリックします。

   

3. Query String および/または Keywords を入力すると、このノードが実行可能になります。

   

4. デバッグ対話を実行し、ツールの返却結果が期待通りか確認します。

パラメータ説明

serviceme-rag ツールをノードに追加後、以下のパラメータで検索動作を調整できます：

入力項目	説明
query	オプション。自然言語クエリ。未入力の場合は keywords と併用可能。
keywords	オプション。キーワードは | で区切ります。
workspaces	オプション。検索範囲を限定する SERVICEME ワークスペースIDの配列。
top_k	必須。返却する結果数。
rag_object	必須。検索対象：both、qna、または doc。
rag_mode	必須。検索モード：hybrid、embedding、または fulltext。
min_similarity	オプション。類似度閾値。範囲は 0~1、デフォルトは 0.8。
metadata_filter	オプション。メタデータフィルタ。現在は default のみサポート。
weights	オプション。ハイブリッド検索用の RRF 重みを JSON で設定。
reranker	オプション。リランカーモデル名を指定。空欄の場合はリランカー無効。 注意：SERVICEME 環境でリランカーモデルが有効でない場合は必ず空欄にしてください

ベストプラクティス

• ビジネスシーンごとに独立した OAuth2 クライアントとスコープを作成し、権限の過剰付与リスクを低減。
• Dify のバージョン管理機能を活用し、本番環境リリース前にサンドボックス環境でプラグイン設定を検証。
• プラグインのログを定期的に確認し、呼び出し異常を早期発見。

よくある問題のトラブルシューティング

1. 認証失敗
   • client_id および client_secret が正しいか確認してください。
   • 指定したスコープのアカウントが該当 SERVICEME 環境で正しいロールを持っているか確認してください。
   • Dify サーバーが SERVICEME アドレスにアクセス可能か確認してください。
2. ツール呼び出しでデータが返らない
   • バインドされたデータソースが同期済みか確認してください。
   • 検索パラメータ（類似度閾値、リコール数など）を調整してください。
   • 呼び出しアカウントが対象データへのアクセス権限を持っているか確認してください。
3. プラグインインストール異常
   • Dify プラグインログでエラーメッセージを確認してください。
   • ローカルインストールの場合、difypkg ファイルが完全で Dify バージョンと互換性があるか確認してください。
   • 最新バージョンのパッケージを再ダウンロードして再試行してください。
4. サードパーティ署名
   • Dify サーバーがセルフホスト型で、サードパーティプラグイン署名が必要な場合は、Medalsoft（SoftwareOne subsidiary）の担当者に連絡し、署名済み公開鍵ファイルを取得してください。

さらなる参考資料

• serviceme-rag-dify GitHub リポジトリ
• Dify Plugins ドキュメント