第一章、LangChain概述与环境准备（下）

第一章、LangChain概述与环境准备（上）

4、环境准备

4.1 基本要求

4.4.1 系统与软件版本

1）Windows 系统：Win10 20H2 及以上 / Win11，内置 PowerShell 5.1+；

2）Python：固定使用 3.10、3.11、3.12 版本，不支持 3.10 以下、3.13 及以上版本；

3）编辑器：推荐 VS Code，安装 Python 官方插件提升开发体验。

4.1.2 硬件配置

• 最低学习配置：双核 CPU、4GB 内存、10GB 以上空闲磁盘；
• 推荐配置：8GB 及以上内存、SSD 固态硬盘（运行本地大模型建议 16GB 内存）。

4.1.3 路径与权限规范

1）项目存放路径禁止中文、空格、特殊符号，防止 uv、Python 解析路径异常；

2）安装 uv、切换 winget 镜像时需要管理员 PowerShell，日常开发普通用户权限即可；

3）不建议将项目放在 C 盘系统目录，缓存依赖会占用大量存储空间。

4.1.4 网络与平台前置

1）网络二选一：

• 合规海外网络：可直连 Github、OpenAI 官方；

• 国内普通网络：使用 CloseAI、DeepSeek 国内中转平台，无需梯子；

  2）提前注册大模型平台，准备 API Key，后续代码需要读取密钥调用模型；

  3）Github 资源下载缓慢时，可使用中科大 winget 镜像、ghproxy 加速。

4.1.5 前置认知

所有项目均使用独立虚拟环境隔离依赖，不污染系统全局 Python，全程使用 uv 统一管理环境与包，无需手动使用 pip、conda、venv。

4.2 conda、uv、pip、venv 到底是什么关系？

在正式搭建环境之前，先花一分钟理清这几个工具的关系------很多同学在这里被绕晕。

1、 内建的模块 不需要你手动的安装，只要你有python 的sdk 可以。 time /os...

2、第三方的模块，需要手动的安装（用什么 安装什么...可控） lanchain/langchain-deepseek/langchain-openai/langchain-an...

3、自己的模块，不需要手动安装，只需要引入就可以。

开发 Python 项目，你需要解决两个问题：① 环境隔离（不同项目用不同的 Python 版本和依赖，互不干扰）和 ② 包安装（把 numpy、langchain 这些库装进来）。市面上的工具就是围绕这两件事做的，只不过各自覆盖的范围不同：

4.2.1 Python工具对比：环境隔离与包安装

|-------|---------------------|------------------------|----------------------|
| | 环境隔离(Python版本+虚拟环境) | 包安装(安装第三方库) | |
| venv | √能建虚拟环境✗不能管Python版本 | ✗不能装包(需搭配pip) | Python自带,最基础 |
| pip | ✗不管环境 | √从PyPI装包 | Python自带,最传统 |
| conda | √管Python版本√能建虚拟环境 | √从conda仓库装包√也能装pip的包 | 全能瑞士军刀还能装C库(CUDA等) |
| uv | √管Python版本√能建虚拟环境 | √从PyPI装包(比pip快10-100倍) | 新一代,Rust编写专注Python生态 |

简单说：venv + pip 是 Python 自带的"原始组合"，能用但体验一般；conda 是"什么都管的瑞士军刀"，功能全但体积大、速度慢；uv 是"新一代替代品"，速度极快、功能覆盖 venv + pip 的全部能力，还能管理 Python 版本。

4.2.2 本课程为什么选 uv 而不是 conda？

|---------------------|-----------------------|--------------------------|
| 对比维度 | conda | uv |
| 安装包速度 | 较慢(依赖解析复杂) | 极快(Rust 编写,快 10-100 倍) |
| 管理 Python 版本 | | (uv python install 3.12) |
| 虚拟环境 | | (uv init 自动创建) |
| 依赖锁定 | environment.yml (不精确) | uv.lock(精确锁定,可复现) |
| 包来源 | conda 仓库 + PyPI | PyPI(LangChain 全生态都在这里) |
| 安装非 Python 库(CUDA等) | √ 这是 conda 的独特优势 | ✗ 只管 Python 包 |
| 体积 | 较大(Anaconda ~3GB) | 极小(单个二进制文件) |

结论：LangChain 的所有包都在 PyPI 上，不需要 conda 仓库。uv 在速度、依赖管理、环境复现上全面优于 conda。本课程统一使用 uv，不再需要 conda/pip/venv。

什么时候还需要 conda？ 如果你做深度学习项目，需要安装 CUDA、cuDNN 等非 Python 的C/C++ 库，conda 仍然有价值。但这不在本课程范围内，遇到时再单独处理即可。

4.3 LangChain 包结构

在安装之前，先了解一下 LangChain 的包是怎么组织的------它不是一个"大而全"的单一包，而是按职责拆分成多个小包，按需安装：

|------|-------------------------|----------------------------|
| 分类 | 包名 | 说明 |
| 核心包 | langchain | 核心包(必须安装) |
| | langchain-core | 核心抽象和基础类(随 langchain 自动安装) |
| | langchain-cli | 命令行工具(可选) |
| 模型集成 | langchain-openai | OpenAI 集成(GPT-4 等) |
| | langchain-anthropic | Anthropic 集成(Claude 系列) |
| | langchain-google-genai | Google Gemini 集成 |
| | langchain-ollama | Ollama 本地模型集成 |
| | langchain-deepseek | DeepSeek 集成 |
| | langchain-community | 社区维护的集成包 |
| 功能扩展 | langchainhub | 提示词和链的共享仓库 |
| | langchain-chroma | Chroma 向量数据库集成 |
| | langchain-elasticsearch | Elasticsearch 集成 |
| | langchain-redis | Redis 缓存集成 |

原则：只安装你用到的包。uv 的依赖解析很快，随时 uv add 新包即可，不用一次装全。

4.4 安装 uv

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh 

如果觉得安装慢可以用这招：

#不用梯子的最优提速方案（推荐，不用开代理），步骤 1 管理员 PowerShell 执行，替换国内源
#这个是Windows版本的
winget source remove winget
winget source add winget https://mirrors.ustc.edu.cn/winget-source
#步骤 2 直接执行安装命令
winget install --id astral-sh.uv -e

安装完成后验证：

uv --version 

也可以用 pip install uv 快速安装，但推荐上面的官方方式（更快、不依赖已有 Python）。

4.5 创建项目环境并安装 LangChain

4.5.1 命令行

# 1. 创建项目目录
mkdir langchain-course && cd langchain-course

# 2. 用 uv 初始化项目（自动创建虚拟环境 + pyproject.toml）
uv init

# 3. 指定 Python 版本（推荐 3.12）
uv python pin 3.12

# 4. 安装 LangChain 核心包
uv add langchain

# 5. 按需安装模型提供商集成（选你要用的）
uv add langchain-openai    # OpenAI（GPT-4 等）
uv add langchain-anthropic    # Anthropic（Claude 系列）
uv add langchain-google-genai    # Google Gemini
uv add langchain-deepseek    # DeepSeek
uv add langchain-ollama    # Ollama 本地模型

# 6. 按需安装功能扩展包
uv add langchain-chroma    # Chroma 向量数据库
uv add python-dotenv    # .env 环境变量加载

为什么用 uv add 而不是 uv pip install ？ uv add 会自动将依赖写入 pyproject.toml 并生成 uv.lock 锁文件，方便团队协作和环境复现。uv pip install 也能用，但不会记录依赖关系。

项目创建图示如下：

1.创建项目

2.选择uv后创建项目，然后按照需要在终端输入上面的命令即可

4.6 理解项目文件：pyproject.toml 和 uv.lock

执行完上面的命令后，你会发现项目目录里多出了几个文件：

langchain-course/
├─ .venv/    # 虚拟环境（uv 自动创建）
├─ pyproject.toml    # 项目配置 + 依赖清单（你手动管理）
├─ uv.lock    # 依赖锁文件（uv 自动生成）
└─ main.py    # 入口文件

4.6.1 这三个东西各自的角色，用一个比喻来理解：

pyproject.toml uv.lock .venv/
"购物清单" "收银小票" "冰箱"
你写的：我要牛奶≥3瓶 uv算的：牛奶3.2瓶 实际安装的包
酸奶1.1瓶（牛奶的依赖）
糖0.5袋（酸奶的依赖）

你手动管理 uv 自动生成 uv 自动安装
✓ 提交到 git ✓ 提交到 git ✗ 不提交（加进 .gitignore）

4.6.2 pyproject.toml --- "我需要什么"

这是项目的配置文件，记录了项目名称、Python 版本要求、以及你手动安装的依赖列表。每次执行 uvadd langchain 时，uv 就往这个文件的 dependencies 里加一条记录：

[project]
name = "langchain-demo"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = [
    "langchain>=1.2.15",
    "langchain-openai>=1.1.15",
    "langchain-anthropic>=1.4.1",
    "langchain-ollama>=1.1.0",
    "openai>=2.32.0",
    "python-dotenv>=1.1.0",
    "notebook>=7.5.5"
] 

版本号后面的 >=1.2.15 表示"至少要这个版本"，是一个宽松的约束。你不需要手动编辑这个文件， uvadd / uv remove 会自动维护它。

4.6.3 uv.lock --- "我实际装了什么"

这是 uv 自动生成的锁文件，记录了每个包及其所有间接依赖的精确版本号。你永远不需要手动编辑它。

它解决的核心问题是可复现性------把 pyproject.toml 和 uv.lock 发给同事，同事执行一条命令就能得到和你完全一致的环境：

# 同事拿到你的项目后，一条命令还原环境
uv sync

不会再出现"在我电脑上能跑、在你电脑上报错"的问题。

常见小坑： python-dotenv 和 dotenv 是两个不同的包。代码里 from dotenv importload_dotenv 实际依赖的是 python-dotenv。如果你不小心装成了 dotenv ，用以下命令修正：

uv remove dotenv
uv add python-dotenv 

4.7 验证安装

# 在项目目录下运行
uv run python -c "import langchain; print(langchain.__version__)

或进入 Python 交互环境：

import langchain
print(langchain.__version__)  # 应显示版本号

4.8 常用大模型服务平台

LangChain 的核心优势之一是模型无关性------切换模型只需改一行配置。但前提是你得有一个能用的API。下面按使用场景整理了主流平台，帮你快速找到适合自己的方案。

海外模型官方平台（需科学上网 + 海外支付）

|------------------|--------------------------------|-------------------------------|---------------------------|
| 平台 | 地址 | 代表模型 | 说明 |
| OpenAI | https://platform.openai.com/ | GPT-4o、GPT-4.1、o3 | 最主流的闭源模型,需Visa/Master 信用卡 |
| Anthropic | https://console.anthropic.com/ | Claude Sonnet 4、Claude Opus 4 | 长上下文、代码能力强,需海外信用卡 |
| Google AI Studio | https://aistudio.google.com/ | Gemini 2.5 Pro/Flash | 免费额度较多,注册门槛低 |

4.8.1 国内代理/中转平台（国内直连、支付宝付费）

如果你没有海外支付手段，或者网络环境不方便直连，可以使用以下代理平台。它们提供与官方完全兼容的 API 接口，只需替换 base_url 即可，代码无需任何修改：

|------------|------------------------------------|--------------------------|---------------------------------------|
| 平台 | 地址 | 可用模型 | 特点 |
| CloseAI | https://platform.closeai-asia.com/ | OpenAI、Claude、Gemini 全系列 | 亚洲最大的 API 中转平台,企业级稳定性,支持支付宝,100% 官方转发 |
| OpenRouter | https://openrouter.ai/ | 350+ 模型(闭源+开源) | 统一接口切换任意模型,美元计费,部分免费模型可用 |

4.8.2 国产模型平台（国内直连、部分有免费额度）

|----------|-------------------------------------|---------------------------|----------------------------------------|
| 平台 | 地址 | 代表模型 | 特点 |
| DeepSeek | https://platform.deepseek.com/ | DeepSeek-V3、DeepSeek-R1 | 性价比极高,推理能力强,兼容OpenAI接口格式 |
| 阿里云百炼 | https://bailian.console.aliyun.com/ | 通义千问 Qwen 系列 | 一站式大模型开发平台,企业级服务 |
| 硅基流动 | https://www.silonflow.cn/ | DeepSeek、Qwen、GLM等50+开源模型 | 开源模型推理加速平台,新用户送2000万Token,兼容OpenAI接口格式 |
| 智谱 AI | https://open.bigmodel.cn/ | GLM-4、GLM-5系列 | GLM-4-Flash永久免费,中文能力强 |

4.8.3 如何选择？

你的情况是？  
有科学上网 + 海外信用卡  
直连 OpenAI / Anthropic 官方（延迟最低、最稳定）  
国内网络 + 只有支付宝  
CloseAI 代理（本课程推荐方案，改一行 base_url 搞定）  
想省钱 / 学习用途  
DeepSeek（超便宜）或 硅基流动（有免费额度）  
想用国产模型  
阿里云百炼（Qwen）或 智谱AI（GLM）

4.9 配置环境变量

使用时只需要注册、充值并创建API-Key，之后即可使用API-Key与BASE_URL来调用平台提供的相应的模型的服务。

4.9.1 通过.env文件配置

适用于实际项目当中：

1. 在项目根目录中创建.env文件

2. 添加环境变量（以OPENAI_BASE_URL和OPENAI_API_KEY为例）：

# OpenAI配置（使用CloseAI代理）
OPENAI_API_KEY=sk-your-api-key
OPENAI_BASE_URL=https://api.closeai-asia.com/v1
# Anthropic配置（可选）
ANTHROPIC_API_KEY=sk-ant-your-api-key
# DeepSeek配置（可选）
DEEPSEEK_API_KEY=sk-your-deepseek-key

3. 在代码中读取环境变量：

# pip install python-dotenv
from dotenv import load_dotenv
import os

# 加载.env文件
load_dotenv()

# 读取环境变量
api_key = os.getenv("OPENAI_API_KEY")
base_url = os.getenv("OPENAI_BASE_URL")
print(api_key)

注意：不要将.env放在git管理目录当中，避免数据泄露。建议将.env添加到.gitignore文件中。

4.9.2 通过Windows全局环境变量配置

适用于学习环境下，经常需要使用到的某些环境变量。

1.设置步骤：

1. 右键"此电脑" → "属性" → "高级系统设置"

2. 点击"环境变量"

3. 在"用户变量"中新建：

○ 变量名：OPENAI_API_KEY

变量值：你的API密钥

2.在代码中使用环境变量

import os
from langchain_openai import ChatOpenAI

# 从环境变量读取配置
llm = ChatOpenAI(
    model="gpt-4",
    api_key=os.getenv("OPENAI_API_KEY"),
    base_url=os.getenv("OPENAI_BASE_URL")
)

5、快速上手：第一个LangChain程序

5.1 简单的模型调用

# pip install langchain-openai
import os
from langchain_openai import ChatOpenAI

# 创建模型实例（确保已设置环境变量）
llm = ChatOpenAI(
    model="gpt-4",
    api_key=os.getenv("OPENAI_API_KEY"),
    base_url=os.getenv("OPENAI_BASE_URL", "https://api.openai.com/v1")
)

# 调用模型
response = llm.invoke("你好，请用一句话介绍Python")
print(response.content)

6、课程预览

接下来我们将深入学习以下内容：

6.1 第一部分：基础篇

|----------------|-----------|------------------------------------|
| 章节 | 内容 | 核心概念 |
| Model I/O | 如何调用各种大模型 | Models, Messages, Prompts |
| Output Parsers | 解析和验证模型输出 | StrOutputParser, JsonOutputParser |
| Prompts | 提示词工程 | PromptTemplate, ChatPromptTemplate |

6.2 第二部分：进阶篇

|--------|--------------|-----------------------------------------|
| 章节 | 内容 | 核心概念 |
| Chains | 组合多个组件形成完整流程 | LCEL (LangChain Expression Language) |
| Memory | 为对话添加记忆 | ConversationBufferMemory, SummaryMemory |
| Tools | 扩展模型能力 | 自定义工具、内置工具 |

6.3 第三部分：高级篇

|-----------|---------|----------------------------------------|
| 章节 | 内容 | 核心概念 |
| RAG | 检索增强生成 | VectorStore, Retriever, DocumentLoader |
| Agents | 构建智能代理 | ReAct, Tool Calling, AgentExecutor |
| LangGraph | 复杂工作流编排 | StateGraph, 条件边 |

6.4 学习路径建议

入门 → Model I/O → Prompts → Chains \text { 入门 } \rightarrow \text { Model I/O } \rightarrow \text { Prompts } \rightarrow \text { Chains } 入门 → Model I/O → Prompts → Chains

进阶 → M e m o r y → T o o l s → R A G \mathrm{进阶} \rightarrow \mathrm{Memory} \rightarrow \mathrm{Tools} \rightarrow \mathrm{RAG} 进阶→Memory→Tools→RAG

高级 → Agents → LangGraph → 部署

7、推荐学习资源

官方文档：https://docs.langchain.com/

LangSmith：https://www.langchain.com/langsmith（调试追踪）

GitHub仓库：https://github.com/langchain-ai/langchain

示例库：https://github.com/langchain-ai/langgraph/tree/main/examples

LangChain Academy：官方教程和课程