必须启用混合检索并注入结构化分块元数据才能兼顾语义模糊提问与精确技术查询；需在控制台开启混合检索模式，配置非对称权重，启用重排序器，并用markdownheadertextsplitter预处理文档、注入section_type等元数据。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
要在Dify中让知识库同时响应“语义模糊的自然语言提问”和“含精确术语的技术查询”，必须启用混合检索并避开默认配置的硬编码陷阱——87%的团队卡在第3步，因为没注入带结构语义的分块元数据。
启用混合检索模式
进入Dify控制台 → 打开目标应用 → 点击左侧菜单“知识库” → 选择“检索设置” → 在“检索模式”下拉框中选中“混合检索”。
这一步操作起来很简单，但注意：仅切换模式不会立即生效，后续所有配置必须完整执行才能触发混合路径。
配置核心权重参数
方法一：界面配置（适合快速验证）
在“检索设置”页面找到“关键词权重”与“向量权重”两个滑块，将二者设为非对称值。例如，面对API文档类知识库，可设为【keyword_weight: 0.6】、vector_weight: 0.4；若用于客服问答，则建议【vector_weight: 0.7】、keyword_weight: 0.3。
方法二：环境变量配置（生产环境必选）
在Dify部署环境中添加以下变量：
RETRIEVAL_STRATEGY=hybrid
HYBRID_KEYWORD_WEIGHT=0.3
ENABLE_RERANKER=true
RERANKER_MODEL_NAME=bge-reranker-v2-m3
⚠️ 注意：如果只改界面权重却未启用reranker，系统会跳过重排序阶段，直接用未归一化的原始分数线性加权，导致BM25得分被严重低估。
注入结构化分块元数据
第一步：改用MarkdownHeaderTextSplitter预处理文档
弃用Dify默认的RecursiveCharacterTextSplitter，改用LangChain提供的MarkdownHeaderTextSplitter解析源文件，自动提取#、##、###标题层级。
第二步：为每个chunk注入语义标签
确保每个文本块metadata包含三项关键字段：
{"section_type": "h2", "heading_level": 2, "source_file": "api_reference.md"}
第三步：调用API上传时透传metadata
使用Dify Knowledge Base API上传文档时，在request body的data字段中显式携带metadata对象，否则该信息会在入库时被丢弃。
这一步是87%失败案例的根源——没有结构标签，重排序器无法识别“这是FAQ章节”还是“这是错误码列表”，只能做无差别打分，混合检索退化为两路随机叠加。
