# 新手入门与常见问题

这份文档是本仓库的新手入口。它不只是告诉你怎么 `pip install`，更重要的是帮你先搞清楚：这个仓库有哪些内容、应该从哪里开始、哪些案例能直接跑、哪些项目需要切到配套源码仓库，以及遇到报错时该按什么顺序排查。

如果你第一次接触 AI 智能体开发，建议先阅读本文，完整章节结构见 [教程目录大纲](教程目录大纲.md)。

---

## 1、项目是什么？我能做什么？

本仓库是 **《AI 智能体实战速成指南：从零到企业级落地》** 的教程主仓，目标是做一套由浅入深、通俗易懂、能跑代码、能做项目、能复盘面试的 Python 智能体学习资料。

它现在主要包含五类内容：

| 内容                           | 位置                                                                                                                            | 什么时候看                                             |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| 系统教程正文                   | 根目录下的 `1-1` 到 `26` 章 Markdown 文档                                                                                       | 想系统学习大模型、RAG、Agent、LangChain / LangGraph 时 |
| Coze / Dify 工作流案例         | `案例与源码-1-Coze&Dify工作流智能体/`                                                                                           | 想先用低代码平台做出可演示应用时                       |
| LangChain / LangGraph 代码案例 | `案例与源码-2-LangChain框架/`、`案例与源码-3-LangGraph框架/`                                                                    | 想在本仓库里直接运行 Python 小案例时                   |
| 企业级实战项目教程             | `实战项目-电商问数/`、`实战项目-深度研搜/`                                                                                      | 想把零散知识点串成完整项目时                           |
| 导航、术语、面试与资料         | `教程目录大纲.md`、`章节索引与跳转指南.md`、`全书术语表.md`、`AI智能体与大模型应用开发面试题库.md`、`工具导航与参考资料索引.md` | 查漏补缺、复盘表达、准备面试时                         |

---

## 2、第一次学习，推荐怎么走

### 2.1 先按目标选路线

| 你的目标               | 推荐起点                                        | 推荐主线                                             | 适合人群                                   |
| ---------------------- | ----------------------------------------------- | ---------------------------------------------------- | ------------------------------------------ |
| 零基础系统入门         | [第 1-1 章](1-1-大模型认知与工程概览.md)        | `1-1 -> 1-2 -> 1-3 -> 2 -> 3 -> 9 -> 10~21 -> 22~26` | 对大模型、RAG、Agent 还没有完整认知的同学  |
| 尽快跑通第一个代码案例 | [第 10 章](10-LangChain快速上手与HelloWorld.md) | `10 -> 11 -> 13 -> 14 -> 15 -> 17 -> 21 -> 22`       | 已有 Python 基础，想快速进入代码实践的同学 |
| 做项目或准备面试       | [第 9 章](9-LangChain概述与架构.md)             | `9~26 -> 电商问数 -> 深度研搜 -> 面试题库`           | 需要“原理 + 实操 + 项目表达”一起建立的同学 |

### 2.2 零基础系统入门

如果你还分不清大模型、提示词、RAG、Agent、LangChain、LangGraph，建议按下面顺序：

```text
1-1 大模型认知
-> 1-2 提示词工程
-> 1-3 RAG、微调、续训与智能体选型
-> 2 RAG 知识库入门
-> 3 Coze / Dify 平台体验
-> 9 LangChain 概述
-> 10~21 LangChain 主线
-> 22~26 LangGraph 主线
```

这个路线的重点不是一上来写复杂代码，而是先建立认知地图：知道每个技术名词解决什么问题，后面跑案例才不会像在背 API。

### 2.3 已有 Python 基础，想尽快跑代码

适合已经会基本 Python，希望尽快进入框架实践的同学。

```text
9 LangChain 概述
-> 10 HelloWorld
-> 11 Model I/O
-> 13 Prompt
-> 14 Parser
-> 15 LCEL
-> 17 Tools
-> 19 RAG
-> 21 Agent
-> 22 LangGraph
```

对应源码主要在：

```text
案例与源码-2-LangChain框架/
案例与源码-3-LangGraph框架/
```

### 2.4 想做一个能写进简历的项目

建议先跑完 LangChain / LangGraph 主线，再进入实战项目：

- [电商问数：前言](实战项目-电商问数/0-前言.md)

### 2.5 按时间预算学习

如果时间比较紧，可以先按下面节奏安排：

| 时间             | 建议学法                                                                                  |
| ---------------- | ----------------------------------------------------------------------------------------- |
| 7 天速通         | `1-1 -> 1-2 -> 9 -> 10 -> 11 -> 13 -> 14 -> 15 -> 17 -> 21 -> 22`，重点是跑通最小代码闭环 |
| 15 天系统入门    | 前 3 天学基础认知，2 天体验 Coze / Dify，6 天吃透 LangChain 主线，最后 3 天进入 LangGraph |
| 90 天项目 / 求职 | 第一周打基础，第二周跑 LangChain / RAG / Agent，第三周学 LangGraph、实战项目和面试题      |

不管选哪条路线，最重要的动作都一样：**每学完一章，至少跑一个案例；每学完一个阶段，用自己的话复述一次。**

### 2.6 什么时候可以进入下一阶段

| 当前阶段       | 进入下一阶段前，至少做到什么                                        |
| -------------- | ------------------------------------------------------------------- |
| 基础认知       | 能区分 Prompt、RAG、Agent、微调，不再把它们混成一个词               |
| 低代码平台     | 能独立搭一个简单 Coze / Dify 工作流，并知道平台拖拽和代码开发的边界 |
| LangChain 主线 | 能写出 `prompt -> model -> parser`，并接一个 Tool 或简单 RAG        |
| Agent 阶段     | 能解释“固定流程”和“模型自主决策”的区别，知道什么时候该用 Agent      |
| LangGraph 阶段 | 能把一个任务拆成 State、Node、Edge，而不是只写线性脚本              |
| 多智能体阶段   | 能判断什么时候值得拆多个 Agent，什么时候保持单 Agent 更稳           |

---

## 3、环境准备：运行本仓库案例

### 3.1 Python 版本

根目录的 `requirements.txt` 和 `pyproject.toml` 已经约束了 Python 版本：

| 项目     | 说明                       |
| -------- | -------------------------- |
| 推荐版本 | Python 3.10                |
| 支持范围 | Python 3.10 到 Python 3.13 |
| 暂不支持 | Python 3.14                |

原因是根目录案例依赖了 `langchain-redis` 等包，这些依赖暂时还没有完整兼容 Python 3.14。

先检查本机版本：

```bash
python3 --version
```

如果电脑里有多个 Python，建议显式使用 `python3.10`。

### 3.2 创建虚拟环境

在项目根目录执行，也就是能看到 `README.md`、`requirements.txt`、`.env-example` 的那一层，打开终端，执行：

macOS / Linux：

```bash
# 创建虚拟环境（会多出一个 .venv 文件夹）；推荐使用 Python 3.10
python3.10 -m venv .venv
# 激活虚拟环境
# Windows（CMD）：
.venv\Scripts\activate
# Windows（PowerShell）：
.venv\Scripts\Activate.ps1
# macOS / Linux：
source .venv/bin/activate
```

激活成功后，终端前面通常会出现 `(.venv)`。

### 3.3 安装依赖

仍在**项目根目录**且虚拟环境已激活时执行：

```bash
pip install -r requirements.txt
```

如果网络较慢，可以换国内清华源镜像：

```bash
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
```

`requirements.txt` 覆盖的是根目录普通案例的主要依赖。电商问数等实战项目有自己的环境说明，见本文第 6 节。

---

## 4、配置 API Key 与 .env

### 4.1 复制 .env-example

在项目根目录执行：

```bash
cp .env-example .env
```

Windows 用户也可以直接手动复制 `.env-example`，然后重命名为 `.env`。

打开 `.env` 后，把占位 Key 改成真实 Key。真实 API Key 不要提交到 Git，本仓库已经通过 `.gitignore` 忽略 `.env`。

### 4.2 常见环境变量

不同章节读取的变量名不完全一样。常见变量如下：

| 变量名         | 用途                                                       |
| -------------- | ---------------------------------------------------------- |
| `QWEN_API_KEY` | 早期 HelloWorld 示例中调用通义千问                         |
| `aliQwen-api`  | 多数 LangChain / LangGraph 示例中调用阿里云百炼 / 通义千问 |
| `deepseek-api` | DeepSeek 相关示例                                          |

一个相对完整的 `.env` 示例：

```env
QWEN_API_KEY='sk-你的通义千问Key'
aliQwen-api='sk-你的阿里云百炼Key'
deepseek-api='sk-你的DeepSeekKey'

# 天气工具示例
OPENWEATHER_API_KEY='你的OpenWeatherKey'
```

这里最容易出错的是变量名。`aliQwen-api`、`deepseek-api`、`tavily_api_key` 要和代码里的 `os.getenv("...")` 完全一致，大小写、横线和下划线都要对上。

> **注意：** 上表里的变量名是本仓库代码约定，不是各厂商官方强制要求的环境变量名。官方平台通常只要求你拥有有效 API Key；放到 `.env` 里时，变量名必须和本地示例代码读取的名字一致。

### 4.3 API Key 去哪里申请

下面按「平台」说明如何拿到 API Key，用于填充 `.env`。

#### 通义千问 / 阿里云百炼

- **用途**：本仓库大量案例使用 `aliQwen-api` 或 `QWEN_API_KEY` 调用通义千问。
- **申请步骤**：教程中有图文说明，可直接查看 [第 10 章 - LangChain 快速上手与 HelloWorld](10-LangChain快速上手与HelloWorld.md) 的「**2、大模型服务平台**」（含阿里云百炼平台、API-Key 管理入口表格）与「**4、实战：基于阿里百炼的 HelloWorld**」（含 API Key 获取、模型名、Base URL 三件套）。简要步骤如下：
  1. 打开 [阿里云官网](https://www.aliyun.com/) 并登录，若没有账号需先注册。
  2. 搜索「**百炼**」或进入「**灵积模型服务**」相关产品页（具体名称以阿里云当前产品为准）。
  3. 开通「模型服务」或「百炼」后，在控制台里找到 **API-KEY** 管理，创建或复制 Key。
  4. Key 一般为 `sk-` 开头的长字符串，复制到 `.env` 的 `aliQwen-api` 或 `QWEN_API_KEY` 中。

#### DeepSeek

- **用途**：本仓库中 `02-models_io` 下的 DeepSeek 示例、以及部分使用 `deepseek-api` 的脚本。
- **申请步骤**：教程中有截图与步骤，见 [第 10 章 - LangChain 快速上手与 HelloWorld](10-LangChain快速上手与HelloWorld.md)（含「多模型共存」中 DeepSeek 的 API Key 获取与配置）。简要步骤如下：
  1. 打开 [DeepSeek 开放平台](https://platform.deepseek.com/)（或搜索「DeepSeek API」）。
  2. 注册/登录后，在控制台或「API Key」页面创建 Key。
  3. 将 Key（一般为 `sk-` 开头）填入 `.env` 的 `deepseek-api`。

#### OpenAI 兼容接口

- 若案例中使用的是 `openai` 库 + `base_url` 方式（例如接 DeepSeek、国内兼容 OpenAI 的厂商），通常只需在 `.env` 里配置对应厂商的 Key 和文档中的 `base_url` 即可。**接入方式与参数说明**见 [第 11 章 - Model I/O 与模型接入](11-Model-I-O与模型接入.md) 的「3.1 使用 OpenAI 兼容接口」与「3.3 接入通义千问（阿里云百炼）」。
- **OpenAI 官方**：需在 [OpenAI 平台](https://platform.openai.com/) 注册并创建 API Key，且需能访问其服务（部分地区可能需代理）。

---

## 5、常见问题速查

### 5.1 依赖相关

| 问题                                         | 常见原因                     | 处理办法                                                                  |
| -------------------------------------------- | ---------------------------- | ------------------------------------------------------------------------- |
| `ModuleNotFoundError: No module named 'xxx'` | 没装依赖，或没有激活 `.venv` | 激活虚拟环境后，在项目根目录执行 `pip install -r requirements.txt`        |
| 安装时报 `requires-python <3.14`             | Python 版本过高              | 根目录普通案例换成 Python 3.10~3.13，推荐 3.10                            |
| RAG、Memory、Redis 示例跑不通                | 依赖外部服务或系统包         | 先跑 HelloWorld，再按对应章节准备 Redis、Redis Stack、PDF / Word 解析依赖 |

检查当前 Python：

macOS / Linux：

```bash
python --version
which python
pip show langchain
```

Windows：

```bat
python --version
where python
pip show langchain
```

### 5.2 API Key 与 .env

| 问题                   | 常见原因                                  | 处理办法                                    |
| ---------------------- | ----------------------------------------- | ------------------------------------------- |
| 401、403、API Key 无效 | Key 填错、平台额度不足、服务未开通        | 回平台控制台检查 Key、额度和模型服务状态    |
| `os.getenv()` 读到空值 | `.env` 不存在、运行目录不对、变量名不一致 | 确认根目录有 `.env`，并在项目根目录运行脚本 |

排查 `.env` 时，不要把真实 Key 发到 Issue、聊天窗口或截图里。只需要说明你配置了哪些变量名即可。

### 5.3 运行目录与编码

| 问题                            | 常见原因               | 处理办法                                                        |
| ------------------------------- | ---------------------- | --------------------------------------------------------------- |
| 找不到 `.env`                   | 在案例子目录里运行脚本 | 回项目根目录执行 `python 案例与源码-2-LangChain框架/.../xxx.py` |
| `UnicodeDecodeError` 或中文乱码 | 文件不是 UTF-8 编码    | 用 VS Code / Cursor 把 `.env`、`.py` 保存为 UTF-8               |
| 相对路径找不到文件              | 当前工作目录不对       | 优先在项目根目录运行案例                                        |

### 5.4 Ollama 示例

Ollama 不需要云 API Key，但需要本机安装并启动 Ollama，还要提前拉取模型。

```bash
ollama --version
ollama list
ollama run qwen:4b
```

`qwen:4b` 是本仓库入门示例使用的轻量模型 tag。Ollama 模型和 tag 会持续更新，实际可用名称请以 [Ollama 模型库](https://ollama.com/search) 当前页面为准。

确认模型能在命令行里正常运行后，再跑 `03-ollama` 目录下的 LangChain 示例。

### 5.5 Black 格式化

本仓库用 Black 统一 Python 代码风格。

```bash
black --check .
black .
```

如果你使用 VS Code / Cursor，可以安装 Microsoft 的 `Black Formatter` 扩展，并开启保存时自动格式化。

---

## 6、遇到问题时怎么提问

如果你卡住了，可以按下面顺序自己先排查一遍：

1. 当前目录是不是项目根目录。
2. 虚拟环境是否已经激活。
3. Python 是否在 3.10 到 3.13 之间。
4. 是否执行过 `pip install -r requirements.txt`。
5. 根目录是否有 `.env`。
6. `.env` 变量名是否和代码一致。
7. 这个案例是否依赖 Redis、Ollama、Docker、Qdrant、Elasticsearch 等外部服务。
8. 是否把根目录普通案例、电商问数等实战项目的环境混在了一起。

如果仍然解决不了，提 Issue 时尽量带上这些信息：

```text
1. 你运行的命令
2. 完整报错信息
3. Python 版本
4. 操作系统
5. 你运行的是哪个章节或哪个脚本
6. 是否配置了 .env，以及配置了哪些变量名（不要贴真实 Key）
```

这样别人不用猜你的环境，也更容易帮你定位问题。

---

## 7、常用入口

- 完整章节导航：[教程目录大纲](教程目录大纲.md)
- 术语随查：[全书术语表](全书术语表.md)
- 案例汇总：[教程案例链接汇总](教程案例链接汇总.md)
- 工具与资料：[工具导航与参考资料索引](工具导航与参考资料索引.md)
- 面试复盘：[AI 智能体与大模型应用开发面试题库](AI智能体与大模型应用开发面试题库.md)
- 实战项目：[电商问数](实战项目-电商问数/0-前言.md)

---

## 8、本项目使用的 Docsify 扩展

本仓库的**在线阅读站点**基于 [Docsify](https://docsify.js.org/) 生成，并使用了以下扩展以提升阅读与检索体验：

| 扩展 / 配置                       | 作用                                                                      |
| --------------------------------- | ------------------------------------------------------------------------- |
| **Docsify 4 + Vue 主题**          | 文档框架与默认样式，负责把 Markdown 文件渲染成在线文档站点                |
| **docsify-darklight-theme**       | 提供白天 / 夜间模式切换                                                   |
| **侧边栏导航**                    | 通过 `_sidebar.md` 组织章节目录，页面内标题最多展示到四级标题             |
| **全文搜索**（search）            | 顶部搜索框，支持按关键词检索文档内容，当前搜索深度配置为 6                |
| **zoom-image**                    | 正文中的图片可点击放大查看，适合查看截图、架构图和流程图                  |
| **docsify-copy-code**             | 代码块右侧提供「复制」按钮，方便直接复制示例代码和命令                    |
| **docsify-pagination**            | 页面底部提供「上一页 / 下一页」跨章节导航                                 |
| **docsify-count**                 | 每页底部显示当前页字数，已按中文统计配置                                  |
| **KaTeX + docsify-katex**         | 数学公式渲染，支持 Markdown 中的行内公式 `$...$` 和块级公式 `$$...$$`     |
| **Prism + prism-python**          | 代码语法高亮，当前额外加载了 Python 语法高亮组件                          |
| **Mermaid**                       | 渲染语言标识为 `mermaid` 的代码块，用于流程图、架构图、时序图等可视化内容 |
| **docsify-giscus**                | 基于 GitHub Discussions 的评论区，每页底部可以承载读者讨论                |
| **Google Analytics / gtag**       | 站点访问统计，用于观察页面访问情况                                        |
| **docsify-sitemap / sitemap.xml** | 生成并维护 `sitemap.xml`，便于搜索引擎收录在线文档                        |