新手入门与常见问题

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

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

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 -> 1-2 -> 1-3 -> 2 -> 3 -> 9 -> 10~21 -> 22~26`	对大模型、RAG、Agent 还没有完整认知的同学
尽快跑通第一个代码案例	第 10 章	`10 -> 11 -> 13 -> 14 -> 15 -> 17 -> 21 -> 22`	已有 Python 基础，想快速进入代码实践的同学
做项目或准备面试	第 9 章	`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 主线，再进入实战项目：

电商问数：前言

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 的「2、大模型服务平台」（含阿里云百炼平台、API-Key 管理入口表格）与「4、实战：基于阿里百炼的 HelloWorld」（含 API Key 获取、模型名、Base URL 三件套）。简要步骤如下：
1. 打开阿里云官网并登录，若没有账号需先注册。
2. 搜索「百炼」或进入「灵积模型服务」相关产品页（具体名称以阿里云当前产品为准）。
3. 开通「模型服务」或「百炼」后，在控制台里找到 API-KEY 管理，创建或复制 Key。
4. Key 一般为 sk- 开头的长字符串，复制到 .env 的 aliQwen-api 或 QWEN_API_KEY 中。

DeepSeek

用途：本仓库中 02-models_io 下的 DeepSeek 示例、以及部分使用 deepseek-api 的脚本。
申请步骤：教程中有截图与步骤，见第 10 章 - LangChain 快速上手与 HelloWorld（含「多模型共存」中 DeepSeek 的 API Key 获取与配置）。简要步骤如下：
1. 打开 DeepSeek 开放平台（或搜索「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 与模型接入的「3.1 使用 OpenAI 兼容接口」与「3.3 接入通义千问（阿里云百炼）」。
OpenAI 官方：需在 OpenAI 平台注册并创建 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 模型库当前页面为准。

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

5.5 Black 格式化

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

bash

black --check .
black .

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

6、遇到问题时怎么提问

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

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

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

text

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

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

7、常用入口

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

8、本项目使用的 Docsify 扩展

本仓库的在线阅读站点基于 Docsify 生成，并使用了以下扩展以提升阅读与检索体验：

扩展 / 配置	作用
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`，便于搜索引擎收录在线文档

微调示例：阅读、比较与复算

prompt-comparison

thinking-control

新手入门与常见问题 ​

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

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

2.1 先按目标选路线 ​

2.2 零基础系统入门 ​

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

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

2.5 按时间预算学习 ​

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

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

3.1 Python 版本 ​

3.2 创建虚拟环境 ​

3.3 安装依赖 ​

4、配置 API Key 与 .env ​

4.1 复制 .env-example ​

4.2 常见环境变量 ​

4.3 API Key 去哪里申请 ​

通义千问 / 阿里云百炼 ​

DeepSeek ​

OpenAI 兼容接口 ​

5、常见问题速查 ​

5.1 依赖相关 ​

5.2 API Key 与 .env ​

5.3 运行目录与编码 ​

5.4 Ollama 示例 ​

5.5 Black 格式化 ​

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

7、常用入口 ​

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

新手入门与常见问题

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

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

2.1 先按目标选路线

2.2 零基础系统入门

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

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

2.5 按时间预算学习

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

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

3.1 Python 版本

3.2 创建虚拟环境

3.3 安装依赖

4、配置 API Key 与 .env

4.1 复制 .env-example

4.2 常见环境变量

4.3 API Key 去哪里申请

通义千问 / 阿里云百炼

DeepSeek

OpenAI 兼容接口

5、常见问题速查

5.1 依赖相关

5.2 API Key 与 .env

5.3 运行目录与编码

5.4 Ollama 示例

5.5 Black 格式化

6、遇到问题时怎么提问

7、常用入口

8、本项目使用的 Docsify 扩展