dify-knowledge-base-upload

Dify 知识库上传

在以下情况下使用此技能

• 目标 Dify 知识库由已发布的流水线数据源提供支持。
• UI 上传成功，但 document/create-by-file 或 create-by-text 返回 completed，且 0 chunks。
• 你需要上传一个本地文件，并可选择随后写入现有元数据字段。

准备调用方输入

• 提供要上传的本地文件路径。
• 对于纯文本，请先将其保存为 .txt 或 .md 文件，然后上传该文件。
• 设置调用方环境变量：
  • DIFY_API_BASE_URL
  • DIFY_DATASET_ID
  • DIFY_API_KEY
• 如果已发布的流水线公开了用户输入变量，可选择提供流水线 inputs JSON。
• 可选择提供元数据 JSON：
  • 一个将现有 Dify 元数据字段名称映射到值的扁平对象，或
  • 一个由 { "name": ..., "value": ... } / { "id": ..., "value": ... } 项组成的列表。
  • 此技能不会硬编码你的元数据架构。请在运行时提供当前字段名称或 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

解读响应

• 成功时会输出 JSON，其中包含 batch、document_id、file_upload_response、pipeline_run_response、indexing_status_response、document_response、可选的 metadata_response，以及 validation。
• 只有满足以下条件时，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 元数据字段名称。
• 使用 --dry-run 可在不调用 Dify 的情况下验证本地文件和请求格式。

快速排查问题

• 如果身份验证失败，请确认 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