1. 为什么这套组合值得花时间折腾1.1 从单点工具到完整链路解决的是什么问题很多人接触大模型的第一反应是打开一个对话框问几句觉得“也就那样”。但真正把大模型用起来的人关注的是另一件事怎么让模型稳定地完成一件具体的事而不是每次都要重新解释一遍背景。这就是智能体这个概念被反复提起的原因。Dify 在这个链路里扮演的是“编排层”的角色。它把提示词、上下文、工具调用、知识库检索这些零散的东西用一个可视化界面串起来。Ollama 负责在本地把模型跑起来省去调用外部接口的成本和网络依赖。LangChain 则是代码层面的胶水当可视化界面满足不了你的定制需求时它能让你用 Python 把逻辑写得更细。Agent 是最终呈现出来的形态用户看到的是一个能对话、能查资料、能调用工具的执行体。这套组合解决的核心问题是让一个不懂底层推理细节的人也能搭出一个能用的智能体。你不需要从零写推理循环不需要自己实现向量检索不需要手动管理对话历史。Dify 把这些都封装好了你只需要关心“我的智能体要做什么”。适合谁来学三类人。第一类是有一定技术基础但没深入过大模型应用开发的开发者想快速看到效果。第二类是产品经理或业务人员想验证一个想法能不能落地不想等排期。第三类是学生或爱好者想搞清楚智能体到底是怎么运转的从可视化入手比直接啃代码要友好得多。1.2 本地部署加可视化编排这套方案的真实优势先说本地部署这件事。Ollama 的价值在于把模型权重、推理引擎、接口服务打包成一个命令行工具。你拉一个模型下来它自动帮你处理好量化、显存分配、并发请求这些事。对于个人开发者来说这意味着你不需要一块顶级显卡也能跑起来一个能用的模型。七B参数级别的模型在消费级显卡上就能跑量化之后甚至纯CPU也能凑合。再说可视化编排。Dify 的界面逻辑是“工作流”式的你把节点拖出来连线配置参数。每个节点代表一个动作比如“调用模型”“检索知识库”“执行代码”“条件判断”。这种方式的优势是调试直观你能看到数据在每个节点之间怎么流动哪个环节出了问题一眼就能定位。LangChain 的定位不太一样。它更像是一个代码库提供的是抽象和组件。当你需要把智能体嵌入到一个已有的 Python 项目里或者需要实现一些 Dify 界面里做不了的逻辑时LangChain 就派上用场了。比如你想自定义一个检索策略或者想把多个模型的输出做融合这些在代码层面更灵活。这三者不是互斥的而是分层的。Ollama 管模型运行Dify 管流程编排LangChain 管代码级定制。你可以只用其中一两个也可以全用上。理解它们各自的位置比死记硬背操作步骤重要得多。2. 环境准备与核心组件安装2.1 Ollama 的安装与模型拉取策略Ollama 的安装本身不复杂官网提供了各平台的安装包。但安装完之后的第一件事不是急着拉模型而是先确认你的硬件条件。打开终端跑一下ollama --version确认命令能正常执行。然后看一下你的显卡情况NVIDIA 的话用nvidia-smi看显存AMD 的话用rocm-smi。显存大小直接决定了你能跑多大的模型。模型拉取有个常见的误区很多人一上来就拉最大的那个。实际上对于智能体场景七B到十四B参数的模型已经能处理大部分任务。更大的模型确实更聪明但推理速度会明显下降交互体验会变差。我的建议是先从七B的通用模型开始比如qwen2.5:7b或者llama3.1:8b跑通了再考虑换大的。拉取命令很简单ollama pull qwen2.5:7b拉完之后用ollama list确认模型在本地了。然后跑一个测试ollama run qwen2.5:7b 用一句话解释什么是向量数据库如果能正常返回说明模型服务没问题。这里有个细节Ollama 默认监听的是11434端口Dify 后面要连的就是这个地址。如果你是在 Docker 里跑 Dify注意网络配置容器内访问宿主机需要用宿主机的内网 IP不能用localhost。注意模型文件默认存在用户目录下的.ollama文件夹里时间长了会占不少空间。定期用ollama rm清理不用的模型是个好习惯。2.2 Dify 的部署方式选择与配置要点Dify 提供了两种主要部署方式Docker Compose 和源码部署。对于绝大多数人Docker Compose 是首选。原因很简单Dify 依赖的组件比较多有数据库、缓存、向量存储、后端服务、前端界面手动一个个装容易出错。Docker Compose 把这些都编排好了你只需要改几个环境变量。拉取代码仓库之后进入docker目录把.env.example复制成.env。然后重点改这几个地方EXPOSE_NGINX_PORT默认是 80如果被占用了改成别的比如 8080。OLLAMA_API_BASE_URL如果你用 Ollama 作为模型提供方这里填 Ollama 的地址。Docker 内部访问宿主机用http://host.docker.internal:11434。DB_PASSWORD和REDIS_PASSWORD改成你自己的密码别用默认的。改完之后docker compose up -d等几分钟然后浏览器打开http://localhost:8080能看到登录界面就说明起来了。第一次登录会让你设置管理员账号设完之后进入控制台。这里有个坑如果你的机器上已经有别的服务占了 80 和 443Dify 的 Nginx 会起不来。这时候要么改端口要么先把占用的服务停掉。我一般建议直接改端口省得影响其他服务。2.3 LangChain 环境搭建与版本兼容性处理LangChain 的安装用 pip 就行pip install langchain langchain-community langchain-ollama但这里有个版本兼容性的问题需要留意。LangChain 的迭代速度很快不同版本之间的 API 可能有变化。如果你在网上找到的示例代码跑不通大概率是版本对不上。我的做法是在项目里固定版本用requirements.txt或者pyproject.toml把版本锁死。和 Ollama 对接的时候用langchain-ollama这个包它提供了ChatOllama和OllamaEmbeddings两个类。前者用来做对话后者用来做文本向量化。向量化在知识库场景里很关键因为检索的本质是比较向量相似度。一个最小的测试脚本长这样from langchain_ollama import ChatOllama llm ChatOllama(modelqwen2.5:7b, base_urlhttp://localhost:11434) response llm.invoke(你好请介绍一下你自己) print(response.content)能打印出内容就说明链路通了。如果报连接错误检查 Ollama 服务是不是在跑端口对不对。3. 知识库搭建的核心逻辑与实操3.1 文档切分策略为什么切得好比模型选得好更重要知识库的效果好不好七成取决于文档怎么切三成取决于模型和检索策略。很多人搭完知识库发现回答不准第一反应是换模型其实问题往往出在切分上。切分的核心矛盾是切得太碎上下文丢失检索出来的片段没有足够信息回答问题切得太大噪声太多模型容易被无关内容干扰。Dify 默认的切分方式是按固定字符数切比如每 500 个字符一段段之间留 50 个字符的重叠。这种方式简单但对结构化的文档不友好。更好的做法是按语义切。比如 Markdown 文档按标题层级切每个二级标题下的内容作为一个块。PDF 文档按段落切遇到表格和图片单独处理。Dify 支持自定义切分规则你可以在上传文档的时候选择“自定义”模式设置分隔符。我实测下来对于技术文档按标题切的效果明显好于按字数切。因为标题本身就是一个语义边界标题下的内容通常是围绕一个主题展开的。检索的时候命中标题就能快速定位到相关段落。提示切分之前先把文档里的页眉页脚、水印、无关的广告文字清理掉。这些内容会进入向量库成为噪声影响检索准确率。3.2 向量化模型的选择与检索参数调优向量化模型决定了文本被映射到向量空间后的分布。不同的模型对语义的理解能力不一样。Ollama 支持不少嵌入模型比如nomic-embed-text、mxbai-embed-large。选择的时候考虑两个因素一是维度维度越高表达能力越强但存储和计算成本也越高二是语言支持中文场景要选对中文优化过的模型。在 Dify 里配置嵌入模型的地方在“设置”-“模型供应商”-“Ollama”里。填上模型名称和地址就行。配置完之后上传文档的时候 Dify 会自动调用这个模型做向量化。检索参数里有两个关键值Top K 和 Score 阈值。Top K 是返回最相似的 K 个片段默认是 4。这个值太小可能漏掉关键信息太大则会引入噪声。我的经验是对于事实型问答Top K 设 3 到 5 比较合适对于需要综合多个片段才能回答的问题可以设到 8 到 10。Score 阈值是相似度分数的下限低于这个值的片段会被过滤掉。这个值需要根据你的嵌入模型来调。有的模型分数普遍偏高阈值就要设高一点有的模型分数分布比较分散阈值就要设低一点。建议先不设阈值观察一下检索结果的实际分数分布再决定阈值设多少。3.3 从上传到召回完整链路走一遍假设你有一份产品手册想做一个能回答产品问题的智能体。操作流程是这样的第一步在 Dify 里创建一个知识库命名选择嵌入模型。第二步上传文档。支持的文件格式挺多PDF、Word、Markdown、TXT 都行。上传之后选择切分方式。如果是结构清晰的文档选自定义切分用标题作为分隔符。第三步等待处理完成。Dify 会显示每个文档的处理状态切了多少段向量化是否成功。如果某一段处理失败通常是文档里有特殊字符或者编码问题可以单独把那一段删掉重新上传。第四步测试召回。知识库有个“召回测试”功能你输入一个问题它显示检索到的片段和相似度分数。这一步很关键能直观看到你的切分和检索参数效果怎么样。如果检索出来的片段和问题不相关就要回去调切分或者换嵌入模型。第五步在智能体里关联这个知识库。创建应用的时候选择“知识库增强”类型把刚才建的知识库挂上去。然后在提示词里告诉模型怎么使用检索到的内容比如“根据以下参考资料回答问题如果资料中没有相关信息就说不知道”。这套流程走下来一个基础的知识库问答智能体就成型了。但要做到好用还需要反复调优。调优的方向无非三个切分更合理、嵌入模型更匹配、提示词更清晰。4. Agent 搭建从对话到工具调用4.1 Agent 和普通对话机器人的本质区别普通对话机器人是“你问我答”模型根据你的输入生成回复仅此而已。Agent 多了一层“决策”的能力。它不仅能回答还能判断“这个问题我需不需要查资料”“我需不需要调用一个工具”“我需不需要分步骤完成”。这个决策能力来自哪里来自提示词的设计和工具的定义。你在 Dify 里创建一个 Agent 类型的应用系统会给你一个默认的提示词模板里面包含了“你可以使用以下工具”这样的描述。你每添加一个工具模型就多了一个可选项。工具在 Dify 里可以是内置的比如网页搜索、代码执行、天气查询也可以是自定义的 API。自定义 API 的方式是填一个接口地址和参数描述模型会根据你的描述来判断什么时候调用这个接口。这里的关键点是模型的决策能力受限于它的理解能力和你的描述清晰度。如果你把工具描述写得很模糊模型就不知道该什么时候用。比如你写“查询数据”模型不知道查什么数据、什么时候该查。你写“根据用户提供的订单号查询订单状态输入参数是订单号字符串”模型就清楚多了。4.2 工具定义与提示词编排的配合技巧工具定义和提示词是相互配合的。工具定义告诉模型“有什么可用”提示词告诉模型“怎么用”和“什么时候用”。我一般会在提示词里明确几个规则第一优先使用知识库回答知识库没有相关内容再考虑调用工具。第二调用工具之前先确认参数是否齐全不齐全就先向用户询问。第三工具返回结果后用自然语言总结给用户不要直接抛原始数据。这些规则写进去之后Agent 的行为会稳定很多。不写的话模型可能会在不该调用工具的时候调用或者该调用的时候不调用。还有一个技巧是给工具起一个语义明确的名字。比如不要叫“tool1”叫“订单查询工具”。模型对名字的语义是有感知的名字起得好调用准确率会提升。注意工具调用是有成本的不管是时间成本还是费用成本。如果一个工具调用需要好几秒用户等待体验就会很差。所以能在本地完成的逻辑尽量放在本地不要什么都做成工具调用。4.3 多轮对话中的上下文管理Agent 在多轮对话里需要记住之前说了什么。Dify 默认会保留一定轮数的对话历史但保留太多会占用上下文窗口导致模型“忘记”更早的内容。保留太少又会导致对话不连贯。我的做法是根据场景来设。如果是客服场景用户的问题通常比较独立保留 3 到 5 轮就够了。如果是咨询场景用户可能会逐步深入保留 10 轮左右比较合适。Dify 里可以在“对话配置”里设置最大历史轮数。另外对于长对话可以考虑做一个“摘要”机制。当对话超过一定轮数时让模型把之前的对话总结成一段话作为新的上下文。这样既保留了关键信息又节省了上下文空间。Dify 的工作流里可以用代码节点实现这个逻辑。5. 常见问题与排查技巧实录5.1 模型连接失败与响应超时这是最常见的问题表现是 Dify 里测试模型连接时报错或者对话时一直转圈最后超时。排查顺序是这样的先确认 Ollama 服务在跑终端里ollama list能列出模型。然后确认端口默认是 11434如果你改过就要对应改 Dify 里的配置。再确认网络如果 Dify 跑在 Docker 里容器内访问宿主机不能用localhost要用宿主机的内网 IP 或者host.docker.internal。如果这些都对了还是超时那可能是模型太大推理速度跟不上。换一个小一点的模型试试或者检查一下显存是不是满了。显存不够的时候Ollama 会回退到 CPU 推理速度会慢很多。5.2 知识库检索不准的排查思路检索不准的表现是明明文档里有答案但智能体就是答不出来或者答非所问。第一步用召回测试看检索出来的片段是什么。如果片段本身就不相关说明切分或者嵌入模型有问题。如果片段相关但模型没用好说明提示词有问题。切分的问题通常是切得太碎或者太大。切得太碎一个完整的答案被拆到多个片段里检索只能命中一部分。切得太大噪声多模型抓不住重点。调整切分参数重新处理文档。嵌入模型的问题通常是模型对中文支持不好。换一个中文优化过的嵌入模型试试。另外如果文档里有大量专业术语通用嵌入模型可能理解不了这时候可以考虑用领域数据微调一个嵌入模型但成本比较高一般场景用不着。5.3 工具调用不触发或参数错误工具调用不触发通常是提示词里没有说清楚什么时候该调用。检查提示词里有没有“当用户询问XX时使用XX工具”这样的明确指令。另外工具的描述也要写清楚包括功能、输入参数、输出格式。参数错误通常是模型对参数的理解有偏差。比如你定义了一个“日期”参数格式是YYYY-MM-DD但模型可能传一个“明天”这样的自然语言。解决办法是在参数描述里写清楚格式要求并且在提示词里强调“参数必须符合指定格式”。还有一个常见问题是工具返回的结果太长超出了上下文窗口。这时候需要在工具定义里加一个“结果摘要”的步骤或者让模型在调用工具后先总结再回复。5.4 性能优化让智能体响应更快响应速度受几个因素影响模型大小、推理硬件、检索效率、工具调用耗时。模型方面七B模型在消费级显卡上通常能跑到每秒几十个 token基本够用。如果追求更快可以用量化版本比如q4_0量化速度能提升不少质量损失在可接受范围内。检索方面向量库的索引类型会影响检索速度。Dify 默认用的向量库对于小规模数据够用如果文档量很大可以考虑换一个更适合大规模检索的向量库。工具调用方面能并行调用的就并行调用不要串行。Dify 的工作流支持并行分支合理利用能省不少时间。6. 从能用到好用一些实战心得6.1 提示词不是越长越好刚开始玩智能体的时候我总想把所有规则都写进提示词里结果发现模型反而变笨了。后来才明白提示词太长会稀释关键指令的权重模型抓不住重点。好的提示词是结构清晰的。用分隔符把不同部分隔开比如用###分隔“角色定义”“任务说明”“输出格式”“约束条件”。每个部分只写最核心的几条不要堆砌。另外提示词里的指令要具体不要抽象。写“回答要准确”不如写“如果知识库中没有相关信息直接回答‘我没有找到相关信息’不要编造”。写“语气友好”不如写“用口语化的表达避免专业术语”。6.2 知识库的维护比搭建更重要很多人搭完知识库就不管了文档更新了也不重新上传结果智能体回答的还是旧信息。知识库是需要持续维护的。我的做法是给每个知识库设一个负责人文档有更新的时候同步更新知识库。另外定期看智能体的对话记录把回答不好的问题整理出来针对性地补充文档或者调整切分。还有一个技巧是给文档打标签。Dify 支持在文档级别设置元数据检索的时候可以按元数据过滤。比如你有多个产品线的文档可以给每个文档打上产品线标签检索的时候只检索相关产品线的文档准确率会提升。6.3 不要追求一步到位智能体的调优是个迭代过程。第一版能跑通就行不要一开始就追求完美。跑起来之后收集真实用户的反馈看哪些问题回答得好哪些回答得不好然后针对性优化。我见过不少人花了很多时间调提示词结果发现根本问题是知识库里的文档质量不行。所以优化的顺序应该是先保证文档质量再调切分和检索最后调提示词。这个顺序反了的话会做很多无用功。6.4 安全边界要提前设好智能体上线之前一定要想清楚它能做什么、不能做什么。比如一个客服智能体不应该回答与产品无关的问题不应该承诺它做不到的事情不应该泄露敏感信息。这些边界要在提示词里写清楚同时也要在工具层面做限制。比如查询订单的工具应该只能查当前用户自己的订单不能查别人的。这些逻辑要在工具实现层面保证不能只靠提示词约束。提示上线前做一轮对抗测试故意问一些边界问题看智能体的反应。比如问它“你能帮我做XX吗”看它会不会答应做超出范围的事。7. 后续可以怎么扩展这套基础链路跑通之后扩展方向其实挺多的。一个方向是接入更多工具比如把内部系统的 API 封装成工具让智能体能直接操作业务系统。另一个方向是做多智能体协作一个负责理解意图一个负责检索一个负责生成各司其职。还有一个方向是结合 LangChain 做更复杂的逻辑。Dify 的工作流虽然灵活但有些逻辑用代码写更直接。比如你想实现一个自定义的检索策略或者想把多个模型的输出做投票融合这些在 LangChain 里实现起来更顺手。我个人在实际操作中的体会是工具是死的思路是活的。同样的组件不同的人搭出来的效果差别很大。关键不在于你用了多少工具而在于你有没有想清楚要解决什么问题以及怎么用最少的组件解决这个问题。先把一个场景做深做透比泛泛地尝试各种功能要有价值得多。
1. 为什么这套组合值得花时间折腾1.1 从单点工具到完整链路解决的是什么问题很多人接触大模型的第一反应是打开一个对话框问几句觉得“也就那样”。但真正把大模型用起来的人关注的是另一件事怎么让模型稳定地完成一件具体的事而不是每次都要重新解释一遍背景。这就是智能体这个概念被反复提起的原因。Dify 在这个链路里扮演的是“编排层”的角色。它把提示词、上下文、工具调用、知识库检索这些零散的东西用一个可视化界面串起来。Ollama 负责在本地把模型跑起来省去调用外部接口的成本和网络依赖。LangChain 则是代码层面的胶水当可视化界面满足不了你的定制需求时它能让你用 Python 把逻辑写得更细。Agent 是最终呈现出来的形态用户看到的是一个能对话、能查资料、能调用工具的执行体。这套组合解决的核心问题是让一个不懂底层推理细节的人也能搭出一个能用的智能体。你不需要从零写推理循环不需要自己实现向量检索不需要手动管理对话历史。Dify 把这些都封装好了你只需要关心“我的智能体要做什么”。适合谁来学三类人。第一类是有一定技术基础但没深入过大模型应用开发的开发者想快速看到效果。第二类是产品经理或业务人员想验证一个想法能不能落地不想等排期。第三类是学生或爱好者想搞清楚智能体到底是怎么运转的从可视化入手比直接啃代码要友好得多。1.2 本地部署加可视化编排这套方案的真实优势先说本地部署这件事。Ollama 的价值在于把模型权重、推理引擎、接口服务打包成一个命令行工具。你拉一个模型下来它自动帮你处理好量化、显存分配、并发请求这些事。对于个人开发者来说这意味着你不需要一块顶级显卡也能跑起来一个能用的模型。七B参数级别的模型在消费级显卡上就能跑量化之后甚至纯CPU也能凑合。再说可视化编排。Dify 的界面逻辑是“工作流”式的你把节点拖出来连线配置参数。每个节点代表一个动作比如“调用模型”“检索知识库”“执行代码”“条件判断”。这种方式的优势是调试直观你能看到数据在每个节点之间怎么流动哪个环节出了问题一眼就能定位。LangChain 的定位不太一样。它更像是一个代码库提供的是抽象和组件。当你需要把智能体嵌入到一个已有的 Python 项目里或者需要实现一些 Dify 界面里做不了的逻辑时LangChain 就派上用场了。比如你想自定义一个检索策略或者想把多个模型的输出做融合这些在代码层面更灵活。这三者不是互斥的而是分层的。Ollama 管模型运行Dify 管流程编排LangChain 管代码级定制。你可以只用其中一两个也可以全用上。理解它们各自的位置比死记硬背操作步骤重要得多。2. 环境准备与核心组件安装2.1 Ollama 的安装与模型拉取策略Ollama 的安装本身不复杂官网提供了各平台的安装包。但安装完之后的第一件事不是急着拉模型而是先确认你的硬件条件。打开终端跑一下ollama --version确认命令能正常执行。然后看一下你的显卡情况NVIDIA 的话用nvidia-smi看显存AMD 的话用rocm-smi。显存大小直接决定了你能跑多大的模型。模型拉取有个常见的误区很多人一上来就拉最大的那个。实际上对于智能体场景七B到十四B参数的模型已经能处理大部分任务。更大的模型确实更聪明但推理速度会明显下降交互体验会变差。我的建议是先从七B的通用模型开始比如qwen2.5:7b或者llama3.1:8b跑通了再考虑换大的。拉取命令很简单ollama pull qwen2.5:7b拉完之后用ollama list确认模型在本地了。然后跑一个测试ollama run qwen2.5:7b 用一句话解释什么是向量数据库如果能正常返回说明模型服务没问题。这里有个细节Ollama 默认监听的是11434端口Dify 后面要连的就是这个地址。如果你是在 Docker 里跑 Dify注意网络配置容器内访问宿主机需要用宿主机的内网 IP不能用localhost。注意模型文件默认存在用户目录下的.ollama文件夹里时间长了会占不少空间。定期用ollama rm清理不用的模型是个好习惯。2.2 Dify 的部署方式选择与配置要点Dify 提供了两种主要部署方式Docker Compose 和源码部署。对于绝大多数人Docker Compose 是首选。原因很简单Dify 依赖的组件比较多有数据库、缓存、向量存储、后端服务、前端界面手动一个个装容易出错。Docker Compose 把这些都编排好了你只需要改几个环境变量。拉取代码仓库之后进入docker目录把.env.example复制成.env。然后重点改这几个地方EXPOSE_NGINX_PORT默认是 80如果被占用了改成别的比如 8080。OLLAMA_API_BASE_URL如果你用 Ollama 作为模型提供方这里填 Ollama 的地址。Docker 内部访问宿主机用http://host.docker.internal:11434。DB_PASSWORD和REDIS_PASSWORD改成你自己的密码别用默认的。改完之后docker compose up -d等几分钟然后浏览器打开http://localhost:8080能看到登录界面就说明起来了。第一次登录会让你设置管理员账号设完之后进入控制台。这里有个坑如果你的机器上已经有别的服务占了 80 和 443Dify 的 Nginx 会起不来。这时候要么改端口要么先把占用的服务停掉。我一般建议直接改端口省得影响其他服务。2.3 LangChain 环境搭建与版本兼容性处理LangChain 的安装用 pip 就行pip install langchain langchain-community langchain-ollama但这里有个版本兼容性的问题需要留意。LangChain 的迭代速度很快不同版本之间的 API 可能有变化。如果你在网上找到的示例代码跑不通大概率是版本对不上。我的做法是在项目里固定版本用requirements.txt或者pyproject.toml把版本锁死。和 Ollama 对接的时候用langchain-ollama这个包它提供了ChatOllama和OllamaEmbeddings两个类。前者用来做对话后者用来做文本向量化。向量化在知识库场景里很关键因为检索的本质是比较向量相似度。一个最小的测试脚本长这样from langchain_ollama import ChatOllama llm ChatOllama(modelqwen2.5:7b, base_urlhttp://localhost:11434) response llm.invoke(你好请介绍一下你自己) print(response.content)能打印出内容就说明链路通了。如果报连接错误检查 Ollama 服务是不是在跑端口对不对。3. 知识库搭建的核心逻辑与实操3.1 文档切分策略为什么切得好比模型选得好更重要知识库的效果好不好七成取决于文档怎么切三成取决于模型和检索策略。很多人搭完知识库发现回答不准第一反应是换模型其实问题往往出在切分上。切分的核心矛盾是切得太碎上下文丢失检索出来的片段没有足够信息回答问题切得太大噪声太多模型容易被无关内容干扰。Dify 默认的切分方式是按固定字符数切比如每 500 个字符一段段之间留 50 个字符的重叠。这种方式简单但对结构化的文档不友好。更好的做法是按语义切。比如 Markdown 文档按标题层级切每个二级标题下的内容作为一个块。PDF 文档按段落切遇到表格和图片单独处理。Dify 支持自定义切分规则你可以在上传文档的时候选择“自定义”模式设置分隔符。我实测下来对于技术文档按标题切的效果明显好于按字数切。因为标题本身就是一个语义边界标题下的内容通常是围绕一个主题展开的。检索的时候命中标题就能快速定位到相关段落。提示切分之前先把文档里的页眉页脚、水印、无关的广告文字清理掉。这些内容会进入向量库成为噪声影响检索准确率。3.2 向量化模型的选择与检索参数调优向量化模型决定了文本被映射到向量空间后的分布。不同的模型对语义的理解能力不一样。Ollama 支持不少嵌入模型比如nomic-embed-text、mxbai-embed-large。选择的时候考虑两个因素一是维度维度越高表达能力越强但存储和计算成本也越高二是语言支持中文场景要选对中文优化过的模型。在 Dify 里配置嵌入模型的地方在“设置”-“模型供应商”-“Ollama”里。填上模型名称和地址就行。配置完之后上传文档的时候 Dify 会自动调用这个模型做向量化。检索参数里有两个关键值Top K 和 Score 阈值。Top K 是返回最相似的 K 个片段默认是 4。这个值太小可能漏掉关键信息太大则会引入噪声。我的经验是对于事实型问答Top K 设 3 到 5 比较合适对于需要综合多个片段才能回答的问题可以设到 8 到 10。Score 阈值是相似度分数的下限低于这个值的片段会被过滤掉。这个值需要根据你的嵌入模型来调。有的模型分数普遍偏高阈值就要设高一点有的模型分数分布比较分散阈值就要设低一点。建议先不设阈值观察一下检索结果的实际分数分布再决定阈值设多少。3.3 从上传到召回完整链路走一遍假设你有一份产品手册想做一个能回答产品问题的智能体。操作流程是这样的第一步在 Dify 里创建一个知识库命名选择嵌入模型。第二步上传文档。支持的文件格式挺多PDF、Word、Markdown、TXT 都行。上传之后选择切分方式。如果是结构清晰的文档选自定义切分用标题作为分隔符。第三步等待处理完成。Dify 会显示每个文档的处理状态切了多少段向量化是否成功。如果某一段处理失败通常是文档里有特殊字符或者编码问题可以单独把那一段删掉重新上传。第四步测试召回。知识库有个“召回测试”功能你输入一个问题它显示检索到的片段和相似度分数。这一步很关键能直观看到你的切分和检索参数效果怎么样。如果检索出来的片段和问题不相关就要回去调切分或者换嵌入模型。第五步在智能体里关联这个知识库。创建应用的时候选择“知识库增强”类型把刚才建的知识库挂上去。然后在提示词里告诉模型怎么使用检索到的内容比如“根据以下参考资料回答问题如果资料中没有相关信息就说不知道”。这套流程走下来一个基础的知识库问答智能体就成型了。但要做到好用还需要反复调优。调优的方向无非三个切分更合理、嵌入模型更匹配、提示词更清晰。4. Agent 搭建从对话到工具调用4.1 Agent 和普通对话机器人的本质区别普通对话机器人是“你问我答”模型根据你的输入生成回复仅此而已。Agent 多了一层“决策”的能力。它不仅能回答还能判断“这个问题我需不需要查资料”“我需不需要调用一个工具”“我需不需要分步骤完成”。这个决策能力来自哪里来自提示词的设计和工具的定义。你在 Dify 里创建一个 Agent 类型的应用系统会给你一个默认的提示词模板里面包含了“你可以使用以下工具”这样的描述。你每添加一个工具模型就多了一个可选项。工具在 Dify 里可以是内置的比如网页搜索、代码执行、天气查询也可以是自定义的 API。自定义 API 的方式是填一个接口地址和参数描述模型会根据你的描述来判断什么时候调用这个接口。这里的关键点是模型的决策能力受限于它的理解能力和你的描述清晰度。如果你把工具描述写得很模糊模型就不知道该什么时候用。比如你写“查询数据”模型不知道查什么数据、什么时候该查。你写“根据用户提供的订单号查询订单状态输入参数是订单号字符串”模型就清楚多了。4.2 工具定义与提示词编排的配合技巧工具定义和提示词是相互配合的。工具定义告诉模型“有什么可用”提示词告诉模型“怎么用”和“什么时候用”。我一般会在提示词里明确几个规则第一优先使用知识库回答知识库没有相关内容再考虑调用工具。第二调用工具之前先确认参数是否齐全不齐全就先向用户询问。第三工具返回结果后用自然语言总结给用户不要直接抛原始数据。这些规则写进去之后Agent 的行为会稳定很多。不写的话模型可能会在不该调用工具的时候调用或者该调用的时候不调用。还有一个技巧是给工具起一个语义明确的名字。比如不要叫“tool1”叫“订单查询工具”。模型对名字的语义是有感知的名字起得好调用准确率会提升。注意工具调用是有成本的不管是时间成本还是费用成本。如果一个工具调用需要好几秒用户等待体验就会很差。所以能在本地完成的逻辑尽量放在本地不要什么都做成工具调用。4.3 多轮对话中的上下文管理Agent 在多轮对话里需要记住之前说了什么。Dify 默认会保留一定轮数的对话历史但保留太多会占用上下文窗口导致模型“忘记”更早的内容。保留太少又会导致对话不连贯。我的做法是根据场景来设。如果是客服场景用户的问题通常比较独立保留 3 到 5 轮就够了。如果是咨询场景用户可能会逐步深入保留 10 轮左右比较合适。Dify 里可以在“对话配置”里设置最大历史轮数。另外对于长对话可以考虑做一个“摘要”机制。当对话超过一定轮数时让模型把之前的对话总结成一段话作为新的上下文。这样既保留了关键信息又节省了上下文空间。Dify 的工作流里可以用代码节点实现这个逻辑。5. 常见问题与排查技巧实录5.1 模型连接失败与响应超时这是最常见的问题表现是 Dify 里测试模型连接时报错或者对话时一直转圈最后超时。排查顺序是这样的先确认 Ollama 服务在跑终端里ollama list能列出模型。然后确认端口默认是 11434如果你改过就要对应改 Dify 里的配置。再确认网络如果 Dify 跑在 Docker 里容器内访问宿主机不能用localhost要用宿主机的内网 IP 或者host.docker.internal。如果这些都对了还是超时那可能是模型太大推理速度跟不上。换一个小一点的模型试试或者检查一下显存是不是满了。显存不够的时候Ollama 会回退到 CPU 推理速度会慢很多。5.2 知识库检索不准的排查思路检索不准的表现是明明文档里有答案但智能体就是答不出来或者答非所问。第一步用召回测试看检索出来的片段是什么。如果片段本身就不相关说明切分或者嵌入模型有问题。如果片段相关但模型没用好说明提示词有问题。切分的问题通常是切得太碎或者太大。切得太碎一个完整的答案被拆到多个片段里检索只能命中一部分。切得太大噪声多模型抓不住重点。调整切分参数重新处理文档。嵌入模型的问题通常是模型对中文支持不好。换一个中文优化过的嵌入模型试试。另外如果文档里有大量专业术语通用嵌入模型可能理解不了这时候可以考虑用领域数据微调一个嵌入模型但成本比较高一般场景用不着。5.3 工具调用不触发或参数错误工具调用不触发通常是提示词里没有说清楚什么时候该调用。检查提示词里有没有“当用户询问XX时使用XX工具”这样的明确指令。另外工具的描述也要写清楚包括功能、输入参数、输出格式。参数错误通常是模型对参数的理解有偏差。比如你定义了一个“日期”参数格式是YYYY-MM-DD但模型可能传一个“明天”这样的自然语言。解决办法是在参数描述里写清楚格式要求并且在提示词里强调“参数必须符合指定格式”。还有一个常见问题是工具返回的结果太长超出了上下文窗口。这时候需要在工具定义里加一个“结果摘要”的步骤或者让模型在调用工具后先总结再回复。5.4 性能优化让智能体响应更快响应速度受几个因素影响模型大小、推理硬件、检索效率、工具调用耗时。模型方面七B模型在消费级显卡上通常能跑到每秒几十个 token基本够用。如果追求更快可以用量化版本比如q4_0量化速度能提升不少质量损失在可接受范围内。检索方面向量库的索引类型会影响检索速度。Dify 默认用的向量库对于小规模数据够用如果文档量很大可以考虑换一个更适合大规模检索的向量库。工具调用方面能并行调用的就并行调用不要串行。Dify 的工作流支持并行分支合理利用能省不少时间。6. 从能用到好用一些实战心得6.1 提示词不是越长越好刚开始玩智能体的时候我总想把所有规则都写进提示词里结果发现模型反而变笨了。后来才明白提示词太长会稀释关键指令的权重模型抓不住重点。好的提示词是结构清晰的。用分隔符把不同部分隔开比如用###分隔“角色定义”“任务说明”“输出格式”“约束条件”。每个部分只写最核心的几条不要堆砌。另外提示词里的指令要具体不要抽象。写“回答要准确”不如写“如果知识库中没有相关信息直接回答‘我没有找到相关信息’不要编造”。写“语气友好”不如写“用口语化的表达避免专业术语”。6.2 知识库的维护比搭建更重要很多人搭完知识库就不管了文档更新了也不重新上传结果智能体回答的还是旧信息。知识库是需要持续维护的。我的做法是给每个知识库设一个负责人文档有更新的时候同步更新知识库。另外定期看智能体的对话记录把回答不好的问题整理出来针对性地补充文档或者调整切分。还有一个技巧是给文档打标签。Dify 支持在文档级别设置元数据检索的时候可以按元数据过滤。比如你有多个产品线的文档可以给每个文档打上产品线标签检索的时候只检索相关产品线的文档准确率会提升。6.3 不要追求一步到位智能体的调优是个迭代过程。第一版能跑通就行不要一开始就追求完美。跑起来之后收集真实用户的反馈看哪些问题回答得好哪些回答得不好然后针对性优化。我见过不少人花了很多时间调提示词结果发现根本问题是知识库里的文档质量不行。所以优化的顺序应该是先保证文档质量再调切分和检索最后调提示词。这个顺序反了的话会做很多无用功。6.4 安全边界要提前设好智能体上线之前一定要想清楚它能做什么、不能做什么。比如一个客服智能体不应该回答与产品无关的问题不应该承诺它做不到的事情不应该泄露敏感信息。这些边界要在提示词里写清楚同时也要在工具层面做限制。比如查询订单的工具应该只能查当前用户自己的订单不能查别人的。这些逻辑要在工具实现层面保证不能只靠提示词约束。提示上线前做一轮对抗测试故意问一些边界问题看智能体的反应。比如问它“你能帮我做XX吗”看它会不会答应做超出范围的事。7. 后续可以怎么扩展这套基础链路跑通之后扩展方向其实挺多的。一个方向是接入更多工具比如把内部系统的 API 封装成工具让智能体能直接操作业务系统。另一个方向是做多智能体协作一个负责理解意图一个负责检索一个负责生成各司其职。还有一个方向是结合 LangChain 做更复杂的逻辑。Dify 的工作流虽然灵活但有些逻辑用代码写更直接。比如你想实现一个自定义的检索策略或者想把多个模型的输出做投票融合这些在 LangChain 里实现起来更顺手。我个人在实际操作中的体会是工具是死的思路是活的。同样的组件不同的人搭出来的效果差别很大。关键不在于你用了多少工具而在于你有没有想清楚要解决什么问题以及怎么用最少的组件解决这个问题。先把一个场景做深做透比泛泛地尝试各种功能要有价值得多。
)
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
