微软生成式 AI 入门课的 notebook 跑不起来：内核、依赖、环境三层排查

2026-08-18

打开 generative-ai-for-beginners 的某个 .ipynb，点运行，第一个单元就红了——ModuleNotFoundError，或者内核连不上、选择内核的下拉框里一个能用的都没有。这类问题的麻烦之处在于报错信息指向的是”缺包”，但真正的原因常常在另外两层：内核选到了别的解释器，或者你 pip install 的那个 Python 和内核跑的那个 Python 压根不是同一个。

排查顺序建议固定成三层：先看依赖清单装的是哪一份，再看内核选的是谁，最后看虚拟环境和内核有没有绑上。顺序反了会很浪费时间——你在错误的解释器里反复重装包，装一百遍也没用。

第一层：这个仓库的依赖清单不止一份

最容易踩的第一个坑：仓库根目录有 requirements.txt，但它不是唯一一份。

00-course-setup/02-setup-local.md 的 Option A 第三步写的是：

pip install -r requirements.txt

.devcontainer/devcontainer.json 里的 updateContentCommand 也是 python3 -m pip install -r requirements.txt，指的都是根目录那一份。但仓库里同时还存在按课时放置的清单，路径分别是 06-text-generation-apps/python/requirements.txt、08-building-search-applications/python/requirements.txt、08-building-search-applications/scripts/requirements.txt，以及 09-building-image-applications/requirements.txt——注意最后这一份不在 python/ 子目录下，跟前面几课的摆放习惯不一样，按目录规律去找会找不到。

除此之外还有三处会影响你环境里到底装了什么：pyproject.toml 的 [project] dependencies、.devcontainer/environment.yml（Conda 路线用的），以及 .devcontainer/post-create.sh。最后这个脚本值得单独看一眼，它在容器创建后又用 pip install 补装了 python-dotenv 与 openai，脚本里自己留了一行注释 # TODO: Check why this can't be done in requirements.txt——脚本本身就在问这几个包为什么不能放进 requirements.txt，至于原因，仓库里没有找到相关说明。

怎么确认是这一层的问题：看报错缺的是哪个模块，然后去你打开的那一课的目录里找有没有 requirements.txt，再和根目录那份对一下。这里有一个具体的、很容易撞上的例子：06-text-generation-apps/python/requirements.txt 里只有 openai 和 python-dotenv 两项，而同目录下的 06-text-generation-apps/python/githubmodels-assignment.ipynb 第一个代码单元导入的是 from azure.ai.inference import ChatCompletionsClient。azure-ai-inference 这个包在根目录 requirements.txt、pyproject.toml 和 .devcontainer/environment.yml 里都有，唯独不在这一课自己的清单里。如果你图省事只装了课时级的那份，这个 notebook 的第一个单元就会缺包。

类似的还有 15-rag-and-vector-databases/notebook-rag-vector-databases.ipynb：它用到的 azure-cosmos 不在任何一份 requirements.txt 里，而是写在 notebook 自己的单元格里；同一个 notebook 里两个安装单元的写法还不一样，一个是 !pip install openai，另一个是不带感叹号的 pip install azure-cosmos。

处置：优先装根目录那一份，缺什么再按课时目录补。

处置后怎么验证：重新运行报错的那个单元。仓库 00-course-setup/02-setup-local.md 的 Troubleshooting 表里对 ModuleNotFoundError: dotenv 给出的处置就是 pip install -r requirements.txt，并在括号里注明原因是环境没装上（env wasn’t installed）。

顺带说一处不一致，值得你装之前先知道：根 requirements.txt 把 pandas 钉死在一个具体版本上，而 08-building-search-applications/python/requirements.txt 要的是低于那个主版本的区间——这两条约束装不进同一个环境。openai 也一样：根目录要的是 1.x 那一代，08 课那份把它限制在 0.28 那一代的区间里，可同目录下的 08-building-search-applications/python/oai-solution.ipynb 用的却是 from openai import OpenAI 再 client = OpenAI(api_key=API_KEY) 这种 1.x 客户端写法——清单和它自己那份 notebook 的代码就对不上。具体的版本写法以仓库最新内容为准，这里要说的只是机制：把课时级清单直接装进同一个 venv，可能会把另一课需要的版本顶掉，而症状看上去仍然是「缺包」或导入报错。

什么情况说明不是这一层：如果你在终端里直接 python -c "import dotenv" 是通的，只有 notebook 里报缺包，那包其实装上了，问题在下面两层。

第二层：内核选到了谁

.ipynb 文件的 metadata.kernelspec 里存着上一个提交者用的内核，这个字段会跟着文件一起进版本库。这个仓库里各课的这个字段并不统一，你可以自己打开文件看：06-text-generation-apps/python/oai-assigment.ipynb 的 display_name 是 venv，07-building-chat-applications/python/oai-assignment.ipynb 是 base，04-prompt-engineering-fundamentals/python/githubmodels-assignment.ipynb 是 ai4beg（和 00-course-setup/02-setup-local.md 里 conda activate ai4beg 那个环境同名），19-slm/python/phi35-instruct-demo.ipynb 的 display_name 是 Python 3.8 - AzureML、name 是 python38-azureml——最后这个名字来自另一套托管环境，你在本机自己建的 venv 不会注册出同名内核。

还有两个更极端的：04-prompt-engineering-fundamentals/python/oai-assignment.ipynb 整个 kernelspec 字段都不存在；而 19-slm/python/Phi-3-Vision-Nividia-NIM.ipynb 的 kernelspec 写的是 .net-csharp、language 是 C#，但它的第一个代码单元是 import requests, base64，是 Python 代码。这个文件在 python/ 目录下、内容是 Python、元数据却标着 C# 内核。

怎么确认是这一层：报错不是缺包而是语法层面的怪异（比如 Python 代码被当成别的语言解析），或者编辑器一直提示”选择内核”、内核反复重连，就先去看这个字段。判定动作很直接：用文本编辑器打开 .ipynb，搜 kernelspec，看 display_name 和 language 写的是什么；跟你本机实际装了哪些内核对一下。

处置：00-course-setup/README.md 的 Troubleshooting 表里给的是——症状”Notebook kernel missing”，处置”Notebook menu ➜ Kernel ▸ Select Kernel ▸ Python 3”。04-prompt-engineering-fundamentals/README.md 的作业段落说得更具体一点：选择运行时内核，如果用的是前两种方式（Codespaces 或 Dev Container），直接选 dev container 提供的默认 Python 内核即可。换句话说，文件里存着的那个名字不必理会，你手动重选一次就好。

验证：重选之后运行一个最短的单元，比如 04 那课作业里的 import tiktoken，能过就说明内核这一层通了。

什么情况说明不是这一层：如果内核已经连上、也确实是 Python，报的仍然是 ModuleNotFoundError，那说明选中的解释器不是你装包的那个——进入第三层。

第三层：venv 和内核有没有绑上

00-course-setup/02-setup-local.md 的 Option A 第二步给的是这三行：

python -m venv .venv          # make one
source .venv/bin/activate     # macOS / Linux
.\.venv\Scripts\activate      # Windows PowerShell

Windows 侧就是第三行那个 .\.venv\Scripts\activate，路径分隔和脚本目录名都和 Linux/macOS 不同，别把 source 那行照抄到 PowerShell 里。文档紧跟着给了一个判定标志：命令行提示符前面出现 (.venv)，说明你已经在这个环境里了。

这一层的现象：pip install -r requirements.txt 明明成功了，notebook 里还是缺包。原因是激活 venv 只影响当前这个终端，notebook 的内核是另一个进程，它跑的是哪个解释器由内核注册信息决定，不由你终端里的激活状态决定。

判定动作（这是通用排查做法，不是仓库文档里的内容）：在 notebook 里新建一个单元，打印 sys.executable，看它指向的路径是不是你那个 .venv 下的 Python；再回终端里对一下激活后的解释器路径。两个路径不同，问题就锁定了。

处置：这里有个仓库自身的细节值得注意——在仓库的几份依赖清单里，ipykernel 只出现在 08-building-search-applications/python/requirements.txt 一处，根目录 requirements.txt、pyproject.toml 和 .devcontainer/environment.yml 里都没有它。也就是说，如果你只装根目录那份并且走的是自建 venv 路线，这个环境里未必有能把自己注册成内核的组件。仓库文档没有给出把 venv 注册为内核的命令，这一点仓库里没有找到相关说明；文档给的替代路线是 Option D，直接在课程目录下起 Jupyter：

jupyter notebook

从已激活 venv 的终端里启动，进程继承的就是这个环境。文档说明启动后访问命令行里给出的 URL，就能打开任意 *.ipynb。

Windows 侧还有一条：00-course-setup/02-setup-local.md 的 Troubleshooting 表里专门列了 Windows 上 pip 编译 wheel 失败的处置——pip install --upgrade pip setuptools wheel 之后重试。这是仓库原文给的命令，遇到装包中途失败先试它，别急着换 Python 版本。

还有一个环境互相打架的情况：同一张表里有一行症状是 VS Code 反复提示重新打开（reopen），处置写的是你可能同时开着两种方式，二选一——要么 venv，要么容器。两套环境并存时，你以为在给 venv 装包，实际内核跑在容器里，现象和上面完全一样。

验证：重新选内核之后再打印一次 sys.executable，路径落在 .venv 里，再跑一次导入单元。

什么情况说明不是这一层：如果 sys.executable 指的就是你装包的那个解释器，导入也过了，只是调用模型时才报错——那已经不是环境问题了，往下看。

排除这三层之后：剩下的错不归环境管

这几种报错看起来也像”跑不起来”，但改环境没有用：

认证类。00-course-setup/02-setup-local.md 的 Troubleshooting 表里列了 OpenAI 的 401 / 429，处置是检查 OPENAI_API_KEY 的值和请求速率。这类错说明包已经装好、请求已经发出去了。

环境变量没配。仓库根目录有 .env.copy，00-course-setup/03-providers.md 让你把它复制成 .env 再填值。要注意选对路线：同一课常有 oai-（OpenAI）、aoai-（Azure OpenAI）、githubmodels- 三个版本的文件，打开哪个就得配哪一组变量。

这里必须提醒一句：githubmodels- 这个前缀现在已经名不副实。仓库多处逐字写明 GitHub Models（连同它的 GITHUB_TOKEN 变量）于 2026 年 7 月底退役，直接替代者是 Microsoft Foundry Models——00-course-setup/02-setup-local.md、00-course-setup/03-providers.md、00-course-setup/README.md、.env.copy 里都写了这条说明。文件名保留了旧前缀，但 06-text-generation-apps/python/githubmodels-app.py 的注释已经改成让你去 Microsoft Foundry 项目的 Overview 页面取值，代码读的变量是 AZURE_INFERENCE_CREDENTIAL 和 AZURE_INFERENCE_ENDPOINT。所以看到 githubmodels- 别去找 GitHub token，实际要配的是 Foundry 的 endpoint 和 key。

参数不被支持。06-text-generation-apps/README.md 写明：Microsoft Foundry 上当前未废弃的是 reasoning 模型（GPT-5 家族、o 系列），它们不支持 temperature 和 top_p，也不支持 max_tokens（改用 max_output_tokens）；给 gpt-5-mini 传 temperature 会收到参数不支持的错误。.env.copy 里也留了同样的注释，并给出 AZURE_INFERENCE_CHAT_MODEL 让你指向一个支持采样参数的非 reasoning 模型。这类报错和内核、依赖、虚拟环境都无关，重装多少遍都不会好。

最后提醒一句：本文提到的路径、清单内容和内核元数据都是仓库当前的状态，课程持续更新，请以仓库最新内容为准。涉及密钥的地方一律用占位写法，.env 不要提交。

本文依据 github.com/microsoft/generative-ai-for-beginners 仓库于 2026-08-18 的公开内容整理，事实来自仓库内的课程正文与代码示例。我们没有跑过文中涉及的代码，因此不涉及运行结果、耗时与生成质量的任何描述。该课程持续更新，文中涉及的文件路径、依赖与接口写法随版本变动，请以仓库最新内容为准。文中涉及的云端服务调用会产生费用并可能上传数据，请自行评估密钥与数据边界。

安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。