AI Agent从无到有18：LangChain 开发环境搭建与首条链的运行

关注

原创 2026-08-14 10:30:54 263 阅读 AI 写同款· GEO 优化 ›

LangChain Agent集成MCP与Skills：构建可调用外部工具的AI智能体在AI应用开发领域，大语言模型（LLM）的推理和规划能力是其核心优势，但要让AI真正解决实际问题，必须使其能够安全、可靠地调用外部工具和系统。这涉及到工具调用（Tool Calling）这一关键技术，它允许AI模型根据用户指令，动态选择并执行预定义的工具函数，从而突破纯文本交互的限制，实现对数据库、文件系统、API等外部资源的操作。其技术价值在于将大模型的通用认知能力与专用工具的执行能力相结合，构建出功能强大的AI智能体（AI Agent）。这种架构在自动化工作流、智能数据分析助手、企业级知识问答与操作等场阅读详情

纲要

环境要求
- Python 版本要求与系统兼容性
- 开发工具选型：VSCode 与 Jupyter 插件
虚拟环境管理
- venv 的核心作用与最佳实践
- 虚拟环境的创建、激活与项目隔离
开发工具链
- Jupyter Notebook 的定位与安装
- VSCode 中 .ipynb 的交互式开发体验
LangChain 安装
- pip 安装 langchain 及其生态子包
- 0.3 版本之后的包结构拆分与选型
配置与第一个程序
- 使用 .env 文件管理敏感配置
- 调用 ChatOpenAI 构建首个对话链
- 完整可运行的脚本示例
常见问题与解决方案
- 依赖冲突、认证错误与网络代理

环境要求

任何 AI Agent 项目的技术落地，均始于标准且可复现的开发环境。LangChain 官方提供 Python 与 TypeScript 双语言支持，本文聚焦 Python 生态，环境基线如下：

Python：要求 3.12.1 或更高版本（向下兼容至 3.8，但推荐使用最新稳定版）
操作系统：Windows、macOS、Linux 均可，本文示例已在 macOS 与 Windows 环境下验证
集成开发环境：VSCode，配合官方 Jupyter 插件可提供单元格级交互能力

Python 作为动态类型语言，其解释执行特性与丰富的科学计算生态，使其成为 AI 与数据处理领域的事实标准。安装时请访问 python.org 下载对应系统版本，并务必勾选“Add Python to PATH”以确保命令行全局可用。

虚拟环境管理

在实际开发中，多项目并行时极易因依赖版本冲突导致运行时异常。Python 3.3 之后内置的 venv 模块为项目级隔离提供了官方标准方案。其核心优势在于：

依赖隔离：每个项目拥有独立的 site-packages，避免全局污染
版本锁定：配合 requirements.txt 实现依赖的精确复现
权限安全：无需管理员权限即可安装包

初始化项目并创建虚拟环境：

mkdir langchain-hello && cd langchain-hello
python -m venv .venv

激活虚拟环境（根据操作系统选择）：

macOS / Linux：
```
source .venv/bin/activate
```
Windows (Command Prompt)：
```
.venv\Scripts\activate
```

激活成功后，终端提示符前缀将出现 (.venv)，表明当前 pip 操作已重定向至隔离环境。推荐的项目结构如下：

langchain-hello/
├── .venv/               # 虚拟环境目录（不应提交至版本控制）
├── .env                 # 敏感环境变量（禁止提交）
├── hello.py             # 主程序入口
└── requirements.txt     # 依赖清单

开发工具链

LangChain 支持两种开发范式：传统脚本式（.py）与交互式笔记本（.ipynb）。Jupyter Notebook 作为基于浏览器的交互式编程环境，支持代码单元格与 Markdown 文本单元格的混排，特别适合提示词工程与链式调试验证。

安装 Jupyter 核心组件：

pip install jupyter

若使用 VSCode，仅需安装 Jupyter 官方插件，即可直接创建与编辑 .ipynb 文件。Notebook 单元格支持 Shell 命令执行（前缀 !），例如查看已安装包信息：

!pip show langchain

交互式执行模型使得每一步的输出均可视化，大幅降低了初学者在环境调试与数据流追踪上的认知负担。典型的 Notebook 工作流如下：

LangChain 安装

从 0.3 版本开始，LangChain 团队对代码库进行了模块化重构，将原先庞大的单体依赖拆分为若干职责单一的轻量包。这一调整使得开发者可以按需引入，显著降低了生产环境的部署体积与依赖冲突风险。

核心分包策略如下：

包名	职责描述
`langchain`	核心抽象：链、提示词模板、输出解析器、记忆模块等
`langchain-openai`	`OpenAI` 系列模型的官方集成
`langchain-deepseek`	`DeepSeek` 系列模型的官方集成
`langchain-community`	社区贡献的第三方模型与工具集成（稳定性略低于官方包）

安装核心包与 OpenAI 集成包（同时安装 python-dotenv 用于环境变量管理）：

pip install langchain langchain-openai python-dotenv

验证安装版本：

pip show langchain

若遇网络连接缓慢，可指定国内镜像源（如清华大学镜像）加速下载：

pip install langchain langchain-openai python-dotenv -i https://pypi.tuna.tsinghua.edu.cn/simple

配置与第一个程序

调用大语言模型通常需要提供 API Key。推荐通过 .env 文件管理敏感信息，该文件应位于项目根目录且不被提交至版本控制系统（建议添加至 .gitignore）。

创建 .env 文件：

OPENAI_API_KEY=sk-xxxx
OPENAI_BASE_URL=https://api.openai.com/v1

其中 OPENAI_BASE_URL 在 OpenAI 官方访问受限时，可配置为兼容 API 的中转地址或代理服务。若使用 DeepSeek 等国内模型，可将 BASE_URL 指向其官方端点，并相应调整 api_key。

以下为完整的 hello.py 脚本，它构建了一个简单的“自我介绍”链，涉及提示词模板、模型调用与输出解析三个核心环节：

import os
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser

# 加载 .env 中的环境变量
load_dotenv()

# 初始化 ChatOpenAI 实例
llm = ChatOpenAI(
    model="gpt-3.5-turbo",            # 可选：gpt-4, gpt-4-turbo, gpt-4o-mini
    temperature=0.7,
    api_key=os.getenv("OPENAI_API_KEY"),
    base_url=os.getenv("OPENAI_BASE_URL"),
)

# 定义消息模板（System 与 User 角色）
prompt = ChatPromptTemplate.from_messages([
    ("system", "你是一个热情的助手，请用中文介绍自己。"),
])

# 字符串输出解析器
parser = StrOutputParser()

# 使用管道运算符构建 LCEL 链
chain = prompt | llm | parser

if __name__ == "__main__":
    response = chain.invoke({})
    print(response)

版本适配说明：上述代码基于 LangChain >= 0.3.0 与 langchain-openai >= 0.2.0。在 0.3 版本中，ChatOpenAI 的参数已统一为 api_key 与 base_url（废弃了旧版的 openai_api_key 与 openai_api_base）。

运行脚本：

python hello.py

预期输出（内容可能因模型版本而异）：

你好！我是由 OpenAI 训练的大型语言模型，我可以回答问题、提供创作灵感、协助翻译，以及陪你聊天。

至此，首个 LangChain 程序已成功运行。后续开发中仅需调整 ChatPromptTemplate 的消息内容，即可快速试验不同场景下的模型响应。

常见问题与解决方案

异常现象	可能原因	解决方案
`ModuleNotFoundError: No module named 'langchain'`	未安装依赖或虚拟环境未激活	检查终端前缀是否包含 `(.venv)`，执行 `pip install langchain`
`AuthenticationError` 或 `Incorrect API key`	`API Key` 无效或 `.env` 未正确加载	检查 `.env` 中的 `OPENAI_API_KEY` 值；确认 `load_dotenv()` 执行成功
请求超时或连接拒绝	网络环境无法直连 `OpenAI` 端点	配置 `OPENAI_BASE_URL` 为有效的代理或中转地址；或切换至国内兼容模型
依赖版本冲突	全局安装与虚拟环境中的包版本不一致	重新创建纯净虚拟环境，仅安装当前项目所需的特定版本依赖

API 速览

本节梳理本文涉及的核心 API，便于开发者快速查阅与引用。

`langchain_openai.ChatOpenAI`

所属库：langchain-openai

方法签名：

class ChatOpenAI(BaseChatModel):
    def __init__(
        self,
        model: str = "gpt-3.5-turbo",
        temperature: float = 0.7,
        api_key: Optional[str] = None,
        base_url: Optional[str] = None,
        max_retries: int = 2,
        timeout: Optional[float] = 120,
        **kwargs
    ):
        ...

关键参数：
- model：模型名称，如 gpt-3.5-turbo、gpt-4-turbo
- temperature：采样温度，介于 0~2 之间，值越高输出越具随机性
- api_key：OpenAI 格式的认证密钥
- base_url：API 请求的基础 URL，可用于指向代理或兼容网关
返回值：ChatOpenAI 实例，实现了 BaseChatModel 抽象接口

`langchain_core.prompts.ChatPromptTemplate`

所属库：langchain-core

类方法：

@classmethod
def from_messages(cls, messages: List[Tuple[str, str]]) -> ChatPromptTemplate:
    ...

参数：messages 为元组列表，每个元组包含角色（system、human、ai）与内容模板字符串
返回值：ChatPromptTemplate 实例，支持管道操作与格式化

`langchain_core.output_parsers.StrOutputParser`

所属库：langchain-core
作用：将模型输出的 AIMessage 对象转换为纯字符串，简化下游处理
使用方式：作为 LCEL 链的末端节点，与 Runnable 协议兼容

Demo 示例

以下提供一个完整的、可独立运行的 HTML 文件（基于 Gradio 构建），用于演示一个具备交互界面的最简 LangChain 应用。该示例并非直接运行于浏览器前端，而是启动一个本地 WebUI 服务，适合作为 Agent 原型验证工具。

运行说明：

安装依赖：pip install gradio langchain langchain-openai python-dotenv
在项目根目录配置 .env 文件（含 OPENAI_API_KEY）
运行脚本：python app.py
浏览器访问 http://127.0.0.1:7860

import gradio as gr
import os
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser

load_dotenv()

llm = ChatOpenAI(
    model="gpt-3.5-turbo",
    temperature=0.7,
    api_key=os.getenv("OPENAI_API_KEY"),
    base_url=os.getenv("OPENAI_BASE_URL"),
)

prompt = ChatPromptTemplate.from_messages([
    ("system", "你是一个有用的 AI 助手，请用中文回答用户的问题。"),
    ("human", "{user_input}"),
])

chain = prompt | llm | StrOutputParser()

def respond(message, history):
    return chain.invoke({"user_input": message})

gr.ChatInterface(
    fn=respond,
    title="LangChain Hello Demo",
    description="基于 LangChain 0.3 与 OpenAI 的简单对话演示"
).launch()

技术点总结：

演示了 LangChain 与 Gradio 的集成，实现 Chat 交互界面
使用了 LCEL 链式调用，包含提示词模板、模型与输出解析器
展示了 ChatPromptTemplate 中 human 变量插值的用法
覆盖了环境变量加载与 API 客户端初始化的完整流程

参考文档

官方文档
参考链接

总结

本文围绕 LangChain 从零开始的开发环境搭建，系统梳理了从 Python 版本选型、venv 虚拟环境隔离、Jupyter 交互式工具链，到 0.3 版本分包安装策略的完整路径。通过一个完整的“自我介绍”链示例，展示了 ChatPromptTemplate、ChatOpenAI 与 StrOutputParser 的核心协作模式。

常见问题章节则针对依赖冲突、认证失效与网络代理提供了可操作的诊断思路。掌握这些基础基建，是后续构建复杂 AI Agent 工作流的必要前提。

收录于