00 · 环境准备：能跑起来，才有后面的一切

本片目标：从零搭起能跑 LangChain 的机器——装 Miniconda、配 conda、建 learn-langchain 环境、装齐所有包、配好 .env、跑通第一段”能验证”的代码。 数据字典：.condarc 配置项、包版本一览、.env 变量、数据文件清单。

1. 上集回顾

这是第 0 篇，没有上一篇。但整个系列的逻辑必然性从这里开始：

你的目标是把 LangChain 学到能搭 RAG 对话机器人。而 LangChain 是一个生态（十几个包），不是一个大包。装错了、装少了、装到别的环境里，后面每一篇的代码都会报 ModuleNotFoundError。所以第一篇必须是”环境”——不是因为它简单，而是因为它是后面所有代码能运行的地基。

另外，你本机可能没有独立的 Python 环境、没有 conda——这些都要从零配。这套教程的所有命令都是 Windows + Miniconda + Python 3.11 实测。

2. 第一幕：装 Miniconda（三步走）

为什么要 Miniconda（而不是直接装 Python）：Python 环境就像衣柜——不分层，所有包堆一起，装什么都互相干扰。conda 能建独立环境层（learn-langchain），每层放一套依赖，互不污染。 ① 下载：别去官网（国外，下载慢），走清华源：

https://mirrors.tuna.tsinghua.edu.cn/anaconda/miniconda/
# → 找 Miniconda3-latest-Windows-x86_64.exe 下载（Windows 64 位就是它）

② 安装：一路下一步。两个关键点：

安装目录：建议装到非 C 盘（如 D:\lib\miniconda3），不占系统盘；
勾选：Add Miniconda3 to my PATH environment variable ☑ ——勾了才能在任意终端直接敲 conda（官网默认不勾，但勾了更方便，风险可接受）。

③ 验证：打开新终端，确认 conda 真的进了环境变量（PATH）：

where.exe conda
# → D:\lib\miniconda3\condabin\conda.bat       ← 能找到 = PATH 添加成功
#   D:\lib\miniconda3\Scripts\conda.exe        （可能显示 1~2 个路径，都正常）
conda --version
# → conda 26.5.3                                ← 能执行 = 命令可用
#   （版本号按你实际安装的输出为准）

安装时添加了哪些环境变量（Miniconda 安装器自动改的，主要是 PATH）：

环境变量	添加的内容	作用
`Path`（追加）	`D:\lib\miniconda3`、`D:\lib\miniconda3\Scripts`、`D:\lib\miniconda3\condabin`	让终端能直接敲 `conda`
`CONDA_EXE`	`D:\lib\miniconda3\Scripts\conda.exe`	标记 conda 主程序位置

没勾选 “Add to PATH” 怎么办：装完发现 where.exe conda 报”找不到”，不用重装——手动把上面三个路径加进用户 PATH 即可，或者装完在开始菜单用 “Anaconda Prompt (miniconda3)” 快捷方式（它自带 PATH），后续课程命令照常能跑。

3. 第二幕：conda init + 配置 .condarc

3.1 conda init（终端初始化）

装完 conda 还不能直接用 conda activate——需要让 conda 往你的终端配置（$PROFILE）注入引导脚本：

conda init powershell   # 或 bash/zsh/cmd（换名即可）
# 然后必须重启终端！已开着的终端不会重新加载配置
# 重启后提示符出现 (base) = 初始化成功

重启后如何验证：conda init 会在 C:\Users\<你>\Documents\WindowsPowerShell\profile.ps1 注入引导脚本，每次新开终端自动执行 conda activate 'base'。验证方式：新开一个终端，看提示符前面有没有 (base)：

(base) PS C:\Users\你>
# ↑ 有 (base) = conda 自动激活了 base，初始化成功

如果新终端提示符没有 (base)，但 conda activate learn-langchain 能正常切换（提示符变 (learn-langchain)），说明 conda 本身已工作——只是你的终端没有加载 conda 注入的引导脚本（profile.ps1），重新检查 conda init powershell 是否执行过、终端是否完全关闭后重新打开（不是新开标签页）。

为什么必须做：conda activate 的原理是——conda 算出要改哪些环境变量，输出一串 PowerShell 赋值语句，这串语句必须有 init 注入的引导脚本接住并执行，环境才会真的切换。

3.2 配置 .condarc（先配源和路径，再建环境）

建环境之前先配 conda——不然下载走官方源（慢），环境建到默认目录。配置文件在 C:\Users\<你>\.condarc。

# C:\Users\<你>\.condarc —— conda 全局配置（用户级）
# （本机实测原样，2026-08）
channels:
  - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main        # 清华主通道（国内快）
  - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/pro/        # 清华商业版源
  - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/r/          # R 语言包源
  - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free/       # 历史免费包归档
  - https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge/  # 社区源（conda-forge 镜像）
  - defaults                                                       # 官方兜底

show_channel_urls: true          # 装包时显示来源地址
channel_priority: strict         # 严格按 channels 顺序选源（main 有就用 main，找不到才往下找）

envs_dirs:                       # 环境装在哪（⚠️ 建环境前配好）
  - D:\lib\miniconda3\envs       #   → 以后 create 的环境全在这
pkgs_dirs:                       # 下载的包缓存装在哪
  - D:\lib\miniconda3\pkgs       #   → 包缓存就是这里

数据字典：.condarc 配置项

配置项	作用	理解
`channels`	装包时去哪下载	清华源列表（main/pro/r/free/conda-forge）= 国内快，`defaults` 兜底
`channel_priority: strict`	严格按列表顺序选源	清华源有就用清华，没有才找 defaults
`envs_dirs`	conda 环境创建到哪个文件夹	`conda create` 出来的环境全在这
`pkgs_dirs`	下载的 .conda 包缓存放哪	装过的包有缓存，重装秒开
`show_channel_urls`	装包时显示来源	排错时知道包从哪来的

为什么 6 个源：pkgs/main 是主通道（绝大多数包）；pro/、r/、free/ 是清华镜像的历史/专用通道（装极老包时能找到）；conda-forge 是社区源镜像（有些包只在 conda-forge 有）；defaults 是官方兜底。strict 模式下按列表顺序逐个找，main 找不到才往后走。

配置方式（二选一）：

# 方式 A：直接编辑文件（推荐，看得见全貌）
notepad C:\Users\<你>\.condarc
# 把上面那份 yaml 原样粘贴保存即可

# 方式 B：命令行逐条配（注意 conda config --add 是"加到列表最前"，要逆序执行才能得到上面的顺序）
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/pro/
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/r/
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free/
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge/
conda config --add channels defaults
conda config --set show_channel_urls true
conda config --set channel_priority strict
conda config --add envs_dirs D:\lib\miniconda3\envs
conda config --add pkgs_dirs D:\lib\miniconda3\pkgs

验证：conda info 看 base environment / envs directories / channel URLs 三行。

pip 源（可选）：pip 装包慢可配国内源：pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple。

4. 第三幕：创建 learn-langchain 环境 + 装包

4.1 建环境

conda create -n learn-langchain python=3.11 -y   # Python 3.11，LangChain 1.x 支持 3.9~3.13 最稳
conda activate learn-langchain                   # 激活（提示符变 (learn-langchain)）
python --version                                 # 验证 → Python 3.11.x
where.exe python                                 # 验证 → ...\envs\learn-langchain\python.exe

4.2 装包（本系列全套）

注意：langchain 主包是”空壳”，真正干活的是各集成包。按需装，别一把梭。

pip install langchain                              # 主包（自动带 langchain-core）
pip install langchain-anthropic                    # 智谱（Anthropic 协议）
pip install langchain-openai                       # DeepSeek/通义（OpenAI 协议）
pip install langchain-chroma                       # 向量库（第 08 篇）
pip install langchain-huggingface                  # 本地 embedding（第 08 篇）
pip install langchain-text-splitters               # 文本切分（第 07 篇）
pip install fastapi uvicorn                        # 服务化（第 14 篇）
pip install python-dotenv                          # 读 .env

5. 数据字典：包版本一览（本机实测，2026-08）

langchain                1.3.14      ← 主包（组装高层功能）
langchain-core           1.5.1       ← 地基（抽象基类/消息/Runnable 协议）
langchain-anthropic      1.5.3       ← 智谱（Anthropic 协议）
langchain-openai         1.4.1       ← DeepSeek/通义（OpenAI 协议）
langchain-chroma         1.1.0       ← Chroma 向量库集成
langchain-huggingface    1.2.2       ← 本地 bge embedding
langchain-text-splitters 1.1.2       ← 文本切分器
fastapi                  0.141.1     ← Web 服务（第 14 篇）
uvicorn                  0.51.0      ← ASGI 服务器（第 14 篇）
chromadb                 1.5.9       ← Chroma 底层库
sentence-transformers    5.6.1       ← embedding 模型运行依赖
python-dotenv            1.2.2       ← 读 .env
pydantic                 2.13.4      ← 数据校验（第 05 篇结构化输出核心）
httpx                    0.28.1      ← 全生态的 HTTP 客户端（第 12 篇）
torch                    2.13.0+cpu  ← embedding 模型推理依赖（CPU 版，装包时 pip 自动带）

包拆分哲学（为什么这么多包）：

langchain-core（地基：定义接口）
   ├── 所有包都依赖它 ← 看 pip show 任何包，Requires 里都有它
langchain（主包：组装高层功能，自动带 langchain-core）
langchain-anthropic（集成包：怎么连智谱/Claude）
langchain-openai（集成包：怎么连 OpenAI 协议的服务）
langchain-chroma / langchain-huggingface / langchain-text-splitters（数据集成）

为什么拆：LangChain 0.x 时代一个大包装所有东西，升级一个组件整个包跟着动。1.x 拆成”核心定义接口 + 集成包实现具体服务”。你只用智谱就只装 langchain-anthropic。

6. .env：密钥和模型配置不进代码

.env 放在项目根目录（已被 .gitignore 排除），密钥永远不进 .py 文件：

# .env
ZHIPU_API_KEY=你的智谱key
ZHIPU_BASE_URL=https://open.bigmodel.cn/api/anthropic   # ⚠️ 不能带 /v1（会自动拼 /v1/messages）
ZHIPU_MODEL=glm-4.7                                     # 备选 glm-4-flash(免费限速) / glm-4.5-air

DEEPSEEK_API_KEY=你的deepseek-key
DEEPSEEK_BASE_URL=https://api.deepseek.com              # OpenAI 协议，要自己带 /v1
DEEPSEEK_MODEL=deepseek-v4-flash                        # 带思考；deepseek-chat 无思考

数据字典：.env 变量

变量	数据类型	用途
`*_API_KEY`	`str`	鉴权密钥
`*_BASE_URL`	`str`（URL）	API 端点。关键差异：Anthropic 协议自动拼 `/v1/messages`（所以 base_url 不带 /v1）；OpenAI 协议不自动拼（要自己带 /v1）
`*_MODEL`	`str`	模型名

验证 .env 生效：python -c "from dotenv import load_dotenv; load_dotenv(); import os; print(os.environ.get('ZHIPU_MODEL'))"——能打印出 glm-4.7 就说明读到了。

7. 数据文件（RAG 的”原料”）

data/
├── 新人培训手册.md     22201 字符    ← 第 07~09 篇主用
├── 十五五就业优先.txt   7448 字，切 54 块
├── 十五五教育规划.txt   7682 字，切 62 块
└── chroma_db/          向量库目录（sqlite，3 个 collection）

8. 弃用包避坑（看到就绕道）

下表全部经本机实测验证（2026-08），langchain 主包 1.3.14 已不再包含 llms/chains/vectorstores 这些旧模块——用 0.x 写法会直接 ModuleNotFoundError。

包/写法	状态（本机实测）	替代
`langchain_community`	停更（0.4.2 最后一版，PyPI 已无新版）。本机已装 0.4.2（其他包的可选依赖带入的），但别 import 它	官方集成包 `langchain-chroma` 等
`langchain-classic`	旧链存放处（`llms/chains/vectorstores/agents/memory` 全在这）。本机已装 1.0.8	本系列用 LCEL 直接组装（09 篇）
`langchain-experimental`	实验性包，本机未装。别主动装	—
`from langchain.llms import OpenAI`	0.x 老写法，实测报 `ModuleNotFoundError`	按协议选：智谱（本系列）→ `langchain_anthropic.ChatAnthropic`；OpenAI/DeepSeek/通义 → `langchain_openai.ChatOpenAI`
`from langchain.vectorstores import ...`	0.x 老写法，实测报 `ModuleNotFoundError`	`langchain_chroma.Chroma`
`from langchain.chains import RetrievalQA`	旧链，实测报 `ModuleNotFoundError`（chains 已搬到 langchain-classic）	LCEL 管道（09 篇）
`langgraph`	⚠️ langchain 主包 1.3.14 硬依赖它（`langgraph>=1.2.5`，本机已装 1.2.10），装 `langchain` 时自动带进来。本系列不使用它的 API，但它作为依赖就在环境里，属于正常现象	本系列全部用 LCEL（09 篇）

识别方法：pip show <包> 看维护状态；import 时报 ModuleNotFoundError 的 0.x 写法直接绕道。2024 年之前的教程 90% 是旧的，看到 langchain_community/langchain.chains/from langchain.llms 别照着抄。 为什么 langgraph 装着却不用：langchain 主包把 langgraph 列为硬依赖（1.x 设计如此），所以 pip install langchain 就自动装上。但”装了”≠“必须用”——本系列刻意不用它的 API（图编排），全部用 LCEL 管道完成，少学一个框架、少踩一类坑。

9. 验证 ①：环境检查脚本

配套代码 code/00_env_check.py——打印所有关键包版本 + 数据文件 + .env 变量名（不含值），全绿就说明环境 OK。

cd enterprise-rag-course\code
python 00_env_check.py

预期输出（节选，本机实测）：

✅ langchain 1.3.14
✅ langchain-core 1.5.1
✅ langchain-anthropic 1.5.3
✅ langchain-chroma 1.1.0
✅ langchain-huggingface 1.2.2
✅ 数据文件 data/新人培训手册.md 存在 (22201 字符)
✅ .env 含 ZHIPU_API_KEY
✅ langchain_core.chat_history.InMemoryChatMessageHistory  ← 记忆 API 存活（第 06 篇用）
全部通过 ✅ 环境就绪

10. 验证 ②：第一个可运行示例（原始函数调用版，不用 `|`）

环境检查过了，但你还没”看到” LangChain 干活。这段示例刻意不用第 09 篇的 | 管道——用最原始的函数调用看清每一步：模板拼消息 → 模型返回 AIMessage → 解析器剥壳 → 历史滚雪球。全程打印完整 JSON 数据字典。 配套代码 code/00_env_setup.py：

from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
from langchain_core.messages import HumanMessage
from langchain_anthropic import ChatAnthropic
from langchain_core.output_parsers import StrOutputParser

prompt = ChatPromptTemplate.from_messages([
    ("system", "你是公司智能助手，说话简洁。"),
    MessagesPlaceholder("history"),
    ("human", "{question}"),
])
model = ChatAnthropic(model="glm-4.7", base_url="...", api_key="...", max_tokens=512)
parser = StrOutputParser()

history = []   # 历史滚雪球
for q in ["我叫小林，是后端工程师", "我叫什么名字？", "我是做什么工作的？"]:
    messages = prompt.invoke({"history": history, "question": q}).to_messages()
    ai_msg = model.invoke(messages)          # ② 模型返回 AIMessage
    answer = parser.invoke(ai_msg)           # ③ 剥壳 → 纯文本
    history.append(HumanMessage(content=q))  # ④ 追加历史
    history.append(ai_msg)                   #    直接 append 原对象！

python 00_env_setup.py

预期输出（节选，本机实测 2026-08）：

第 1 轮·给模型的输入消息列表（history 还是空的 → 只有 system + 当前问题）：
[
  { "content": "你是公司智能助手，说话简洁。", "additional_kwargs": {}, "response_metadata": {}, "type": "system", "name": null, "id": null },
  { "content": "我叫小林，是后端工程师", "additional_kwargs": {}, "response_metadata": {}, "type": "human", "name": null, "id": null }
]
第 1 轮·模型返回的 AIMessage：
{
  "content": "好的，小林。请问有什么可以帮你？",   ← 模型回答内容每次可能不同，以你实际输出为准
  "additional_kwargs": {},
  "response_metadata": { "id": "msg_xxx", "model": "glm-4.7", "stop_reason": "end_turn", "usage": {...} },
  "usage_metadata": { "input_tokens": 22, "output_tokens": 11, "total_tokens": 33 },   ← token 数随回答长度浮动
  "type": "ai", "name": null, "id": "lc_run--xxx", "tool_calls": [], "invalid_tool_calls": []
}
第 2 轮·给模型的输入消息列表（历史滚雪球了）：
[ system, {human:我叫小林...}, {ai:好的，小林...}, {human:我叫什么名字？} ]

这个示例的意义：你亲眼看到了三件事——① 输入是消息列表不是字符串；② 模型返回的是 AIMessage 对象不是字符串；③ “记忆”就是把历史消息不断 append 进列表。这三点是后面全部概念的地基。

11. 边界

没激活环境 → import langchain 直接 ModuleNotFoundError。看终端提示符是 (learn-langchain) 才算激活。
装错环境 → 没激活就 pip install，可能装进 base。先激活再装。
忘记 conda init + 重启终端 → conda activate 不生效。新终端提示符没有 (base)，conda activate 报错。重跑 conda init powershell 再完全重启终端。
安装时没勾 “Add to PATH” → where.exe conda 报”找不到”，但 conda 已装好。手动把 D:\lib\miniconda3、...\Scripts、...\condabin 加进用户 PATH（或直接用开始菜单的 Anaconda Prompt），不用重装。
load_dotenv() 找不到 .env → 它不是”只读当前目录”，而是从调用者 .py 文件所在目录逐级向上搜索 .env（实测：在 code/ 子目录跑也能读到项目根的 .env）。搜不到的场景：调用文件与 .env 不在同一棵目录树（如从 C:\Windows 跑）→ 返回 False、变量为空。稳妥做法：load_dotenv(PROJECT_ROOT / ".env") 显式传绝对路径（本系列 code/ 里都是这么写的）。
密钥写进代码 → 泄漏风险。.env 必须被 .gitignore 排除。

12. 未完待续

环境好了，模型连上了。第 01 篇要回答第一个”为什么”：我直接 requests.post 调智谱 API 不就行了，为什么要 LangChain？ → 01 · 为什么需要 LangChain

RAG 教程

小林学 LangChain

00 · 环境准备：能跑起来，才有后面的一切

00 · 环境准备：能跑起来，才有后面的一切

1. 上集回顾

2. 第一幕：装 Miniconda（三步走）

3. 第二幕：conda init + 配置 .condarc

3.1 conda init（终端初始化）

3.2 配置 .condarc（先配源和路径，再建环境）

4. 第三幕：创建 learn-langchain 环境 + 装包

4.1 建环境

4.2 装包（本系列全套）

5. 数据字典：包版本一览（本机实测，2026-08）

6. .env：密钥和模型配置不进代码

7. 数据文件（RAG 的”原料”）

8. 弃用包避坑（看到就绕道）

9. 验证 ①：环境检查脚本

10. 验证 ②：第一个可运行示例（原始函数调用版，不用 `|`）

11. 边界

推荐资料（延伸阅读）

12. 未完待续

​00 · 环境准备：能跑起来，才有后面的一切

​1. 上集回顾

​2. 第一幕：装 Miniconda（三步走）

​3. 第二幕：conda init + 配置 .condarc

​3.1 conda init（终端初始化）

​3.2 配置 .condarc（先配源和路径，再建环境）

​4. 第三幕：创建 learn-langchain 环境 + 装包

​4.1 建环境

​4.2 装包（本系列全套）

​5. 数据字典：包版本一览（本机实测，2026-08）

​6. .env：密钥和模型配置不进代码

​7. 数据文件（RAG 的”原料”）

​8. 弃用包避坑（看到就绕道）

​9. 验证 ①：环境检查脚本

​10. 验证 ②：第一个可运行示例（原始函数调用版，不用 |）

​11. 边界

​推荐资料（延伸阅读）

​12. 未完待续

00 · 环境准备：能跑起来，才有后面的一切

1. 上集回顾

2. 第一幕：装 Miniconda（三步走）

3. 第二幕：conda init + 配置 .condarc

3.1 conda init（终端初始化）

3.2 配置 .condarc（先配源和路径，再建环境）

4. 第三幕：创建 learn-langchain 环境 + 装包

4.1 建环境

4.2 装包（本系列全套）

5. 数据字典：包版本一览（本机实测，2026-08）

6. .env：密钥和模型配置不进代码

7. 数据文件（RAG 的”原料”）

8. 弃用包避坑（看到就绕道）

9. 验证 ①：环境检查脚本

10. 验证 ②：第一个可运行示例（原始函数调用版，不用 `|`）

11. 边界

推荐资料（延伸阅读）

12. 未完待续