LangChain应用开发用脚手架组装本地 LLM 应用前面的 RAG 全链路是用手写 Python 跑通的每一步——加载、切块、嵌入、检索、拼 Prompt——都是散的。如果打算把这些步骤复用、组装成更大的应用就需要一层胶水LangChain 是这层胶水里用得最广的一个。这一篇把它和本地 Ollama 拼起来跑通也顺带回答一个更实际的问题什么规模的个人项目其实用不上它。一、为什么需要它装完 Ollama之后很多人的下一步就是写点代码调模型。直接的办法是拿 requests 直接 POST 到 Ollama 的 OpenAI 兼容端点接口细节见《AI-08 Ollama进阶与API开发》——做一次性问答小脚本完全够用。但一个真正的应用往往不止一次调用提示词要模板化带变量、带角色设定、输出要解析抽 JSON、取字段、做格式化、可能要换模型分类用一个、生成用一个、还要把 RAG 检索结果拼进上下文。这些如果全靠手写裸 API 调用等于自己在重复造一层胶水而且换个模型、换个接口就要返工。LangChain 的定位正是这一层把 LLM 组装成应用的脚手架/胶水层。它给模型ChatModel、“提示词”PromptTemplate、“输出”OutputParser、“组件串联”Chain/Runnable提供统一接口任何遵循 OpenAI 兼容协议的模型包括本地 Ollama都能被当成一个可插拔的组件接进来。你写的是应用逻辑而不是翻译层。还有一层容易被忽略LangChain 生态是拆包的。你一条命令装的是主包具体模型集成接 OpenAI 兼容端点的 ChatOpenAI 等放在 langchain-community 这个社区包里核心抽象提示词、Runnable、解析器则随主包带进 langchain-core。所以不同教程里的导入路径长得不一样很多时候只是包版本不同——这是教程代码跑不起来的主要原因之一本篇统一按以官方文档为准的口径处理。先把话说死LangChain 本身不带模型、不占显存——它是个纯进程内的 Python 库推理全部发生在 Ollama或其他推理服务那端。显存预算还是《显存计算与模型选择》那套口径LangChain 一分不加。这也是本篇环境要求里没有 GPU 硬指标的原因。“LangChain 教程”LangChain 接本地模型这类词的搜索热度持续很高但抱怨也很集中接口迭代快教程和库版本对不上。本篇以官方文档当前版本的写法为准示例也都按这个口径标注——思路可以迁移具体类名与参数请按官方文档核对后再用。二、环境要求项目要求说明Python3.10 / 3.11 / 3.12保守选 3.11详见《AI-03 Python环境与虚拟环境》虚拟环境建议 venv 隔离防止依赖互相污染见 3.1Ollama已安装且拉取至少一个 LLM如 qwen2.5:7b详见《AI-07 Ollama本地部署大模型》Ollama APIhttp://localhost:11434可达curl http://localhost:11434/api/tags能返回模型列表网络pip 安装国内建议清华镜像-i https://pypi.tuna.tsinghua.edu.cn/simple显存LangChain 本身不需要额外显存预算在 Ollama 模型侧AI-05 口径三、安装与部署3.1 先建虚拟环境防依赖地狱的第一铁律LangChain 的依赖树不小且迭代快装进全局环境基本等于把依赖地狱请回家。我一般每个项目单独建一个 venvpython -m venv .venv .venv\Scripts\activate # WindowsLinux 用 source .venv/bin/activate3.2 安装 langchainpip install langchain langchain-communitylangchain主包核心抽象都在这里langchain-community社区集成包接 Ollama 走的 OpenAI 兼容端点所用的类就在这个包里这行省不掉。国内网络加镜像pip install langchain langchain-community -i https://pypi.tuna.tsinghua.edu.cn/simple。3.3 四个核心概念接口迭代快以官方文档说明为准LLM / ChatModel模型接口。ChatModel 面向对话式模型消息进出本地 LLM 基本都走它PromptTemplate提示词模板。用{变量}留空调用时填入具体值OutputParser输出解析器。把模型的原始输出整理成程序里好用的形式字符串、JSON、对象Chain / Runnable组件串联。上述组件都实现了 Runnable 接口可以用|管道运算符串成一条链——prompt | llm | parser是 LangChain 最经典的写法。把它们串成直觉PromptTemplate 像一张带空格的表单ChatModel 是填表提交这个动作OutputParser 是把返回结果整理成程序可用格式的后处理Chain 是把三者接起来的传送带。后面 7 行代码看似能干很多事本质就是这条流水线填表 → 提交 → 整理结果。具体类名、导入路径、参数名以官方文档当前版本为准python.langchain.com下文示例按写作时官方文档的写法给出跑之前先核对一遍导入路径。3.4 一个最小可跑链路Prompt → LLM → Parser前提Ollama 已启动且ollama list里能看到qwen2.5:7b或你已有的任意模型名# 注意导入路径 / 参数名以官方文档当前版本为准fromlangchain_community.chat_modelsimportChatOpenAIfromlangchain_core.promptsimportChatPromptTemplatefromlangchain_core.output_parsersimportStrOutputParser# 接本地 Ollama走 OpenAI 兼容端点llmChatOpenAI(modelqwen2.5:7b,base_urlhttp://localhost:11434/v1,# Ollama 的 /v1 兼容端点api_keyollama,# Ollama 不校验 key随便填个字符串即可)promptChatPromptTemplate.from_template(用一句话解释{概念}面向新手避免术语。)parserStrOutputParser()chainprompt|llm|parser# Runnable 链print(chain.invoke({概念:RAG}))两个常见变体同样以官方文档当前写法为准一是结构化输出——让模型返回 JSON再换成对应的 OutputParser 解析成 dict程序里就能直接取字段比从一大段文字里正则抠信息稳定得多二是流式输出——回答逐段吐出来而不是等完整结果前端体验好很多。做小项目时的顺序建议先把非流式、纯文本版本跑通再叠加这两个能力。执行顺序模板填变量 → 组装好的提示词发到 Ollama 的/v1/chat/completions→ 返回文本交给 Parser → 得到最终输出。把model换成ollama list里的另一个模型名就完成了一次换模型——这正是框架替你买到的能力裸 API 写法里它要改的不止一处。四、验证网络层宿主机curl http://localhost:11434/api/tags能返回 JSON 模型列表环境层where pythonWindows/which pythonLinux指向.venv里的解释器且python -c import langchain; print(langchain.__version__)能出版本号链路层运行 3.4 的脚本终端打印出一句解释内容随模型而定重点是有输出且跑通三段组件层可选在链上加打印确认模板填充后的提示词、LLM 原始返回、Parser 结果各段都符合预期。这四层验证的意义不只是跑通了而是给你一套 30 秒排错反射以后出问题先按顺序跑这四步确定断在哪层再只修那一层。这就是系列统一的分层定位法——网络层服务应不应→ 环境层解释器对不对→ 应用层链通不通。常见的情况是花一小时改代码最后发现Ollama 忘了启动。卡在哪一层对照第六节这四层就是排错的顺序。五、进阶技巧5.1 RAG 在 LangChain 里怎么搭组件对应表不重复原理为什么强调不重复原理RAG 的完整原理 AI-19 已经讲清本篇要回答的是另一个问题这条链路如果想自己用代码写每一步该找什么组件。答案就是下面这张对应表——你只需要记住环节 → 组件的映射关系每个组件的具体类名与参数到官方文档里查当前版本。RAG 标准链路文档 → 解析 → 切块 → 嵌入 → 入库 → 检索 → 拼提示词 → 生成原理详见与 LangChain 组件一一对应RAG 链路环节LangChain 组件备注解析LoaderDocument Loader读 TXT/MD/PDF 等切块SplitterText Splitter经验值chunk 800-1200 字 10-15% 重叠嵌入EmbeddingEmbeddings 接口本地可用 Ollama 的 bge-m3 / nomic-embed-text以 library 为准入库向量库向量库集成Chroma / FAISS / Milvus选型见《AI-20 向量数据库与嵌入模型》检索top-kRetriever经验参考 top-k 3-8拼提示词 生成PromptTemplate ChatModel Parser复用 3.4 的最小链可以看到LangChain 没有发明新的 RAG它只是给 RAG 链路的每个环节提供了可插拔的槽位。不写代码想要 RAGAnythingLLM、Dify都是现成平台需要定制、要嵌进自己的程序里才轮到 LangChain。有一个细节值得单独强调RAG 里的嵌入模型和生成模型是两次独立的选择。本地场景两者都可以让 Ollama 提供——嵌入选 bge-m3 或 nomic-embed-text生成选 qwen2.5:7b 这类模型名以 ollama.com/library 为准。漏配嵌入模型是本地 RAG 最经典的链路转不起来事故和 AI-18 里 Dify 知识库的教训完全同源。5.2 LangGraph 一句话LangChain 解决一串组件多步、有状态、带循环和分支的流程比如 Agent 的思考 → 调工具 → 观察结果 → 再思考交给 LangGraph它把流程表达成一张带状态的图Agent 循环就是其中一个典型用例。一条判断标准如果你的流程是直线型A → B → C一次走完LangChain 的链就够了如果流程里有循环模型调了工具、要看结果、再决定下一步可能反复或需要记住中间状态多轮对话上下文、任务进度就该上 LangGraph。编程 Agent、“深度研究型 Agent 都属于后者——它们的本质是带记忆的循环”不是一串组件。5.3 生态选型建议开工前先对号入座你的场景建议一问一答的小脚本、只用一个模型不一定要框架requests 直连 Ollama/v1AI-08多组件编排 / 多模型切换 / RAG且要代码定制LangChain复杂 Agent多步、有状态、工具循环LangGraphAI-36不写代码、要可视化编排DifyAI-18我的判断标准项目里只有一处 LLM 调用框架是负担出现三件以上组件提示词模板 检索 解析 第二个模型框架就开始回本。5.4 三大常见坑都是高频真实体验依赖地狱LangChain 生态包多版本约束也严典型症状是pip install 成功了import 却报错或者升级了一个包另外两个跟着坏。我的习惯每项目一个独立 venv3.1 那步不是可选项从不单独升级某个包——要么整套一起升要么都不动遇到版本冲突先整体升级 langchain 全家桶对齐生态再逐个定位。版本迭代快这个库的迭代速度远高于一般 Python 库教程天然滞后几个月——你看的文章里的类名、参数、导入路径在你装的版本里可能已经不存在了。正确姿势把教程当概念讲解用动手时以官方文档查到的当前 API 形态为准本篇示例也都是这个处理方式。接口变动接口变动导致昨天能跑今天报错在这个生态不罕见。处理顺序先对比两个环境的pip show langchain版本确认不是环境不一致再查官方文档的迁移说明最后才考虑去论坛找代码片段——直接照抄论坛代码往往把旧版本的问题原样搬进新环境。三个坑的根源是同一个一切以官方文档的当前版本为准。本篇代码写作时同样以此为准你运行前请按当前版本再核对一遍。六、故障排查按层定位#症状报错原文层原因解决1ModuleNotFoundError: No module named langchain环境激活的解释器不是装了包的环境全局与 venv 混了where pythonWin/which pythonLinux确认解释器路径重新激活.venv再装2ModuleNotFoundError: No module named langchain.chains网上教程的导入路径失效类依赖LangChain 拆包、模块重组旧导入路径已不存在接口迭代快以 python.langchain.com 当前模块结构为准别照抄旧博客代码整套包一起升级别只升单个3ImportError: DLL load failed while importing ...Windows环境VC 运行库缺失 / Python 位数不对32 位装 VC 2015-2022 Redistributable x64确认是 64 位 Python4HuggingFace 下载卡住 / ConnectionError / 超时下载 bge-m3 等嵌入模型时网络国内访问 huggingface.co 受限set HF_ENDPOINThttps://hf-mirror.comWin/export HF_ENDPOINThttps://hf-mirror.comLinux或走 ModelScope详见《AI-06 模型下载全攻略》5Ollama 拉模型中途断网络抖动/ollama: command not found网络/安装大文件传输中断或 PATH 未刷新重新ollama pull支持断点续传继续拉即可重开终端检查安装6Failed to start Ollama serviceLinux/ 11434 端口被占服务/端口端口被占用 / 服务未起netstat -ano | findstr :11434Win/lsof -i:11434Linux找占用sudo journalctl -u ollama看日志7代码连http://localhost:11434/v1超时/拒绝连接应用Ollama 没启动或代码里模型名不在库里宿主机先curl http://localhost:11434/api/tags验证服务确认ollama list里有代码里写的那个模型名排错顺序环境层解释器对不对→ 网络层装得上吗→ 服务层Ollama 活着吗→ 应用层链通吗。应用层反复改代码没用的时候多半是下层 Ollama 没启动。七、本篇自检清单能说出 LangChain 的定位LLM 应用脚手架/胶水层本身不占显存pip install langchain langchain-community完成且装在独立 venv 里能说出四个核心概念ChatModel / PromptTemplate / OutputParser / Chain-Runnable各管什么3.4 的最小链路跑通接 Ollama 用的是base_urlhttp://localhost:11434/v1能默写 RAG ↔ LangChain 组件对应表Loader / Splitter / Embeddings / 向量库 / Retriever理解 LangGraph 的边界多步、有状态、Agent 循环与四行选型表能独立排掉两种ModuleNotFoundError与ImportError: DLL load failed对自己的项目做过判断一处调用不用框架多组件编排才用