LangChain应用开发:用脚手架组装本地 LLM 应用

简介: LangChain 是专为 LLM 应用开发设计的 Python 脚手架,提供模型(ChatModel)、提示模板(PromptTemplate)、输出解析(OutputParser)和链式编排(Runnable)等统一接口,轻松集成本地 Ollama 等兼容服务,不占显存、解耦模型、提升复用性。(239字)

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 接本地模型"这类词的搜索热度持续很高,但抱怨也很集中:接口迭代快,教程和库版本对不上。本篇以官方文档当前版本的写法为准,示例也都按这个口径标注——思路可以迁移,具体类名与参数请按官方文档核对后再用。

二、环境要求

项目 要求 说明
Python 3.10 / 3.11 / 3.12 保守选 3.11(详见《AI-03 Python环境与虚拟环境》)
虚拟环境 建议 venv 隔离 防止依赖互相污染(见 3.1)
Ollama 已安装且拉取至少一个 LLM(如 qwen2.5:7b) 详见《AI-07 Ollama本地部署大模型》
Ollama API http://localhost:11434 可达 curl http://localhost:11434/api/tags 能返回模型列表
网络 pip 安装(国内建议清华镜像) -i https://pypi.tuna.tsinghua.edu.cn/simple
显存 LangChain 本身不需要额外显存 预算在 Ollama 模型侧(AI-05 口径)

三、安装与部署

3.1 先建虚拟环境(防依赖地狱的第一铁律)

LangChain 的依赖树不小且迭代快,装进全局环境基本等于把"依赖地狱"请回家。我一般每个项目单独建一个 venv:

python -m venv .venv
.venv\Scripts\activate      # Windows(Linux 用 source .venv/bin/activate)

3.2 安装 langchain

pip install langchain langchain-community
  • langchain:主包,核心抽象都在这里;
  • 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(或你已有的任意模型名):

# 注意:导入路径 / 参数名以官方文档当前版本为准
from langchain_community.chat_models import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser

# 接本地 Ollama:走 OpenAI 兼容端点
llm = ChatOpenAI(
    model="qwen2.5:7b",
    base_url="http://localhost:11434/v1",   # Ollama 的 /v1 兼容端点
    api_key="ollama",                        # Ollama 不校验 key,随便填个字符串即可
)

prompt = ChatPromptTemplate.from_template(
    "用一句话解释{概念},面向新手,避免术语。"
)
parser = StrOutputParser()

chain = prompt | llm | parser                # Runnable 链
print(chain.invoke({
   "概念": "RAG"}))

两个常见变体(同样以官方文档当前写法为准):一是结构化输出——让模型返回 JSON,再换成对应的 OutputParser 解析成 dict,程序里就能直接取字段,比从一大段文字里正则抠信息稳定得多;二是流式输出——回答逐段吐出来而不是等完整结果,前端体验好很多。做小项目时的顺序建议:先把非流式、纯文本版本跑通,再叠加这两个能力。

执行顺序:模板填变量 → 组装好的提示词发到 Ollama 的 /v1/chat/completions → 返回文本交给 Parser → 得到最终输出。把 model 换成 ollama list 里的另一个模型名,就完成了一次"换模型"——这正是框架替你买到的能力,裸 API 写法里它要改的不止一处。

四、验证

  1. 网络层:宿主机 curl http://localhost:11434/api/tags 能返回 JSON 模型列表;
  2. 环境层:where python(Windows)/ which python(Linux)指向 .venv 里的解释器,且 python -c "import langchain; print(langchain.__version__)" 能出版本号;
  3. 链路层:运行 3.4 的脚本,终端打印出一句解释(内容随模型而定,重点是有输出且跑通三段);
  4. 组件层(可选):在链上加打印,确认模板填充后的提示词、LLM 原始返回、Parser 结果各段都符合预期。

这四层验证的意义不只是"跑通了",而是给你一套 30 秒排错反射:以后出问题,先按顺序跑这四步,确定断在哪层,再只修那一层。这就是系列统一的"分层定位法"——网络层(服务应不应)→ 环境层(解释器对不对)→ 应用层(链通不通)。常见的情况是花一小时改代码,最后发现"Ollama 忘了启动"。

卡在哪一层,对照第六节;这四层就是排错的顺序。

五、进阶技巧

5.1 RAG 在 LangChain 里怎么搭:组件对应表(不重复原理)

为什么强调"不重复原理"?RAG 的完整原理 AI-19 已经讲清,本篇要回答的是另一个问题:这条链路如果想自己用代码写,每一步该找什么组件。答案就是下面这张对应表——你只需要记住"环节 → 组件"的映射关系,每个组件的具体类名与参数到官方文档里查当前版本。

RAG 标准链路(文档 → 解析 → 切块 → 嵌入 → 入库 → 检索 → 拼提示词 → 生成,原理详见)与 LangChain 组件一一对应:

RAG 链路环节 LangChain 组件 备注
解析(Loader) Document Loader 读 TXT/MD/PDF 等
切块(Splitter) Text Splitter 经验值:chunk 800-1200 字 + 10-15% 重叠
嵌入(Embedding) Embeddings 接口 本地可用 Ollama 的 bge-m3 / nomic-embed-text(以 library 为准)
入库(向量库) 向量库集成(Chroma / FAISS / Milvus) 选型见《AI-20 向量数据库与嵌入模型》
检索(top-k) Retriever 经验参考 top-k 3-8
拼提示词 + 生成 PromptTemplate + ChatModel + Parser 复用 3.4 的最小链

可以看到:LangChain 没有发明新的 RAG,它只是给 RAG 链路的每个环节提供了可插拔的槽位。不写代码想要 RAG,AnythingLLM、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 /v1(AI-08)
多组件编排 / 多模型切换 / RAG,且要代码定制 LangChain
复杂 Agent(多步、有状态、工具循环) LangGraph(AI-36)
不写代码、要可视化编排 Dify(AI-18)

我的判断标准:项目里只有一处 LLM 调用,框架是负担;出现三件以上组件(提示词模板 + 检索 + 解析 + 第二个模型),框架就开始回本。

5.4 三大常见坑(都是高频真实体验)

依赖地狱:LangChain 生态包多,版本约束也严,典型症状是"pip install 成功了,import 却报错",或者"升级了一个包,另外两个跟着坏"。我的习惯:每项目一个独立 venv(3.1 那步不是可选项);从不单独升级某个包——要么整套一起升,要么都不动;遇到版本冲突,先整体升级 langchain 全家桶对齐生态,再逐个定位。

版本迭代快:这个库的迭代速度远高于一般 Python 库,教程天然滞后几个月——你看的文章里的类名、参数、导入路径,在你装的版本里可能已经不存在了。正确姿势:把教程当"概念讲解"用,动手时以官方文档查到的当前 API 形态为准(本篇示例也都是这个处理方式)。

接口变动:接口变动导致"昨天能跑今天报错"在这个生态不罕见。处理顺序:先对比两个环境的 pip show langchain 版本,确认不是"环境不一致";再查官方文档的迁移说明;最后才考虑去论坛找代码片段——直接照抄论坛代码,往往把旧版本的问题原样搬进新环境。

三个坑的根源是同一个:一切以官方文档的当前版本为准。本篇代码写作时同样以此为准,你运行前请按当前版本再核对一遍。

六、故障排查(按层定位)

# 症状(报错原文) 层 原因 解决
1 ModuleNotFoundError: No module named 'langchain' 环境 激活的解释器不是装了包的环境(全局与 venv 混了) where python(Win)/ which python(Linux)确认解释器路径;重新激活 .venv 再装
2 ModuleNotFoundError: No module named 'langchain.chains'(网上教程的导入路径失效类) 依赖 LangChain 拆包、模块重组,旧导入路径已不存在(接口迭代快) 以 python.langchain.com 当前模块结构为准,别照抄旧博客代码;整套包一起升级,别只升单个
3 ImportError: DLL load failed while importing ...(Windows) 环境 VC++ 运行库缺失 / Python 位数不对(32 位) 装 VC++ 2015-2022 Redistributable x64;确认是 64 位 Python
4 HuggingFace 下载卡住 / ConnectionError / 超时(下载 bge-m3 等嵌入模型时) 网络 国内访问 huggingface.co 受限 set HF_ENDPOINT=https://hf-mirror.com(Win)/ export HF_ENDPOINT=https://hf-mirror.com(Linux),或走 ModelScope(详见《AI-06 模型下载全攻略》)
5 Ollama 拉模型中途断(网络抖动)/ ollama: command not found 网络/安装 大文件传输中断;或 PATH 未刷新 重新 ollama pull(支持断点续传,继续拉即可);重开终端,检查安装
6 Failed to start Ollama service(Linux)/ 11434 端口被占 服务/端口 端口被占用 / 服务未起 `netstat -ano \ findstr :11434(Win)/lsof -i:11434(Linux)找占用;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_url="http://localhost:11434/v1"
  • [ ] 能默写 RAG ↔ LangChain 组件对应表(Loader / Splitter / Embeddings / 向量库 / Retriever)
  • [ ] 理解 LangGraph 的边界(多步、有状态、Agent 循环)与四行选型表
  • [ ] 能独立排掉两种 ModuleNotFoundError 与 ImportError: DLL load failed
  • [ ] 对自己的项目做过判断:一处调用不用框架,多组件编排才用
相关文章
|
1月前
|
并行计算 PyTorch Linux
显存计算与模型选择:你的显卡能跑多大的模型
本篇直击本地部署核心痛点:显存不够?模型选错?用公式(权重+KV Cache+开销)教你精准估算,附8/12/16/24/48GB显存档位经验表,明确给出“24G甜点是32B Q4_K_M”,告别OOM玄学。
|
Java Go Nacos
Spring Cloud Alibaba Nacos配置导入问题解决方案
Spring Cloud Alibaba Nacos配置导入问题解决方案
3155 0
|
1月前
|
缓存 并行计算 PyTorch
模型量化完全指南:GGUF、GPTQ、AWQ 怎么选
本指南详解大模型量化核心:显存为何能减半/四分之一?GGUF(CPU/GPU通用,Q4_K_M甜点)、GPTQ(PyTorch生态,4/8bit)、AWQ(激活感知,vLLM服务首选)三大方案适用场景与选型逻辑——不比谁压得狠,而看“你的显存配哪档最划算”。
|
1月前
|
机器学习/深度学习 编解码 运维
工业缺陷检测实战:小样本训练与漏检控制全流程
本文详解工业缺陷检测实战:聚焦小样本训练与漏检控制全流程。直击“极小目标、极少样本、极高漏检代价”三大痛点,系统梳理数据组织、建模选型(检测/分割/异常)、迁移学习、缺陷贴片增强、类别平衡及漏检率优先评估等关键环节,附可运行代码与排查指南。(239字)
|
1月前
|
文字识别 并行计算 物联网
RAG检索增强实战:原理、七步链路与最小可用代码
本文详解RAG检索增强生成的原理与实战,拆解文档解析、切块、嵌入、入库、检索、Prompt拼接、答案生成七大关键步骤,揭示各环节可调参数与典型陷阱。附最小可用Python代码(Ollama+Chroma),助你手写可控RAG系统,精准定位知识库失效根源。(239字)
|
1月前
|
并行计算 Linux 开发工具
llama.cpp 与 GGUF 格式:本地大模型的“裸引擎“
llama.cpp是纯C/C++编写的轻量级大模型推理引擎,无需Python依赖,支持CPU/GPU混合加速;GGUF为其统一二进制格式,集量化权重、架构配置、元数据于一体,实现“一模多用”。本文手把手教你Windows/Linux下获取、运行模型及启动OpenAI兼容API服务。(239字)
|
9月前
|
人工智能 数据可视化 Java
AI智能体的开发方法
本文系统梳理国内AI智能体开发全景:从“感知-决策-行动-记忆”认知闭环架构出发,对比Dify、Coze等低代码平台与LangGraph、AgentScope、Eino、Spring AI Alibaba等编程级框架;解析MCP协议、RAG技术栈等基础设施;并按MVP、企业级、极客定制三类场景给出选型建议。(239字)
|
9月前
|
缓存 JSON API
锦程物流item_get - 获取详情接口对接全攻略:从入门到精通
锦程物流item_get接口是RESTful风格的HTTPS安全API,用于实时查询物流订单状态、轨迹及收发货人信息。支持JSON传输、签名认证(MD5)、沙箱/生产双环境,并提供Python/Java/PHP示例、批量查询、缓存与异步回调等高级功能。(239字)
|
4月前
|
消息中间件 存储 分布式计算
AutoMQ x 阿里云 OSS Tables:基于 Iceberg 构建流表一体的实时入湖
实时数据入湖效率影响分析时效。传统Kafka→Flink→Iceberg链路需维护同步任务与表优化,成本高、运维重。AutoMQ x OSS Tables新方案实现Kafka Topic自动物化为Iceberg表,并在OSS侧提供托管Catalog与自动化Compaction,端到端简化架构,零额外计算负担,支持Schema演进与CDC Upsert,大幅提升实时入湖可靠性与效率。(239字)
374 0
|
10月前
|
数据采集 监控 API
淘宝评论API:差评预警系统,及时处理!
利用淘宝评论API可构建差评预警系统,实时监控商品评价,自动识别低分或含负面关键词的评论,并通过邮件等渠道及时通知商家。系统由数据采集、差评检测、预警触发和响应处理模块组成,支持快速干预,提升客户满意度与店铺信誉,降低负面评价对销量的影响。