1. 这套组合拳到底在解决什么问题先把话说在前头Dify、Ollama、Agent、LangChain这四个词放在一起不是简单的工具堆砌而是一条从“本地跑模型”到“搭出能干活儿的智能体”的完整链路。我见过太多人卡在第一步——想玩智能体结果要么被API费用劝退要么被环境配置搞崩溃要么搭出来的东西只能聊天、干不了实事。这套方案的核心价值就在于用Ollama把大模型拉到本地跑用Dify做可视化编排用LangChain补足复杂逻辑最后用Agent把工具调用串起来形成一个能查知识库、能调外部接口、能自主决策的完整系统。适合谁来参考三类人一是想入门AI应用开发但不想一上来就啃论文的开发者二是手里有本地数据、想做私有知识库问答的技术团队三是已经用过Dify但觉得“只能做简单工作流”、想进阶到Agent模式的玩家。不管你之前有没有LangChain经验只要会装软件、能看懂基本的Python代码这套流程都能跑通。我自己的体会是这套组合最大的优势在于“可控”——模型在本地数据不出内网Agent的每一步决策你都能看到日志。缺点也有本地模型的推理能力跟云端旗舰模型有差距所以Agent的工具调用逻辑要设计得更细致不能指望它自己“悟”。下面我按实际搭建顺序把每个环节拆开讲。2. 环境准备与核心组件选型2.1 为什么是Ollama而不是其他本地推理方案本地跑模型的选择其实不少比如直接上llama.cpp、用text-generation-webui、或者vLLM。我选Ollama的理由很实际它把模型下载、量化版本管理、API暴露这三件事做成了“一条命令”的体验。你不需要手动编译CUDA内核不需要折腾GGUF文件的路径ollama pull之后直接就有OpenAI兼容的接口。但要注意Ollama默认的上下文长度和并发数偏保守。如果你要跑Agent工具调用的提示词往往很长建议在启动时调整参数。我实测下来7B级别的模型在16GB内存的机器上跑得比较稳13B以上最好有独立显卡。具体选哪个模型看你的任务复杂度——纯知识库问答7B够用要做多步推理和工具调用建议上到14B或32B的量化版本。提示Ollama的模型存储默认在系统盘如果C盘空间紧张记得提前改环境变量OLLAMA_MODELS到其他盘符。2.2 Dify的部署方式选择Docker还是源码Dify官方推荐Docker Compose部署这也是我最推荐的方式。原因很简单Dify依赖PostgreSQL、Redis、Weaviate或Qdrant这几个服务手动装一遍能把人折腾疯。Docker Compose一条命令拉起所有依赖版本匹配问题也少。但有个坑要注意Dify的Docker镜像默认拉的是latest标签不同版本之间的数据库迁移脚本可能不兼容。我的做法是锁定具体版本号比如dify-api:0.6.8这种升级前先备份数据库。另外如果你打算把Dify暴露到公网务必改掉默认的admin密码和SECRET_KEY这两个在.env文件里。源码部署适合需要二次开发的场景比如你要改Dify的Agent执行逻辑。但源码模式下前端构建需要Node环境后端需要Python 3.10依赖冲突的概率比Docker高不少。我建议先用Docker跑通全流程确认需求之后再考虑源码定制。2.3 LangChain和Dify的关系互补而非替代很多人会问Dify已经能做工作流和Agent了为什么还要LangChain这个问题我一开始也纠结过。实际用下来发现Dify的可视化编排适合“流程固定、节点明确”的场景比如“用户提问→检索知识库→LLM生成回答”这种线性流程。但一旦涉及动态工具选择、多轮反思、条件分支嵌套Dify的画布就会变得非常臃肿。LangChain的优势在于代码级的灵活性。你可以写一个自定义的AgentExecutor在里面嵌入Dify的API调用让Dify负责知识库检索和基础对话LangChain负责复杂的决策逻辑。反过来也行把LangChain的Chain包装成Dify的一个自定义工具。我的建议是先用Dify把能可视化的部分搭好遇到画布表达不了的逻辑再用LangChain写代码补上。2.4 硬件与网络环境的最低要求CPU推理不是不能跑但体验很差。我的实测数据同样的7B模型纯CPU推理每秒出2-3个tokenGPURTX 3060 12GB能到30-40个token。Agent场景下一次工具调用可能要等十几秒CPU方案基本不可用。内存方面7B模型量化后约占4-6GB加上Dify和数据库16GB是起步线。如果要用14B模型建议32GB内存加8GB以上显存。硬盘最好用SSD模型加载速度差距很明显。网络环境有个容易被忽略的点Ollama首次拉取模型需要访问外部仓库如果网络不稳定可以用离线导入的方式——在能联网的机器上ollama pull之后把模型文件拷贝到目标机器的对应目录。3. 从零搭建的完整实操流程3.1 Ollama安装与模型拉取的具体步骤Linux下安装Ollama就是一行命令但Windows和macOS的体验略有不同。Windows建议用WSL2原生Windows版本虽然能用但GPU直通配置比较麻烦。macOS的Metal加速做得不错M系列芯片跑7B模型很流畅。安装完成后先跑ollama run qwen2.5:7b测试一下。第一次会下载模型大概4-5GB。下载完成后进入交互界面随便问个问题确认推理正常。然后退出用ollama serve启动API服务默认监听11434端口。这里有个关键配置Ollama默认的num_ctx是2048对于Agent场景太短了。你可以在Modelfile里改或者通过API请求时传参数。我一般设成8192再大内存吃不消。另外num_predict控制最大输出长度Agent的工具调用结果往往很长建议设到2048以上。# 查看已安装模型 ollama list # 启动API服务后台运行 ollama serve # 测试API连通性 curl http://localhost:11434/api/tags3.2 Dify的Docker部署与初始化配置先把Dify的仓库克隆下来进入docker目录复制.env.example为.env。然后重点改这几个参数EXPOSE_NGINX_PORT改成你想要的端口SECRET_KEY用随机字符串生成INIT_PASSWORD设一个强密码。启动命令是docker compose up -d第一次会拉取镜像视网络情况可能要等十几分钟。启动完成后访问http://localhost:你的端口用初始账号登录第一件事就是改密码。进入Dify后台后先别急着建应用。到“设置→模型供应商”里添加Ollama作为模型来源。基础URL填http://host.docker.internal:11434这是Docker容器访问宿主机的地址模型名称填你在Ollama里拉取的模型名。如果连接失败检查防火墙是否放行了11434端口。注意Docker Desktop for Mac和Windows下host.docker.internal是内置的。Linux下需要手动加--add-hosthost.docker.internal:host-gateway参数或者在compose文件里配置extra_hosts。3.3 知识库搭建从文档上传到检索调优Dify的知识库支持多种格式txt、pdf、md、docx。我建议先把文档整理成markdown格式因为PDF解析经常出问题尤其是扫描版和复杂表格。上传后Dify会自动分段但默认的分段策略不一定适合你的内容。分段设置里有两个关键参数分段长度和重叠长度。技术文档建议分段长度500-800字符重叠100-150字符。太小了检索不到完整语义太大了噪声多。我试过把分段长度设成200结果每个片段都是半句话检索效果很差。索引方式选“高质量”会调用embedding模型需要额外配置。如果不想再跑一个embedding模型可以选“经济”模式用关键词检索。但实测下来高质量模式的召回准确率明显更高。Embedding模型我推荐用bge-m3Ollama里可以直接拉中英文效果都不错。检索测试环节很重要。Dify提供了“召回测试”功能输入一个问题看返回的片段是否相关。如果召回不准先调分段再调检索的top-k和score阈值。我的经验是top-k设3-5score阈值0.5左右比较平衡。3.4 Agent搭建工具定义与提示词设计Dify的Agent节点需要你定义“工具”。工具可以是HTTP请求、自定义代码、或者另一个Dify应用。我一般先把工具在“工具”菜单里建好然后在Agent节点里勾选。工具描述写得好不好直接决定Agent会不会正确调用。比如一个“查询天气”的工具描述不能只写“查天气”要写清楚“输入城市名称返回该城市当前温度和天气状况”。Agent是根据描述来判断什么时候调用哪个工具的描述越具体误调用越少。提示词设计是Agent的灵魂。我的模板一般包含这几块角色定义、可用工具列表、调用规则、输出格式。调用规则里要明确“如果用户问题涉及实时数据必须先调用工具”“如果工具返回错误尝试换一种参数重新调用最多重试两次”。这些约束能显著减少Agent的“胡言乱语”。3.5 LangChain补足复杂逻辑的代码示例当Dify的画布搞不定时就该LangChain上场了。最常见的场景是“多步推理条件分支”。比如一个客服Agent要先判断用户意图再决定查知识库还是查订单系统最后根据结果决定是否转人工。from langchain.agents import AgentExecutor, create_react_agent from langchain.tools import Tool from langchain_community.llms import Ollama # 初始化本地模型 llm Ollama(modelqwen2.5:7b, base_urlhttp://localhost:11434) # 定义工具调用Dify的知识库检索API def query_dify_knowledge(query: str) - str: import requests resp requests.post( http://localhost:你的Dify端口/v1/retrieve, headers{Authorization: Bearer 你的APIKey}, json{query: query, top_k: 3} ) return resp.json()[results] tools [ Tool( name知识库检索, funcquery_dify_knowledge, description当用户询问产品功能、操作步骤时使用输入是用户的问题 ) ] # 构建Agent agent create_react_agent(llm, tools, prompt) executor AgentExecutor(agentagent, toolstools, max_iterations5) result executor.invoke({input: 怎么重置密码})这段代码的关键在于max_iterations设太小了Agent没想完就停了设太大了可能陷入死循环。我一般设5-8之间。另外create_react_agent的prompt需要自己写格式要符合ReAct范式网上有模板可以参考。4. 常见问题与排查技巧实录4.1 模型连接失败与超时问题最常见的问题是Dify连不上Ollama。排查顺序先在宿主机上curl http://localhost:11434/api/tags确认Ollama正常然后在Dify的容器里curl http://host.docker.internal:11434/api/tags确认容器能访问宿主机。如果容器内访问失败八成是网络配置问题。Linux下Docker默认的bridge网络无法解析host.docker.internal需要在compose文件里加extra_hosts: - host.docker.internal:host-gateway。另外如果宿主机开了防火墙11434端口可能被拦截临时关闭防火墙测试一下。超时问题多半是模型推理太慢。Agent场景下一次请求可能触发多次模型调用总耗时很容易超过Dify默认的60秒超时。解决办法是在模型供应商配置里把超时时间调到300秒以上同时考虑换更小的模型或者加GPU。4.2 知识库检索不准的调优思路检索不准的表现是明明文档里有答案但Agent就是找不到。原因通常有三个分段不合理、embedding模型不匹配、检索参数太严。分段问题前面说过了这里补充一点如果文档里有大量表格建议先把表格转成文字描述再上传。Embedding模型方面中文内容用bge-m3或text-embedding-3-large英文内容用nomic-embed-text。混用中英文的话bge-m3是当前比较稳的选择。检索参数里score_threshold设太高会过滤掉相关片段设太低会引入噪声。我的做法是先设0.3看召回结果再逐步往上调。另外可以开启“重排序”功能Dify支持接入重排序模型对召回结果做二次排序准确率能提升不少。4.3 Agent不调用工具或乱调用的解法Agent不调用工具通常是提示词里没写清楚“什么时候该用工具”。我见过有人把工具描述写成“查询数据”Agent根本不知道什么数据、什么时候查。改成“当用户询问订单状态时输入订单号返回订单当前状态和预计送达时间”调用率立刻上去了。乱调用工具则是描述太宽泛。比如同时有“查天气”和“查日历”两个工具描述都写“查询信息”Agent就会随机选。解决办法是在描述里加否定条件比如“本工具不处理日期计算日期计算请使用日历工具”。还有一个隐藏问题本地模型的函数调用能力参差不齐。有些模型对ReAct格式支持不好经常输出格式错误。如果遇到这种情况换一个对工具调用优化过的模型比如qwen2.5系列或者mistral系列。4.4 性能瓶颈的定位与优化整套系统的性能瓶颈通常在三个地方模型推理、向量检索、网络传输。定位方法是看日志时间戳如果模型调用耗时占比超过70%就是推理慢如果检索耗时高就是向量库的问题如果都不高但总耗时很长可能是Docker网络转发开销。模型推理优化换更小的量化版本、开GPU加速、减少num_predict。向量检索优化减少分段数量、降低top-k、用更快的向量库Qdrant比Weaviate轻量。网络优化把Dify和Ollama部署在同一台机器上避免跨机调用。我实测过一个配置Ollama跑qwen2.5:7b-q4Dify用Qdrant做向量库全部在一台16GB内存RTX 3060的机器上。知识库问答的端到端延迟在3-5秒Agent多步调用在10-15秒。这个性能做内部工具够用了但要做面向公众的服务还是得考虑云端API。4.5 常见问题速查表问题现象可能原因排查方法解决措施Dify连不上Ollama网络不通或端口未放行容器内curl测试加extra_hosts或改防火墙模型加载失败内存不足或模型文件损坏查看Ollama日志换小模型或重新pull知识库检索为空分段太长或阈值太高用召回测试功能调小分段、降低阈值Agent不调工具工具描述不清晰查看Agent执行日志重写工具描述响应超时推理太慢或超时设置短看各环节耗时加GPU或调大超时输出格式错误模型不支持ReAct检查模型输出换模型或改提示词5. 进阶玩法与扩展思路5.1 多Agent协作的初步尝试单个Agent搞不定复杂任务时可以考虑多Agent分工。比如一个“协调者Agent”负责拆解任务一个“检索Agent”负责查知识库一个“执行Agent”负责调外部接口。Dify目前对多Agent的支持还在演进中但可以通过“Agent调用Agent”的方式模拟。具体做法是把子Agent封装成Dify应用然后在主Agent的工具列表里添加“调用子Agent”的工具。主Agent根据任务类型决定调用哪个子Agent。这种架构的挑战在于上下文传递——子Agent的返回结果要能被主Agent理解所以输出格式要统一约定。LangChain这边有AgentExecutor的嵌套方案但调试起来比较麻烦。我的建议是先用Dify的可视化方式跑通逻辑确认分工合理之后再用LangChain重写性能敏感的部分。5.2 知识库的增量更新与版本管理知识库不是建一次就完事了。文档会更新旧内容会过时。Dify支持对已有知识库追加文档但删除和修改比较麻烦。我的做法是按“文档集”来管理每个文档集对应一个主题更新时新建文档集测试通过后再切换Agent的检索范围。版本管理方面Dify没有内置的知识库版本控制。我一般用Git管理原始文档每次更新打tagDify这边手动同步。如果更新频繁可以考虑用Dify的API做自动化同步写个脚本监控文档目录的变化。提示知识库更新后记得清空检索缓存。Dify的缓存机制有时会导致旧内容被召回重启一下api容器就能解决。5.3 从本地Demo到生产环境的差距本地跑通和上线服务是两码事。生产环境要考虑并发、鉴权、日志、监控。Dify本身支持多用户和API Key管理但并发能力受限于本地模型的推理速度。如果用户量上来要么加GPU要么把模型换成云端API。鉴权方面Dify的API Key要妥善保管不要硬编码在前端。日志方面Dify有操作日志但Agent的详细执行过程需要自己埋点。监控方面至少要把模型调用的延迟和错误率统计出来不然出了问题都不知道从哪查。我的经验是本地Demo验证可行性生产环境先用小流量灰度观察一周再全量。别一上来就追求高并发先把单次请求的稳定性和准确性做好。5.4 几个容易踩的坑和应对技巧第一个坑Ollama的模型默认加载到内存后不会自动卸载多个模型切换时内存会爆。解决办法是设置OLLAMA_MAX_LOADED_MODELS1或者手动ollama stop不用的模型。第二个坑Dify的Docker Compose默认没有资源限制Ollama和Dify抢内存。建议在compose文件里给每个服务加deploy.resources.limits避免一个服务把整机内存吃光。第三个坑Agent的提示词里如果包含大量示例会占用很多上下文窗口。本地模型的上下文本来就有限示例太多会导致真正的问题被截断。我的做法是示例精简到2-3个只保留最典型的场景。第四个坑知识库的embedding模型和检索时的模型必须一致。我见过有人建库时用了一个模型检索时换了另一个结果召回率直接归零。换embedding模型意味着要重建整个知识库这个成本要提前考虑。5.5 后续可以扩展的方向这套架构跑通之后可以往几个方向扩展。一是接入更多工具比如邮件发送、日历创建、数据库查询让Agent真正能“干活”。二是做多模态Ollama已经支持部分视觉模型可以把图片理解加进知识库。三是做自动化评测写一组测试问题定期跑一遍看Agent的回答质量有没有下降。我个人最看好的是“Agent工作流”的混合模式。简单任务走工作流保证稳定性和速度复杂任务走Agent保证灵活性。Dify的画布支持条件分支可以根据用户输入自动路由到不同的处理路径。这个模式在实际项目中比纯Agent靠谱得多。最后分享一个小技巧调试Agent时把max_iterations设成1强制它只走一步看每一步的输出是否符合预期。确认单步没问题了再放开迭代次数。这样排查问题比看一长串日志高效得多。
