> ## Documentation Index > Fetch the complete documentation index at: https://www.yuan111.asia/doc/llms.txt > Use this file to discover all available pages before exploring further. # 00 · 环境准备：能跑起来，才有后面的一切 # 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）： ```powershell theme={null} 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`）注入引导脚本： ```powershell theme={null} conda init powershell # 或 bash/zsh/cmd（换名即可） # 然后必须重启终端！已开着的终端不会重新加载配置 # 重启后提示符出现 (base) = 初始化成功 ``` **重启后如何验证**：`conda init` 会在 `C:\Users\<你>\Documents\WindowsPowerShell\profile.ps1` 注入引导脚本，每次新开终端自动执行 `conda activate 'base'`。**验证方式：新开一个终端，看提示符前面有没有 `(base)`**： ```powershell theme={null} (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`。 ```yaml theme={null} # 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` 找不到才往后走。 **配置方式（二选一）**： ```powershell theme={null} # 方式 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 建环境 ```powershell theme={null} 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` 主包是"空壳"，真正干活的是各集成包。按需装，别一把梭。 ```powershell theme={null} 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） ```text theme={null} 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 theme={null} # .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。 ```powershell theme={null} 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`： ```python theme={null} 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 原对象！ ``` ```powershell theme={null} 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` 排除。 *** ## 推荐资料（延伸阅读） * [LangChain 官方文档 · 安装指南](https://docs.langchain.com/oss/python/langchain/install) —— 官方支持的安装方式与包拆分 * [LangChain 官方文档 · 快速开始](https://docs.langchain.com/oss/python/langchain/quickstart) —— 官方起步教程，第一段对话 * [智谱开放平台](https://open.bigmodel.cn/) —— 本教程使用的模型厂商，密钥与 API 文档入口 *** ## 12. 未完待续 环境好了，模型连上了。第 01 篇要回答第一个"为什么"：**我直接 requests.post 调智谱 API 不就行了，为什么要 LangChain？** → [01 · 为什么需要 LangChain](/doc/doc/enterprise-rag-course/01-为什么需要LangChain)