LangChain 新手入门与环境搭建指南

LangChain 是由哈佛大学的 Harrison Chase 于 2022 年 10 月发起研发的开源框架，用于开发由大语言模型驱动的应用程序。它的发布比 ChatGPT 问世（2022 年 11 月）还要早一个月。通过不到 10 行代码，开发者即可连接 OpenAI、Anthropic、Google 等多种模型，并快速将 LLM 集成到 Agent 和应用中。

宏观生态：LangChain 的三层架构

LangChain 并非一个孤立的库，其背后是一个层层递进的三层架构生态：

Deep Agents（套件）：建立在 LangChain 之上，开箱即用，内置最佳实践，适合信任 LLM 自主决策的场景。就像一辆“给目的地就出发”的自动驾驶汽车。
LangChain（框架）：提供标准化抽象层，允许自由组装组件，适合自定义 Agent 或 RAG 等通用开发。相当于“自己组装零件开车” 。
LangGraph（运行时）：建立在底层，用“图”精确控制每一步流程，控制力最强，适合需要确定性流程的企业级编排。相当于“自己造引擎、画电路” 。

三、LangChain 核心架构总览

在深入代码之前，需要理解 LangChain 内部的模块划分。整个架构分为三个层次：

1. 基础层（用什么说话）

这一层定义了 LangChain 与模型之间的通信协议，是上层功能的地基。

Messages：标准化消息格式，如 SystemMessage、HumanMessage、AIMessage 等。
Prompts：提示词模板，支持变量插入和复用。
Streaming：实时流式输出，逐 token 返回结果。
Middleware：在模型调用前后插入重试、缓存等逻辑。

2. 能力层（怎么做）

这一层提供了模型之上的核心能力组件，每个组件可独立使用或自由组合。

Models：统一的模型调用接口，所有模型均使用 invoke、batch 或 stream 方法。
Tools：使用 @tool 装饰器定义函数，使模型具备调用外部 API 的能力。
Memory：管理对话历史，包括短期、长期和摘要记忆。
Structured Output：利用 Pydantic 模型约束输出格式，确保返回标准的 JSON 。

3. 应用层（做什么）

这一层是面向业务场景的顶层模块，负责组合底层能力来解决实际问题。

Chains：通过管道符（如 prompt | llm | parser）将多个组件串联成流水线。
Retrieval (RAG)：覆盖文档加载、文本切分、向量存储到检索的增强生成全链路。
Agents：自主规划执行步骤，循环调用工具直至任务完成。

四、环境准备与包管理

在 Python 开发中，解决环境隔离和包安装是首要任务。本教程推荐并统一使用 uv，不再依赖 conda、pip 或 venv 。

为什么选择 uv？

相比于传统的 venv + pip 组合或体积庞大的 conda，uv 是由 Rust 编写的新一代工具。

它在安装包的速度上比 pip 快 10-100 倍。
它能直接管理 Python 版本并自动创建虚拟环境。
它使用 uv.lock 进行精确依赖锁定，保证了环境的可复现性。

认识项目核心文件

在使用 uv 初始化项目后，会生成以下关键结构：

pyproject.toml：类似“购物清单”，记录项目配置以及你手动要求安装的依赖清单（如 langchain >=1.2.15）。
uv.lock：类似“收银小票”，由 uv 自动生成，记录每个包及其间接依赖的精确版本，确保他人可以通过 uv sync 一键还原相同环境。
.venv/：类似“冰箱”，是由 uv 自动创建的虚拟环境，存放实际安装的包，不需要提交到 Git 。

LangChain 按需安装策略

LangChain 采用模块化包结构，避免提供臃肿的单一包，应当遵循“只安装用到包”的原则。

langchain 与 langchain-core 为核心包。
集成包按需安装，例如 langchain-openai、langchain-anthropic 或本地模型的 langchain-ollama 。
扩展包如 langchain-chroma（向量数据库）等。

初始化项目实操

# 1. 创建项目目录
mkdir langchain-course && cd langchain-course

# 2. 用 uv 初始化项目 (自动创建虚拟环境 + pyproject.toml)
uv init

# 3. 指定 Python 版本 (推荐3.12)
uv python pin 3.12

# 4. 安装 LangChain 核心包 (自动写入 pyproject.toml 和 uv.lock)
uv add langchain

# 5. 安装你需要的模型提供商集成 (如 OpenAI 和环境变量加载工具)
uv add langchain-openai
uv add python-dotenv

注：使用 uv add 可以自动记录依赖关系并生成锁文件，比 uv pip install 更利于团队协作。

五、模型平台选择与环境变量配置

LangChain 的优势在于其模型无关性，切换模型通常只需更改一行配置，前提是正确配置 API 。

主流大模型平台推荐

海外官方平台：如 OpenAI (GPT系列) 或 Anthropic (Claude系列)，提供最低延迟和最稳定的服务，但需要科学上网与海外信用卡支持。
代理/中转平台：如 CloseAI 或 OpenRouter，提供完全兼容官方的 API，只需替换 base_url，适合国内网络且支持支付宝。
国产模型平台：如 DeepSeek、阿里云百炼 (Qwen)、智谱 AI (GLM)，提供直连服务，性价比高，部分提供免费额度。

环境变量配置

在实际项目中，推荐在项目根目录创建 .env 文件来管理密钥。

创建 .env 文件（以 OpenAI 与 CloseAI 代理为例）：

OPENAI_API_KEY=sk-your-api-key
OPENAI_BASE_URL=https://api.closeai-asia.com/v1

严谨提示：切勿将 .env 文件提交到版本控制系统中，以防数据泄露，应将其加入 .gitignore 。代码中依赖的是 python-dotenv 包，切勿错误安装为 dotenv 。

六、快速上手：你的第一个 LangChain 程序

当环境与密钥准备妥当，只需几行代码即可完成模型的调用：

import os
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI

# 加载 .env 文件中的环境变量
load_dotenv()

# 创建模型实例
llm = ChatOpenAI(
    model="gpt-4",
    api_key=os.getenv("OPENAI_API_KEY"),
    base_url=os.getenv("OPENAI_BASE_URL", "https://api.openai.com/v1")
)

# 调用模型进行对话
response = llm.invoke("你好，请用一句话介绍Python")
print(response.content)

以上便是从 0 到 1 搭建 LangChain 开发环境的最基础流程。掌握基础的 Model I/O 后，便可以逐步深入学习 Chains 串联、Memory 记忆管理、Tools 工具调用，以及最终的 RAG 与 Agents 构建。

AI Agent技术社区

Agent 垂直技术社区，欢迎活跃、内容共建。

更多推荐

深入理解 AI Agent · AGENT #02：Agent 的四大核心机制，拆开来看每个都在干什么

AI Agent技术社区

MCP协议开发实战：从零搭建AI Agent工具链

本文介绍了MCP协议在AI工具链中的应用与实践。MCP协议旨在解决异构工具集成难题，为AI模型提供标准化、安全的工具调用接口。文章详细解析了MCP的核心架构，包括Server、Client、Transport等组件，以及通信流程与安全模型。通过实战示例，指导读者开发计算器和文件系统工具Server，并集成到Claude等AI客户端中。进阶部分展示了如何构建复杂工具链，包括API集成、数据库查询和多