LangChain新手安装保姆级教程：从下载到首次运行

LangChain是什么，适合谁学习

LangChain 是一个面向大模型应用开发的 AI 开发框架，常用于将语言模型、提示词、外部数据、工具调用与工作流无缝串联。与直接调用模型接口相比，它更像一套“应用搭建工具箱”：能帮助开发者快速构建问答机器人、文档检索系统、知识库助手、自动化信息整理工具以及智能客服原型等典型项目。

对于新手而言，LangChain 入门的关键并非一开始就掌握所有模块，而是先完成三件事：搭建好运行环境、成功调用一个语言模型、跑通第一个最小示例。一旦首次运行成功，后续学习 Prompt 模板、链式调用、检索增强生成（RAG）、Agent 等高级概念就会顺畅许多。

安装前准备：确认电脑环境

LangChain 主要运行在 Python 环境中，推荐使用 Python 3.10 或 3.11 版本。版本过旧可能导致依赖不兼容，过新也可能存在部分包尚未完全适配的情况。安装前请打开终端或命令提示符，输入 python --version 或 python3 --version 查看当前 Python 版本。

此外，还需准备一个代码编辑器，例如 VS Code、PyCharm 或其他熟悉的工具。新手建议使用 VS Code，它体积轻便，终端集成、文件管理与 Python 插件都很便捷。为避免不同项目的依赖互相干扰，强烈建议为 LangChain 单独创建虚拟环境——这也是所有 AI 工具安装教程中至关重要的一步。

第一步：创建项目文件夹和虚拟环境

先在电脑中创建一个项目文件夹，例如命名为 langchain-demo。进入该目录后创建虚拟环境。Windows 用户在终端中执行：python -m venv .venv；macOS 或 Linux 用户执行：python3 -m venv .venv。

创建完成后需要激活虚拟环境。Windows 执行：.venv\Scripts\activate；macOS 或 Linux 执行：source .venv/bin/activate。激活成功后，命令行前面通常会出现 (.venv) 标识。此后安装的所有依赖都会进入当前项目环境，不会污染系统级 Python 安装。

如果提示找不到 python 命令，说明 Python 未正确安装或未加入系统路径。可以重新安装 Python，并在安装界面勾选“Add Python to PATH”选项。macOS 用户若系统自带 Python 版本过旧，可通过官方安装包或常见的包管理工具安装新版 Python。

第二步：安装LangChain相关依赖

虚拟环境激活后，建议先升级 pip：python -m pip install --upgrade pip。然后安装 LangChain 核心包：pip install langchain。目前 LangChain 生态已拆分得更细，许多模型接入能力被放在独立的子包中。例如，当使用 OpenAI 兼容接口时，通常还需安装：pip install langchain-openai。

如果后续需要实现文档问答，可能还会用到向量数据库、PDF 解析、文本切分等依赖。但新手首次运行不建议一次性安装太多包。先让最小示例跑通，再按项目需求逐步添加依赖，这样出错时也更容易定位问题。

安装过程中如果速度较慢，可更换为稳定的国内镜像源；若遇到权限错误，请优先检查虚拟环境是否已激活，不建议直接使用管理员权限全局安装。如果提示某个依赖版本冲突，可先创建全新的虚拟环境重新安装，避免旧项目残留包造成干扰。

第三步：准备模型访问配置

LangChain 本身并非大模型，它负责组织调用流程，真正生成文本仍需接入模型服务或本地模型。对于新手而言，最常用的方式是接入云端模型接口。注册模型服务后，通常可获得一个 API Key，用于程序身份校验。

为安全起见，切勿将 API Key 直接写在代码中，更不要上传到公开代码仓库。推荐使用环境变量保存。Windows PowerShell 中可临时设置：$env:OPENAI_API_KEY="你的密钥"；macOS 或 Linux 执行：export OPENAI_API_KEY="你的密钥"。临时设置仅对当前终端有效，关闭后需要重新设置。

如果使用其他兼容接口，可能还需要配置模型名称、接口地址等参数。不同服务商字段略有差异，但思路一致：先确认密钥有效，再确认模型名可用，最后确认调用地址填写正确。新手排查问题时，不要同时修改多个参数，否则很难判断是哪一步导致失败。

第四步：编写首次运行示例

在项目文件夹中新建 main.py 文件，写入一个最小示例。示例逻辑很简单：导入模型封装类，创建模型对象，发送一句提示词，打印返回结果。可参考如下内容：from langchain_openai import ChatOpenAI，接着创建 llm = ChatOpenAI(model="gpt-4o-mini")，再执行 result = llm.invoke("用三句话解释LangChain适合做什么")，最后打印 print(result.content)。

保存文件后，在已激活虚拟环境的终端中运行：python main.py。如果看到模型返回的中文解释，说明 LangChain 安装、模型配置和基本调用均已完成。此时可以尝试修改提示词，例如让它生成会议纪要模板、产品介绍提纲或学习计划，借此感受框架调用模型的基本流程。

注意：LangChain 版本迭代较快，网络上旧教程中的导入路径可能已发生变化。例如早期写法常将所有组件从 langchain 主包导入，当前版本更推荐按模块安装和导入。如果复制旧代码报错，请优先查阅当前包的官方文档或安装包提示信息。

第五步：理解最小示例背后的流程

首次运行的示例虽然只有几行代码，却包含了 LangChain 应用的核心流程：用户输入提示词，LangChain 将请求整理成模型可识别的格式，模型服务返回结果，程序再提取内容并输出。后续无论是知识库问答还是复杂工作流，本质上都是在这个流程基础上增加数据读取、上下文拼接、结果解析和工具调用。

新手在跑通示例后，可以继续学习三个基础概念。第一是 Prompt 模板，用于将变量填入固定的提示结构；第二是 Output Parser，用于将模型输出整理成 JSON、列表或特定格式；第三是 Retriever，用于从文档或数据库中取回相关内容，再交给模型回答。这些能力组合起来，就是常见 RAG 应用的基础。

常见问题与解决办法

问题一：运行时提示 ModuleNotFoundError。通常是依赖未安装到当前环境。请先确认终端前是否有 (.venv) 标识，再执行 pip show langchain 或重新安装相关包。

问题二：提示找不到 API Key。说明环境变量未正确设置，或运行代码的终端并非设置变量的同一个窗口。可在当前终端重新设置一次，再运行脚本。若使用 IDE 内置运行按钮，也需检查 IDE 是否读取到了环境变量。

问题三：模型名称不可用。不同账号或服务支持的模型列表可能不同。请将示例中的模型名替换为自己服务中明确支持的名称，不要盲目复制教程中的旧名称。

问题四：请求超时或连接失败。先确认本地网络能正常访问目标服务，再检查接口地址、密钥和服务状态。若偶发失败，可稍后重试；若持续失败，应查看服务端控制台日志或错误码说明。

问题五：依赖版本冲突。新手最省事的处理方式是删除当前 .venv 目录，重新创建虚拟环境，再按顺序安装依赖。不要在同一环境中长期混装多个实验项目的包。

安全边界与使用建议

使用 LangChain 开发 AI 应用时，务必重视数据安全与调用成本。切勿将个人敏感信息、企业内部资料、未公开项目文档直接发送给不确定的模型服务。若必须处理业务数据，应先完成脱敏，并确认服务协议、数据保留策略与访问权限。

API Key 应像密码一样管理，避免写入截图、教程、公开仓库或共享文档。项目中可使用 .env 文件配合环境变量加载工具，但需将 .env 加入忽略列表，防止误提交。多人协作时，建议为不同成员或环境分配不同的密钥，便于审计和停用。

此外，还需为程序设置合理的输入限制、超时时间和异常处理机制。大模型输出并非总是准确，不能将结果直接用于高风险决策。面向真实用户的应用应增加人工复核、日志记录、内容过滤和失败兜底机制，避免因模型误答、格式异常或接口波动影响业务。

下一步学习路线

完成首次运行后，可以按照“从简单到复杂”的路线继续学习。第一阶段掌握 ChatModel、PromptTemplate 和基础调用；第二阶段学习文档加载、文本切分、向量检索，搭建一个本地文档问答原型；第三阶段再接触工具调用、Agent 和多步骤工作流。

学习过程中建议保留一个可运行的最小项目，每次只增加一个新功能，并用清晰的文件名记录实验结果。遇到问题先回到最小示例验证环境是否正常，再排查新增代码。这样既能减少挫败感，也能更快建立对 LangChain 工程化开发的理解。

总体而言，LangChain 入门并不困难，难点在于环境隔离、依赖版本和模型配置。只要按照创建虚拟环境、安装核心包、配置密钥、运行示例、逐步扩展的顺序推进，新手也能在较短时间内搭建出第一个可用的大模型应用原型。