LangChain 安装与环境配置

第一次安装 LangChain 时，几乎每个人都会踩同一个坑：pip install langchain 跑完，一运行就报 ModuleNotFoundError: No module named 'langchain_openai'。

这不是你的问题，也不是 langchain 装坏了。LangChain 是刻意设计成模块化的——核心框架只有骨架，模型适配器（OpenAI、Claude、Gemini）是单独的包，按需装。好处是项目体积小、依赖清晰；坏处是第一次上手容易搞懵。

这页把常见场景一次说清楚，帮你跳过那段试错时间。

---

#第一步：先建虚拟环境（跳过这步你会后悔的）

bash复制
python -m venv venv
source venv/bin/activate      # macOS / Linux
venv\Scripts\activate         # Windows

为什么不能省？因为 LangChain 对 pydantic 版本有要求，而 pydantic 是很多其他库也依赖的公共包。如果你之前用全局 Python 跑过 FastAPI 或者其他框架，很可能已经装了一个版本不兼容的 pydantic，结果 pip install 虽然成功，一 import 就各种奇怪报错。

虚拟环境是隔离这类问题最省力的办法，养成习惯之后完全不觉得麻烦。

---

#第二步：装包

最常用的三行：

bash复制
# 基础（OpenAI 模型 + 社区工具 + .env 支持）
pip install langchain langchain-openai langchain-community python-dotenv

# 如果用 Claude
pip install langchain-anthropic

# 如果用 Gemini
pip install langchain-google-genai

# 如果需要构建 Agent 循环逻辑
pip install langgraph

# 调试追踪（强烈建议第一天就装）
pip install langsmith

下面这张表解释每个包是干什么的，方便你按需选：

最简安装（只用 OpenAI，做个小 demo）：

bash复制
pip install langchain langchain-openai python-dotenv

标准开发环境：

bash复制
pip install langchain langchain-openai langchain-community langgraph langsmith python-dotenv

---

#第三步：配置 API Key

在项目根目录创建 .env 文件：

bash复制
# LLM 模型密钥（按需选）
OPENAI_API_KEY="sk-proj-..."
ANTHROPIC_API_KEY="sk-ant-..."
GOOGLE_API_KEY="AIza..."

# LangSmith 调试追踪（强烈推荐从第一天就配）
LANGCHAIN_TRACING_V2="true"
LANGCHAIN_API_KEY="ls__..."
LANGCHAIN_PROJECT="my-project"

然后在 Python 代码最开头加这一行：

python复制
from dotenv import load_dotenv
load_dotenv()  # 必须在任何 LangChain import 之前调用

一个很容易犯的错：load_dotenv() 放在文件中间，结果在它之前的代码初始化 LLM 时 API Key 还没加载进来，报 AuthenticationError。我在调试别人代码时见过好几次这个问题，很难发现。把 load_dotenv() 固定放第一行就不会有这个问题。

另外，.gitignore 里一定要加 .env，不然 API Key 可能被提交到代码仓库：

bash复制
echo ".env" >> .gitignore

这是很多人第一次用 GitHub 时翻车的地方，某天收到 OpenAI 发来的邮件说"检测到你的 API Key 在公开仓库"，然后 Key 被自动撤销。

---

#验证安装：跑通这个就成功了

python复制
from dotenv import load_dotenv
from langchain_core.prompts import ChatPromptTemplate
from langchain_openai import ChatOpenAI
from langchain_core.output_parsers import StrOutputParser

load_dotenv()

chain = (
    ChatPromptTemplate.from_messages([
        ("system", "你是一个简洁的助手，回答不超过 50 字。"),
        ("user", "{question}"),
    ])
    | ChatOpenAI(model="gpt-4o-mini")
    | StrOutputParser()
)

result = chain.invoke({"question": "LangChain 是什么？"})
print(result)

能看到输出就说明安装和 API Key 都配成功了。

---

#关于 LangSmith：为什么我觉得它该跟安装包放在同一天做

没有 LangSmith 调试 LangChain，就像没有 DevTools 调试前端——能做，但效率差一个量级。

它能让你看到：

• 每一步的完整 Prompt 和模型响应（不是压缩版，是原始内容）
• Token 用量和费用估算（每次调用花了多少钱）
• 调用耗时分布（哪一步是瓶颈）
• 失败链路的完整报错上下文

接入成本是零：注册 smith.langchain.com↗（免费），在 .env 里加三行，什么业务代码都不用改。之后每次运行 Chain，控制台里自动有记录。

---

#常见报错速查

---

#版本管理：一定要锁

LangChain 更新频繁，不锁版本是有风险的。用 requirements.txt：

langchain>=0.3.0,<0.4.0
langchain-openai>=0.2.0
langchain-community>=0.3.0
langgraph>=0.2.0
langsmith>=0.1.0
python-dotenv>=1.0.0

bash复制
# 新环境复现
pip install -r requirements.txt

我的习惯是每次新项目第一件事就生成这个文件，而不是等到要部署前。

---

#推荐项目结构

标准 LangChain 项目的目录组织：

my-langchain-project/
├── .env                    # API Keys（加入 .gitignore！）
├── .env.example            # Keys 示例（只有名字没有值，可提交）
├── requirements.txt        # 依赖版本锁定
├── main.py                 # 入口
├── chains/
│   ├── rag_chain.py        # RAG 相关 Chain
│   ├── chat_chain.py       # 对话 Chain
│   └── agent.py            # Agent 定义
├── prompts/
│   ├── system_prompts.py   # System Prompt 常量
│   └── templates.py        # PromptTemplate 定义
└── tests/
    └── test_chains.py

不一定要照搬，但把 Prompt 单独放一个目录是个好习惯——后期维护 Prompt 时不用在业务代码里翻来翻去。

---

#小结

1. pip install langchain 之后还需要装模型适配器（如 langchain-openai），这是设计如此，不是装错了。
2. 虚拟环境是必须的——LangChain 对 pydantic 版本有严格要求，全局环境容易冲突。
3. load_dotenv() 放第一行，不然 API Key 加载时机可能出问题。
4. .env 加入 .gitignore——不然某天 API Key 可能被提交到 GitHub。
5. LangSmith 和装包同一天配——调试时你会庆幸自己早配了。

---

下一步：Model I/O — PromptTemplate、LCEL 和 OutputParser，构建你的第一个真正可用的 Chain

相关链接：LangChain 官方安装文档↗ | LangSmith 注册↗