Chapter 01

LangChain 0.3.x 生态全景

架构演进、核心包解析、与 LangGraph / LangSmith 的关系，以及从零搭建开发环境

LangChain 是什么？

LangChain 是一个用于构建大语言模型（LLM）应用的开源框架，由 Harrison Chase 在 2022 年 10 月创建，短短数月内成为 GitHub 增长最快的项目之一。它的核心价值在于：提供一套标准化的抽象层，让开发者不必从零处理 LLM 调用、提示词管理、上下文传递等重复工作，而是可以专注于业务逻辑。

截至 2025-2026 年，LangChain 已演进到 0.3.x 版本，彻底重构了内部架构——告别旧式 Chain 类继承体系，全面采用 LCEL（LangChain Expression Language） 管道模式。与此同时，官方生态也扩展为三大支柱：

LangChain
核心框架本体，提供 Chat Models、Prompts、OutputParsers、Retrievers、Tools 等基础构件，以及 LCEL 管道组合能力。
LangGraph
基于有向图的 Agent 编排框架（当前版本 0.2.x），将 Agent 的执行过程建模为状态机，支持循环、条件分支、多智能体协作。是构建生产级 Agent 的首选方案。
LangSmith
LLM 应用的可观测性与评估平台。追踪每次模型调用的输入输出、耗时、成本；管理提示词版本；创建评估数据集并打分。是调试和监控 LLM 应用的必备工具。
LangServe
将 LangChain 链（Chain/Runnable）一键部署为 FastAPI HTTP 服务，自动生成 /invoke、/stream、/batch 接口，内置 Playground UI 页面。
版本说明

本教程基于 langchain 0.3.x、langchain-core 0.3.x、langgraph 0.2.x。0.3.x 是一次重大重构，所有旧式 LLMChain、ConversationChain 已被标记为废弃（deprecated），统一迁移至 LCEL 管道。如果你正在从 0.1/0.2 版本迁移，请特别注意第3章的迁移指南。

架构演进：从 Chain 继承到 LCEL 管道

理解 LangChain 的架构演进，是掌握 0.3.x 思维模式的关键。LangChain 经历了三个明显的阶段：

第一阶段（0.0.x ~ 0.1.x）：面向对象的 Chain 体系

早期 LangChain 通过继承 BaseChain 来构建应用组件。每种场景都有专用 Chain：LLMChain（基础链）、ConversationalRetrievalChain（对话检索）、MapReduceChain（长文本摘要）等。这种方式的问题在于：组合困难、流式支持差、无法并行执行、难以测试和调试。

第二阶段（0.2.x）：LCEL 引入，双轨并行

LangChain 0.2.x 引入了 LCEL（基于 | 管道操作符的声明式组合），但旧式 Chain 仍然保留，造成文档和代码风格混乱。

第三阶段（0.3.x）：全面 LCEL 化，生态分层

0.3.x 版本完成了架构的统一。所有旧式 Chain 被标记为废弃，统一基于 LCEL Runnable 接口。包结构也完成了拆分重组：

核心包（必装）

  • langchain-core：所有抽象类和接口，Runnable 协议定义
  • langchain：高层链、检索器、记忆等组件
  • langgraph：Agent 状态机框架

集成包（按需装）

  • langchain-openai：OpenAI / Azure OpenAI
  • langchain-anthropic：Anthropic Claude
  • langchain-community：数百个社区集成
  • langchain-chroma、langchain-qdrant 等

核心概念速览

在深入每个主题之前，先对贯穿全教程的核心抽象有一个整体认识：

Runnable
LangChain 0.3.x 的核心接口。所有组件（Prompt、Model、Parser、Retriever……）都实现了 Runnable 协议，具备 invoke()、stream()、batch()、astream() 方法，支持通过 | 操作符串联成管道。
LCEL
LangChain Expression Language。用 | 操作符组合 Runnable 的声明式 DSL。chain = prompt | model | parser 即可构建一个完整的链，天然支持流式、批处理、异步执行。
ChatModel
基于消息（Message）的 LLM 接口，接收 HumanMessage / AIMessage / SystemMessage 列表，返回 AIMessage。区别于旧式文本补全模型（LLM）。
Document
LangChain 的基础数据单元，包含 page_content（文本内容）和 metadata（来源、页码等元数据字典）。
Retriever
实现 Runnable 协议的检索器，输入字符串问题，输出 Document 列表。可基于向量搜索、关键词搜索或混合策略实现。
Tool
Agent 可以调用的外部功能函数，有明确的输入 schema（用于告知 LLM 如何使用）和输出。支持同步/异步，可用 @tool 装饰器快速创建。

安装与环境配置

推荐的虚拟环境方案

LangChain 生态依赖较多，推荐使用 uv（极速 Python 包管理器）来创建隔离环境：

# 安装 uv（macOS/Linux）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 创建项目
uv init my-langchain-app
cd my-langchain-app

# 创建虚拟环境并安装依赖
uv add langchain langchain-core langgraph
uv add langchain-openai langchain-anthropic

# 可选：向量存储集成
uv add langchain-chroma chromadb
uv add langchain-qdrant qdrant-client

如果你偏好传统 pip，也可以使用：

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

pip install langchain langchain-core langgraph
pip install langchain-openai langchain-anthropic

环境变量配置

LangChain 通过环境变量管理 API Key。推荐使用 python-dotenv 在本地加载 .env 文件：

# .env 文件（不要提交到 Git！）
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

# LangSmith 可观测性（可选但强烈推荐）
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=ls__...
LANGCHAIN_PROJECT="my-project"
from dotenv import load_dotenv
load_dotenv()  # 加载 .env 文件

import os
print(os.environ["OPENAI_API_KEY"][:8] + "...")

验证安装

from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage

model = ChatOpenAI(model="gpt-4o-mini")

response = model.invoke([
    HumanMessage(content="你好，用一句话介绍 LangChain")
])

print(response.content)
使用国内兼容 API

国内用户可以使用 OpenAI 兼容的 API（如 DeepSeek、智谱 GLM 等），只需配置 base_url 参数：
ChatOpenAI(model="deepseek-chat", base_url="https://api.deepseek.com", api_key="...")

包版本关系与依赖图

理解 LangChain 的包依赖关系，避免版本冲突是非常实际的工程问题。下表列出了 2025-2026 年稳定版本组合：

包名稳定版本作用必装？
langchain-core0.3.x所有抽象基类与 Runnable 协议是
langchain0.3.x高层组件：Chains、Memory、Retrievers是
langgraph0.2.x状态机 Agent 框架推荐
langchain-openai0.2.xOpenAI / Azure 集成按需
langchain-anthropic0.3.xClaude 系列集成按需
langchain-community0.3.x数百个社区贡献的集成按需
langsmith0.1.xLangSmith SDK（追踪/评估）推荐
langserve0.3.xFastAPI 部署工具生产需要

LangChain Hub 与社区资源

LangChain Hub（hub.langchain.com）是官方提供的提示词模板共享平台。你可以直接拉取经过社区验证的 Prompt：

from langchain import hub

# 拉取 ReAct Agent 的官方提示词模板
prompt = hub.pull("hwchase17/react")

# 拉取 RAG QA 提示词
rag_prompt = hub.pull("rlm/rag-prompt")
关于 LangChain Community 包的注意事项

langchain-community 包含大量第三方集成，但维护质量参差不齐。对于生产环境中频繁使用的集成（如 OpenAI、Anthropic、Chroma、Qdrant），优先使用其专属包（langchain-openai、langchain-chroma 等），它们由官方或对应厂商维护，更稳定。

本章小结

本章建立了学习 LangChain 的整体框架：

下一章，我们将进入 LangChain 的核心入口：Chat Models 与 Prompts，学习如何灵活地与各类 LLM 交互。