文档目录 → 自动遍历 → 批量上传 → 索引轮询 → 完成
Dify 1.13.3
测试通过
Python 3.13+
源码运行
Windows
GUI 客户端
macOS / Linux
跨平台支持
Dify 知识库上传界面在批量上传大量文件时操作较繁琐——需要手动逐个选择、上传、等待解析。本工具自动遍历指定目录及子目录，将文档逐个上传到知识库并轮询索引进度，减少手动分批上传与等待解析的耗时。
功能完整的批量上传工具，覆盖从遍历到索引完成的整个流程
自动遍历文档目录及子目录，将所有支持的文档文件批量上传到 Dify 知识库。支持 .md、.txt、.pdf、.docx 等多种格式（由 DOC_SUFFIX 配置）。
上传后通过官方 API 轮询索引进度，支持阶段显示（排队中 → 解析中 → 清洗中 → 切分中 → 索引中 → 已完成）。一个文件索引完成后再处理下一个。
自动记录每个文件的处理状态（待处理 / 已上传 / 索引中 / 完成 / 失败）。中断后重新运行会自动跳过已完成的文件，仅继续处理未完成或失败的文件。
即使进度记录丢失，也会通过 API 查询文档是否已存在，避免重复上传。对已存在但未完成索引的文档，自动恢复轮询。
支持为文档设置自定义元数据——创建同名 .meta.json 文件，工具自动按 key 创建知识库元数据字段并赋值。
知识库不存在时可选按名称自动创建。仅凭一个 dataset- 开头的 API Key 即可运行。
无需数据库依赖，不直连 Dify 后端数据库，仅使用官方知识库 API，部署简单、安全可靠。
独立记录每次 Dify API 请求（地址 / 请求头脱敏 / 请求体 / 响应），便于排查问题。敏感字段（auth/token/secret/password）自动脱敏。日志按天切割，保留 30 天。
提供 基于 customtkinter 的图形界面客户端，可在 Releases 页面下载编译好的 Windows / macOS / Linux 可执行程序，启动后直接在界面填写配置，无需手动编辑配置文件。
简单六步，从配置到完成
填入 Dify API 地址和 dataset- 开头的 API Key
配置文档所在目录和文件后缀
工具遍历目录及子目录，筛选符合条件的文档
检查去重后，通过 create-by-file 接口上传
轮询索引进度，等待当前文件完成
记录处理状态，完成后处理下一个文件
纯 API 模式，安全可靠的工作流程
指定文件夹
递归遍历
Dify API
状态监控
文档入库
工具仅使用 Dify 官方知识库 API，无需数据库依赖，不直连 Dify 后端数据库。这种设计确保了部署简单、安全可靠，适用于自部署 Dify 或 Dify Cloud（需开启知识库 API）。
选择适合你的使用方式
git clone https://github.com/Samge0/dify-upload
pip install -r requirements.txt
configs.demo.py → configs.py 并填写配置
python -m difys.main
需要 Python 3.13+ 环境
无需技术背景，适合所有用户
快速找到你问题的答案
在项目根目录使用 -m 方式运行：python -m difys.main，或配置 PYTHONPATH 环境变量。
检查 API_KEY 是否正确（需 dataset- 开头）、是否有效，以及 API_URL 是否包含 /v1。
向空知识库添加第一个文档时必须指定 INDEXING_TECHNIQUE（high_quality 或 economy）。