LangChain 入门与环境搭建

HSXISAWD2026/5/14大约 9 分钟

LangChain 入门与环境搭建

什么是 LangChain

基本概念

LangChain 是一个用于开发由大语言模型（LLM）驱动的应用程序的开源框架。它提供了一套标准化的接口和组件，帮助开发者将 LLM 与外部数据源、工具和计算能力结合起来，构建复杂的 AI 应用。

简单来说，如果 LLM 是一个「大脑」，LangChain 就是连接这个大脑与外部世界的「神经系统」。

为什么需要 LangChain

直接调用 LLM API 看起来很简单，但当你需要构建真实应用时，会面临一系列问题：

问题	直接调用 API	使用 LangChain
多模型切换	每次都要改代码	统一接口，一行切换
提示词管理	字符串拼接，难以维护	模板化管理，支持变量
上下文记忆	手动管理历史消息	内置多种记忆组件
外部数据接入	自己写检索和拼接逻辑	RAG 管道开箱即用
复杂工作流	嵌套调用，代码混乱	声明式链式调用
输出格式控制	提示词赌运气，解析靠手写	结构化输出 + 自动解析

LangChain 能做什么

LangChain 的典型应用场景包括：

LangChain 生态体系

核心包

LangChain 在 2024 年进行了重大重构，目前由以下核心包组成：

包名	用途	安装命令
`langchain-core`	核心抽象和接口	`pip install langchain-core`
`langchain`	链、Agent、检索等主逻辑	`pip install langchain`
`langchain-community`	社区第三方集成	`pip install langchain-community`
`langchain-openai`	OpenAI 模型集成	`pip install langchain-openai`
`langchain-cli`	命令行工具	`pip install langchain-cli`

生态工具

LangSmith：用于追踪、调试和评估 LLM 应用。它记录每一步的输入输出、延迟、Token 消耗等信息
LangServe：将 LangChain 应用一键部署为 REST API 服务
LangGraph：用于构建具有状态管理和循环逻辑的复杂 Agent 工作流

环境搭建

Python 环境准备

推荐使用 Python 3.9 及以上版本，通过虚拟环境隔离项目依赖：

# 创建项目目录
mkdir langchain-project && cd langchain-project

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
# Windows
venv\Scripts\activate
# macOS / Linux
source venv/bin/activate

# 确认 Python 版本
python --version
# 建议输出: Python 3.11.x 或更高

安装 LangChain

# 安装 LangChain 主包（会自动安装 langchain-core）
pip install langchain

# 安装模型提供商的集成包（按需安装）
pip install langchain-openai      # OpenAI / Azure OpenAI
pip install langchain-anthropic   # Claude
pip install langchain-community   # 社区集成（HuggingFace、Ollama 等）

# 安装常用工具包
pip install langchain-chroma      # Chroma 向量数据库
pip install langchain-text-splitters  # 文本分割器

提示

如果网络较慢，可以使用国内镜像源：pip install -i https://pypi.tuna.tsinghua.edu.cn/simple langchain

使用 uv 管理项目（推荐）

uv 是一个极速的 Python 包管理工具，比 pip 快 10-100 倍：

# 安装 uv
pip install uv

# 使用 uv 创建项目
uv init langchain-project
cd langchain-project

# 添加依赖
uv add langchain langchain-openai langchain-community
uv add langchain-chroma langchain-text-splitters

# 添加开发依赖
uv add --dev pytest jupyter

项目结构规范

一个标准的 LangChain 项目建议按以下结构组织：

langchain-project/
├── .env                    # 环境变量（API Key 等，不提交到 Git）
├── .env.example            # 环境变量模板
├── pyproject.toml          # 项目配置和依赖
├── README.md
├── app/
│   ├── __init__.py
│   ├── main.py             # 应用入口
│   ├── config.py           # 配置管理
│   ├── chains/             # 自定义链
│   │   ├── __init__.py
│   │   └── qa_chain.py
│   ├── agents/             # 自定义 Agent
│   │   ├── __init__.py
│   │   └── research_agent.py
│   ├── tools/              # 自定义工具
│   │   ├── __init__.py
│   │   └── search_tool.py
│   ├── loaders/            # 文档加载器
│   │   ├── __init__.py
│   │   └── pdf_loader.py
│   └── prompts/            # 提示词模板
│       ├── __init__.py
│       └── chat_prompts.py
├── data/                   # 数据文件
│   ├── raw/                # 原始数据
│   └── processed/          # 处理后的数据
├── tests/                  # 测试
│   ├── test_chains.py
│   └── test_agents.py
└── notebooks/              # Jupyter 笔记本
    └── exploration.ipynb

配置 API Key

不要将 API Key 硬编码在代码中，使用环境变量管理：

# .env 文件
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx
OPENAI_API_BASE=https://api.openai.com/v1  # 或自定义代理地址

# 如果使用国内模型
DASHSCOPE_API_KEY=sk-xxxxxxxx               # 通义千问
ZHIPUAI_API_KEY=xxxxxxxx                    # 智谱 GLM

# app/config.py
from dotenv import load_dotenv
import os

load_dotenv()

class Config:
    """应用配置"""

    # OpenAI
    OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
    OPENAI_API_BASE = os.getenv("OPENAI_API_BASE", "https://api.openai.com/v1")
    OPENAI_MODEL = os.getenv("OPENAI_MODEL", "gpt-4o-mini")

    # 通义千问
    DASHSCOPE_API_KEY = os.getenv("DASHSCOPE_API_KEY")

    # 智谱
    ZHIPUAI_API_KEY = os.getenv("ZHIPUAI_API_KEY")

    # LangSmith 追踪（可选）
    LANGCHAIN_TRACING_V2 = os.getenv("LANGCHAIN_TRACING_V2", "false")
    LANGCHAIN_API_KEY = os.getenv("LANGCHAIN_API_KEY")
    LANGCHAIN_PROJECT = os.getenv("LANGCHAIN_PROJECT", "default")

注意

.env 文件必须添加到 .gitignore，避免 API Key 泄露到代码仓库。

# .gitignore
.env
__pycache__/
*.pyc
venv/
data/raw/

第一个 LangChain 程序

Hello World

# hello_langchain.py
from langchain_openai import ChatOpenAI

# 1. 创建模型实例
llm = ChatOpenAI(
    model="gpt-4o-mini",
    temperature=0.7,       # 创造性程度，0=确定性，1=随机性
    max_tokens=512,        # 最大生成 Token 数
)

# 2. 调用模型
response = llm.invoke("用一句话解释什么是 LangChain")

# 3. 输出结果
print(response.content)
# 输出示例：LangChain 是一个用于构建大语言模型应用的开发框架，
#         它提供了模型调用、提示词管理、链式调用等标准化组件，
#         帮助开发者快速搭建 AI 应用。

理解返回结果

invoke 方法返回的是一个 AIMessage 对象，它不只是简单的文本：

response = llm.invoke("你好")

print(type(response))       # <class 'langchain_core.messages.ai.AIMessage'>
print(response.content)     # 消息内容（文本）
print(response.response_metadata)  # 模型返回的元数据
# {
#   'token_usage': {
#     'completion_tokens': 15,
#     'prompt_tokens': 10,
#     'total_tokens': 25
#   },
#   'model_name': 'gpt-4o-mini',
#   'system_fingerprint': 'fp_abc123'
# }
print(response.id)          # 消息唯一 ID

使用不同模型提供商

LangChain 的统一接口让你可以轻松切换模型：

# ===== OpenAI =====
from langchain_openai import ChatOpenAI

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


# ===== Azure OpenAI =====
from langchain_openai import AzureChatOpenAI

azure_llm = AzureChatOpenAI(
    azure_deployment="my-deployment",
    api_version="2024-02-15-preview",
)


# ===== Anthropic Claude =====
from langchain_anthropic import ChatAnthropic

claude_llm = ChatAnthropic(model="claude-sonnet-4-20250514")


# ===== 通义千问（通过 OpenAI 兼容接口）=====
from langchain_openai import ChatOpenAI

qwen_llm = ChatOpenAI(
    model="qwen-plus",
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
    api_key="your-dashscope-api-key",
)


# ===== 智谱 GLM =====
from langchain_openai import ChatOpenAI

glm_llm = ChatOpenAI(
    model="glm-4-flash",
    base_url="https://open.bigmodel.cn/api/paas/v4",
    api_key="your-zhipuai-api-key",
)


# ===== 本地模型（Ollama）=====
from langchain_ollama import ChatOllama

local_llm = ChatOllama(model="qwen2.5:7b")

所有模型的调用方式完全相同：

# 不管用哪个模型，调用代码一样
result = llm.invoke("你好，请介绍一下自己")
print(result.content)

流式输出

在实际应用中，等待完整响应会让用户觉得卡顿，流式输出可以逐字显示：

# 流式输出
for chunk in llm.stream("请写一首关于编程的短诗"):
    print(chunk.content, end="", flush=True)

# 输出效果：
# 代码如诗行行写，
# 逻辑似水处处流。
# Bug 修尽见明月，
# 上线方知夜已深。

# 批量调用（并行处理多个请求）
results = llm.batch([
    "什么是 Python？一句话回答",
    "什么是 Java？一句话回答",
    "什么是 Go？一句话回答",
])

for r in results:
    print(r.content)
    print("---")

# 批量调用会自动并发请求，提高吞吐量

模型选型指南

各模型能力对比

模型	提供商	上下文长度	适用场景	价格级别
GPT-4o	OpenAI	128K	复杂推理、代码生成	$$$$
GPT-4o-mini	OpenAI	128K	通用任务、高性价比	$
Claude Sonnet 4	Anthropic	200K	长文本分析、代码	$$$
Claude Haiku 3.5	Anthropic	200K	快速响应、低成本	$
Qwen-Max	阿里	32K	中文场景、通用	$$
Qwen-Plus	阿里	128K	中文场景、均衡	$
GLM-4	智谱	128K	中文场景、函数调用	$$
DeepSeek-V3	DeepSeek	64K	代码、数学推理	$

选型建议

常见问题排查

API Key 问题

# 检查 API Key 是否配置正确
import os
from dotenv import load_dotenv

load_dotenv()

api_key = os.getenv("OPENAI_API_KEY")
if not api_key:
    raise ValueError("OPENAI_API_KEY 未设置，请检查 .env 文件")
if not api_key.startswith("sk-"):
    raise ValueError("OPENAI_API_KEY 格式不正确，应以 sk- 开头")

print(f"API Key 已加载: {api_key[:8]}...{api_key[-4:]}")

网络连接问题

国内访问 OpenAI API 可能需要配置代理：

# 方式1：使用国内中转 API
llm = ChatOpenAI(
    model="gpt-4o-mini",
    base_url="https://your-proxy.com/v1",  # 替换为你的代理地址
    api_key="your-api-key",
)

# 方式2：使用国内模型替代
qwen_llm = ChatOpenAI(
    model="qwen-plus",
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
    api_key="your-dashscope-key",
)

依赖冲突

# 如果遇到依赖冲突，建议使用 uv 创建隔离环境
uv venv --python 3.11
source .venv/bin/activate
uv pip install langchain langchain-openai

本章小结

核心要点

LangChain 定位：LLM 应用的开发框架，不是模型本身
统一接口：一套代码适配多个模型，切换成本为零
环境管理：API Key 通过 .env 管理，不硬编码
项目结构：按功能模块划分，保持代码整洁