纲要

• 环境要求
  • 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实现依赖的精确复现
• 权限安全：无需管理员权限即可安装包

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

mkdirlangchain-hello&&cdlangchain-hello python-mvenv .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核心组件：

pipinstalljupyter

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

!pip show langchain

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

LangChain 安装

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

核心分包策略如下：

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

pipinstalllangchain langchain-openai python-dotenv

验证安装版本：

pip show langchain

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

pipinstalllangchain langchain-openai python-dotenv-ihttps://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脚本，它构建了一个简单的“自我介绍”链，涉及提示词模板、模型调用与输出解析三个核心环节：

importosfromdotenvimportload_dotenvfromlangchain_openaiimportChatOpenAIfromlangchain_core.promptsimportChatPromptTemplatefromlangchain_core.output_parsersimportStrOutputParser# 加载 .env 中的环境变量load_dotenv()# 初始化 ChatOpenAI 实例llm=ChatOpenAI(model="gpt-3.5-turbo",# 可选：gpt-4, gpt-4-turbo, gpt-4o-minitemperature=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|parserif__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的消息内容，即可快速试验不同场景下的模型响应。

常见问题与解决方案

API 速览

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

langchain_openai.ChatOpenAI

• 所属库：langchain-openai
• 方法签名：

  classChatOpenAI(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
• 类方法：

  @classmethoddeffrom_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原型验证工具。

运行说明：

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

importgradioasgrimportosfromdotenvimportload_dotenvfromlangchain_openaiimportChatOpenAIfromlangchain_core.promptsimportChatPromptTemplatefromlangchain_core.output_parsersimportStrOutputParser 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()defrespond(message,history):returnchain.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 SDK 官方文档
  • LangChain Core API Reference
  • OpenAI API 文档

• 参考链接

  • LangChain 0.3 迁移指南
  • Python venv 官方指南
  • python-dotenv 项目仓库

总结

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

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