本地跑通微软生成式 AI 入门课：Python 版本、依赖与 .env 字段

2026-08-18

想在自己机器上跟着 generative-ai-for-beginners 走一遍，通常不是被课程内容拦住的。拦住人的是那种很土的东西：虚拟环境激活命令在 Windows 上和文档里那行不一样、装完依赖 import 还是报 ModuleNotFoundError: dotenv、.env 放错了一层目录导致 load_dotenv() 静默读不到、变量名记成了另一条 provider 路线的。

这些问题在仓库里都有白纸黑字的答案，只是分散在好几个文件里。这篇就把它们归拢：前置条件、依赖安装、.env 的位置与字段，每一条都注明出自哪个文件的哪一节。主要依据是 00-course-setup/02-setup-local.md 和 00-course-setup/03-providers.md，另外核对了根目录的 .env.copy、.gitignore、requirements.txt、.python-version 与 .devcontainer/ 下的配置文件。该课程持续更新，以仓库最新内容为准。

一、前置条件：文档写了什么，仓库里又摆着什么

00-course-setup/02-setup-local.md 开头第 1 节是一张 Prerequisites 表，四行：

工具	文档中的说明
Python	3.10 +
Git	Latest
VS Code	Optional but recommended
Docker Desktop	Only for Option B

有两点值得先说清楚。

Docker Desktop 只在选 Option B（Dev Container）时才需要。 表里那个斜体的 Only 是文档自己标的。你要是走原生 Python 路线，装 Docker 纯属给自己添活。

Python 版本这件事，仓库里有三处声明，而且它们不一样。 文档表里写的是 3.10 +；仓库根目录有一个 .python-version 文件，内容是 3.12.10；而 .devcontainer/environment.yml 里钉的是 python=3.10.0。这三处都是仓库里真实存在的内容，我们只把它们放在一起指出这个差异，并不替维护者解释原因——实际选版本时，如果你用 pyenv 一类按 .python-version 自动切换的工具，它读到的会是根目录那个文件，而不是文档表格里的下限。

文档紧接着给了一条 Tip，让你在终端里逐个确认工具是否就位：

python --version
git --version
docker --version
code --version

这四条是 02-setup-local.md 第 1 节 Tip 里原样列出的。docker --version 只有走 Option B 才需要它通过。

二、四条安装路径，先想清楚走哪一条

02-setup-local.md 里并列了四个选项（文档的小节编号有重复，都写成了「2.」，看目录时别被带偏）：Option A 原生 Python + venv、Option B VS Code Dev Container、Option C Miniconda、Option D 经典 Jupyter / JupyterLab。

Option A：venv

文档给的三步，逐字如下。第一步克隆你 fork 后的仓库：

git clone https://github.com/<your-github>/generative-ai-for-beginners
cd generative-ai-for-beginners

第二步建虚拟环境并激活：

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

这三行在文档里是写在同一个代码块里的，第二行和第三行是二选一，不是顺序执行。Windows 那行文档注明是 PowerShell 下的写法。文档还给了一条判断标志：激活后命令提示符前面应该出现 (.venv)。

顺带一提，环境目录名建议照抄 .venv——仓库 .gitignore 的 Environments 一节里列了 .env、.venv、env/、venv/、ENV/ 这几项，你要是取一个不在这份清单里的目录名，它就不在忽略范围内，有被误提交的可能。

第三步装依赖：

pip install -r requirements.txt

这里有个容易踩的坑：仓库里不止一份 requirements.txt。根目录那份包含 python-dotenv、openai、azure-ai-inference、tiktoken、numpy、pandas、matplotlib、scikit-learn、ipywidgets、tqdm 这些包名；而具体课程目录下还有自己的那一份，比如 06-text-generation-apps/python/requirements.txt 只列了 openai 和 python-dotenv 两项。这些文件里多数依赖是钉了确切版本号的，具体值请直接看仓库文件，不要照抄任何二手清单。

02-setup-local.md 的 Troubleshooting 表里，ModuleNotFoundError: dotenv 对应的处置就是「Run pip install -r requirements.txt (env wasn’t installed)」——也就是说文档把这个报错归因为依赖压根没装进当前环境，而不是包名写错了。

Option B：Dev Container

文档说明配置定义在仓库根目录 .devcontainer/ 下的 devcontainer.json，需要装 Docker Desktop 和 VS Code 的 Remote - Containers 扩展，扩展 ID 文档里给了：ms-vscode-remote.remote-containers。之后 File ▸ Open Folder 打开仓库目录，VS Code 检测到 .devcontainer/ 会弹提示，点 Reopen in Container。

devcontainer.json 里两个字段值得知道，因为它们决定了容器里依赖是怎么进来的：updateContentCommand 是 python3 -m pip install -r requirements.txt，postCreateCommand 是 bash .devcontainer/post-create.sh。而 post-create.sh 里除了再装一遍 python-dotenv 和 openai，还装了 ruff black mypy pytest，脚本注释自述这几个是为了让贡献者能在本地复现 .github/workflows/code-quality.yml 里跑的检查。脚本里还留着一行 TODO 注释，写的是没搞清楚为什么这两个包不能只靠 requirements.txt 装上——这是仓库文档自述的内容，我们不做推测。

Option C：Miniconda

文档让你自己写一份 environment.yml，并注明如果用 Codespaces 就放在 .devcontainer/ 目录下。然后：

conda env create --name ai4beg --file .devcontainer/environment.yml
conda activate ai4beg

这里同样有个仓库内的对不齐：文档正文给的 environment.yml 模板里 channels 写了 defaults 和 microsoft 两个，python=<python-version> 是占位符；但仓库里已经存在的 .devcontainer/environment.yml，name 是 dev，channels 只有 defaults，python 钉死在 3.10.0。也就是说照着上面那条 conda env create 命令直接跑，用到的是仓库里现成那份，而不是文档正文示范的那份。Troubleshooting 表里还有一条与 channel 相关的处置：「Errors using Conda」→ conda install -c microsoft azure-ai-ml。

Option D：Jupyter

最轻的一条：进到课程目录直接 jupyter notebook（文档也给了 jupyterhub 作为替代），URL 会打在命令行窗口里。文档举的例子是打开 08-building-search-applications/python/oai-solution.ipynb。

三、`.env` 放哪、字段叫什么

这是最容易出错的一段，因为仓库里有两份关于 .env 的说明，做法不同。

02-setup-local.md 第 3 节「Add Your API Keys」是这么走的：先 cd 到你项目的根目录（文档原话是 project’s root directory，也就是仓库根，不是某一课的子目录），在那里创建 .env：

touch .env

Windows 侧文档单独给了一行，标注为 cmd：

echo . > .env

然后打开这个文件，写入两行：

AZURE_INFERENCE_ENDPOINT=your_foundry_endpoint_here
AZURE_INFERENCE_CREDENTIAL=your_foundry_api_key_here

这两个字段对应的是 Microsoft Foundry Models 这条路线。文档在这一节前面挂了一条 Note：GitHub Models 及其 GITHUB_TOKEN 变量即将退役（文档写明是 2026 年 7 月底），所以这份指南改用 Microsoft Foundry Models。这一条属于文档明确标注的废弃说明，别再按老教程去配 GITHUB_TOKEN。

而 03-providers.md 的「Create .env file」一节给的是另一条路：仓库根目录本来就有一个 .env.copy 模板文件，直接复制即可。

cp .env.copy .env

.env.copy 里的字段比 02-setup-local.md 那两行多得多，按 provider 分了组：OPENAI_API_KEY；AZURE_OPENAI_API_VERSION、AZURE_OPENAI_API_KEY、AZURE_OPENAI_ENDPOINT、AZURE_OPENAI_DEPLOYMENT、AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT；AZURE_INFERENCE_ENDPOINT、AZURE_INFERENCE_CREDENTIAL、AZURE_INFERENCE_CHAT_MODEL；以及 HUGGING_FACE_API_KEY。

两处摆在一起看，结论很实际：如果你只打算跑 Foundry Models 那条线，按 02-setup-local.md 手写两行就够；如果你打算把课程里带 aoai / oai / hf 前缀的示例都试一遍，直接 cp .env.copy .env 更省事。另外要注意，03-providers.md 里那张变量释义表和根目录 .env.copy 的实际内容并非完全一一对应——AZURE_INFERENCE_CHAT_MODEL 出现在 .env.copy 文件里，但那张表里没有它。以仓库文件本身为准。

03-providers.md 还写明了一条对找文件很有用的约定：需要特定 provider 的作业，文件名里会带标签——aoai 要 Azure OpenAI 的 endpoint 与 key，oai 要 OpenAI 的，hf 要 Hugging Face token，githubmodels 要 Microsoft Foundry Models 的 endpoint 与 key。所以 06-text-generation-apps/python/ 下 oai-app.py、aoai-app.py、githubmodels-app.py 三个同名不同前缀的文件，读哪条线就打开哪个文件，配置不要混着抄。

装载环境变量这一步文档也给了代码，用的是 python-dotenv：

from dotenv import load_dotenv
import os

# Load environment variables from .env file
load_dotenv()

# Access the Microsoft Foundry Models variables
endpoint = os.getenv("AZURE_INFERENCE_ENDPOINT")
token = os.getenv("AZURE_INFERENCE_CREDENTIAL")

print(endpoint)

以上片段原样来自 00-course-setup/02-setup-local.md 第 3 节。

四、边界：文档没保证的地方

.env 的安全性只到「不进版本库」这一层。 文档最后一句是「Never commit .env—it’s already in .gitignore」，我们在仓库 .gitignore 里确认了 .env 这一行确实存在。但这只挡住 git，密钥仍然明文躺在磁盘上，也仍然会随请求发到云端。课程示例会调用云端 API 并可能上传数据，密钥与数据边界请自行评估。

Codespaces 那条路的变量名和本地不是一套。 00-course-setup/README.md 里 Codespaces 的做法是加一个名为 OPENAI_API_KEY 的 user secret，而 02-setup-local.md 主推的两个变量是 AZURE_INFERENCE_*。03-providers.md 也提到 Codespaces 可以用仓库 secrets 免掉本地 .env，但明确写了这只在用 Codespaces 时成立，用 Docker Desktop 仍然要配 .env。

模型能力的限制文档自己标了。 .env.copy 的注释里写明，gpt-5-mini 是 reasoning 模型，不支持 temperature / top_p，且用 max_output_tokens 而非 max_tokens；要试 temperature 就得在 AZURE_INFERENCE_CHAT_MODEL 里填一个支持它的部署名。这里出现的模型名只是仓库文件里的示例值，不是推荐清单。

同时开两条路会打架。 Troubleshooting 表里有一条：「VS Code keeps prompting to reopen」→ 你可能同时激活了两个选项，选一个（venv 或 container）。

.env 加载失败时的具体表现，仓库里没有找到相关说明。 文档只给了 os.getenv 的读法，而 06-text-generation-apps/python/aoai-app.py 与 githubmodels-app.py 里用的是 os.environ[...] 下标写法。这两种写法在变量缺失时行为不同，这是 Python 标准库层面的差异，不是这门课的内容，文档没有就此展开。

五、怎么确认配对了

按文档给的动作，从下往上逐层确认：

四条 --version 命令能出结果（docker --version 只有走 Option B 时才需要）；
激活虚拟环境后提示符前出现 (.venv)；
pip install -r requirements.txt 之后，import dotenv 不再报 ModuleNotFoundError；
用第 3 节那段代码 load_dotenv() 后 print(endpoint)，看打印出来的是不是你填进 .env 的那个值——如果是 None，说明 .env 没被找到或者字段名拼错了；
Windows 上如果 pip 在装某些包时报 wheel 构建失败，Troubleshooting 表给的处置是 pip install --upgrade pip setuptools wheel 之后重试；如果 python not found，处置是把 Python 加进 PATH 或者安装后重开终端。

以上命令与代码片段均原样取自仓库文档，未经实测，以仓库最新内容为准。整套流程里唯一需要你动脑的其实只有两处：选哪条安装路径，以及 .env 里填哪条 provider 路线的字段。其余都是照抄。

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

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