dify-knowledge-base-upload

用途

本技能用于将本地文件上传到 Dify 知识库，前提是该知识库由已发布的 pipeline 数据源（datasource）支撑。它适用于以下场景：

目标 Dify 知识库背后是已发布的 pipeline 数据源。
通过 UI 上传成功，但使用 document/create-by-file 或 create-by-text 接口时返回 completed 且 0 chunks。
需要上传一个本地文件，并可选地在之后写入已有的元数据字段。

主要能力

发现已发布的数据源插件。
上传本地文件到 Dify pipeline。
运行已发布的 pipeline。
轮询文档索引状态。
获取文档详情。
可选地解析元数据字段名称。
可选地更新文档元数据。

使用方式

准备调用方输入

提供要上传的本地文件路径。
对于纯文本，先保存为 .txt 或 .md 文件再上传。
设置调用方环境变量：
- DIFY_API_BASE_URL
- DIFY_DATASET_ID
- DIFY_API_KEY
可选：如果已发布的 pipeline 暴露了用户输入变量，提供 pipeline 输入 JSON。
可选：提供元数据 JSON，格式为：
- 扁平对象，映射已有 Dify 元数据字段名到值；或
- 列表，包含 { "name": ..., "value": ... } 或 { "id": ..., "value": ... } 项。

该技能不硬编码元数据 schema，需在运行时传入当前字段名或 id。

运行工作流

使用 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 运行已发布的 pipeline。
轮询 ${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

带 pipeline 输入上传：

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，则 tokens 也应大于 0。部分 pipeline 部署可能将 tokens 留为 null，脚本会将其报告为警告而非硬失败。

如果必需检查失败，脚本以非零状态退出。

如果省略 --metadata-json，脚本仅上传文件并跳过元数据 API 调用。

元数据键必须已存在于目标数据集中。未知名称会在元数据写入请求前快速失败。

assets/example-metadata.json 仅为模板，实际使用前需将其键替换为已有的 Dify 元数据字段名。

使用 --dry-run 可在不调用 Dify 的情况下验证本地文件和请求结构。

适用场景

需要将本地文件上传到由已发布 pipeline 数据源支撑的 Dify 知识库。
通过常规 API 上传遇到 0 chunks 问题，需要走 pipeline 数据源流程。
上传后需要写入已有元数据字段。

限制

如果已发布的数据源不是 local_file，则本技能不是正确的上传工具。
元数据键必须已存在于目标数据集中，否则会失败。
如果只有原始文本，需先保存为 .txt 或 .md 再上传。
在当前测试部署中，.md 上传成功，而 .txt 遇到 Dify 侧索引 400 错误。如果纯文本以 .txt 失败，可重试为 .md。

故障排查

如果认证失败，检查 DIFY_API_KEY 和 Authorization 头格式。
如果数据源发现失败，确认数据集有已发布的 pipeline 数据源，且密钥属于该数据集。
如果 pipeline 运行因缺少输入而失败，检查 discovery_response 中的 user_input_variables，并在 --inputs-json 中传入缺失的键。
如果元数据解析失败，将元数据 JSON 中的键重命名为 Dify 中定义的精确字段名。

参考与资源

references/env.md
references/request-response.md
references/testing.md
assets/example-pipeline-inputs.json
assets/example-metadata.json