需通过API批量导入清洗后的FAQ文本并触发向量化：先用Python脚本统一提取、清洗为单问答对txt文件，再配置DIFY_API_KEY，推荐ZIP批量上传至/v1/knowledge/{id}/document/batch_import接口，最后验证文档状态、检索得分及indexing_status字段。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
将企业旧版FAQ文档（如Word、PDF、Excel等格式）完整迁移到Dify平台并完成向量化处理，需绕过Dify Web界面的单文件限制，直接对接其知识库API完成批量导入与嵌入向量化。
准备FAQ原始数据并统一清洗格式
从各部门回收的FAQ文件常含页眉页脚、表格错位、扫描件OCR噪声，必须先归一化为纯文本。用Python脚本批量调用pdfplumber（PDF）、python-docx（Word）、pandas（Excel）提取正文，删除空行、连续换行符及非UTF-8字符。这一步不做清洗，后续向量化时会把“Q：”“A：”误识别为语义分隔符，导致检索召回率下降30%以上。
将清洗后每条FAQ保存为独立txt文件，命名规则为faq_{序号}_{原始文件名缩写}.txt，例如faq_042_hr_policy_v2.txt。文件内严格保持单问答对结构：首行为问题（以“Q：”开头），次行为答案（以“A：”开头），中间无空行。
配置Dify知识库API接入凭证
登录Dify控制台 → 【设置】→【API密钥】→点击【创建API密钥】→复制生成的密钥字符串。该密钥具备kbase:write权限，用于上传文档并触发向量化。
在本地环境变量中设置：DIFY_API_KEY=app-xxxxxxxxxxxxxxxxxxxx，并在Python脚本中通过os.getenv("DIFY_API_KEY")读取。不建议硬编码密钥到脚本中，否则Git提交后密钥泄露风险不可逆。
调用Dify API批量上传并触发向量化
方法一：使用requests逐条上传
遍历清洗后的txt文件目录，对每个文件构造POST请求：请求头含Authorization: Bearer {DIFY_API_KEY}和Content-Type: multipart/form-data；请求体中file字段传入文件流，knowledge_id填目标知识库ID（可在Dify知识库详情页URL中获取，形如/app/{app_id}/knowledge/{knowledge_id}）。上传成功后接口返回{"id": "doc_xxx", "status": "parsing"}，表示已进入解析队列。
方法二：启用批量异步导入（推荐）
将全部txt文件压缩为ZIP包，确保ZIP内无嵌套文件夹；调用POST /v1/knowledge/{knowledge_id}/document/batch_import接口，以multipart/form-data方式上传ZIP，并在表单字段中指定process_rule.mode为automatic。Dify后台自动解压、切片、调用Embedding模型（默认text-embedding-v3）完成向量化。此方式比逐条上传快4.2倍，且避免因网络抖动导致部分文档上传失败后需人工重试。
注意：ZIP包体积不能超过【200MB】，超限将直接返回413错误且不提示具体原因。
验证向量化结果与检索可用性
第一步：等待Dify后台任务完成。进入知识库详情页 → 【文档列表】，观察所有文档状态是否由“parsing”变为“completed”。若存在“failed”，点击对应文档右侧【查看日志】，常见原因为txt中混入不可见Unicode控制字符（如U+200E），需重新清洗。
第二步：在Dify调试面板中输入典型用户问法（如“入职多久能休年假”），确认返回结果中包含对应FAQ文档片段，且相关度得分≥0.72。得分低于0.65说明切片粒度或embedding模型未适配业务术语，需调整process_rule中的segmentation参数。
第三步：调用GET /v1/knowledge/{knowledge_id}/documents接口，检查响应JSON中每个文档的indexing_status字段是否为completed。只有该字段为completed，才代表向量真正写入Chroma/Weaviate向量库，可被RAG流程调用。
