1.3 环境搭建

第一章 langchain入门与环境准备

1.1 AI大模型应用开发和Langchain的关系

1.2 LangChain 1.2.7 版本核心特性与升级点

1.3 环境搭建（Python 版本要求、langchain/langchain-core 1.2.7 安装与版本验证）

1.4 LangChain 1.2.7 核心架构概览（Runnable、Prompt、Agent、Memory 核心链路）

1.3 环境搭建

在上一节我们解析了 LangChain 1.2.7 版本的核心特性与升级点，本节将提供完整的环境搭建指南。环境搭建是后续学习 Runnable 协议、组件编排、Agent 等核心功能的基础，需严格遵循版本要求，避免因版本不兼容导致的功能异常。本节将按"Python 版本要求→虚拟环境创建→核心依赖安装→版本验证→常见问题排查"的逻辑，系统完成环境搭建，确保内容全面、步骤清晰、可落地。

1.3.1 Python 版本要求（核心前提）

LangChain 1.2.7 版本的核心依赖（如 langchain-core、pydantic）对 Python 版本有明确约束，版本不匹配会直接导致安装失败或功能异常，具体要求如下：

• 推荐版本：Python 3.9 ~ 3.11（最稳定适配版本，优先选择 Python 3.10，兼顾兼容性和运行性能，可完美支持所有核心功能）；

• 不支持版本：

  • Python 3.8 及以下：langchain-core 1.2.7 依赖 pydantic v2 系列，该系列不兼容 Python 3.8，安装时会直接抛出版本不兼容错误；

  • Python 3.12 及以上：部分第三方依赖（如部分工具类、存储适配类依赖）尚未完成适配，可能出现流式执行、异步调用等核心功能异常。

• 关键提醒：建议使用虚拟环境（如 venv、conda）搭建独立开发环境，避免与系统 Python 或其他项目的依赖包冲突，尤其适合多版本 LangChain 并行开发、多项目切换的场景。

1.3.2 虚拟环境创建（推荐步骤）

无论使用 Windows、MacOS 还是 Linux 系统，均优先推荐创建虚拟环境，以下以 Python 内置的 venv 为例（简单易用、无需额外安装），分步骤完成虚拟环境的创建、激活与退出，适配全系统：

1. 打开终端/命令提示符：

   • Windows 系统：按下 Win + R 组合键，输入 cmd 打开命令提示符，或输入 PowerShell 打开 PowerShell（推荐 PowerShell，兼容性更好）；

   • MacOS/Linux 系统：直接打开终端（Terminal）即可。

2. 创建虚拟环境：

   • 第一步（可选）：切换到自定义工作目录，建议创建专门的 LangChain 学习/开发目录，便于文件管理：
     `# MacOS/Linux 系统切换目录
     cd ~/LangChain-Learn

   Windows 系统切换目录（示例路径，可自定义）

   cd D:\LangChain-Learn`

   • 第二步：执行创建命令，创建名为 langchain-1.2.7-env 的虚拟环境（名称可自定义，建议包含版本号，便于区分）：
     python -m venv langchain-1.2.7-env

3. 激活虚拟环境：

   • Windows（cmd 命令提示符）：
     langchain-1.2.7-env\Scripts\activate.bat

   • Windows（PowerShell）：
     .\langchain-1.2.7-env\Scripts\Activate.ps1

   • MacOS/Linux 系统：
     source langchain-1.2.7-env/bin/activate

   • 激活验证：终端/命令提示符前会显示虚拟环境名称（如 (langchain-1.2.7-env)），此时执行的所有 pip 命令均仅作用于该虚拟环境，不影响其他环境。

4. 退出虚拟环境（可选）：

   • 后续不需要使用该虚拟环境时，在终端/命令提示符中执行以下命令，即可退出虚拟环境：
     deactivate

   • 退出验证：终端/命令提示符前的虚拟环境名称消失，恢复系统默认显示。

1.3.3 langchain/langchain-core 1.2.7 安装（核心步骤）

LangChain 1.2.7 版本的核心依赖为 langchain-core1.2.7 和 langchain1.2.7：其中 langchain-core 是框架核心，包含 Runnable 协议、LCEL 表达式等核心功能；langchain 是完整框架，包含所有官方组件、工具链。安装时需严格指定版本号，避免安装最新版本导致不兼容，提供两种安装方式，可根据自身需求选择。

1.3.3.1 方式1：完整安装（推荐，新手首选）

完整安装会自动安装 langchain1.2.7、langchain-core1.2.7 以及常用依赖（如 pydantic、requests、aiohttp 等），无需手动安装其他依赖，一次性完成环境配置，执行以下命令：

# 完整安装，指定版本号，避免升级到最新版
pip install langchain==1.2.7 langchain-core==1.2.7 -i https://pypi.tuna.tsinghua.edu.cn/simple

补充说明：

• -i https://pypi.tuna.tsinghua.edu.cn/simple：使用清华源安装，大幅提升下载速度，避免官方源卡顿、超时问题；

• 依赖兼容：安装过程中 pip 会自动处理依赖版本兼容，若出现"版本冲突"提示，无需手动修改，等待 pip 自动适配即可；

• 功能支持：完整安装后，可直接使用 LangChain 1.2.7 的所有核心功能（Runnable、Prompt、LCEL 组件编排等），无需额外补充依赖。

1.3.3.2 方式2：最小化安装（适合按需扩展）

最小化安装仅安装 langchain-core1.2.7 和 langchain1.2.7 核心包，不安装额外依赖，适合有明确依赖管理需求、追求环境轻量化的开发者，步骤如下：

# 最小化安装，仅安装核心包，不安装额外依赖
pip install langchain==1.2.7 langchain-core==1.2.7 --no-deps -i https://pypi.tuna.tsinghua.edu.cn/simple

# 按需安装额外依赖（根据后续学习/开发需求安装，示例如下）
# 示例1：安装 OpenAI 模型依赖（后续调用 OpenAI 模型需用到）
pip install openai==1.30.1 -i https://pypi.tuna.tsinghua.edu.cn/simple
# 示例2：安装异步执行依赖（后续使用 ainvoke/astream 需用到）
pip install aiohttp==3.9.5 -i https://pypi.tuna.tsinghua.edu.cn/simple
# 示例3：安装环境变量配置依赖（后续管理 API Key 需用到）
pip install python-dotenv==1.0.1 -i https://pypi.tuna.tsinghua.edu.cn/simple

补充说明：最小化安装后，后续使用特定功能（如调用 OpenAI 模型、异步执行、环境变量配置）时，需手动安装对应依赖，否则会抛出"ModuleNotFoundError"（模块缺失）错误。

1.3.4 安装常见问题排查

安装过程中若出现错误，可参考以下常见问题及解决方案，快速排查并解决，避免影响后续学习/开发：

• 问题1：pip 版本过低，无法安装依赖

  • 提示信息：ERROR: Could not find a version that satisfies the requirement langchain==1.2.7

  • 解决方案：先升级 pip 版本，再重新执行安装命令：
    pip install --upgrade pip -i https://pypi.tuna.tsinghua.edu.cn/simple

• 问题2：Python 版本不兼容，安装失败

  • 提示信息：langchain-core 1.2.7 requires Python >=3.9, ❤️.12, but you have Python 3.8.10 which is incompatible

  • 解决方案：卸载当前不兼容的 Python 版本，安装 Python 3.9~3.11 中的任意版本（优先推荐 Python 3.10），重新创建虚拟环境并执行安装命令。

• 问题3：网络超时，无法下载依赖包

  • 提示信息：ReadTimeoutError: HTTPSConnectionPool(host='pypi.org', port=443): Read timed out

  • 解决方案：确保安装命令中添加了清华源（-i https://pypi.tuna.tsinghua.edu.cn/simple）；若仍超时，检查网络连接是否正常，或多次重试安装命令。

1.3.5 版本验证（关键步骤，确保环境可用）

安装完成后，必须进行版本验证，确认 Python、langchain、langchain-core 的版本符合要求，避免因安装错误导致后续功能异常，验证步骤分4步，适配全系统，简单易操作：

1. 验证 Python 版本

   • 操作：在激活虚拟环境的终端/命令提示符中，执行以下命令：
     python --version # Windows/MacOS/Linux 通用

   • 验证标准：输出版本号在 3.9~3.11 范围内，示例：Python 3.10.10（合格）。

2. 验证 langchain 版本

   • 操作：在激活虚拟环境的终端/命令提示符中，执行以下命令：
     pip show langchain

   • 验证标准：输出结果中 Version 字段为 1.2.7，示例：Version: 1.2.7（合格）。

3. 验证 langchain-core 版本

   • 操作：在激活虚拟环境的终端/命令提示符中，执行以下命令：
     pip show langchain-core

   • 验证标准：输出结果中 Version 字段为 1.2.7，示例：Version: 1.2.7（合格）。

4. 功能验证（可选，确保环境可正常使用）

   • 操作：执行简单代码，验证 LangChain 核心模块可正常导入，步骤如下：
     `# 第一步：进入 Python 交互环境
     python

   第二步：导入 langchain-core 核心模块（Runnable 协议）

   from langchain_core.runnables import Runnable

   第三步：打印 Runnable 类，确认版本适配

   print(Runnable)`

   • 验证标准：未抛出"ModuleNotFoundError"等异常，且正常打印 Runnable 类信息，说明环境搭建成功，可用于后续学习/开发。

1.3.6 章节总结

本节系统完成了 LangChain 1.2.7 环境的搭建，核心要点总结如下，便于快速回顾和后续查阅：

• 版本约束：Python 必须使用 3.9~3.11 版本，langchain 和 langchain-core 必须指定 1.2.7 版本，避免版本不兼容；

• 环境规范：优先使用虚拟环境（venv）搭建独立环境，避免依赖冲突，提升环境可维护性；

• 安装选择：新手首选完整安装，按需扩展可选择最小化安装，安装时建议使用清华源提升速度；

• 关键步骤：安装后必须进行版本验证，确保 Python、langchain、langchain-core 版本合格，可选做功能验证，确保环境可用；