我最近在Dify上搭了一个既能联网搜索、又能读本地文档的智能体整个过程比我预想的顺利但没有哪一步是光靠直觉就能成的。比如工具描述写得不清楚模型就死活不调搜索接口比如文档上传方式选错了几十页PDF解析出来的内容根本没法命中。这篇文章就按我实际操作的顺序把每一步怎么点、为什么这么点、踩过的坑是什么全部摊开来讲。适合看这篇内容的人想做一个能回答实时资讯、也能消化自己手里资料的问答助手但没时间从零写代码的开发者、产品经理、运营和研究者。你不需要太深的编程基础只要愿意跟着一步步点基本能搭出一个能用的搜索文档阅读智能体。1. 先拆解这个智能体的核心价值搜索与文档阅读缺一不可1.1 只接搜索的智能体一到本地资料就失忆很多人觉得给大模型接一个搜索API就万事大吉。搜索结果确实能覆盖最新资讯和网络公开信息但一个很现实的场景会很快击穿这个方案你手上有一份公司内部的产品定价表、一份上一季度的销售复盘PDF、一个只有几十人常用的内部FAQ文档——这些内容搜索引擎根本抓不到模型在训练时也没见过。你问它按这份定价表某套餐和某套餐的差价是多少它能搜出一堆网页却无法从你本地文档里给出准确数字。搜索工具解决的是网络上有没有的问题解决不了我手里这份文档里写了什么的问题。这个边界如果不提前想清楚搭出来的智能体就会在第一个本地文档问题面前露馅。1.2 只做文档阅读的智能体回答不了最新和未来反过来如果只把文档接入知识库模型确实能回答文档范围内的问题可一旦问题超出文档边界比如今年行业里有没有出现类似方案最近一周有没有相关公告它就陷入沉默或者开始编造。文档里是存量信息搜索里是增量信息两者在解决真实问题的时候是互补关系很少能互相替代。我最早只做了文档阅读版本测试时问了几个文档里有答案的问题效果都不错。结果一换到帮我查一下某个产品的最新版本说明它就只能凭训练数据里的旧知识硬答推荐了一个已经废弃的版本号。那次之后我才确定搜索能力不是锦上添花而是这类智能体必备的另一条腿。1.3 为什么选择Dify而不是从零写代码我选择Dify最核心的原因是它把Agent的工具调用链路做成了可视化配置。如果我从零用代码实现需要处理函数定义、工具返回结果的结构化、多轮对话中工具与模型的交替、文件上传解析、聊天界面和鉴权……一套下来成本不低。Dify里这些能力都是现成的创建Agent应用、添加工具、开知识库、挂文件和网页端对话界面技术上复杂的东西被封装成配置项我可以把精力放在怎么让这个智能体更好用上而不是重写一个聊天框架。当然Dify不是唯一选择但它在工具生态、知识库、文件处理这三块正好覆盖了搜索文档阅读智能体的全部核心需求而且每一步都有界面反馈排错比纯代码直观得多。2. 搭建前的地基模型配置、密钥获取与环境检查2.1 选模型时最容易被忽略的三个指标第一是上下文长度。搜索工具返回的摘要和文档分段内容都会进入上下文上下文太短的模型读点搜索结果就失忆。至少选上下文16K以上的如果打算让模型阅读完整文档最好选64K甚至更长的。第二是工具调用能力也就是function calling。不是所有模型都支持稳定的结构化工具调用选模型前先确认它是否支持工具/函数调用否则Agent节点里即使配好了工具模型也只会假装调用或者直接拒绝。我见过不少在普通聊天里很流畅的模型放到Agent场景里却无法正确输出工具参数。第三是性价比。搜索阅读这类Agent场景每次问答都可能触发多次API调用成本会被放大。我试过好几个模型能力不错且定价低的模型往往比顶配模型更实用尤其在工具调用这类任务上差距没有想象中大。关注点为什么重要建议标准上下文长度搜索结果文档分段都会占用token16K起步64K更佳工具调用能力模型要按格式输出工具参数明确支持 function calling并发/限流工具返回慢时容易触发超时关注服务商限流策略价格Agent多轮调用会放大成本按场景计算单次问答成本2.2 需要准备的密钥清单构建这个智能体需要三类密钥模型服务的API Key、搜索服务的API Key以及可选的额外服务密钥。模型API Key在Dify的设置→模型供应商里添加搜索API Key在工具页面配置。有一点必须提醒不要把API Key写进系统提示词或工具描述里那样会出现在日志中存在泄露风险。我见过有人把搜索key直接写在提示词里让模型自己用结果key在每次日志里明文展示这不是正确的做法。搜索服务商的选择很多常见的有通用网页搜索API、新闻搜索API、学术搜索API等按你的实际场景选一个即可。申请Key之后先用服务商自带的调试页面发一次请求确认能正常返回再进Dify配置。2.3 用云服务还是本地部署Dify提供两个选择云端托管版适合快速验证注册后几分钟就能创建一个应用社区版Docker本地部署适合长期使用和对数据安全有要求的人。我自己用的是Docker部署机器配置不需要太高2核4G也能跑起来真正吃性能的是大模型API调用而不是Dify本身。部署时注意把环境配置文件里的密钥配置好升级前先备份数据库这几件事做好了后面基本不会出大问题。本地部署还有一个隐藏好处你可以随意折腾不用担心弄坏别人的数据。我前期调试时改过好几次应用类型和工具配置如果用的是共享云环境多少会有点放不开手脚。3. 保姆级搭建过程从创建空白应用到跑通首轮对话3.1 创建应用时为什么选Agent而不是Chatbot进入Dify首页点创建空白应用应用类型里有两个选项聊天助手Chatbot和Agent。Agent与Chatbot的核心区别在于Agent能主动调用工具它会根据用户问题判断需要哪个工具、以什么参数调用、怎么把结果组织成回答而聊天助手更适合纯粹的多轮对话工具只是可选项不会主动去思考下一步动作。我们的搜索和文档阅读都依赖工具调用所以必须选Agent。如果选错成Chatbot后面即使加了工具模型的调用逻辑也不够灵活经常会出现工具在手却不用的情况。创建应用时顺手填一下应用名称和描述比如搜索与文档阅读助手方便后面在应用列表里识别。3.2 配置模型和系统提示词创建应用后进入编排页面默认有一个Agent节点。在节点里选择模型用第2节讲的标准去选。然后把系统提示词写进去。系统提示词是Agent行为的总纲这一步别偷懒直接决定后面对话质量。我先给一个基础版本第6节还会讲怎么扩充。你是一个搜索与文档阅读助手。 - 当问题需要最新资讯、网络信息时调用搜索工具获取并在回答中标注消息来源。 - 当用户提供了文档或知识库命中内容时优先基于文档内容回答。 - 信息不足时明确说明不要编造。这个版本足够跑通第一个对话但别指望它多聪明。它明确了一个关键原则搜索和文档是并行的两个信息源模型要根据问题类型自行选择。后面我会在第6节给出一版更完整的提示词结构。3.3 添加工具并跑通第一次对话在Agent节点的工具区域添加我们要用的搜索工具和文档读取相关工具具体接入方法分别见第4节和第5节。添加后在右侧调试对话框直接输入帮我搜索一下今天AI行业有什么新动态发送后立刻去看左侧的日志面板模型有没有调用工具、工具传入了什么参数、返回了什么结果。第一次调试的目标不是答案多完美而是确认工具调用链是通的。我遇到过一个情况模型调用了搜索工具但传进去的关键词是空字符串工具返回错误模型却直接忽略错误继续硬答。后来才发现是工具描述里没说明关键词参数必填模型不知道该传什么。这些细节只能通过看日志发现。3.4 发布到WebApp与权限设置调试通过后点击右上角发布Dify会生成一个访问链接。发布设置里可以选仅自己或公开访问。如果只是自己用把仅自己打开就够了要给团队用再考虑公开并接入自己的登录鉴权。WebApp界面是Dify自动生成的聊天窗口不需要写前端代码这对我来说省了一大半工作量。发布之后还可以在设置里改应用的头像、名称和开场白这些细节会影响使用体验。我建议开场的欢迎语里就直接告诉用户你可以让我搜索网络也可以上传文档让我阅读这样别人拿到链接就知道怎么用不用你逐字解释。4. 搜索工具的接入与调优工具描述决定智能体的搜商4.1 Dify里搜索工具的两种来源第一种是内置插件市场中现成的搜索插件下载后填API Key就能用适合快速验证。第二种是自定义OpenAPI工具在工具→自定义→创建自定义工具里粘贴OpenAPI schema。我建议至少掌握第二种因为搜索服务的参数差异很大内置插件不一定支持你想要的时间过滤、结果数量、地域限制等自定义工具才有完全控制权。我一开始用的是内置插件五分钟就接通了但很快发现两个问题一是我需要的按时间范围过滤参数插件不支持导致搜索结果经常夹杂几年前的旧内容二是插件返回字段太固定我想让模型看到更结构化的摘要信息做不到。后来自己写OpenAPI schema两个问题都解决了。4.2 用OpenAPI Schema自定义搜索工具的完整步骤先到你选定的搜索服务商后台申请API Key拿到它的接口文档。通常搜索接口都长这样发一个HTTP GET请求带关键词参数和API Key参数返回包含标题、链接、摘要的JSON。然后在Dify自定义工具里粘贴OpenAPI schema下面是一个实际能用的模板openapi: 3.0.0 info: title: WebSearchTool version: 1.0.0 servers: - url: https://api.example-search-service.com/v1 paths: /search: get: operationId: searchWeb summary: 搜索网络信息 description: 当用户需要最新资讯、实时数据、网络公开信息时调用此工具。传入查询关键词返回网页标题、链接、摘要列表。 parameters: - name: q in: query required: true schema: type: string description: 搜索关键词 - name: time_range in: query required: false schema: type: string enum: [day, week, month, year] description: 时间范围过滤 responses: 200: description: 搜索结果这里的operationId会变成工具名summary和description会被模型作为调用依据。把什么时候调用、传入什么参数、返回什么内容写进description模型才能准确调用。填好后保存用服务商提供的测试Key试一次确认返回结构正常。如果接口需要鉴权头而不是URL参数在工具的鉴权配置里选择API Key或Bearer Token即可。4.3 工具描述和参数过滤才是搜商关键同一个搜索接口描述写得不同效果差异很大。如果你在description里只写搜索工具模型可能在需要最新资讯的时候不调用反而自己硬答。正确的做法是写明触发条件、参数取值规则和返回内容。比如这样写当用户询问实时新闻、最新公告、市场动态、网络公开信息时调用。 传入简短准确的关键词必要时使用 time_range 参数限定时间范围。 返回结果包含网页标题、URL 和摘要。另一个容易忽略的是参数过滤做资讯类问答时应该让Agent优先使用time_range参数做产品调研时语言和地域参数也值得在提示词里一并交代。搜索结果返回的数量默认给5到10条就够多了浪费token也容易让模型抓不住重点。我最后把结果数量固定为5条回答质量和成本都更可控。5. 文档阅读的两种实现路径知识库检索与即时上传解析5.1 路径一知识库方式适合高频复用的核心资料知识库适合那些会被反复提问的固定文档。操作路径是顶部知识库→创建知识库→上传文档→选择分段和索引方式。Dify会自动把文档切成小段并为每段生成向量索引用户提问时先做向量检索再把命中片段交给模型回答。这个方案的精髓是只取相关片段不会把整篇文档都塞给模型所以上下文开销小、回答速度快。这一步有几个关键设置值得停下来认真调分段方式自动分段适合格式统一的文档自定义分段适合结构明显的文档比如合同、标书。我遇到过一个教训一份PDF目录是自动分段结果目录页被切成了十几个无意义的碎片检索时频繁命中回答质量明显下降。Embedding模型选择与主模型兼容的嵌入模型直接影响检索准确性。索引方式高质量索引效果更好但成本更高资料量大时先评估预算。5.2 路径二对话内上传附件适合一次性临时文档如果你只是偶尔阅读某一份PDF、Word或Excel没必要专门建知识库。在应用的功能中开启对话文件上传即可。开启后用户在对话里直接传文件Agent会把文件内容读取进上下文再结合搜索工具和提示词完成任务。这个方案的好处是灵活、零预处理成本坏处是文件过长会消耗大量上下文token因此适合几十页以内的文档。我建议开启这个功能因为它补上了知识库的短板知识库适合已经知道要长期使用的资料而对话内上传适合今天临时给我的一份文件。有一次别人在对话里传了一份30页的行业报告让我总结核心观点我直接让它基于上传内容回答再把相关的最新新闻搜来对照整个过程没有建任何知识库几十秒就完成了。5.3 两种路径怎么选、怎么混用对比项知识库对话内上传使用频率高频复用文档一次性临时文档准备工作上传分段索引无需准备上下文开销只检索命中片段整个文件读入适合场景内部规范、产品手册单份合同、临时报告我实际使用时通常是混用把使用频率高的产品手册放进知识库临时收到的报告直接在对话中上传。这样既能保证核心问题回答快、成本低又不被什么都要入库的流程拖累。有人会把所有文档都塞进知识库结果上传耗时不说检索命中率还会因为文档质量参差不齐而下降。分场景使用效果和成本都友好得多。6. 提示词与调试技巧把通用模型变成懂规矩的搜索阅读助理6.1 系统提示词的分块写法我建议把系统提示词分成三个板块工作流程、输出规范、注意事项。工作流程告诉模型先做什么后做什么输出规范约束回答格式注意事项划出行为红线。下面是我实际在用的版本可以直接抄你是搜索与文档阅读助手服务于信息整合和问答。 工作流程 1. 先判断问题是否涉及最新资讯或本地文档。 2. 需要网络信息时调用搜索工具优先使用时间过滤参数。 3. 如果用户上传了文档先读取文档内容再回答。 4. 综合所有信息后给出有逻辑的回答并对关键结论标注来源。 输出规范 - 回答分点列出关键数据带来源链接。 - 文档内容回答需标注根据文档。 - 信息不足时明确说我没有找到相关资料不要编造。 注意事项 - 不要为了调用工具而调用工具能基于已有文档回答时优先用文档。 - 搜索失败时重试一次仍失败则诚实告知。这套提示词解决了最典型的两个问题模型不分青红皂白乱调工具以及回答内容不标注来源。来源标注在信息类场景里特别重要没有来源的回答用户根本不敢信。6.2 工具调用失败的排查链路我踩坑最多的是模型明明该搜索却直接说我无法联网。这类问题的排查链路如下第一看模型是否支持function calling部分模型在Dify里即使能用也无法稳定走工具调用。第二检查工具是否被添加进Agent节点的工具列表没添加就相当于工具对模型不可见。第三看日志中模型的输出里是否出现了工具调用的结构化内容如果有但工具报错多半是API Key无效或schema字段不匹配。第四用调试时的日志面板逐条核对请求和响应不要凭感觉猜。排查时把官方日志面板当成唯一依据远比反复改描述有效。我试过最迷惑的一次是搜索工具单独测试正常Agent模式下却一直报参数错误。后来看日志才发现模型把time_range参数传成了最近一周而不是枚举值weekschema里没写清楚导致校验失败。在参数描述里加上取值为固定枚举值之后问题消失了。6.3 控制成本与输出质量的平衡习惯Agent模式每轮回答可能调用多次API成本比普通聊天高不少。我有三个习惯来压成本。一是提示词里明确信息充足时直接回答不要启动搜索二是给搜索工具设定合理的结果数量默认5条就够三是知识库分段不要设得太小否则一次回答会塞入过多碎片导致token浪费。经过这轮调整我实际使用下来成本基本可以控制在可接受范围内而回答质量并不会明显下降。还有一个小技巧把搜索工具和文档工具的调用频次上限写进提示词。比如搜索最多调用两次这能防止模型在一条复杂问题上疯狂调用搜索接口把成本推高到夸张的程度。6.4 发布后的小迭代建议不要期望第一次搭建就出完美效果。发布后我把使用中遇到答得不好的对话都收集起来定期回放在调试面板里看工具调用过程然后小步改进提示词或工具描述。持续一两个星期后这个智能体的表现会明显稳定很多。我印象最深的迭代是一次文档内容被搜索答案覆盖的问题。用户上传了产品手册问价格时模型却优先用了搜索出来的过时价格导致回答错误。我在注意事项里加了一句本地文档与搜索结果冲突时以文档为准这个问题立刻解决。这类边界问题只有实际用起来才会暴露也是提示词调优最值得投入的地方。最后说一点个人体会这类搜索文档阅读智能体真正值钱的不是搭建那一下子而是搭建完之后你愿意花多少时间去调提示词和观察日志。工具是骨架提示词是肌肉调试记录才是让它慢慢变聪明的养料。按这套流程搭完你得到的不是一个能用的Demo而是一个会随着使用越来越贴合你需求的长期助手。 
长河君 · 2026/10/17 12:13:03 · 阅读 1.2k Dify搭建搜索与文档阅读智能体：工具调用、提示词与避坑全指南
我最近在Dify上搭了一个既能联网搜索、又能读本地文档的智能体整个过程比我预想的顺利但没有哪一步是光靠直觉就能成的。比如工具描述写得不清楚模型就死活不调搜索接口比如文档上传方式选错了几十页PDF解析出来的内容根本没法命中。这篇文章就按我实际操作的顺序把每一步怎么点、为什么这么点、踩过的坑是什么全部摊开来讲。适合看这篇内容的人想做一个能回答实时资讯、也能消化自己手里资料的问答助手但没时间从零写代码的开发者、产品经理、运营和研究者。你不需要太深的编程基础只要愿意跟着一步步点基本能搭出一个能用的搜索文档阅读智能体。1. 先拆解这个智能体的核心价值搜索与文档阅读缺一不可1.1 只接搜索的智能体一到本地资料就失忆很多人觉得给大模型接一个搜索API就万事大吉。搜索结果确实能覆盖最新资讯和网络公开信息但一个很现实的场景会很快击穿这个方案你手上有一份公司内部的产品定价表、一份上一季度的销售复盘PDF、一个只有几十人常用的内部FAQ文档——这些内容搜索引擎根本抓不到模型在训练时也没见过。你问它按这份定价表某套餐和某套餐的差价是多少它能搜出一堆网页却无法从你本地文档里给出准确数字。搜索工具解决的是网络上有没有的问题解决不了我手里这份文档里写了什么的问题。这个边界如果不提前想清楚搭出来的智能体就会在第一个本地文档问题面前露馅。1.2 只做文档阅读的智能体回答不了最新和未来反过来如果只把文档接入知识库模型确实能回答文档范围内的问题可一旦问题超出文档边界比如今年行业里有没有出现类似方案最近一周有没有相关公告它就陷入沉默或者开始编造。文档里是存量信息搜索里是增量信息两者在解决真实问题的时候是互补关系很少能互相替代。我最早只做了文档阅读版本测试时问了几个文档里有答案的问题效果都不错。结果一换到帮我查一下某个产品的最新版本说明它就只能凭训练数据里的旧知识硬答推荐了一个已经废弃的版本号。那次之后我才确定搜索能力不是锦上添花而是这类智能体必备的另一条腿。1.3 为什么选择Dify而不是从零写代码我选择Dify最核心的原因是它把Agent的工具调用链路做成了可视化配置。如果我从零用代码实现需要处理函数定义、工具返回结果的结构化、多轮对话中工具与模型的交替、文件上传解析、聊天界面和鉴权……一套下来成本不低。Dify里这些能力都是现成的创建Agent应用、添加工具、开知识库、挂文件和网页端对话界面技术上复杂的东西被封装成配置项我可以把精力放在怎么让这个智能体更好用上而不是重写一个聊天框架。当然Dify不是唯一选择但它在工具生态、知识库、文件处理这三块正好覆盖了搜索文档阅读智能体的全部核心需求而且每一步都有界面反馈排错比纯代码直观得多。2. 搭建前的地基模型配置、密钥获取与环境检查2.1 选模型时最容易被忽略的三个指标第一是上下文长度。搜索工具返回的摘要和文档分段内容都会进入上下文上下文太短的模型读点搜索结果就失忆。至少选上下文16K以上的如果打算让模型阅读完整文档最好选64K甚至更长的。第二是工具调用能力也就是function calling。不是所有模型都支持稳定的结构化工具调用选模型前先确认它是否支持工具/函数调用否则Agent节点里即使配好了工具模型也只会假装调用或者直接拒绝。我见过不少在普通聊天里很流畅的模型放到Agent场景里却无法正确输出工具参数。第三是性价比。搜索阅读这类Agent场景每次问答都可能触发多次API调用成本会被放大。我试过好几个模型能力不错且定价低的模型往往比顶配模型更实用尤其在工具调用这类任务上差距没有想象中大。关注点为什么重要建议标准上下文长度搜索结果文档分段都会占用token16K起步64K更佳工具调用能力模型要按格式输出工具参数明确支持 function calling并发/限流工具返回慢时容易触发超时关注服务商限流策略价格Agent多轮调用会放大成本按场景计算单次问答成本2.2 需要准备的密钥清单构建这个智能体需要三类密钥模型服务的API Key、搜索服务的API Key以及可选的额外服务密钥。模型API Key在Dify的设置→模型供应商里添加搜索API Key在工具页面配置。有一点必须提醒不要把API Key写进系统提示词或工具描述里那样会出现在日志中存在泄露风险。我见过有人把搜索key直接写在提示词里让模型自己用结果key在每次日志里明文展示这不是正确的做法。搜索服务商的选择很多常见的有通用网页搜索API、新闻搜索API、学术搜索API等按你的实际场景选一个即可。申请Key之后先用服务商自带的调试页面发一次请求确认能正常返回再进Dify配置。2.3 用云服务还是本地部署Dify提供两个选择云端托管版适合快速验证注册后几分钟就能创建一个应用社区版Docker本地部署适合长期使用和对数据安全有要求的人。我自己用的是Docker部署机器配置不需要太高2核4G也能跑起来真正吃性能的是大模型API调用而不是Dify本身。部署时注意把环境配置文件里的密钥配置好升级前先备份数据库这几件事做好了后面基本不会出大问题。本地部署还有一个隐藏好处你可以随意折腾不用担心弄坏别人的数据。我前期调试时改过好几次应用类型和工具配置如果用的是共享云环境多少会有点放不开手脚。3. 保姆级搭建过程从创建空白应用到跑通首轮对话3.1 创建应用时为什么选Agent而不是Chatbot进入Dify首页点创建空白应用应用类型里有两个选项聊天助手Chatbot和Agent。Agent与Chatbot的核心区别在于Agent能主动调用工具它会根据用户问题判断需要哪个工具、以什么参数调用、怎么把结果组织成回答而聊天助手更适合纯粹的多轮对话工具只是可选项不会主动去思考下一步动作。我们的搜索和文档阅读都依赖工具调用所以必须选Agent。如果选错成Chatbot后面即使加了工具模型的调用逻辑也不够灵活经常会出现工具在手却不用的情况。创建应用时顺手填一下应用名称和描述比如搜索与文档阅读助手方便后面在应用列表里识别。3.2 配置模型和系统提示词创建应用后进入编排页面默认有一个Agent节点。在节点里选择模型用第2节讲的标准去选。然后把系统提示词写进去。系统提示词是Agent行为的总纲这一步别偷懒直接决定后面对话质量。我先给一个基础版本第6节还会讲怎么扩充。你是一个搜索与文档阅读助手。 - 当问题需要最新资讯、网络信息时调用搜索工具获取并在回答中标注消息来源。 - 当用户提供了文档或知识库命中内容时优先基于文档内容回答。 - 信息不足时明确说明不要编造。这个版本足够跑通第一个对话但别指望它多聪明。它明确了一个关键原则搜索和文档是并行的两个信息源模型要根据问题类型自行选择。后面我会在第6节给出一版更完整的提示词结构。3.3 添加工具并跑通第一次对话在Agent节点的工具区域添加我们要用的搜索工具和文档读取相关工具具体接入方法分别见第4节和第5节。添加后在右侧调试对话框直接输入帮我搜索一下今天AI行业有什么新动态发送后立刻去看左侧的日志面板模型有没有调用工具、工具传入了什么参数、返回了什么结果。第一次调试的目标不是答案多完美而是确认工具调用链是通的。我遇到过一个情况模型调用了搜索工具但传进去的关键词是空字符串工具返回错误模型却直接忽略错误继续硬答。后来才发现是工具描述里没说明关键词参数必填模型不知道该传什么。这些细节只能通过看日志发现。3.4 发布到WebApp与权限设置调试通过后点击右上角发布Dify会生成一个访问链接。发布设置里可以选仅自己或公开访问。如果只是自己用把仅自己打开就够了要给团队用再考虑公开并接入自己的登录鉴权。WebApp界面是Dify自动生成的聊天窗口不需要写前端代码这对我来说省了一大半工作量。发布之后还可以在设置里改应用的头像、名称和开场白这些细节会影响使用体验。我建议开场的欢迎语里就直接告诉用户你可以让我搜索网络也可以上传文档让我阅读这样别人拿到链接就知道怎么用不用你逐字解释。4. 搜索工具的接入与调优工具描述决定智能体的搜商4.1 Dify里搜索工具的两种来源第一种是内置插件市场中现成的搜索插件下载后填API Key就能用适合快速验证。第二种是自定义OpenAPI工具在工具→自定义→创建自定义工具里粘贴OpenAPI schema。我建议至少掌握第二种因为搜索服务的参数差异很大内置插件不一定支持你想要的时间过滤、结果数量、地域限制等自定义工具才有完全控制权。我一开始用的是内置插件五分钟就接通了但很快发现两个问题一是我需要的按时间范围过滤参数插件不支持导致搜索结果经常夹杂几年前的旧内容二是插件返回字段太固定我想让模型看到更结构化的摘要信息做不到。后来自己写OpenAPI schema两个问题都解决了。4.2 用OpenAPI Schema自定义搜索工具的完整步骤先到你选定的搜索服务商后台申请API Key拿到它的接口文档。通常搜索接口都长这样发一个HTTP GET请求带关键词参数和API Key参数返回包含标题、链接、摘要的JSON。然后在Dify自定义工具里粘贴OpenAPI schema下面是一个实际能用的模板openapi: 3.0.0 info: title: WebSearchTool version: 1.0.0 servers: - url: https://api.example-search-service.com/v1 paths: /search: get: operationId: searchWeb summary: 搜索网络信息 description: 当用户需要最新资讯、实时数据、网络公开信息时调用此工具。传入查询关键词返回网页标题、链接、摘要列表。 parameters: - name: q in: query required: true schema: type: string description: 搜索关键词 - name: time_range in: query required: false schema: type: string enum: [day, week, month, year] description: 时间范围过滤 responses: 200: description: 搜索结果这里的operationId会变成工具名summary和description会被模型作为调用依据。把什么时候调用、传入什么参数、返回什么内容写进description模型才能准确调用。填好后保存用服务商提供的测试Key试一次确认返回结构正常。如果接口需要鉴权头而不是URL参数在工具的鉴权配置里选择API Key或Bearer Token即可。4.3 工具描述和参数过滤才是搜商关键同一个搜索接口描述写得不同效果差异很大。如果你在description里只写搜索工具模型可能在需要最新资讯的时候不调用反而自己硬答。正确的做法是写明触发条件、参数取值规则和返回内容。比如这样写当用户询问实时新闻、最新公告、市场动态、网络公开信息时调用。 传入简短准确的关键词必要时使用 time_range 参数限定时间范围。 返回结果包含网页标题、URL 和摘要。另一个容易忽略的是参数过滤做资讯类问答时应该让Agent优先使用time_range参数做产品调研时语言和地域参数也值得在提示词里一并交代。搜索结果返回的数量默认给5到10条就够多了浪费token也容易让模型抓不住重点。我最后把结果数量固定为5条回答质量和成本都更可控。5. 文档阅读的两种实现路径知识库检索与即时上传解析5.1 路径一知识库方式适合高频复用的核心资料知识库适合那些会被反复提问的固定文档。操作路径是顶部知识库→创建知识库→上传文档→选择分段和索引方式。Dify会自动把文档切成小段并为每段生成向量索引用户提问时先做向量检索再把命中片段交给模型回答。这个方案的精髓是只取相关片段不会把整篇文档都塞给模型所以上下文开销小、回答速度快。这一步有几个关键设置值得停下来认真调分段方式自动分段适合格式统一的文档自定义分段适合结构明显的文档比如合同、标书。我遇到过一个教训一份PDF目录是自动分段结果目录页被切成了十几个无意义的碎片检索时频繁命中回答质量明显下降。Embedding模型选择与主模型兼容的嵌入模型直接影响检索准确性。索引方式高质量索引效果更好但成本更高资料量大时先评估预算。5.2 路径二对话内上传附件适合一次性临时文档如果你只是偶尔阅读某一份PDF、Word或Excel没必要专门建知识库。在应用的功能中开启对话文件上传即可。开启后用户在对话里直接传文件Agent会把文件内容读取进上下文再结合搜索工具和提示词完成任务。这个方案的好处是灵活、零预处理成本坏处是文件过长会消耗大量上下文token因此适合几十页以内的文档。我建议开启这个功能因为它补上了知识库的短板知识库适合已经知道要长期使用的资料而对话内上传适合今天临时给我的一份文件。有一次别人在对话里传了一份30页的行业报告让我总结核心观点我直接让它基于上传内容回答再把相关的最新新闻搜来对照整个过程没有建任何知识库几十秒就完成了。5.3 两种路径怎么选、怎么混用对比项知识库对话内上传使用频率高频复用文档一次性临时文档准备工作上传分段索引无需准备上下文开销只检索命中片段整个文件读入适合场景内部规范、产品手册单份合同、临时报告我实际使用时通常是混用把使用频率高的产品手册放进知识库临时收到的报告直接在对话中上传。这样既能保证核心问题回答快、成本低又不被什么都要入库的流程拖累。有人会把所有文档都塞进知识库结果上传耗时不说检索命中率还会因为文档质量参差不齐而下降。分场景使用效果和成本都友好得多。6. 提示词与调试技巧把通用模型变成懂规矩的搜索阅读助理6.1 系统提示词的分块写法我建议把系统提示词分成三个板块工作流程、输出规范、注意事项。工作流程告诉模型先做什么后做什么输出规范约束回答格式注意事项划出行为红线。下面是我实际在用的版本可以直接抄你是搜索与文档阅读助手服务于信息整合和问答。 工作流程 1. 先判断问题是否涉及最新资讯或本地文档。 2. 需要网络信息时调用搜索工具优先使用时间过滤参数。 3. 如果用户上传了文档先读取文档内容再回答。 4. 综合所有信息后给出有逻辑的回答并对关键结论标注来源。 输出规范 - 回答分点列出关键数据带来源链接。 - 文档内容回答需标注根据文档。 - 信息不足时明确说我没有找到相关资料不要编造。 注意事项 - 不要为了调用工具而调用工具能基于已有文档回答时优先用文档。 - 搜索失败时重试一次仍失败则诚实告知。这套提示词解决了最典型的两个问题模型不分青红皂白乱调工具以及回答内容不标注来源。来源标注在信息类场景里特别重要没有来源的回答用户根本不敢信。6.2 工具调用失败的排查链路我踩坑最多的是模型明明该搜索却直接说我无法联网。这类问题的排查链路如下第一看模型是否支持function calling部分模型在Dify里即使能用也无法稳定走工具调用。第二检查工具是否被添加进Agent节点的工具列表没添加就相当于工具对模型不可见。第三看日志中模型的输出里是否出现了工具调用的结构化内容如果有但工具报错多半是API Key无效或schema字段不匹配。第四用调试时的日志面板逐条核对请求和响应不要凭感觉猜。排查时把官方日志面板当成唯一依据远比反复改描述有效。我试过最迷惑的一次是搜索工具单独测试正常Agent模式下却一直报参数错误。后来看日志才发现模型把time_range参数传成了最近一周而不是枚举值weekschema里没写清楚导致校验失败。在参数描述里加上取值为固定枚举值之后问题消失了。6.3 控制成本与输出质量的平衡习惯Agent模式每轮回答可能调用多次API成本比普通聊天高不少。我有三个习惯来压成本。一是提示词里明确信息充足时直接回答不要启动搜索二是给搜索工具设定合理的结果数量默认5条就够三是知识库分段不要设得太小否则一次回答会塞入过多碎片导致token浪费。经过这轮调整我实际使用下来成本基本可以控制在可接受范围内而回答质量并不会明显下降。还有一个小技巧把搜索工具和文档工具的调用频次上限写进提示词。比如搜索最多调用两次这能防止模型在一条复杂问题上疯狂调用搜索接口把成本推高到夸张的程度。6.4 发布后的小迭代建议不要期望第一次搭建就出完美效果。发布后我把使用中遇到答得不好的对话都收集起来定期回放在调试面板里看工具调用过程然后小步改进提示词或工具描述。持续一两个星期后这个智能体的表现会明显稳定很多。我印象最深的迭代是一次文档内容被搜索答案覆盖的问题。用户上传了产品手册问价格时模型却优先用了搜索出来的过时价格导致回答错误。我在注意事项里加了一句本地文档与搜索结果冲突时以文档为准这个问题立刻解决。这类边界问题只有实际用起来才会暴露也是提示词调优最值得投入的地方。最后说一点个人体会这类搜索文档阅读智能体真正值钱的不是搭建那一下子而是搭建完之后你愿意花多少时间去调提示词和观察日志。工具是骨架提示词是肌肉调试记录才是让它慢慢变聪明的养料。按这套流程搭完你得到的不是一个能用的Demo而是一个会随着使用越来越贴合你需求的长期助手。