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

纲要环境要求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-hellocdlangchain-hello python-mvenv .venv激活虚拟环境根据操作系统选择macOS / Linuxsource.venv/bin/activateWindows (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工作流如下是否创建 .ipynb 文件编写 Markdown 说明单元格编写代码单元格执行并观察输出结果是否符合预期进入下一模块开发调整代码或提示词LangChain 安装从0.3版本开始LangChain团队对代码库进行了模块化重构将原先庞大的单体依赖拆分为若干职责单一的轻量包。这一调整使得开发者可以按需引入显著降低了生产环境的部署体积与依赖冲突风险。核心分包策略如下包名职责描述langchain核心抽象链、提示词模板、输出解析器、记忆模块等langchain-openaiOpenAI系列模型的官方集成langchain-deepseekDeepSeek系列模型的官方集成langchain-community社区贡献的第三方模型与工具集成稳定性略低于官方包安装核心包与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_KEYsk-xxxx OPENAI_BASE_URLhttps://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 实例llmChatOpenAI(modelgpt-3.5-turbo,# 可选gpt-4, gpt-4-turbo, gpt-4o-minitemperature0.7,api_keyos.getenv(OPENAI_API_KEY),base_urlos.getenv(OPENAI_BASE_URL),)# 定义消息模板System 与 User 角色promptChatPromptTemplate.from_messages([(system,你是一个热情的助手请用中文介绍自己。),])# 字符串输出解析器parserStrOutputParser()# 使用管道运算符构建 LCEL 链chainprompt|llm|parserif__name____main__:responsechain.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 langchainAuthenticationError或Incorrect API keyAPI Key无效或.env未正确加载检查.env中的OPENAI_API_KEY值确认load_dotenv()执行成功请求超时或连接拒绝网络环境无法直连OpenAI端点配置OPENAI_BASE_URL为有效的代理或中转地址或切换至国内兼容模型依赖版本冲突全局安装与虚拟环境中的包版本不一致重新创建纯净虚拟环境仅安装当前项目所需的特定版本依赖API 速览本节梳理本文涉及的核心API便于开发者快速查阅与引用。langchain_openai.ChatOpenAI所属库langchain-openai方法签名classChatOpenAI(BaseChatModel):def__init__(self,model:strgpt-3.5-turbo,temperature:float0.7,api_key:Optional[str]None,base_url:Optional[str]None,max_retries:int2,timeout:Optional[float]120,**kwargs):...关键参数model模型名称如gpt-3.5-turbo、gpt-4-turbotemperature采样温度介于0~2之间值越高输出越具随机性api_keyOpenAI格式的认证密钥base_urlAPI请求的基础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原型验证工具。运行说明安装依赖pip install gradio langchain langchain-openai python-dotenv在项目根目录配置.env文件含OPENAI_API_KEY运行脚本python app.py浏览器访问http://127.0.0.1:7860importgradioasgrimportosfromdotenvimportload_dotenvfromlangchain_openaiimportChatOpenAIfromlangchain_core.promptsimportChatPromptTemplatefromlangchain_core.output_parsersimportStrOutputParser load_dotenv()llmChatOpenAI(modelgpt-3.5-turbo,temperature0.7,api_keyos.getenv(OPENAI_API_KEY),base_urlos.getenv(OPENAI_BASE_URL),)promptChatPromptTemplate.from_messages([(system,你是一个有用的 AI 助手请用中文回答用户的问题。),(human,{user_input}),])chainprompt|llm|StrOutputParser()defrespond(message,history):returnchain.invoke({user_input:message})gr.ChatInterface(fnrespond,titleLangChain Hello Demo,description基于 LangChain 0.3 与 OpenAI 的简单对话演示).launch()技术点总结演示了LangChain与Gradio的集成实现Chat交互界面使用了LCEL链式调用包含提示词模板、模型与输出解析器展示了ChatPromptTemplate中human变量插值的用法覆盖了环境变量加载与API客户端初始化的完整流程参考文档官方文档LangChain Python SDK 官方文档LangChain Core API ReferenceOpenAI API 文档参考链接LangChain 0.3 迁移指南Python venv 官方指南python-dotenv 项目仓库总结本文围绕LangChain从零开始的开发环境搭建系统梳理了从Python版本选型、venv虚拟环境隔离、Jupyter交互式工具链到0.3版本分包安装策略的完整路径。通过一个完整的“自我介绍”链示例展示了ChatPromptTemplate、ChatOpenAI与StrOutputParser的核心协作模式。常见问题章节则针对依赖冲突、认证失效与网络代理提供了可操作的诊断思路。掌握这些基础基建是后续构建复杂AI Agent工作流的必要前提。