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 和 443，Dify 的 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(model="qwen2.5:7b", base_url="http://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 里实现起来更顺手。
我个人在实际操作中的体会是，工具是死的，思路是活的。同样的组件，不同的人搭出来的效果差别很大。关键不在于你用了多少工具，而在于你有没有想清楚要解决什么问题，以及怎么用最少的组件解决这个问题。先把一个场景做深做透，比泛泛地尝试各种功能要有价值得多。
空间解法)
