核心功能：上传文件即自动处理 — 将原始文档放入 raw_data/ 目录（或通过 API 上传），系统自动完成读取→清洗→AI语义分割→保存本地→上传 Dify 知识库，全流程无需人工干预。
🚀 推荐使用 API 方式：一行
curl命令上传文件即可触发完整流水线，详见 API 快速上传。
- 📤 上传即处理 — 【核心功能】通过 API 上传文件到
raw_data/后，自动完成读取→清洗→AI 语义分割→上传 Dify 的完整流水线，无需手动调用各步骤 - 📄 多格式支持 — 自动识别并读取 9 种文件格式：TXT、MD、HTML、CSV、JSON(L)、PDF、DOCX、XLSX、XLS
- 🧹 智能清洗 — 自动去除 PUA 乱码字符（PDF 数学公式常见问题）、控制字符、合并空白与空行
- 🤖 AI 语义分割 — 先按 AI 语义切分（DeepSeek），再按字符数二次切分，段落主题精准
- 🏷️ 语义命名 — AI 自动概括段落主题作为文件名（
原文件名_语义标签.txt） - ☁️ Dify 集成 — 一键上传到 Dify 知识库，自动轮询等待嵌入完成，多轮重试保障可靠性
- 🏷️ 元数据标注 — 自动分析文档内容，生成分类、部门、适用对象等元数据标签
- ⏱️ 时间戳归档 — 每次运行自动创建独立输出目录和日志文件，历史记录不覆盖
- 🔄 流水线调度 — 支持每日定时执行（crontab）和文件监听（watch）两种运维模式
- ⏭️ 跳过已处理 — 基于文件哈希/标题的状态追踪，避免重复处理
- Python 3.10+
- pip
pip install -r requirements.txtchmod +x install.sh
./install.sh部署脚本会自动：创建 venv → 安装依赖 → 配置 .env → 设置 crontab（每天早上 7:00 运行）
创建 .env 文件（基于 .env.example）：
cp .env.example .env
# 编辑 .env 填入真实的 API Key# .env
DIFY_API_BASE=http://your-dify-server:8080/v1
DATASET_ID=your-dataset-id
DIFY_API_KEY=dataset-your-key
DEEPSEEK_API_KEY=sk-your-key
DEEPSEEK_MODEL=deepseek-v4-flash
也可直接修改脚本顶部的配置区默认值。
⚠️ Dify API Key 必须使用数据集密钥（dataset-前缀），应用 Key（app-前缀）无权操作知识库。在 Dify 后台 → 知识库 → API 访问 中创建。
这是核心功能 — 通过 HTTP 上传文件到 API 服务，服务端自动执行完整流水线，无需手动调用各步骤。
# 上传文件到 API，自动完成清洗→分割→上传 Dify
curl -X POST http://localhost:8001/api/v1/pipeline/upload \
-F "file=@学生手册2025.pdf" \
-F "chunk_size=2000"处理流程: 文件保存到 raw_data/ → 读取内容 → 清洗 → AI 语义分割 → 保存到 cleaned/ → 逐一上传到 Dify 知识库
查询进度:
# 获取返回的 task_id 后，查询处理结果
curl http://localhost:8001/api/v1/pipeline/upload/status/up-20260601-103000-a1b2c3完整的 API 接口文档请参见
自动化知识库API接口文档.md，包含全部 15+ 个接口的详细说明和调用示例。
将文档放入 raw_data/ 目录。
python Dify知识库数据清洗+文件分割+自动上传.pypython 元数据标注.py -i ./cleaned_时间戳python Dify知识库数据清洗+文件分割+自动上传.py [参数]| 参数 | 说明 | 默认值 |
|---|---|---|
-i, --input-dir |
输入文件夹路径 | ./raw_data |
-o, --output-dir |
输出文件夹（会自动追加时间戳） | cleaned_时间戳 |
-p, --pattern |
文件匹配模式（glob） | * |
--chunk-size |
字符分割阈值，0 关闭分割 |
5000 |
--chunk-overlap |
段落重叠字符数 | 500 |
--no-save |
只上传，不保存本地 | — |
--no-dify |
只本地清洗，不上传 | — |
--no-ai |
禁用 AI 语义分割，回退到纯字符分割 | — |
--semantic-only |
仅 AI 语义分割，不二次切分 | — |
--skip-processed |
跳过已处理的文件（运维用） | — |
--state-dir |
状态文件目录 | .pipeline_state |
--env-file |
指定 .env 文件路径 |
自动查找 |
使用示例：
# 基本用法（AI 语义分割 + 上传）
python Dify知识库数据清洗+文件分割+自动上传.py
# 仅本地清洗不上传
python Dify知识库数据清洗+文件分割+自动上传.py --no-dify
# 禁用 AI 语义分割，纯字符分割
python Dify知识库数据清洗+文件分割+自动上传.py --no-ai
# 跳过已处理文件（定期运行用）
python Dify知识库数据清洗+文件分割+自动上传.py --skip-processed
# 自定义切分大小
python Dify知识库数据清洗+文件分割+自动上传.py --chunk-size 3000python 元数据标注.py -i ./cleaned_时间戳 [参数]| 参数 | 说明 | 默认值 |
|---|---|---|
-i, --input-dir |
清洗输出目录 | 必填 |
--dry-run |
仅预览 AI 生成结果，不写入 Dify | — |
--limit |
限制处理文档数（0=全部） | 0 |
--max-retry |
最大重试轮数 | 3 |
--skip-processed |
跳过已标注的文件 | — |
--state-dir |
状态文件目录 | .pipeline_state |
python run_pipeline.py --mode cron|watch [参数]| 参数 | 说明 | 默认值 |
|---|---|---|
--mode |
运行模式：cron（定时）/ watch（监听） |
必填 |
-i, --input-dir |
输入文件夹 | ./raw_data |
--skip-processed |
跳过已处理文件 | — |
--watch-delay |
watch 模式：检测新文件后延迟小时数 | 1 |
--watch-poll |
watch 模式：轮询间隔秒数 | 60 |
--dry-run |
仅显示将要执行的操作 | — |
使用示例：
# cron 模式：完整执行一次（供 crontab 调用）
python run_pipeline.py --mode cron --skip-processed
# watch 模式：持续监听新文件
python run_pipeline.py --mode watch
# 预览将要执行的操作
python run_pipeline.py --mode cron --dry-runraw_data/（输入）
│
├── .pdf / .docx / .txt ... → 读取 + 清洗
│
▼
AI 语义分割（DeepSeek）
├── 多段采样（头部+中部+尾部）→ AI 识别语义边界
├── 各段落独立命名（AI 概括语义）
└── 超大段落 → 字符数二次切分（_partN）
│
▼
保存到 cleaned_时间戳/
└── 原文件名_语义标签.txt（如 国家奖学金管理办法.txt）
│
▼
上传到 Dify 知识库（多轮重试）
│
▼
元数据标注（可选）
└── AI 分析 → 生成标签 → 更新 Dify
├── api_server.py # FastAPI 接口服务（新增）
├── Dify知识库数据清洗+文件分割+自动上传.py # 主脚本：清洗+分割+上传
├── 元数据标注.py # 元数据自动标注工具
├── 元数据补充.py # 元数据重试补充工具
├── AI云辅导员.py # AI 辅导员（仅 API 服务依赖）
├── run_pipeline.py # 流水线调度器（cron/watch）
├── install.sh # 服务器一键部署脚本
├── .env.example # 环境变量模板
├── config/
│ └── settings.json # 非敏感配置
├── requirements.txt # 依赖清单
├── README.md # 本文件
├── 自动化知识库API接口文档.md # API 接口文档
├── raw_data/ # 输入文件夹
├── cleaned_*/ # 输出文件夹（自动生成）
├── .pipeline_state/ # 处理状态记录（自动生成）
│ ├── processed_files.json
│ └── metadata_processed.json
└── log_*.txt / pipeline_*.txt # 运行日志
| 依赖 | 用途 | 必需 |
|---|---|---|
requests |
HTTP 请求（上传 Dify、调用 DeepSeek） | ✅ |
python-dotenv |
从 .env 文件加载环境变量 |
✅ |
fastapi |
RESTful API 框架 | 仅 API 服务 |
uvicorn |
ASGI 服务器 | 仅 API 服务 |
PyMuPDF |
PDF 文本提取 | 仅 PDF |
python-docx |
Word 文档读取 | 仅 DOCX |
openpyxl |
Excel (.xlsx) 读取 | 仅 XLSX |
xlrd |
Excel 旧版 (.xls) 读取 | 仅 XLS |
watchdog |
文件系统监听（run_pipeline.py watch 模式） | 仅 watch 模式 |
/opt/dify-kb/
├── .env # API Keys
├── .pipeline_state/ # 处理状态
├── config/settings.json
├── raw_data/ # 放入待处理文件
├── cleaned_*/ # 自动生成输出
├── run_pipeline.py
├── install.sh
└── ...
安装脚本已自动添加，每天早上 7:00 执行：
0 7 * * * cd /opt/dify-kb && ./venv/bin/python run_pipeline.py --mode cron --skip-processed >> ./cron.log 2>&1# 完整执行一次
cd /opt/dify-kb
./venv/bin/python run_pipeline.py --mode cron --skip-processed
# 查看最近日志
tail -f cron.log如果后端工程师需要通过 RESTful API 调用功能，可使用 FastAPI 接口服务：
# 安装额外依赖
pip install fastapi uvicorn
# 开发模式（自动重载）
uvicorn api_server:app --reload --host 0.0.0.0 --port 8001
# 生产模式（内存紧张时 workers=1-2）
uvicorn api_server:app --host 0.0.0.0 --port 8001 --workers 2启动后浏览器访问：
| 地址 | 说明 |
|---|---|
http://localhost:8001/docs |
Swagger UI（交互式在线测试） |
http://localhost:8001/redoc |
ReDoc（文档阅读） |
http://localhost:8001/api/v1/health |
健康检查 |
详细接口说明见 自动化知识库API接口文档.md。
端口说明：默认使用
8001端口以避免与常见服务冲突。如需修改，编辑启动命令中的--port参数即可。
# 创建服务文件
sudo tee /etc/systemd/system/dify-kb-api.service << 'SERVICE'
[Unit]
Description=Dify KB API Service
After=network.target
[Service]
Type=simple
User=root
WorkingDirectory=/opt/dify-kb
ExecStart=/opt/dify-kb/venv/bin/uvicorn api_server:app --host 0.0.0.0 --port 8001 --workers 2
Restart=always
[Install]
WantedBy=multi-user.target
SERVICE
# 启用并启动
sudo systemctl daemon-reload
sudo systemctl enable dify-kb-api
sudo systemctl start dify-kb-api
# 查看状态
sudo systemctl status dify-kb-api