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

> 前面的 RAG 全链路是用手写 Python 跑通的，每一步——加载、切块、嵌入、检索、拼 Prompt——都是散的。如果打算把这些步骤复用、组装成更大的应用，就需要一层"胶水"，LangChain 是这层胶水里用得最广的一个。这一篇把它和本地 Ollama 拼起来跑通，也顺带回答一个更实际的问题：什么规模的个人项目，其实用不上它。

![在这里插入图片描述](https://developer.qcloudimg.com/http-save/yehe-12801654/e67138210bc08435c12e9dcfec805fa5.png)


## 一、为什么需要它

装完 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`（或你已有的任意模型名）：

```python
# 注意：导入路径 / 参数名以官方文档当前版本为准
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`
- [ ] 对自己的项目做过判断：一处调用不用框架，多组件编排才用

前面的 RAG 全链路是用手写 Python 跑通的，每一步——加载、切块、嵌入、检索、拼 Prompt——都是散的。如果打算把这些步骤复用、组装成更大的应用，就需要一层"胶水"，LangChain 是这层胶水里用得最广的一个。这一篇把它和本地 Ollama 拼起来跑通，也顺带回答一个更实际的问题：什么规模的个人项目，其实用不上它。

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

人工智能

LangChain作为LLM应用开发脚手架，通过PromptTemplate、ChatModel、OutputParser和Chain四类核心组件实现模块化组装。与本地Ollama结合时，利用OpenAI兼容端点无缝接入。提供RAG链路组件映射、LangGraph流程编排及版本迭代应对策略，是构建可复用、可扩展LLM应用的关键工具。

向量数据库

文件传输

代码解释

数据库

LangChain

LangGraph

解释器

Windows

Python

Agent

Linux

JSON

2026上云采购 | AI焕新·智启新局

4核4G3M云服务器 新用户低至38元/年！

lexiang

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

LangChain作为LLM应用开发脚手架，通过PromptTemplate、ChatModel、OutputParser和Chain四类核心组件实现模块化组装。与本地Ollama结合时，利用OpenAI兼容端点无缝接入。提供RAG链路组件映射、LangGraph流程编排及版本迭代应对策略，是构建可复用、可扩展LLM应...

LangChain应用开发：用脚手架组装本地 LLM 应用-腾讯云开发者社区-腾讯云

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

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

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐