一、为什么我们需要 LangChain？
1.1 大模型应用开发的三大核心痛点
在 LangChain 出现之前，开发工业级 LLM 应用需要从零解决以下问题，这也是绝大多数个人和团队的痛点：
| 痛点 | 具体表现 | 传统解决方案的缺陷 |
|---|---|---|
| 接口碎片化 | 不同大模型（OpenAI、Anthropic、通义千问、本地模型）的 API 格式、参数、返回值完全不同 | 重复编写适配代码，维护成本高，切换模型需要重构 |
| 可观测性缺失 | LLM 是 "黑盒"，无法追踪每一步的输入输出、执行时间、Token 消耗 | 难以调试错误、无法定位性能瓶颈、无法评估系统效果 |
| 复杂流程难实现 | 多轮对话、工具调用、循环推理、人机交互等复杂逻辑需要手动管理状态和流程 | 代码混乱、扩展性差、容易出现无限循环和状态不一致 |
1.2 LangChain 的本质：LLM 应用的操作系统
LangChain 不是一个简单的工具库，而是大语言模型应用的操作系统，它提供了一套标准化的抽象和工具链，让开发者可以专注于业务逻辑，而不是底层基础设施。
它解决了 LLM 应用开发的三大核心问题：
- ✅ 可组合性：将 LLM、提示词、检索、工具等组件标准化为可插拔的 "积木"，任意组合
- ✅ 可观测性：通过 LangSmith 实现全链路追踪、评估和监控
- ✅ 可扩展性：支持从简单的问答机器人到复杂的多智能体系统的平滑演进
1.3 为什么必须学 LangChain 1.2+，而不是旧版本？
LangChain 1.0 是一个里程碑式的版本，它彻底重构了架构，解决了 0.x 版本的所有核心问题。
本课程完全不涉及任何已弃用的 0.x API（如LLMChain、AgentExecutor、旧Chain类），所有代码均符合 1.2 + 工业级标准。
二、LangChain 全景与架构解析
2.1 LangChain 四大核心层级架构
LangChain 采用分层架构设计，每层职责明确，依赖关系清晰，这是它能够支持大规模复杂应用的关键。
LangChain 核心层级图：
各层级详细说明：
-
langchain-core（最底层，核心抽象）
- 定义了所有组件的基础接口：
Runnable、BaseChatModel、BaseRetriever、BaseTool等 - 实现了 LCEL 表达式语言、状态管理、Middleware 系统
- 无任何第三方依赖，是整个生态的基石
- 版本更新最慢，保证 API 稳定性
- 定义了所有组件的基础接口：
-
langchain-community（社区贡献层）
- 由社区维护的第三方集成：各种大模型、向量数据库、工具、加载器
- 包含超过 1000 种集成，覆盖几乎所有主流 LLM 服务和工具
- 版本更新快，新功能优先在这里发布
-
langchain（官方组件层）
- 由 LangChain 官方维护的核心组件
- 包含经过验证的、生产级的 RAG 链、Agent 实现、提示模板等
- 依赖 langchain-core 和 langchain-community
- 是大多数应用开发的主要依赖
-
LangGraph（编排层，1.2 + 核心）
- 专门用于构建有状态、多步骤、循环工作流的库
- 是 LangChain 1.0 + 所有 Agent 的底层实现
- 支持状态持久化、断点续跑、人机交互、时间旅行调试
- 解决了传统 Chain 无法处理复杂流程的问题
2.2 LangChain 完整生态系统
LangChain 不是一个孤立的框架，而是一个完整的生态系统，覆盖了 LLM 应用从开发到部署、监控的全生命周期。
LangChain 生态全景图：
各生态组件的作用：
- LangSmith：LLM 应用的可观测性平台，提供追踪、评估、提示词管理、监控功能，是开发和调试 LLM 应用的必备工具
- LangServe：基于 FastAPI 的 LLM 应用部署框架，一键将 LangChain 应用部署为 RESTful API，自带 Playground 测试界面
- 集成层：提供了与各种第三方服务的标准化集成，让开发者无需关心底层 API 差异
三、开发环境搭建
3.1 环境标准与工具选型
为了避免 "我这里能跑，你那里跑不了" 的问题，本课程采用以下统一标准：
| 工具 | 版本要求 | 选型理由 |
|---|---|---|
| Python | 3.12.3 | LangChain 1.2 + 官方推荐，性能最好，兼容性最佳 |
| 版本管理 | pyenv 2.4.0+ | 管理多个 Python 版本，隔离系统 Python |
| 依赖管理 | poetry 1.8.3+ | 替代 pip+venv，自动管理虚拟环境和依赖版本 |
| 编辑器 | VS Code 最新版 | 丰富的 Python 和 LangChain 扩展 |
| 版本控制 | Git 2.40+ | 代码版本管理 |
3.2 第一步：Python 版本管理（pyenv）
3.2.1 为什么用 pyenv？
- 可以在同一台机器上安装和切换多个 Python 版本
- 不会污染系统 Python 环境
- 支持为不同项目指定不同的 Python 版本
- 跨平台支持（Windows、Mac、Linux）
3.2.2 pyenv 安装与配置
Windows 安装：
python
# 使用pyenv-win
winget install pyenv-win.pyenv-win
# 配置环境变量（系统属性→高级→环境变量）
# 添加PYENV_ROOT：%USERPROFILE%\.pyenv
# 添加到Path：%PYENV_ROOT%\bin;%PYENV_ROOT%\shims
# 重启PowerShell3.2.3 安装 Python 3.12.3
python
# 安装Python 3.12.3（国内用户建议先配置镜像加速）
# 国内镜像配置（MacOS/Linux）
export PYTHON_BUILD_MIRROR_URL="https://npm.taobao.org/mirrors/python/"
# 安装Python
pyenv install 3.12.3
# 设置全局默认Python版本
pyenv global 3.12.3
# 验证安装
python --version
# 输出：Python 3.12.33.3 第二步：依赖管理（poetry）
3.3.1 为什么用 poetry？
- 同时管理虚拟环境和依赖
- 自动生成
poetry.lock文件，保证所有环境依赖版本完全一致 - 支持依赖分组（开发依赖、生产依赖）
- 内置打包和发布功能
- 比 pip+venv 更高效、更可靠
3.3.2 poetry 安装与配置
python
# 安装poetry
curl -sSL https://install.python-poetry.org | python3 -
# 配置环境变量
# MacOS/Linux：
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
# 验证安装
poetry --version
# 输出：Poetry (version 1.8.3)
# 配置国内镜像源（必须配置，否则下载依赖会非常慢）
poetry config repositories.aliyun https://mirrors.aliyun.com/pypi/simple/
poetry config virtualenvs.in-project true # 在项目目录下创建虚拟环境，方便管理3.4 第三步：创建项目并安装核心依赖
3.4.1 初始化项目
python
# 创建项目目录
mkdir langchain-tutorial && cd langchain-tutorial
# 初始化poetry项目
poetry init -n
# 激活虚拟环境
poetry shell执行完以上命令后，你会看到项目目录下生成了pyproject.toml文件，这是 poetry 的配置文件。
3.4.2 安装精确版本的核心依赖
必须安装以下精确版本，否则可能会出现 API 不兼容的问题：
python
# 核心依赖
poetry add langchain==1.2.14 langchain-core==0.3.12 langchain-openai==0.2.2
poetry add langgraph==1.2.0 langgraph-checkpoint-sqlite==1.0.6
# 工具依赖
poetry add python-dotenv==1.0.1 pydantic-settings==2.5.2
# 开发依赖
poetry add --dev jupyterlab ipykernel pytest black isort安装完成后，项目目录下会生成poetry.lock文件，这个文件记录了所有依赖的精确版本，必须提交到 Git 仓库，保证所有团队成员使用相同的依赖版本。
3.5 第四步：LangSmith 追踪配置
LangSmith 是开发和调试 LangChain 应用的必备工具，它可以让你看到每一次调用的完整链路，包括输入、输出、执行时间、Token 消耗等。
3.5.1 注册 LangSmith 账号并获取 API 密钥
- 访问LangSmith 官网
- 使用 GitHub 账号注册（免费版足够个人和小团队使用）
- 进入API Keys 页面
点击 "Create API Key"，生成一个新的 API 密钥，保存好这个密钥
3.5.2 配置环境变量
在项目根目录下创建.env文件，添加以下内容：
bash
# LangSmith配置
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=你的LangSmith API密钥
LANGCHAIN_PROJECT=langchain-tutorial # 项目名称，会显示在LangSmith中
# OpenAI配置（替换为你的API密钥）
OPENAI_API_KEY=你的OpenAI API密钥
# 如果使用代理，添加以下配置
# OPENAI_BASE_URL=https://你的代理地址/v1