必须手动配置weaviate并启用bm25模块、关闭dify内置elasticsearch关键词索引，才能实现语义+关键词双路召回；需在docker-compose中启用bm25模块、dify中勾选“启用混合检索”、上传文档触发双字段索引构建，并通过权重配置与api验证确保hybrid生效。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
要在Dify中让知识库真正支持语义+关键词双路召回，必须绕过默认的单向量检索路径，显式启用Weaviate原生混合检索能力——这要求你手动配置Weaviate实例、在Dify中指定其为向量数据库类型，并关闭Dify内置的Elasticsearch关键词索引模块，否则两套全文检索机制会冲突导致结果错乱。
准备Weaviate服务并启用混合搜索能力
启动Weaviate容器时，必须在环境变量中显式开启BM25支持，否则即使后续配置了hybrid模式也无法触发关键词通道：
在docker-compose.yml的weaviate服务块中添加：
【ENABLE_MODULES="text2vec-transformers,ref2vec-centroid,bm25"】
启动后访问http://localhost:8080/v1/modules验证bm25是否在loadedModules列表中；若未出现，说明模块未加载成功，需检查镜像版本是否≥1.24.0（低于此版本不支持BM25内建）。
执行curl -X GET http://localhost:8080/v1/meta确认ready状态为true，表示服务已就绪。
在Dify中绑定Weaviate作为向量数据库
进入Dify管理后台 → 数据集 → 新建知识库 → 点击“高级设置” → 展开“向量数据库配置”。
选择“自定义向量数据库”，填写以下参数：
Host：http://host.docker.internal:8080（Docker Desktop on Mac/Windows）或实际宿主机IP（Linux裸机部署）
API Key：WVF5YsdfkYwhfasdfsX3dsfsddN8pkih（与Weaviate配置一致）
Vector Type：weaviate
【必须勾选“启用混合检索”开关，否则Dify将强制走纯向量路径】
保存后，该知识库底层将不再使用FAISS或Qdrant，而是直连Weaviate并调用其/hybrid端点。
上传文档并触发混合索引构建
第一步：上传PDF/DOCX/TXT文件到知识库，Dify自动调用extractor模块解析文本。
第二步：Dify调用splitter按段落切分（默认512 token），每段生成两个嵌入：
① 用BGE-M3生成稠密向量存入Weaviate向量字段
② 同时提取该段关键词（TF-IDF + BM25权重）写入Weaviate的text字段，供后续倒排索引使用
第三步：点击“重新索引”，Dify会向Weaviate发送包含vector + text双字段的batch请求，Weaviate自动建立HNSW索引与倒排索引两套结构。
注意：索引过程中若出现“failed to write batch: context deadline exceeded”，说明Weaviate内存不足，需在docker-compose.yml中增加weaviate服务的mem_limit: 4g。
配置混合检索权重与查询行为
方法一：通过Dify UI调整权重
进入知识库 → 检索设置 → 将“检索类型”设为“混合检索” → 拖动滑块设置关键词权重（keyword_weight）和语义权重（semantic_weight）。
方法二：通过API直接覆盖配置
向Dify后端PATCH /api/datasets/{dataset_id}/retrieval-settings，提交JSON：
{ "retrieval_mode": "hybrid", "weights": { "keyword": 0.35, "semantic": 0.65 }, "top_k": 7 }
方法三：在Weaviate侧强制融合策略
在Weaviate客户端查询时，显式调用with_hybrid()并传入alpha参数：
.with_hybrid(query="屏幕不亮", alpha=0.35) —— 此值会覆盖Dify传来的权重，优先级更高。
这一步操作起来很简单，直接把文件拖进去就行。
验证混合检索是否生效
第一步：构造一个含歧义词的查询，例如“苹果”。
第二步：在Dify聊天界面输入该词，打开浏览器开发者工具 → Network标签页 → 筛选fetch/XHR → 找到/retrieval请求。
第三步：查看请求体中的retrieval_type字段是否为"hybrid"，响应体中返回的chunks是否同时包含高BM25得分（如匹配“苹果手机维修指南”）和高向量相似度（如“iPhone 15 Pro屏幕更换步骤”）的混合结果。
若响应中仅有vector_score字段而无bm25_score字段，说明Weaviate未启用BM25模块或Dify未正确传递hybrid指令，需回溯前两步检查。
