📝

Dify (Cloud版) v1.9.2 「ナレッジパイプライン」経由で「メタデータフィルタ」機能を利用した際のバグ検証レポート

に公開
メタデータ
Dify
ナレッジパイプライン
メタデータフィルタリング
tech

Difyの「メタデータフィルタ」機能が便利そうだったので試してみました。

ところが、「ナレッジパイプライン」機能でナレッジベースを作成したDSLファイルをエクスポート・インポートして構築したナレッジベースで、メタデータフィルタリングを適用しようとしたところ、Dify v1.9.2（Cloud版）ではバグがあるようで、利用できませんでした。

さらに、「ナレッジパイプライン」機能で直接作成したナレッジベースに対しても、同様にメタデータフィルタリングを試みたところ、エラーが発生しました。
調べてみると、この問題はGitHub Issueでも報告されており、2025年11月2日現在のクラウド最新版（v1.9.2）において改善されておりませんでしたので注意が必要でございます。
https://github.com/langgenius/dify/issues/27427

本来であれば、UI上からポチポチと手軽にメタデータを設定できることを期待していましたが、
現状では画面からは設定が反映されず、代わりに「ナレッジベースAPI」経由ならうまくいくかもしれないと思い、APIでも検証してみました。しかし、結論としてはAPI経由でもエラーのままでした。ちなみに、通常の「ナレッジベースから作成」で作成したナレッジベースに対しては、メタデータフィルタリング機能は動作できたことを確認しました。

メタデータフィルタリング機能についての理解を深めるため、これらの不具合の再現手順をまとめてみました。

Dify バージョン

  • 1.9.2
  • クラウド版
  • 2025/11/2 現在

エラーの発生した画面

「ナレッジパイプライン」経由で作成したナレッジベースに対して、「メタデータフィルタ」を設定すると、以下のように、「Internal Server Error」が発生して、登録したドキュメントが全部消えるバグが発生しています。

目的

  • Dify v1.1.0 で導入された「メタデータフィルタリング機能」を試す。
    しかし、クラウド版の最新版v1.9.2(2025年11月2日現在）では、以下の不具合が発生している：
    • 「ナレッジパイプライン」経由で作成したナレッジベースからメタデータを設定すると 500エラーが発生し、ドキュメントが消える。
    • 組み込みフィルタリングをオンにしても 適用されない。
  • そこで、「ナレッジベースAPI」経由であれば成功するのではないかと考え、APIからの操作も検証した。

結論

凡例： 〇=メタデータフィルタリングが使えた / ×=エラー

対象 UI操作
（ナレッジ画面）		 API経由
（ナレッジAPI）
「ナレッジパイプライン」経由 × ×
「ナレッジベースから作成」ボタン 〇 〇

□「ナレッジパイプライン」経由で「メタデータフィルタリング」について

  • クラウド版Dify の最新1.9.2 では、「ナレッジパイプライン」経由で「メタデータフィルタリング」がエラーが発生して利用できない。
    • メタデータを付与しようと設定すると、登録済みドキュメントが全部消えてしまう。
    • 本来、組み込みのメタデータフィルタについて、トグルボタンでオンにしても、設定が反映されない
  • 「ナレッジベースAPI」経由でも同様のバグで、同じ現象が発生することを確認。
  • まとめると、エラーが発生したパターンは以下です。
    • 「知識パイプラインから作成する」ボタンから作成した場合
    • 事前に作成した「ナレッジパイプライン」をエクスポートしたファイル(拡張子が.pipline)からインポート機能で作成した場合
    • 「ナレッジベースAPI」の「メタデータフィルタリング」関連の操作を行った場合
  • ただし、通常の「ナレッジベースから作成」ボタンより作成したナレッジベースに関しては、メタデータフィルタリングが利用できました。

□「ナレッジベースAPI」による「メタデータフィルタリング」について

  • 現状、「ナレッジベースAPI」には メタデータを条件に検索（フィルタリング）できるAPIが提供されていないようです。
  • GitHub Issue でも取り上げられていましたが、既にcloseされていましたので、今のところAPIに実装予定はないようです。
  • 一方で、メタデータそのものを作成・付与するAPI は存在し、ドキュメントやチャンク（文章の分割単位）に対してメタデータを設定することは可能です。つまり、「メタデータを登録することはできるが、その値を使って検索・抽出することは現時点ではできない」という状態のようです。
  • 以下のURLで「metadata」でキーワード検索しましたが、フィルタリング機能を使った検索の項目は存在しませんでした。あとAIで検索しても同様の結果でした。
  • よって、UI上の「知識ノード」でフィルタリングするか、自前でコードでフィルタ処理を実装する必要がありそうです。

再現手順

成功パターン　再現手順

□「ナレッジベースを作成」ボタンから作成した場合は、メタデータフィルタリング機能は成功しました。

  • 「ナレッジ」一覧ページの「ナレッジベースを作成」からナレッジベースを作成する

  • 任意のファイルをアップロードして、「次へ」を押す

  • チャンク設定等は、任意で設定する

  • ナレッジ一覧ページからメタデータをクリックします。

  • 「メタデータを追加」から以下のようにメタデータ項目を作成します。(名称は任意)

  • 組み込みのトグルをオンにします。

  • 次に、ドキュメントの詳細ページに行って、「ラベリングを開始」ボタンを押下します。

  • 「メタデータを追加」「{作成したメタデータ項目}」を選択します。

  • 任意の値を入力して、保存を押します。

  • チャットアプリで、「知識検索ノード」の「メタデータフィルタ条件」で「である」と登録済みのメタデータの値を設定してみると、フィルタリングは機能しているようでした。

  • 「知識検索」ノードでのテスト実行でレスポンスが返ってきていました。

  • メタデータフィルタ条件を「でない」にして、再度テスト実行してみます。

  • レスポンスが空なので、メタデータフィルタ条件の機能が動作していると思われます。

失敗パターン　再現手順

□「知識パイプラインから作成する」ボタンから(または、知識パイプラインからのDSLファイルのインポート)ナレッジベースを作成した場合、エラーが発生し 失敗しました。

  • ナレッジのトップページから「知識パイプラインから作成する」ボタンを選択します。

  • 任意のパターンで「ナレッジパイプライン」からナレッジベースを作成します。今回は、「一般文書処理」を選択しました。

  • 「公開する」「更新を公開」した後、「ドキュメントを追加するために… 」を押します。

  • データソースを選択します。

  • 設定方法については、各プラグインの詳細ページの手順に従って設定します。

  • 以前のこちらの記事で、一部データソースについて設定手順を整理してみました。

  • 今回は、Google Drive から任意のファイルを選択しました。

  • 「保存して処理する」

  • 「ドキュメントに移動」

  • ナレッジ一覧ページからメタデータをクリックします。

  • 「メタデータを追加」から以下のようにメタデータ項目を作成します。(名称は任意)

  • メタデータの項目を追加して、「組み込み」トグルをオンにして、ブラウザ更新します。(本来自動で保存される)

  • ブラウザ更新すると、組み込みをオンにしたはずが、リセットされてしまう。(ここがバグ)

  • 次に、ドキュメントの詳細ページに行って、「ラベリングを開始」ボタンを押下します。

  • 「メタデータを追加」「{作成したメタデータ項目}」を選択します。

  • 任意の値を入力して、保存を押します。

  • すると、Internal Server Errorとダイアログが表示され、 内部エラーが発生します。(ここがバグ)

  • 他の画面に遷移してもエラーがで続けるので、ブラウザ更新して、ドキュメントページに戻ってみると、データがなぜかすべて消えてしまいました。

  • (この場合、ナレッジベース自体を削除するしかないようで、ナレッジベースを削除します。そのため、重要なナレッジベースの場合はご注意ください。)

ナレッジベースAPIを利用した場合の再現手順

※ナレッジベースAPIキーの場所が、変わったようでしたので、改めて手順を整理してみました。

  • https://cloud.dify.ai/datasets　の自身のナレッジのページにアクセスし、「ナレッジパイプライン」経由で、ナレッジベースを作成します。（前述の手順と同様）

  • ナレッジ一覧ページの以下画面より「ナレッジAPIキー」を作成し、控えておきます。

  • 任意のファイルを追加して、データを登録します。

  • 登録したドキュメントを選択して、ブラウザのURLから、「dataset_id」「document_id」を取得します。のちに使いますので控えておきます。

https://cloud.dify.ai/datasets/{dataset_id}/documents/{document_id}

  • ナレッジベースを操作するための コマンドを公式ドキュメントから調べます。

  • 公式のAPIレファレンスページに飛ぶので、サイドバーから使いたいAPIを選択します。今回はメタデータ関連を使ってみたいので、メタデータ関連のAPIを選択して、「Try it」ボタンを押下します。

  • 先ほど取得したナレッジAPIキーを設定して、「Send」ボタンを押下すると、ブラウザ上で直接APIの動作確認ができて大変便利と感じました。

  • しかし、成功するはずでしたが、エラーとなりました。

エラー内容
  • エラー内容
{"code":"not_found","message":"Dataset not found. 
You have requested this URI [\/v1\/datasets\/tags] but did you mean \/v1\/datasets\/tags or \/v1\/datasets\/<uuid:dataset_id>\/tags or \/v1\/datasets\/<uuid:dataset_id>\/documents\/<uuid:document_id>\/segments\/<uuid:segment_id>\/child_chunks\/<uuid:child_chunk_id> ?","status":404}

データセットが見つかりません。
あなたがリクエストしたURI（アドレス）/v1/datasets/tags は存在しません。
もしかして次のどれかのURLを意味していますか？

/v1/datasets/tags
/v1/datasets/{dataset_id}/tags
/v1/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}

ステータスコード: 404
番号 意味 よくある場面
200 OK（成功） 通信成功・データ取得できた
400 Bad Request（リクエストが間違い） パラメータが不正など
401 Unauthorized（認証エラー） APIキーが無効など
404 Not Found（見つからない） URLが間違っている・存在しない
500 Internal Server Error（サーバ内部エラー） サーバ側でバグ・障害

  • 他のAPIを試すと成功しており、API_KEY などは間違っていませんでした。

  • 404 は、URLが間違っているか、存在しないということですが、他のAPIは成功することと、以下の公式ドキュメントの記載のcurlコマンドは成功しましたので、公式のAPIレファレンスページが間違っているのではと考えられます。2025/11/2 現在 https://docs.dify.ai/api-reference　の APIレファレンスのページはどうやら自動生成されているようで、更新が追い付いていないようです。(今後改善されているかもしれません)

  • 「APIレファレンス」ページではなく、以下のページの「公式ドキュメント」の内容で、試したところターミナルでは動きました(ただし、「ナレッジパイプライン」経由の場合、メタデータフィルタリング関連のAPIはバグにより同じく500エラーになりました)

https://docs.dify.ai/ja-jp/guides/knowledge-base/knowledge-and-documents-maintenance/maintain-dataset-via-api

  • そこで、ターミナル上で、APIをたたいて、動作確認してみます。
  • Linux 環境でしたら、公式ドキュメントやAPIレファレンスページ(metadataの箇所を除く)のcurl 文をそのままコピペしてAPIキー等を設定するとうまくいくと思われます。
  • わたしがWindows 環境で、Windowsのコマンドプロンプトで確認したため、以下のようにcurlコマンドを変更しました。(chat gpt 利用)
  • 以下のcurlコマンドは成功したことを確認しました。※{dataset_id}、{document_id}、{api_key} は、事前に取得した自身の値に置き換えます。
Windows CMD用curlコマンド
# ナレッジベースのドキュメントリストを取得
curl -X GET "https://api.dify.ai/v1/datasets/{dataset_id}/documents?page=1&limit=20"^
 -H "Authorization: Bearer {api_key}" 

# dataset_id（ナレッジベースのID）を取得 
curl --request GET ^
  --url "https://api.dify.ai/v1/datasets" ^
  --header "Authorization: Bearer {api_key}" 
 
# ドキュメントIDの取得 
curl --request GET ^
  --url "https://api.dify.ai/v1/datasets/{dataset_id}/documents" ^
  --header "Authorization: {api_key}"

# データセットのメタデータリスト
curl -X GET "https://api.dify.ai/v1/datasets/{dataset_id}/metadata"^
 -H "Authorization: Bearer {api_key}"

# メタデータフィルタの追加　
curl --request POST ^
  --url https://api.dify.ai/v1/datasets/{dataset_id}/metadata ^
  --header "Content-Type: application/json" ^
  --header "Authorization: Bearer {api_key}" ^
  --data "{\"type\":\"string\",\"name\":\"test\"}"

# ナレッジベースのメタデータにある組み込みフィールドを有効化/無効化する 
curl --request POST ^
  --url "https://api.dify.ai/v1/datasets/{dataset_id}/metadata/built-in/**enable**" ^
  --header "Authorization: Bearer {api_key}"

# メタデータ項目（metadata_id）を取得
curl --request GET ^
  --url "https://api.dify.ai/v1/datasets/{dataset_id}/metadata" ^
  --header "Authorization: Bearer {api_key}"

# ドキュメントのメタデータを修正する（値の割り当て）
# {metadata_id}には、上記で取得したidを設定する
curl --request POST ^
  --url "https://api.dify.ai/v1/datasets/{dataset_id}/documents/metadata" ^
  --header "Content-Type: application/json" ^
  --header "Authorization: Bearer {api_key}" ^
  --data "{\"operation_data\":[{\"document_id\":\"{document_id}\",\"metadata_list\":[{\"id\":\"{metadata_id}\",\"value\":\"dify\",\"name\":\"test\"}]}]}"

  • 以下レスポンスの一例です。
    ※jq を使って見やすくなるように整形しています(jqをインストールして末尾に「|jq」を付ける)

  • 「メタデータフィルタの追加」APIは正常にできました。

  • しかし、「ナレッジベースのメタデータにある組み込みフィールドを有効化/無効化する 」「ドキュメントのメタデータを修正する（値の割り当て）」APIは、ターミナル上では、200で成功になりましたが、クラウド版の画面をみると、同様の500エラーが表示されており、登録済みのドキュメントが勝手に消えてしまいます。

  • APIで試しても同様のバグが発生していることを確認しました。

  • 「ナレッジパイプライン」経由で作成した「ナレッジベース」に対して、「ナレッジベースAPI」を操作すると、エラーが発生しましたが、もともとあった「ナレッジベースから作成」で作成したナレッジベースに対して、「ナレッジベースAPI」のメタデータフィルタ関連のAPIを試すと正常に動作していたことを確認しました。

エラー対応検討案

  • ローカル版のDify でバージョンをダウングレードして試す(未検証)
  • メタデータの管理をDify 側で管理するのではなく、外部のスプレッドシートなどで管理する(未検証。ただし、手間が増えそう)
  • 公式のバグが改善されるまで待ち、その間、ナレッジパイプライン機能でナレッジベースを作成しない
  • ローカルのソースコードを分析して、バグの原因を調査する(勉強になりそうだが時間や難易度が高そう)

参考サイト

  • 公式ドキュメント

https://docs.dify.ai/ja-jp/guides/knowledge-base/knowledge-and-documents-maintenance/maintain-dataset-via-api

https://docs.dify.ai/en/guides/knowledge-base/knowledge-and-documents-maintenance/maintain-dataset-via-api#metadata-list-of-the-dataset

  • 公式APIレファレンス

https://docs.dify.ai/api-reference/メタデータ・タグ/ナレッジベースタイプタグを取得

Discussion