# LangChain 安装与文档阅读路线：从环境配置到工程上手

LangChain 的上手难点通常不在安装命令，而在“到底该装哪些包、看哪份文档、用哪套新 API”。尤其是 LangChain 生态迭代很快，很多旧文章还停留在 0.1、0.2 或早期 Chain 写法，但当前 LangChain 已经明显转向 Agent、LangGraph、LangSmith 和 provider integration packages 这套工程体系。

所以安装 LangChain 时，不要只记一条 pip install langchain。更好的方式是先理解它的包结构，再按应用场景选择依赖，最后沿着官方文档的阅读路线逐步建立知识图谱。

# 先理解 LangChain 的包结构

LangChain 不是一个单体包。它更像一个围绕 LLM 应用开发的生态，由多个包共同组成。

常见包可以这样理解：

包名	作用	什么时候需要
`langchain`	高层应用框架，包含 Agent、工具组合等能力	构建普通 LangChain 应用时安装
`langchain-core`	核心抽象，如 messages、runnables、prompts、output parsers	通常作为依赖自动安装
`langchain-openai`	OpenAI 模型与 embedding 集成	使用 OpenAI 或兼容 OpenAI API 的模型时安装
`langchain-anthropic`	Anthropic Claude 集成	使用 Claude 时安装
`langchain-community`	历史社区集成包，正在 sunset	旧项目兼容或少量组件尚未迁移时才作为 fallback
`langchain-text-splitters`	文本切分组件	做 RAG、文档切分时常用
`langgraph`	有状态 Agent 和工作流编排	复杂流程、循环、分支、人工审批、多 Agent 时使用
`langsmith`	追踪、调试、评估与观测	需要 trace、eval、线上排障时使用

现在更推荐按需安装。比如只做 OpenAI 的基础应用，可以先安装：

pip install -U langchain langchain-openai

也可以使用 extra 形式安装 OpenAI 集成：

pip install -U "langchain[openai]"

如果你用 uv 管理依赖：

uv add langchain langchain-openai

如果后面要接 Anthropic：

pip install -U langchain-anthropic

如果要做复杂 Agent 工作流：

pip install -U langgraph

如果要接入 LangSmith 观测：

pip install -U langsmith

实际项目里，不要一上来把所有包都装满。LangChain 生态集成非常多，依赖装得越多，版本冲突和环境体积也越容易变复杂。新项目优先找独立 provider package，例如 langchain-openai、langchain-anthropic、langchain-chroma；只有旧组件暂时没有迁移路径时，再短期保留 langchain-community。

# 建议的 Python 环境

生产项目里，建议为 LangChain 单独创建虚拟环境，并固定依赖版本。

使用 venv：

python -m venv .venv
.venv\Scripts\activate
pip install -U pip
pip install -U langchain langchain-openai

1
2
3
4

macOS 或 Linux：

python -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -U langchain langchain-openai

1
2
3
4

使用 uv：

uv init
uv add langchain langchain-openai

1
2

依赖文件建议提交到仓库，例如：

pip freeze > requirements.txt

或者使用 uv.lock / poetry.lock / pdm.lock 这类锁文件。LangChain 和各模型 provider 包迭代很快，没有锁文件时，很容易出现“昨天能跑，今天新环境安装后就报错”的情况。

# 配置模型 API Key

以 OpenAI 为例，安装 langchain-openai 后，需要配置 API Key。

Windows PowerShell：

$env:OPENAI_API_KEY="你的 API Key"

macOS 或 Linux：

export OPENAI_API_KEY="你的 API Key"

在生产环境里，不要把 API Key 写进代码或提交到 Git。推荐放在：

环境变量。
.env 文件，但 .env 必须加入 .gitignore。
Kubernetes Secret。
云厂商 Secret Manager。
公司统一密钥系统。

如果是本地开发，可以用 python-dotenv 加载 .env：

pip install python-dotenv

from dotenv import load_dotenv

load_dotenv()

1
2
3

密钥管理是 LLM 应用的底线。模型调用、工具调用、数据库访问都可能牵涉敏感信息，不能把密钥散落在样例代码里。

# 最小可运行示例

安装完成后，可以先跑一个最小示例，验证模型调用链路。

from langchain_openai import ChatOpenAI


model = ChatOpenAI(model="gpt-4o-mini", temperature=0)

response = model.invoke("用一句话解释 LangChain 是什么")

print(response.content)

1
2
3
4
5
6
7
8

如果要体现 LangChain 的组合能力，可以加入 Prompt 和 Output Parser：

from langchain_core.output_parsers import StrOutputParser
from langchain_core.prompts import ChatPromptTemplate
from langchain_openai import ChatOpenAI


prompt = ChatPromptTemplate.from_messages([
    ("system", "你是一个擅长解释技术概念的 Python 后端工程师。"),
    ("human", "{question}"),
])

model = ChatOpenAI(model="gpt-4o-mini", temperature=0)
parser = StrOutputParser()

chain = prompt | model | parser

answer = chain.invoke({
    "question": "LangChain 的 Runnable 是什么？"
})

print(answer)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

这里的 | 是 LangChain Expression Language，也就是 LCEL 的组合方式。它把 prompt、model、parser 连接成一条可调用链路。后续加入 RAG、工具调用、流式输出、批处理、异步调用时，也会围绕这类可组合抽象展开。

# 常见安装问题

# 只安装 `langchain` 后找不到 `ChatOpenAI`

现在很多模型集成已经拆到单独 provider 包里。使用 OpenAI 时，需要安装：

pip install -U langchain-openai

然后这样导入：

from langchain_openai import ChatOpenAI

不要再依赖很旧的导入路径。旧路径可能还能通过兼容层工作一段时间，但新项目应该直接使用 provider package。

# `OPENAI_API_KEY` 未配置

如果报 API Key 相关错误，先确认环境变量是否生效。

PowerShell：

echo $env:OPENAI_API_KEY

macOS 或 Linux：

echo $OPENAI_API_KEY

如果是在 IDE、Jupyter、Docker、CI 里运行，还要确认运行进程能拿到环境变量。很多时候命令行里有变量，不代表 IDE 的 Python 进程也有。

# 版本不一致导致导入失败

LangChain 生态包之间存在版本配套关系。比如 langchain、langchain-core、langchain-openai、langgraph 同时存在时，某个包过旧可能导致导入路径或类型不匹配。

排查时可以先查看版本：

pip show langchain langchain-core langchain-openai langgraph

必要时统一升级：

pip install -U langchain langchain-core langchain-openai langgraph

但生产项目不要在线上临时 pip install -U。应该先在开发或测试环境验证，再更新锁文件，通过发布流程上线。

如果项目还依赖 langchain-community，建议单独列出来做迁移清单：确认每个 loader、tool、vector store 是否已有独立包，能迁移就迁移，不能迁移再评估 fork、替代库或内部封装。

# 代理和网络问题

模型调用失败不一定是 LangChain 的问题。常见原因包括：

本地网络无法访问模型 API。
公司代理未配置。
API base URL 配错。
Key 没有权限访问指定模型。
账号额度不足。
模型名称不存在或已下线。

排查时先用 provider 原生 SDK 或简单 HTTP 请求确认模型服务可用，再排查 LangChain 代码。

# 官方文档怎么看

LangChain 文档信息量很大，不建议从 API Reference 开始硬啃。更合理的阅读方式是：先看概览，再跑 Quickstart，然后沿着 LangChain、LangGraph、Integrations、Learn、Reference 逐步展开。

当前文档已经是 agent-first 的组织方式。它不是把 Chain 类作为唯一中心，而是把 create_agent、model、tools、prompt、middleware、context engineering 放在主线位置。

# Overview

Overview 适合建立整体认知。它会告诉你 LangChain 现在的定位：围绕 Agent、model、tools、prompt、middleware 组合应用，而不是只把链式调用当成唯一中心。

第一次看文档时，建议先弄清楚几个关系：

LangChain：高层 Agent 和 LLM 应用框架。
LangGraph：更底层、更可控的状态图编排。
LangSmith：调试、评估、监控和观测平台。
Integrations：模型、向量库、文档加载器、工具等第三方集成。

理解这几个边界，比背组件列表更重要。

# Quickstart

Quickstart 适合快速跑通第一个 Agent。它的价值不是让你复制代码上线，而是确认：

本地环境能运行。
模型 Key 配置正确。
create_agent 能把 model、tools、system prompt 组合起来。
你理解一次 agent.invoke 的输入输出。

跑通 Quickstart 后，再去看 Models、Messages、Tools、Agents、Context engineering、Memory、Retrieval 会顺很多。

# LangChain

LangChain 这一栏是日常开发最常用的部分。它会拆开解释：

Models：如何初始化模型、流式输出、结构化输出、工具调用。
Messages：模型上下文的基本单位。
Tools：如何把函数能力暴露给模型。
Agents：如何用 create_agent 组装模型、工具、提示词和中间件。
Context engineering：如何把状态、记忆、运行时上下文送进 Agent。
Retrieval：如何接入外部知识。

这部分适合边做项目边查。尤其是 Agent 章节，现在应该优先看 create_agent 的用法，而不是围绕旧 Chain 类找入口。

# LangGraph

LangChain 的 Agent 底层建立在 LangGraph 之上。如果业务需要更强的状态控制、循环、分支、人工审批、持久化、多 Agent 协作，就应该继续看 LangGraph。

简单应用可以先用 create_agent；流程一旦变复杂，不要在业务代码里手写一堆 if/else 去模拟状态机，而是考虑用 LangGraph 把执行过程显式建模。

# Integrations

Integrations 用来查模型、embedding、vector store、retriever、document loader、tool 等外部系统的接入方式。它的重点是按 provider 找包，而不是默认把所有东西都装进一个大依赖。

例如 OpenAI 看 langchain-openai，Anthropic 看 langchain-anthropic，Chroma 看 langchain-chroma。这种独立包模式更适合生产依赖治理。

# Learn 与 Reference

Learn 适合补设计理解，例如 agent 架构、RAG、评估、记忆、上下文工程等。Reference 是 API 细节，适合查类、方法、参数、类型定义，不适合作为入门材料。

例如你已经知道要用 Runnable，但想看它支持哪些方法、输入输出类型、异步调用、批处理、流式接口，这时再看 Reference。

# 推荐阅读路线

我建议按下面顺序掌握。

# 第一阶段：跑通基础调用

目标是知道 LangChain 应用的最小单元是什么。

阅读重点：

Install
Quickstart，也就是先跑通一个 create_agent
Models
Prompts
Messages
Output parsers
LCEL / Runnable

练习任务：

调用一个 Chat Model。
用 PromptTemplate 管理提示词。
用 StrOutputParser 解析输出。
把 prompt、model、parser 组合成 chain。
用 create_agent 接入一个只读工具。

# 第二阶段：接入真实业务上下文

目标是把模型从“只会回答通用问题”变成“能回答业务问题”。

阅读重点：

Document loaders
Text splitters
Embedding models
Vector stores
Retrievers
RAG 相关 guides

练习任务：

加载一批 Markdown、网页或业务文档。
切分文本并写入向量库。
根据问题检索相关片段。
把检索结果放入 Prompt。
回答时附上来源。

# 第三阶段：工具调用和 Agent

目标是让模型能调用外部能力。

阅读重点：

Tools
Tool calling
Agents
Middleware
Context engineering

练习任务：

写一个查询天气或数据库的工具。
让模型决定什么时候调用工具。
给敏感工具加确认逻辑。
记录每次工具调用的入参和结果。

# 第四阶段：生产观测和评估

目标是让应用可调试、可评估、可迭代。

阅读重点：

LangSmith tracing
Evaluation
Datasets
Prompt / model 对比
LangGraph persistence

练习任务：

打开 LangSmith trace。
给每次请求打上用户 ID、会话 ID、Prompt 版本。
准备一组黄金测试问题。
对比两个 Prompt 或两个模型的效果。
记录 token、耗时和失败率。

# 文档里的旧版信息怎么看

LangChain 变化很快，阅读文章或旧项目时，经常会看到这些旧写法：

from langchain.chat_models import ChatOpenAI

新项目更推荐使用：

from langchain_openai import ChatOpenAI

还可能看到大量早期 Chain 类、旧 memory 类、旧 callback 写法。遇到这类代码时，不要急着照抄，先确认它对应的 LangChain 版本。

判断一段代码是否偏旧，可以看几个信号：

导入路径是否来自 langchain.chat_models、langchain.llms 等旧位置。
是否没有使用 provider package，例如 langchain-openai。
是否围绕旧 Chain 类写死流程。
是否没有 Runnable / LCEL 概念。
是否完全没有 LangGraph 和 LangSmith。

不是所有旧代码都不能用，但新项目最好沿着当前文档写。否则后面升级会很痛。

# 项目中如何组织 LangChain 代码

不要把 LangChain 调用直接写在 Flask route 或 FastAPI endpoint 里。更好的方式是把 AI 应用拆成几个层次。

app/
  api/
    chat.py
internal/
  ai/
    models.py
    prompts.py
    parsers.py
    chains.py
    tools.py
    retrievers.py
    agents.py
  services/
    chat_service.py

1
2
3
4
5
6
7
8
9
10
11
12
13
14

示例：

# internal/ai/models.py
from langchain_openai import ChatOpenAI


def get_chat_model():
    return ChatOpenAI(model="gpt-4o-mini", temperature=0)

1
2
3
4
5
6

# internal/ai/prompts.py
from langchain_core.prompts import ChatPromptTemplate


chat_prompt = ChatPromptTemplate.from_messages([
    ("system", "你是一个专业、克制、准确的技术助手。"),
    ("human", "{question}"),
])

1
2
3
4
5
6
7
8

# internal/ai/chains.py
from langchain_core.output_parsers import StrOutputParser
from internal.ai.models import get_chat_model
from internal.ai.prompts import chat_prompt


def build_chat_chain():
    return chat_prompt | get_chat_model() | StrOutputParser()

1
2
3
4
5
6
7
8

# internal/services/chat_service.py
from internal.ai.chains import build_chat_chain


def answer_question(question: str) -> str:
    chain = build_chat_chain()
    return chain.invoke({"question": question})

1
2
3
4
5
6
7

这样做的好处是，接口层不关心 Prompt 和模型细节。后续要替换模型、加入检索、增加 trace、添加 parser，都可以在 AI 模块内完成。

# 生产项目的依赖建议

一个生产项目可以按功能逐步引入依赖。

基础聊天：

pip install -U langchain langchain-openai

RAG：

pip install -U langchain langchain-openai langchain-text-splitters

如果使用特定向量库，再安装对应包，例如：

pip install -U langchain-chroma

复杂 Agent 工作流：

pip install -U langchain langgraph

观测评估：

pip install -U langsmith

最终应该把这些依赖固化到项目依赖文件里，而不是靠开发者手动安装。

# 什么时候需要 LangSmith

本地写 demo 时，不接 LangSmith 也能跑。但只要应用要长期维护，观测就很重要。

LangSmith 能帮助你回答这些问题：

哪次模型调用失败了？
最终 Prompt 是什么？
检索到了哪些文档？
工具调用了几次？
哪一步最慢？
token 花在哪里？
新 Prompt 是否比旧 Prompt 更好？

LLM 应用的 bug 往往不是堆栈异常，而是“回答质量不稳定”。没有 trace 和 eval，很难系统性优化。

# 小结

LangChain 的安装应该按需进行：基础应用安装 langchain 和对应 provider package，RAG 再加文本切分、向量库和文档加载相关依赖，复杂 Agent 再引入 LangGraph，生产观测再接 LangSmith。

文档阅读也要有路线：先 Overview 建立边界，再 Quickstart 跑通 create_agent，再看 LangChain 的 Models、Messages、Tools、Agents 和 Context engineering，用 Integrations 查 provider package，用 LangGraph 处理复杂状态流，最后用 Reference 查 API 细节。

如果只记住一件事，那就是：不要把 LangChain 当成一个单独的 pip 包，而要把它看成一套 LLM 应用工程生态。安装、文档、代码组织和生产观测，都应该围绕这个生态来设计。

← 为什么选择 LangChain：从 LLM 调用到可维护的 AI 应用工程 LangChain Prompt 组件实践：模板、消息占位符与提示词工程化 →

# LangChain 安装与文档阅读路线：从环境配置到工程上手

# 先理解 LangChain 的包结构

# 建议的 Python 环境

# 配置模型 API Key

# 最小可运行示例

# 常见安装问题

# 只安装 langchain 后找不到 ChatOpenAI

# OPENAI_API_KEY 未配置

# 版本不一致导致导入失败

# 代理和网络问题

# 官方文档怎么看

# Overview

# Quickstart

# LangChain

# LangGraph

# Integrations

# Learn 与 Reference

# 推荐阅读路线

# 第一阶段：跑通基础调用

# 第二阶段：接入真实业务上下文

# 第三阶段：工具调用和 Agent

# 第四阶段：生产观测和评估

# 文档里的旧版信息怎么看

# 项目中如何组织 LangChain 代码

# 生产项目的依赖建议

# 什么时候需要 LangSmith

# 小结

# 只安装 `langchain` 后找不到 `ChatOpenAI`

# `OPENAI_API_KEY` 未配置