必须用LlamaIndex接管解析与切片：PDF用MagicPDFReader（需显式安装magic-pdf）、DOCX用DocxReader、数据库用DatabaseReader，切片≤512字符后调API推入Dify知识库。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
要在Dify中接入LlamaIndex实现PDF、Word、数据库等异构数据的统一预处理与向量化，必须绕过Dify原生知识库的格式限制，让LlamaIndex接管文档解析与切片逻辑，再将结构化chunk推入Dify知识库API。
准备LlamaIndex运行环境与依赖
确保已安装Python 3.10+，然后执行以下命令安装核心组件：
pip install llama-index-core llama-index-readers-file llama-index-readers-database magic-pdf pypdf python-docx pandas
【magic-pdf必须显式安装】——Dify官方知识库不支持PDF语义解析，而LlamaIndex默认PDF Reader（pypdf）会丢失表格、图片、多栏布局；magic-pdf是MinerU生态的底层解析包，能输出带标题层级和Markdown表格的纯文本流，这是后续RAG效果的根基。
验证magic-pdf是否可用：python -c "from magic_pdf.libs.box_layout import do_layout; print('OK')"
用LlamaIndex加载并预处理异构数据源
创建preprocess_loader.py，按以下顺序组织代码：
① 初始化LlamaIndex文档加载器：对PDF使用MagicPDFReader，对DOCX使用DocxReader，对SQLite数据库使用DatabaseReader。
② 配置解析参数：PDF加载时传入parse_method="auto"和model_path=None（触发本地MinerU2.5-Pro轻量模型），DOCX启用keep_basic_formatting=True保留加粗/列表符号，数据库查询需指定sql="SELECT title, content FROM docs"。
③ 执行load_data()并调用SentenceSplitter(chunk_size=512, chunk_overlap=64)切片——【切片尺寸必须≤Dify知识库单条chunk上限512字符】，否则后续调用knowledge_base/create接口会返回400错误。
④ 对每个Document对象注入metadata：{"source_type": "pdf", "file_name": "report.pdf", "page_number": 3}，这些字段将透传至Dify知识库的chunk元数据，用于后续溯源。
将LlamaIndex处理结果推入Dify知识库
方法一：直连Dify知识库API（推荐）
从Dify后台「Settings → API Keys」获取具备knowledge_base:write权限的API Key，保存为DIFY_API_KEY环境变量。
构造POST请求体：将LlamaIndex生成的Node列表逐条序列化为JSON，字段包括text（chunk正文）、metadata（上一步注入的字典）、id_（可选，建议用uuid4生成）。
向https://your-dify-domain/v1/knowledge_bases/{kb_id}/documents/chunks发起POST，Header携带Authorization: Bearer {DIFY_API_KEY}，Body为application/json。
方法二：通过Dify内置工具节点（仅限v0.15.0+）
在Dify Flow Editor中拖入「Custom Tool」节点，选择「LlamaIndex Preprocessor」模板（需提前在/dify/extensions/tools/下部署该插件），输入路径如./data/reports/，自动触发LlamaIndex流水线并写入默认知识库。
注意：该模板依赖本地已配置好的llama-index-readers-*和magic-pdf，未安装则节点执行失败且无明确报错。
验证预处理效果与调试入口
登录Dify知识库管理页，打开对应知识库→点击「Chunks」标签页，检查首条chunk的text字段是否含完整表格Markdown（如|列1|列2|→|---|---|），而非“表格内容丢失”类占位符。
若发现chunk中存在乱码或空段落，立即回查LlamaIndex日志中的magic_pdf.libs.ocr模块输出——90%的PDF解析失败源于OCR引擎未加载成功，此时需手动下载mineru-2604-1.2b.onnx到~/.cache/magic-pdf/models/目录。
执行curl -X GET "https://your-dify-domain/v1/knowledge_bases/{kb_id}/documents" -H "Authorization: Bearer {DIFY_API_KEY}"，确认返回的document_count等于LlamaIndex load_data()输出的Document总数。
