3. 环境搭建与依赖安装

在开始编写任何LangChain Agent代码之前，必须先构建一个稳定、可复现且安全的开发环境。环境搭建的质量直接决定了后续调试效率、依赖冲突概率以及生产部署的平滑度。本章将围绕三大核心任务展开：Python虚拟环境的创建与依赖管理、LangChain及其生态包的安装策略、以及或其他LLM API的密钥配置与网络验证。我们将从原理出发，逐步深入到可操作的命令与配置，并辅以实战案例和常见误区分析，帮助你一次性搭建出专业级的Agent开发环境。

3.1 Python 虚拟环境：隔离是避免依赖灾难的第一道防线

核心原理

LangChain 生态发展迅速，不同版本之间可能存在破坏性变更。例如，LangChain 0.1.x 与 0.2.x 在 Agent 执行器接口上就有显著差异。如果直接在系统全局 Python 环境中安装，多个项目共享同一套包，一旦某个项目升级了依赖，其他项目可能立即崩溃。虚拟环境（如 venv、conda）通过创建独立的 Python 解释器副本和 site-packages 目录，实现了项目间依赖的完全隔离。这不仅是最佳实践，更是保证开发效率的基础设施。

操作流程：基于 venv 的标准搭建步骤

1. 检查 Python 版本：LangChain 0.2+ 要求 Python 3.8 以上，但推荐使用 3.10-3.12 以获得最佳兼容性。执行 python --version 确认。
2. 创建虚拟环境：在项目根目录执行

   python -m venv .venv

   其中 .venv 是环境目录名，通常加入 .gitignore。
3. 激活环境：
   • Windows (CMD/PowerShell): .venv\Scripts\activate
   • macOS/Linux (bash/zsh): source .venv/bin/activate
   激活后命令行前缀会出现 (.venv) 标识。
4. 升级 pip 与核心构建工具：

   python -m pip install --upgrade pip setuptools wheel

案例拆解：一次依赖冲突的排查与解决

背景与约束：某团队在开发一个 Agent 应用时，使用了 langchain==0.1.0 和 langchain-==0.0.5。后来为了使用新的工具调用功能，将 langchain 升级到 0.2.5，但未升级 langchain-。

初始现象：运行 Agent 时抛出 ImportError: cannot import name 'create_agent' from 'langchain.agents'。

分析判断：LangChain 0.2 将 Agent 创建逻辑重构，旧版 langchain- 中的 create__tools_agent 函数签名已变更，且内部引用了已移除的模块。

实际操作：在虚拟环境中执行 pip install --upgrade langchain- langchain langchain-community，将所有核心包统一升级到最新兼容版本。随后运行 pip check 验证依赖一致性。

结果对比：升级后 Agent 正常执行。复盘发现，根因是未使用 requirements.txt 锁定版本，导致部分包升级部分未升级。此后团队规定所有依赖必须写入 requirements.txt 并提交到版本库。

常见误区与总结

• 误区一：使用 pip install langchain 后以为万事大吉，忽略了 langchain- 等集成包。LangChain 0.2+ 采用模块化设计，必须按需安装对应集成包。
• 误区二：在虚拟环境外使用 pip 安装，导致包被装到全局环境。务必确认激活状态。
• 误区三：忽略 Python 版本要求。LangChain 0.3 已宣布放弃 Python 3.8 支持，使用旧版本 Python 会导致安装失败或运行时异常。

3.2 LangChain 核心包安装：版本选择与依赖管理

核心原理

LangChain 自 0.2 版本起，将原先的单一 langchain 包拆分为多个子包：langchain-core（基础抽象）、langchain（链与 Agent 编排）、langchain-community（社区集成）、以及针对特定提供商的包（如 langchain-、langchain-anthropic）。这种拆分降低了安装体积，但也要求开发者明确知道自己需要哪些包。安装策略的核心是：先装核心，再按需扩展。

安装命令与版本对照表

操作流程：从零到可运行的最小安装

# 1. 激活虚拟环境（假设已创建）
source .venv/bin/activate

# 2. 安装核心包
pip install langchain langchain- langchain-community

# 3. 安装辅助工具（可选但推荐）
pip install python-dotenv  # 用于加载 .env 文件
pip install langsmith      # 用于调试追踪

# 4. 验证安装
python -c "import langchain; print(langchain.__version__)"

案例拆解：使用 requirements.txt 锁定可复现环境

背景：一个 Agent 项目需要部署到三台服务器，且需要保证开发、测试、生产环境完全一致。

操作步骤：

1. 在开发环境执行 pip freeze > requirements.txt，生成当前环境的精确版本列表。
2. 编辑 requirements.txt，将其中与 LangChain 无关的传递依赖（如 certifi）保留，但将核心包版本显式标注：

   langchain==0.2.5
   langchain-==0.1.3
   langchain-community==0.2.5
   python-dotenv==1.0.1

3. 在目标服务器上执行 pip install -r requirements.txt。

结果对比：三台服务器均成功运行，无版本漂移。复盘发现，使用 pip freeze 会包含所有传递依赖，虽然完整但可能引入不必要的包。更精细的做法是使用 pip-tools 的 pip-compile 来生成干净的约束文件。

3.3 与其他 LLM API 配置：密钥管理、网络与模型选择

核心原理

LangChain 本身不包含大模型，它通过 API 调用外部 LLM。因此，配置的核心是让 LangChain 能够安全地读取你的 ，并正确路由到目标服务。对于 ，需要设置 _ 环境变量；对于 Azure ，还需要设置 AZURE__ENDPOINT 和 AZURE__。对于其他兼容 协议的服务（如 Ollama、vLLM、Moonshot），则需要通过 base_url 参数指定服务地址。

操作流程：使用 .env 文件管理密钥

1. 创建 .env 文件：在项目根目录创建 .env 文件，内容如下：

   _=sk-your-key-here
   # 可选：如果使用代理或自定义端点
   # _BASE_URL=https://api..com/v1
   # 可选：设置默认模型
   # _MODEL_NAME=-mini

2. 加载 .env 文件：在 Python 代码入口处添加：

   from dotenv import load_dotenv
   load_dotenv()  # 加载 .env 文件到环境变量

3. 初始化模型：

   from langchain_ import ChatOpenAI
   
   llm = ChatOpenAI(
       model="-mini",
       temperature=0.7,
       # 如果使用非  官方端点，取消注释下一行
       # base_url="http://localhost:11434/v1",  # Ollama 示例
   )

案例拆解：从 切换到本地 Ollama 的完整过程

背景与约束：某企业内部开发环境无法访问外网，但需要测试 Agent 功能。团队决定使用 Ollama 在本地运行 Llama 3.1 8B 模型，并通过 兼容接口接入 LangChain。

初始现象：直接使用 ChatOpenAI 默认配置，报错 Connection error。

分析判断：LangChain 的 ChatOpenAI 默认指向 官方域名，需要覆盖 base_url 和 （Ollama 不校验密钥，可填任意非空字符串）。

实际操作：

1. 在本地启动 Ollama 服务：ollama serve，并拉取模型：ollama pull llama3.1:8b。
2. 修改 .env 文件：

   _=ollama
   _BASE_URL=http://localhost:11434/v1

3. 修改代码，指定模型名称：

   llm = ChatOpenAI(model="llama3.1:8b", temperature=0.3)

4. 执行测试调用，确认返回正常。

结果对比：切换后 Agent 功能完全正常，且响应速度提升（本地推理）。风险与代价：本地模型能力弱于 ，复杂推理任务效果下降。复盘经验：base_url 是 LangChain 对接任何 兼容服务的关键开关，务必熟练掌握。

常见误区与总结

• 误区一：将 硬编码在代码中，并提交到 Git 仓库。这会导致密钥泄露。必须使用环境变量或 .env 文件，并将 .env 加入 .gitignore。
• 误区二：忽略网络代理。在企业内网，访问 可能需要设置 HTTP 代理。可以在 .env 中设置 HTTP_PROXY 和 HTTPS_PROXY，或在代码中通过 requests.Session 传递。
• 误区三：混淆 _ 与 _ORG_ID。如果使用组织账户，还需要设置 _ORG_ID，否则可能报权限错误。
• 误区四：使用 langchain.llms. 而不是 langchain_.ChatOpenAI。前者是旧版接口，在 0.2+ 中已标记为弃用，且不支持工具调用功能。

3.4 环境验证与排障：确保一切就绪

核心原理

搭建完成后，必须进行端到端的冒烟测试，验证三个关键链路：包导入是否正常、是否被正确读取、模型调用是否成功。任何一环失败都会导致后续 Agent 开发无法进行。

操作流程：三步验证法

1. 导入验证：

   python -c "from langchain_ import ChatOpenAI; from langchain.agents import create_agent; print('Imports OK')"

2. 密钥验证：

   python -c "import os; print('Key exists:', bool(os.getenv('_')))"

3. 模型调用验证：

   python -c "
   from langchain_ import ChatOpenAI
   llm = ChatOpenAI(model='-mini', temperature=0)
   resp = llm.invoke('Say hello in 3 words')
   print(resp.content)
   "

常见排障清单

案例复盘：一次超时问题的定位

背景：Agent 在调用 时频繁出现 TimeoutError，但直接使用 curl 测试 API 却正常。

分析：LangChain 默认请求超时时间为 60 秒，但 Agent 在一次推理中可能包含多轮工具调用，每轮都消耗时间。当总时长超过 60 秒时，客户端主动断开。

解决：在初始化 ChatOpenAI 时增加 request_timeout=120 参数，并设置 max_retries=2。同时，检查代码中是否有死循环导致重复调用。

复盘：环境问题不总是安装问题，也可能是配置参数不合理。建议在开发初期就设置合理的超时和重试策略。