このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、英語版 を参照してください。カスタム API スキャナーでスキャンするナレッジベースでは、アップロードされたファイルを Dify が自社のスキャンサービスに送信します。その後、サービスが返した判定結果に従って処理します。問題のないファイルは通常どおりインデックス化され、感染したファイルはブロックされます。 エンドポイントが稼働したら、連携 > ファイルセキュリティスキャン > スキャナーを追加 > カスタム API で追加します。ナレッジベースでスキャンを有効にする方法は、アップロードされたファイルのマルウェアスキャン を参照してください。
このスキャナーの種類は、連携 の カスタム API セクションとは別のものです。同セクションは API ベースの拡張機能を管理するもので、リクエストの形式も異なります。
ファイルの受信
Dify は、ファイルを 1 つずつ個別のリクエストで送信します。401 を返してください。
フォームには、ファイルと 5 つのテキストフィールドが含まれます。
このスキャンの ID です。Dify がスキャンを自動で再試行する際は、同じ ID が送信されます。そのため、同じリクエストが再び届いたときは、スキャンし直さずに初回の結果で応答できます。後からナレッジベースでドキュメントを再試行した場合は、新しい ID で新しいスキャンが始まります。
判定結果の返却
2xx のいずれかのステータスコードと、JSON オブジェクトを返します。
検出された脅威の名前です。ブロックされたドキュメントのエラーメッセージでユーザーに表示されます。省略した場合、メッセージには
unknown が検出されたと表示されます。Dify は最大 20 件の名前を保持し、それぞれ 200 文字を超える部分は切り捨てます。- サイズが大きすぎる場合:
413を返します。エラーメッセージには、ファイルがスキャナーのサイズ上限を超えていると表示されます。 - 暗号化されている、形式に対応していない、またはその他の理由の場合:
unscannableを返します。理由にかかわらず、エラーメッセージには、スキャナーがそのファイルに対応していないと表示されます。
ステータスコードの選び方
Dify は、返されたステータスコードとボディに基づいて、ファイルの扱いを決めます。一時的な過負荷で、再試行すれば処理できる見込みがある場合は、
429 ではなく 503 を返してください。制限時間内の応答
各リクエストには 2 分以内に応答してください。Docker Compose でデプロイしている場合、Dify のリクエストはプロキシを経由します。このプロキシは、2 分間応答がないリクエストを切断します。 このプロキシを経由しない場合は、Dify 自体のタイムアウトが上限になります。デフォルトは 300 秒で、FILE_SCAN_REQUEST_TIMEOUT_SECONDS で設定します。詳しくは 環境変数 を参照してください。
タイムアウトしたリクエストは再送され、試行回数はデフォルトで最大 3 回です。そのため、エンドポイントの応答が遅いと、ドキュメントが約 6 分(3 × 2 分)待たされることがあります。その後、ナレッジベースの スキャナーが利用できない場合 の設定が適用されます。
時間内に処理を終えられないとわかっている場合は、タイムアウトを待たずに、すぐに 413 または unscannable を返してください。
Dify からエンドポイントへの接続
Dify の エンドポイント URL には、http://scanner.example.internal:8000/scan のように、パスを含む完全な URL を入力します。localhost ではなく、Dify から到達できるアドレスを使用してください。
Docker Compose でデプロイしている場合、Dify のリクエストが経由するプロキシは、デフォルトで内部アドレスへの通信もブロックします。エンドポイントが内部アドレスを使っている場合、そのアドレスを許可するまで、Dify はエンドポイントに接続できず、スキャナーも保存できません。許可するには、次のように設定します。
- エンドポイント URL に IP アドレスを使う場合:
SSRF_PROXY_ALLOW_PRIVATE_IPSにそのアドレスを設定します。 - エンドポイント URL にホスト名を使う場合:
SSRF_PROXY_ALLOW_PRIVATE_DOMAINSにそのホスト名を設定します。
https の通信をポート 443 でのみ許可します。デプロイ環境で HTTP_REQUEST_NODE_SSL_VERIFY が false に設定されていない限り、Dify は https エンドポイントの TLS 証明書を検証します。
保存前のテスト
エンドポイントが動作しているマシンから、Dify と同じ形式のリクエストを送信します。file_name、file_size、mime_type を変更します。エンドポイントからは、1 回目に clean、2 回目に infected が返るはずです。
EICAR テストファイルは無害なファイルですが、どのウイルス対策エンジンもマルウェアとして検出します。eicar.org から入手できます。
infected:無期限に再利用されます。そのため、問題のないファイルをサービスが誤って検出した場合、スキャナーを修正した後もそのファイルはブロックされたままです。clean:デフォルトで 24 時間再利用されます(FILE_SCAN_CLEAN_VERDICT_TTL_HOURSで設定)。その間は、スキャナーを更新して検出できるようにしても、同じファイルはそのまま通過します。
file:clean-test.txt(text/plain)scan_id:connectivity-checkfile_hash:空
413 も合格です。Dify がスキャナーを保存するのは、確認に合格した場合だけです。
ナレッジベースでスキャナーを使い始めたら、そのナレッジベースに EICAR テストファイルをアップロード して、一連の処理全体を確認してください。
サンプルを基にした実装
次の Flask エンドポイントのmy_scanner を、独自のスキャンロジックに置き換えてください。
scanner.py
scanner.py として保存します。次に Flask をインストールし、Dify に入力する API キーを指定してエンドポイントを起動します。