知识库未被智能体调用的四大原因：未绑定、知识库构建异常、元数据过滤不匹配、未启用身份过滤或日志中无knowledge_search调用记录。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
火山引擎智能体回答问题时完全没提知识库里的内容，连一句“根据《XX制度》第X条”都没有，说明知识库虽已接入，但检索链路在某个环节彻底断开——不是模型不理解，是根本没拿到切片结果。
确认知识库是否真正绑定到该智能体
进入「方舟 → AI 智能体」→ 找到目标智能体 → 点击「编辑」→ 切换到「知识配置」标签页。检查「企业知识引擎」下拉框中是否已勾选目标知识库名称；若为空或显示“未选择”，说明只是建了库，没绑给这个智能体用。【未绑定的知识库对当前智能体完全不可见】。
若已绑定但名称灰显，把鼠标悬停在右侧的ℹ️图标上，查看提示文字：若显示“知识库状态异常”，需先返回知识库详情页处理构建失败问题。
用调试工具直连知识库查原始响应
打开知识库详情页 → 左侧导航栏点击「检索调试」→ 在搜索框输入一个你100%确定存在于某份文档中的短语（例如“保证金退还周期为5个工作日”）→ 勾选「显示查询执行计划」→ 点击「搜索」。
重点看返回 JSON 中的 hits 字段：若为空数组 []，说明知识库本身没召回任何内容，问题出在知识库配置或文档解析；若 hits 有数据，再往下翻找 response.metadata 字段，确认 source.tags、department 等元数据字段值是否与你在智能体里设置的过滤条件完全一致——大小写、空格、中文冒号一个都不能错。
这一步操作起来很简单，直接把确定存在的短句粘贴进去就行，但必须跳过“我以为它应该能搜到”的假设，用真实词验证。
检查智能体调用知识库时是否传了有效 filter
方法一：在智能体「知识配置」页，找到「元数据过滤」区域。若此处填写了 department: "fin" 或 tags: ["财务制度"] 这类条件，但知识库实际文档 metadata 中对应字段是 "DEPARTMENT": "FIN" 或 "tags": ["财务制度v2"]，就会全量过滤失效。
方法二：启用「模拟身份」验证动态过滤是否生效。回到「检索调试」页 → 勾选「启用身份模拟」→ 输入你当前账号在 IAM 中绑定的 role 值（如 investbank_analyst）→ 提交搜索。若此时能召回内容，而关闭模拟后无结果，说明问题出在【策略中未勾选「启用用户身份元数据过滤」】，导致身份字段压根没参与检索。
验证智能体是否真的触发了知识库调用
第一步：在智能体编辑页 → 「日志与监控」→ 开启「详细调用日志」开关 → 保存并退出。
第二步：用测试账号向智能体发送一条明确需要查知识库的问题（如“员工试用期最长几个月？”）→ 立即返回「日志与监控」页 → 筛选最近1分钟日志 → 查找包含 “knowledge_search” 的日志条目。
若整页日志里没有任何一行含这个词，说明模型根本没决定调用知识库——此时要检查 system prompt 是否禁用了工具调用，或问题表述太模糊（如“帮我看看制度”），模型判断无需检索。
若日志里出现 knowledge_search 但 status 显示 failed，点开详情看 error_message：常见报错是 “kb_id not found”，代表绑定的知识库 ID 已被删除或权限失效，需重新从知识库列表中选择并保存。
