dify-knowledge-base-upload

Dify ナレッジベースへのアップロード

このスキルを使う場合

• 対象の Dify ナレッジベースが、公開済みのパイプラインデータソースを使用している場合。
• UI からのアップロードは成功するものの、document/create-by-file または create-by-text で completed になり、0 chunks が返される場合。
• ローカルファイルを 1 つアップロードし、必要に応じて既存のメタデータフィールドを後から書き込む場合。

呼び出し元側の入力を準備する

• アップロードするローカルファイルのパスを指定します。
• テキストのみの場合は、まず .txt または .md として保存し、そのファイルをアップロードします。
• 呼び出し元の環境変数を設定します。
  • DIFY_API_BASE_URL
  • DIFY_DATASET_ID
  • DIFY_API_KEY
• 公開済みのパイプラインでユーザー入力変数が公開されている場合は、パイプラインの inputs JSON を指定できます。
• メタデータ JSON を指定できます。
  • 既存の Dify メタデータフィールド名を値に対応付けるフラットなオブジェクト、または
  • { "name": ..., "value": ... } / { "id": ..., "value": ... } の項目のリスト。
  • このスキルではメタデータスキーマをハードコードしません。実行時に指定する JSON に、現在のフィールド名または ID を渡してください。
• 環境変数やデバッグの詳細が必要な場合にのみ、references/env.md を読みます。

ワークフローを実行する

• scripts/upload_to_dataset.py を使用して、以下を実行します。
  • ${DIFY_API_BASE_URL}/datasets/${DIFY_DATASET_ID}/pipeline/datasource-plugins?is_published=true から公開済みのデータソースプラグインを検出する
  • ファイルを ${DIFY_API_BASE_URL}/datasets/pipeline/file-upload にアップロードする
  • ${DIFY_API_BASE_URL}/datasets/${DIFY_DATASET_ID}/pipeline/run を通じて公開済みのパイプラインを実行する
  • ${DIFY_API_BASE_URL}/datasets/${DIFY_DATASET_ID}/documents/{batch}/indexing-status をポーリングする
  • ${DIFY_API_BASE_URL}/datasets/${DIFY_DATASET_ID}/documents/{document_id}?metadata=without を取得する
  • 必要に応じて ${DIFY_API_BASE_URL}/datasets/${DIFY_DATASET_ID}/metadata を通じてメタデータフィールド名を解決する
  • 必要に応じて ${DIFY_API_BASE_URL}/datasets/${DIFY_DATASET_ID}/documents/metadata を通じてメタデータを更新する
• メタデータなしでアップロードします。

python3 scripts/upload_to_dataset.py \
  --file /path/to/document.pdf

• パイプライン入力を指定してアップロードします。

python3 scripts/upload_to_dataset.py \
  --file /path/to/document.pdf \
  --inputs-json assets/example-pipeline-inputs.json

• アップロード後にメタデータを適用します。

python3 scripts/upload_to_dataset.py \
  --file /path/to/document.pdf \
  --metadata-json assets/example-metadata.json

レスポンスを解釈する

• 成功すると、batch、document_id、file_upload_response、pipeline_run_response、indexing_status_response、document_response、任意の metadata_response、および validation を含む JSON が出力されます。
• validation.ok が true になるのは、以下を満たす場合のみです。
  • indexing_status = "completed"
  • total_segments > 0
  • segment_count > 0
• ドキュメント詳細 API から tokens が返される場合、その値も 0 より大きい必要があります。一部のパイプラインデプロイでは tokens = null のままとなるため、スクリプトはハードエラーではなく警告として報告します。
• 必須チェックに失敗すると、スクリプトはゼロ以外の終了コードで終了します。
• --metadata-json を省略すると、ファイルのみをアップロードし、メタデータ API の呼び出しはスキップします。
• メタデータキーは、対象のデータセットにすでに存在している必要があります。不明な名前がある場合、メタデータ書き込みリクエストを送信する前にエラーになります。
• assets/example-metadata.json はテンプレートにすぎません。実際に使用する前に、キーを既存の Dify メタデータフィールド名に置き換えてください。
• Dify にリクエストを送信せずにローカルファイルとリクエストの形式を検証するには、--dry-run を使用します。

すぐにトラブルシューティングする

• 認証に失敗する場合は、DIFY_API_KEY と Authorization ヘッダーの形式を確認してください。
• データソースの検出に失敗する場合は、データセットに公開済みのパイプラインデータソースがあること、およびキーがそのデータセットに属していることを確認してください。
• パイプラインの実行で入力不足のエラーが発生する場合は、discovery_response の user_input_variables を確認し、不足しているキーを --inputs-json に渡してください。
• 公開済みのデータソースが local_file でない場合、このスキルは適切なアップローダーではありません。
• メタデータの解決に失敗する場合は、メタデータ JSON のキーを Dify で定義されている正確なフィールド名に変更してください。
• テキストしかない場合は、.txt または .md に保存してから、そのファイルをアップロードしてください。
• 現在のテスト済みデプロイでは、.md は正常にアップロードされましたが、.txt は Dify 側のインデックス作成で 400 エラーになりました。.txt のプレーンテキストで失敗する場合は、.md として再試行してください。

リファレンス

• references/env.md
• references/request-response.md
• references/testing.md

Assets

• assets/example-pipeline-inputs.json
• assets/example-metadata.json