generative-ai-for-beginners 环境搭建完全指南Fork、Codespaces 与本地跑通第一课【免费下载链接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners本指南以仓库课程初始化章节对应translations/en/00-course-setup/README.md仓库根目录的原文见 00-course-setup/README.md为核心系统讲解如何从零准备一个可运行 21 课 Generative AI 动手项目的开发环境。你将掌握 Fork 仓库、创建 GitHub Codespaces、安全托管 API Key、配置.env并能在云上或本机原生 Python、Conda、VS Code Dev Container、Jupyter任一形态中运行课程代码最终安全高效地进入 第 1 课生成式 AI 与 LLM 入门。一、课程环境概览与整体路线这个仓库是一个开源课程项目关于课程规模与定位可在仓库根目录的 pyproject.toml 与课程说明中确认学习过程会涉及大量需要调用云端模型接口的 Notebook 与脚本例如基于 OpenAI / Azure OpenAI / Hugging Face 的作业。为了让你“零折腾”地聚焦学习本身官方给出了完整的环境准备路线我要做什么前往哪个文档直接开始第 1 课01-introduction-to-genai离线、在自有电脑上运行00-course-setup/02-setup-local.md配置一个 LLM ProviderOpenAI / Azure / Hugging Face / Foundry Models 等00-course-setup/03-providers.md不想安装任何东西、云端一键开跑00-course-setup/01-setup-cloud.md仓库还提供了整套共享工具代码用于环境变量的安全读取shared/python/env_utils.py与 OpenAI/Azure 客户端的创建shared/python/api_utils.py后文会结合这些源码说明“配置变量 → 被代码消费”的完整链路。二、第一步Fork 本仓库获得可写副本课程要求你动手修改代码、完成挑战因此需要把仓库 Fork 到自己的账号下。具体操作打开仓库主页点击右上角Fork把整个仓库复制到你自己的账号中得到可自由修改的副本可选但推荐顺手给仓库点一个Star方便日后在“你 Star 过的仓库”里快速找回本仓库及其关联项目。Fork 完成后你既可以把它作为云端 Codespace 的基底也可以本地git clone你自己的副本。三、第二步创建 Codespace让环境“预装好”为避免依赖安装带来的各类兼容性问题官方推荐在GitHub Codespaces中运行本课程。在 GitHub 的云端开发环境中仓库已通过预构建的开发容器帮你装好 Python、Node.js、.NET、Java 等运行时首次启动大约需要几分钟构建容器。在你自己的 Fork 副本中依次点击Code → Codespaces → New on main即基于main分支新建一个 codespace浏览器就会打开一个云端的 VS Code 窗口并开始构建开发容器。关于云端方案的更多细节个人免费配额、停止/删除空闲 codespace 以节约配额的提示等见 00-course-setup/01-setup-cloud.md。3.1 用 Codespaces Secrets 安全保存密钥推荐把 API Key 直接写进代码库是危险的。Codespaces 提供了“Secrets”机制将密钥与代码隔离保存点击左下角 ⚙️ 齿轮图标 →Command Palette输入并执行Codespaces : Manage user secret→Add a new secret名称填OPENAI_API_KEY粘贴你的密钥后Save保存。保存后仓库里的代码会自动读取该密钥你无需在仓库内落盘任何明文密钥。3.2 备选在 Codespace 里使用.env文件如果你确实需要一份本地可见的.env例如需要在多个 Provider 间切换仓库也提供了现成模板。在 Codespace 终端中执行cp .env.copy .env code .env # 将占位符替换为真实 Key仓库根目录确实存在 .env.copy 模板文件所有需要填写的变量及其注释都列在其中。四、第三步安全配置 API Key 与.env文件绝对不要把任何 API Key 写死在代码里提交到公开仓库可能引发安全问题甚至被他人盗用而产生费用。规范的姿势是把密钥放入python-dotenv读取的.env文件该文件已被.gitignore忽略不会进入版本库或用 Codespaces Secrets 保存。下面是一份完整的六步流程1. 进入项目根目录cd path/to/your/project2. 创建.env文件Unix 系系统touch .envWindows 系统echo . .env3. 编辑.env填入你的 Provider 凭据用任意文本编辑器VS Code、Notepad 等打开.env参考仓库根目录 .env.copy 模板的结构把占位符替换成真实值。仓库各文档与代码目前使用的主要变量如下关于 GitHub Models 退役与 Microsoft Foundry Models 接管的说明见下文“技术需求与 Provider 选择”# OpenAI Provider OPENAI_API_KEYadd your OpenAI API key here ## Azure OpenAI in Microsoft Foundry AZURE_OPENAI_API_VERSION2024-10-21 AZURE_OPENAI_API_KEYadd your Foundry resource key here AZURE_OPENAI_ENDPOINTadd your Foundry resource endpoint here, e.g. https://resource-name.openai.azure.com AZURE_OPENAI_DEPLOYMENTadd your chat completion model deployment name here, e.g. gpt-4o-mini AZURE_OPENAI_EMBEDDINGS_DEPLOYMENTadd your embeddings model deployment name here, e.g. text-embedding-3-small ## Microsoft Foundry Models (multi-provider model catalog) AZURE_INFERENCE_ENDPOINTadd your Microsoft Foundry project endpoint here AZURE_INFERENCE_CREDENTIALadd your Microsoft Foundry Models API key here ## Hugging Face HUGGING_FACE_API_KEYadd your HuggingFace API or token here各变量的含义对照表变量含义HUGGING_FACE_API_KEY在 Hugging Face 个人资料中创建的 Access Token用于鉴权故沿用 API key 命名OPENAI_API_KEY非 Azure 场景下 OpenAI 服务的授权 KeyAZURE_OPENAI_API_KEYAzure OpenAI 资源的授权 KeyAZURE_OPENAI_ENDPOINTAzure OpenAI 资源对应的部署端点AZURE_OPENAI_DEPLOYMENT文本生成chat completion模型的部署名例如gpt-4o-miniAZURE_OPENAI_EMBEDDINGS_DEPLOYMENT文本嵌入embeddings模型的部署名例如text-embedding-3-smallAZURE_INFERENCE_ENDPOINTMicrosoft Foundry 项目的端点用于 Microsoft Foundry ModelsAZURE_INFERENCE_CREDENTIALMicrosoft Foundry 项目的 API Key说明AZURE_OPENAI_DEPLOYMENT与AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT分别代表课程默认使用的文本生成与向量检索模型具体如何在作业中使用会在对应课程的任务说明中给出。各 Provider 如何注册账号、申请 Key、部署模型完整指引在 00-course-setup/03-providers.md。4. 保存文件并关闭编辑器5. 安装python-dotenv用于把.env中的变量加载进 Python 应用pip install python-dotenv仓库根目录 requirements.txt 中已固定python-dotenv1.2.2因此执行pip install -r requirements.txt亦可。6. 在 Python 脚本中加载环境变量from dotenv import load_dotenv import os # 从 .env 文件加载环境变量 load_dotenv() # 读取 Microsoft Foundry Models 变量 endpoint os.getenv(AZURE_INFERENCE_ENDPOINT) token os.getenv(AZURE_INFERENCE_CREDENTIAL) print(endpoint)到这里你已经成功创建.env、写入凭据并能在 Python 中读取它们。4.1 源码侧环境变量是如何被“消费”的仓库并不要求你手写样板代码而是把环境读取逻辑收敛进了 shared/python/env_utils.pyget_required_env(var_name, description)shared/python/env_utils.py读取必填变量缺失时抛出带变量名与用途提示的ValueError提示内容会引导你去.env中补齐validate_env_vars(*var_names)shared/python/env_utils.py批量校验多个变量是否都已设置并返回变量名到值的字典get_env_with_default(var_name, default)shared/python/env_utils.py为可选变量提供默认值。客户端创建侧则由 shared/python/api_utils.py 负责create_openai_client()shared/python/api_utils.py在没有显式传入 key 时自动读取OPENAI_API_KEY环境变量缺失即抛出异常create_azure_openai_client()shared/python/api_utils.py自动读取AZURE_OPENAI_ENDPOINT、AZURE_OPENAI_API_KEY并以endpoint/openai/v1/作为base_url构造客户端。这意味着只要.env或 Codespaces Secrets 配置正确课程中的示例脚本便会自动取到凭据不需要你改动任何共享代码。五、常见问题排查Troubleshooting环境搭建失败大多集中在容器构建、终端会话、密钥与 Notebook 内核四个方面。官方给出的对照表如下症状解决方法容器构建卡住超过 10 分钟Codespaces → “Rebuild Container”重建容器提示python: command not found终端没有正确附着到容器点击→ 选择bash新开终端来自 OpenAI 的401 UnauthorizedOPENAI_API_KEY有误或已过期重新生成并更新密钥VS Code 一直显示 “Dev container mounting…”刷新浏览器标签页——Codespaces 偶尔会丢失连接Notebook 内核缺失Notebook 菜单 →Kernel ▸ Select Kernel ▸ Python 3ModuleNotFoundError: dotenv环境未装依赖执行pip install -r requirements.txtOpenAI 返回 401 / 429检查OPENAI_API_KEY是否正确、是否触发限流Docker 构建报No space leftDocker Desktop →Settings→Resources调大磁盘分配若配置的是本地环境而不是 Codespaces可对照 00-course-setup/02-setup-local.md 末尾的排障表如 Windows 下pip无法构建 wheel 时先pip install --upgrade pip setuptools wheel。六、在本机运行课程代码如果你选择在自己电脑上运行需要先安装某个版本的 Python。然后克隆仓库git clone https://github.com/your-github/generative-ai-for-beginners cd generative-ai-for-beginners课程官方原仓库地址为https://github.com/microsoft/generative-ai-for-beginners实际使用中建议直接克隆你自己 Fork 的副本以便提交练习成果。克隆完成后还需要按第四节配置.env或在对应课程目录内安装依赖。仓库根目录的 requirements.txt 与 pyproject.toml 对 Python 版本有明确约定requires-python 3.10主要依赖包括openai1.12.0、python-dotenv1.2.2、azure-ai-inference、tiktoken以及numpy/pandas/matplotlib等数据科学工具链。七、可选的高级环境方案官方环境准备不止一种以下方案可按需选用7.1 方案 AMiniconda 虚拟环境Miniconda 是 Conda 的轻量安装器。Conda 本身是一个包管理器能方便地创建与切换不同的 Python虚拟环境对pip装不了的包也很有用。按官方指南装好 Miniconda验证conda --version若尚未克隆仓库先完成克隆创建环境描述文件environment.yml在 Codespace 中请建在.devcontainer目录下即.devcontainer/environment.yml并填入name: environment-name channels: - defaults - microsoft dependencies: - pythonpython-version - openai - python-dotenv - pip - pip: - azure-ai-mlenvironment-name是你想给环境起的名字python-version是你想用的 Python 版本例如3表示最新的 Python 3 大版本。用以下命令创建并激活环境conda env create --name ai4beg --file .devcontainer/environment.yml # 其中 .devcontainer 路径仅适用于 Codespace 场景 conda activate ai4beg如果 Conda 解析频道报错也可以手动安装微软 AI 库conda install -c microsoft azure-ai-ml7.2 方案 BVS Code Python 扩展官方推荐使用 Visual Studio Code 搭配Python 扩展IDms-python.python学习本课程但这只是推荐而非硬性要求克隆并在 VS Code 中打开仓库后VS Code 会自动建议你安装 Python 扩展仓库内含.devcontainer目录因此打开时会提示是否“在容器中重新打开”项目注意若你想使用本机安装的 Python当 VS Code 提示以容器方式重开时请选择拒绝以继续使用本地 Python。7.3 方案 C浏览器里的 Jupyter喜欢经典 Jupyter 界面、不想依赖 VS Code 的话也可以在浏览器里跑课程。进入课程目录后执行jupyter notebook或jupyterhub启动后命令行窗口会给出访问 URL。打开后你能看到课程大纲并可导航到任意*.ipynb文件例如 08-building-search-applications/python/oai-solution.ipynb。7.4 方案 D在容器Dev Container中运行不想在自己的电脑或 Codespace 里装环境还可以使用容器。仓库的.devcontainer目录让 VS Code 可以把整个项目放进容器构建。在 Codespaces 之外使用此方案需要自行安装 Docker工程量不小只推荐有容器使用经验的开发者尝试。在 GitHub Codespaces 中保护 API Key 的最佳实践是使用Codespaces Secrets具体管理方式见 GitHub 官方的 Secrets 管理文档。八、课程的技术需求与 Provider 选择本课程中的编码作业可以并非必须配置为调用一个或多个 LLM Provider 的托管端点例如 OpenAI、Azure OpenAI、Microsoft Foundry Models、Hugging Face如果你想完全离线也可以选择 Foundry Local 或 Ollama 在本机运行开源模型。你需要使用自己的账号来完成这些练习——作业都是可选的你可以按兴趣配置其中一个、全部或一个都不配置。需要说明的是仓库中的 00-course-setup/03-providers.md 明确提示GitHub Models及其GITHUB_TOKEN变量将于 2026 年 7 月底停用官方建议改用Microsoft Foundry Models一个端点 一个 API Key 即可访问 OpenAI、Meta、Mistral、Cohere、Microsoft 等数百个模型因此本指南沿用了 Foundry 相关的变量命名。作业文件名会通过标签标明所需的 Provideraoai需要 Azure OpenAI 端点与 Keyoai需要 OpenAI 端点与 Keyhf需要 Hugging Face Tokengithubmodels需要 Microsoft Foundry Models 端点与 Key对应 GitHub Models 退役后的替代方案。你可以只配置其中一部分。未配置对应凭据的作业在运行时自然报错不影响其他课程的推进。8.1 如何获取各 Provider 的端点与密钥Azure OpenAI登录 Azure Portal在左侧菜单进入Keys and Endpoint点击Show Keys即可看到 KEY 1、KEY 2 与 Endpoint用 KEY 1 作为AZURE_OPENAI_API_KEY、Endpoint 作为AZURE_OPENAI_ENDPOINT。随后在Model deployments里点击进入 Microsoft Foundry 门户旧入口为 “Manage Deployments”查看已部署模型推荐部署一个文本生成模型如gpt-4o-mini与一个文本嵌入模型如text-embedding-3-small并把部署名填入AZURE_OPENAI_DEPLOYMENT与AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT。OpenAI在 OpenAI 平台账号页创建 API Key填入OPENAI_API_KEY。Hugging Face在个人资料的 Access Tokens 里为本项目新建一个 Token填入HUGGING_FACE_API_KEY技术上它不是 API Key 而是鉴权 Token此处沿用统一命名。请不要公开分享该 Token。Microsoft Foundry Models进入 Microsoft Foundry 创建或打开一个项目在模型目录中部署一个模型例如gpt-4o-mini然后在项目Overview页复制endpoint与API key分别填入AZURE_INFERENCE_ENDPOINT与AZURE_INFERENCE_CREDENTIAL。离线 Provider不需要任何云订阅时可选用 Foundry Local自动选择 NPU/GPU/CPU 并暴露 OpenAI 兼容端点或 Ollama本地运行 Llama、Phi、Mistral、Gemma 等开源模型的流行选择。离线方案的动手示例可参考 19-slm/README.md。每个 Provider 的注册成本、Key 获取入口、Playground 等更多细节都整理在 00-course-setup/03-providers.md 的对比表中。8.2 在等待申请期间可以做什么Azure OpenAI 这类服务有时需要先提交申请、等待审批。在等待期间每个编码课程目录下的README.md都内嵌了代码与运行结果展示你可以先阅读、理解代码逻辑等凭据到位后再实际运行 Notebook。九、验证环境是否就绪配置完成后可以用下面这个最小的 Python 片段做自检——它能确认python-dotenv可导入、.env能被加载、关键变量已读取不输出密钥本身python -c from dotenv import load_dotenv; import os; load_dotenv(); assert os.getenv(OPENAI_API_KEY) or os.getenv(AZURE_OPENAI_API_KEY) or os.getenv(AZURE_INFERENCE_CREDENTIAL); print(env OK)更进一步可以尝试调用共享模块的校验函数。仓库的单元测试也覆盖了这些逻辑见 tests/ 下的test_env_utils.py等如果你后续修改了共享代码可参考 pyproject.toml 中配置的pytest运行测试。按官方文档的约定“缺少凭据”只会让对应作业在运行时报错相关作业会给出清晰的缺失变量提示不会破坏整个课程仓库。十、学完准备后如何开始完成上述步骤后你已具备完整的运行环境。接下来推荐按 00-course-setup/README.md 的路线进入学习主线从 第 1 课生成式 AI 与 LLM 入门 开始然后一路推进到提示工程、文本/图像/搜索应用、Function Calling、RAG、微调、AI Agent 等章节目录编号01…21。如果你在学习中遇到问题官方在 AI 社区 Discord 中设有学习者频道项目团队也会在该频道协助答疑本课程同时是开源项目欢迎以 Pull Request 或 Issue 的方式提出改进——需要注意按贡献规范提交且翻译类贡献不接受机器翻译结果请只在精通的语言上参与翻译。【免费下载链接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 generative-ai-for-beginners 环境搭建完全指南：Fork、Codespaces 与本地跑通第一课
generative-ai-for-beginners 环境搭建完全指南Fork、Codespaces 与本地跑通第一课【免费下载链接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners本指南以仓库课程初始化章节对应translations/en/00-course-setup/README.md仓库根目录的原文见 00-course-setup/README.md为核心系统讲解如何从零准备一个可运行 21 课 Generative AI 动手项目的开发环境。你将掌握 Fork 仓库、创建 GitHub Codespaces、安全托管 API Key、配置.env并能在云上或本机原生 Python、Conda、VS Code Dev Container、Jupyter任一形态中运行课程代码最终安全高效地进入 第 1 课生成式 AI 与 LLM 入门。一、课程环境概览与整体路线这个仓库是一个开源课程项目关于课程规模与定位可在仓库根目录的 pyproject.toml 与课程说明中确认学习过程会涉及大量需要调用云端模型接口的 Notebook 与脚本例如基于 OpenAI / Azure OpenAI / Hugging Face 的作业。为了让你“零折腾”地聚焦学习本身官方给出了完整的环境准备路线我要做什么前往哪个文档直接开始第 1 课01-introduction-to-genai离线、在自有电脑上运行00-course-setup/02-setup-local.md配置一个 LLM ProviderOpenAI / Azure / Hugging Face / Foundry Models 等00-course-setup/03-providers.md不想安装任何东西、云端一键开跑00-course-setup/01-setup-cloud.md仓库还提供了整套共享工具代码用于环境变量的安全读取shared/python/env_utils.py与 OpenAI/Azure 客户端的创建shared/python/api_utils.py后文会结合这些源码说明“配置变量 → 被代码消费”的完整链路。二、第一步Fork 本仓库获得可写副本课程要求你动手修改代码、完成挑战因此需要把仓库 Fork 到自己的账号下。具体操作打开仓库主页点击右上角Fork把整个仓库复制到你自己的账号中得到可自由修改的副本可选但推荐顺手给仓库点一个Star方便日后在“你 Star 过的仓库”里快速找回本仓库及其关联项目。Fork 完成后你既可以把它作为云端 Codespace 的基底也可以本地git clone你自己的副本。三、第二步创建 Codespace让环境“预装好”为避免依赖安装带来的各类兼容性问题官方推荐在GitHub Codespaces中运行本课程。在 GitHub 的云端开发环境中仓库已通过预构建的开发容器帮你装好 Python、Node.js、.NET、Java 等运行时首次启动大约需要几分钟构建容器。在你自己的 Fork 副本中依次点击Code → Codespaces → New on main即基于main分支新建一个 codespace浏览器就会打开一个云端的 VS Code 窗口并开始构建开发容器。关于云端方案的更多细节个人免费配额、停止/删除空闲 codespace 以节约配额的提示等见 00-course-setup/01-setup-cloud.md。3.1 用 Codespaces Secrets 安全保存密钥推荐把 API Key 直接写进代码库是危险的。Codespaces 提供了“Secrets”机制将密钥与代码隔离保存点击左下角 ⚙️ 齿轮图标 →Command Palette输入并执行Codespaces : Manage user secret→Add a new secret名称填OPENAI_API_KEY粘贴你的密钥后Save保存。保存后仓库里的代码会自动读取该密钥你无需在仓库内落盘任何明文密钥。3.2 备选在 Codespace 里使用.env文件如果你确实需要一份本地可见的.env例如需要在多个 Provider 间切换仓库也提供了现成模板。在 Codespace 终端中执行cp .env.copy .env code .env # 将占位符替换为真实 Key仓库根目录确实存在 .env.copy 模板文件所有需要填写的变量及其注释都列在其中。四、第三步安全配置 API Key 与.env文件绝对不要把任何 API Key 写死在代码里提交到公开仓库可能引发安全问题甚至被他人盗用而产生费用。规范的姿势是把密钥放入python-dotenv读取的.env文件该文件已被.gitignore忽略不会进入版本库或用 Codespaces Secrets 保存。下面是一份完整的六步流程1. 进入项目根目录cd path/to/your/project2. 创建.env文件Unix 系系统touch .envWindows 系统echo . .env3. 编辑.env填入你的 Provider 凭据用任意文本编辑器VS Code、Notepad 等打开.env参考仓库根目录 .env.copy 模板的结构把占位符替换成真实值。仓库各文档与代码目前使用的主要变量如下关于 GitHub Models 退役与 Microsoft Foundry Models 接管的说明见下文“技术需求与 Provider 选择”# OpenAI Provider OPENAI_API_KEYadd your OpenAI API key here ## Azure OpenAI in Microsoft Foundry AZURE_OPENAI_API_VERSION2024-10-21 AZURE_OPENAI_API_KEYadd your Foundry resource key here AZURE_OPENAI_ENDPOINTadd your Foundry resource endpoint here, e.g. https://resource-name.openai.azure.com AZURE_OPENAI_DEPLOYMENTadd your chat completion model deployment name here, e.g. gpt-4o-mini AZURE_OPENAI_EMBEDDINGS_DEPLOYMENTadd your embeddings model deployment name here, e.g. text-embedding-3-small ## Microsoft Foundry Models (multi-provider model catalog) AZURE_INFERENCE_ENDPOINTadd your Microsoft Foundry project endpoint here AZURE_INFERENCE_CREDENTIALadd your Microsoft Foundry Models API key here ## Hugging Face HUGGING_FACE_API_KEYadd your HuggingFace API or token here各变量的含义对照表变量含义HUGGING_FACE_API_KEY在 Hugging Face 个人资料中创建的 Access Token用于鉴权故沿用 API key 命名OPENAI_API_KEY非 Azure 场景下 OpenAI 服务的授权 KeyAZURE_OPENAI_API_KEYAzure OpenAI 资源的授权 KeyAZURE_OPENAI_ENDPOINTAzure OpenAI 资源对应的部署端点AZURE_OPENAI_DEPLOYMENT文本生成chat completion模型的部署名例如gpt-4o-miniAZURE_OPENAI_EMBEDDINGS_DEPLOYMENT文本嵌入embeddings模型的部署名例如text-embedding-3-smallAZURE_INFERENCE_ENDPOINTMicrosoft Foundry 项目的端点用于 Microsoft Foundry ModelsAZURE_INFERENCE_CREDENTIALMicrosoft Foundry 项目的 API Key说明AZURE_OPENAI_DEPLOYMENT与AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT分别代表课程默认使用的文本生成与向量检索模型具体如何在作业中使用会在对应课程的任务说明中给出。各 Provider 如何注册账号、申请 Key、部署模型完整指引在 00-course-setup/03-providers.md。4. 保存文件并关闭编辑器5. 安装python-dotenv用于把.env中的变量加载进 Python 应用pip install python-dotenv仓库根目录 requirements.txt 中已固定python-dotenv1.2.2因此执行pip install -r requirements.txt亦可。6. 在 Python 脚本中加载环境变量from dotenv import load_dotenv import os # 从 .env 文件加载环境变量 load_dotenv() # 读取 Microsoft Foundry Models 变量 endpoint os.getenv(AZURE_INFERENCE_ENDPOINT) token os.getenv(AZURE_INFERENCE_CREDENTIAL) print(endpoint)到这里你已经成功创建.env、写入凭据并能在 Python 中读取它们。4.1 源码侧环境变量是如何被“消费”的仓库并不要求你手写样板代码而是把环境读取逻辑收敛进了 shared/python/env_utils.pyget_required_env(var_name, description)shared/python/env_utils.py读取必填变量缺失时抛出带变量名与用途提示的ValueError提示内容会引导你去.env中补齐validate_env_vars(*var_names)shared/python/env_utils.py批量校验多个变量是否都已设置并返回变量名到值的字典get_env_with_default(var_name, default)shared/python/env_utils.py为可选变量提供默认值。客户端创建侧则由 shared/python/api_utils.py 负责create_openai_client()shared/python/api_utils.py在没有显式传入 key 时自动读取OPENAI_API_KEY环境变量缺失即抛出异常create_azure_openai_client()shared/python/api_utils.py自动读取AZURE_OPENAI_ENDPOINT、AZURE_OPENAI_API_KEY并以endpoint/openai/v1/作为base_url构造客户端。这意味着只要.env或 Codespaces Secrets 配置正确课程中的示例脚本便会自动取到凭据不需要你改动任何共享代码。五、常见问题排查Troubleshooting环境搭建失败大多集中在容器构建、终端会话、密钥与 Notebook 内核四个方面。官方给出的对照表如下症状解决方法容器构建卡住超过 10 分钟Codespaces → “Rebuild Container”重建容器提示python: command not found终端没有正确附着到容器点击→ 选择bash新开终端来自 OpenAI 的401 UnauthorizedOPENAI_API_KEY有误或已过期重新生成并更新密钥VS Code 一直显示 “Dev container mounting…”刷新浏览器标签页——Codespaces 偶尔会丢失连接Notebook 内核缺失Notebook 菜单 →Kernel ▸ Select Kernel ▸ Python 3ModuleNotFoundError: dotenv环境未装依赖执行pip install -r requirements.txtOpenAI 返回 401 / 429检查OPENAI_API_KEY是否正确、是否触发限流Docker 构建报No space leftDocker Desktop →Settings→Resources调大磁盘分配若配置的是本地环境而不是 Codespaces可对照 00-course-setup/02-setup-local.md 末尾的排障表如 Windows 下pip无法构建 wheel 时先pip install --upgrade pip setuptools wheel。六、在本机运行课程代码如果你选择在自己电脑上运行需要先安装某个版本的 Python。然后克隆仓库git clone https://github.com/your-github/generative-ai-for-beginners cd generative-ai-for-beginners课程官方原仓库地址为https://github.com/microsoft/generative-ai-for-beginners实际使用中建议直接克隆你自己 Fork 的副本以便提交练习成果。克隆完成后还需要按第四节配置.env或在对应课程目录内安装依赖。仓库根目录的 requirements.txt 与 pyproject.toml 对 Python 版本有明确约定requires-python 3.10主要依赖包括openai1.12.0、python-dotenv1.2.2、azure-ai-inference、tiktoken以及numpy/pandas/matplotlib等数据科学工具链。七、可选的高级环境方案官方环境准备不止一种以下方案可按需选用7.1 方案 AMiniconda 虚拟环境Miniconda 是 Conda 的轻量安装器。Conda 本身是一个包管理器能方便地创建与切换不同的 Python虚拟环境对pip装不了的包也很有用。按官方指南装好 Miniconda验证conda --version若尚未克隆仓库先完成克隆创建环境描述文件environment.yml在 Codespace 中请建在.devcontainer目录下即.devcontainer/environment.yml并填入name: environment-name channels: - defaults - microsoft dependencies: - pythonpython-version - openai - python-dotenv - pip - pip: - azure-ai-mlenvironment-name是你想给环境起的名字python-version是你想用的 Python 版本例如3表示最新的 Python 3 大版本。用以下命令创建并激活环境conda env create --name ai4beg --file .devcontainer/environment.yml # 其中 .devcontainer 路径仅适用于 Codespace 场景 conda activate ai4beg如果 Conda 解析频道报错也可以手动安装微软 AI 库conda install -c microsoft azure-ai-ml7.2 方案 BVS Code Python 扩展官方推荐使用 Visual Studio Code 搭配Python 扩展IDms-python.python学习本课程但这只是推荐而非硬性要求克隆并在 VS Code 中打开仓库后VS Code 会自动建议你安装 Python 扩展仓库内含.devcontainer目录因此打开时会提示是否“在容器中重新打开”项目注意若你想使用本机安装的 Python当 VS Code 提示以容器方式重开时请选择拒绝以继续使用本地 Python。7.3 方案 C浏览器里的 Jupyter喜欢经典 Jupyter 界面、不想依赖 VS Code 的话也可以在浏览器里跑课程。进入课程目录后执行jupyter notebook或jupyterhub启动后命令行窗口会给出访问 URL。打开后你能看到课程大纲并可导航到任意*.ipynb文件例如 08-building-search-applications/python/oai-solution.ipynb。7.4 方案 D在容器Dev Container中运行不想在自己的电脑或 Codespace 里装环境还可以使用容器。仓库的.devcontainer目录让 VS Code 可以把整个项目放进容器构建。在 Codespaces 之外使用此方案需要自行安装 Docker工程量不小只推荐有容器使用经验的开发者尝试。在 GitHub Codespaces 中保护 API Key 的最佳实践是使用Codespaces Secrets具体管理方式见 GitHub 官方的 Secrets 管理文档。八、课程的技术需求与 Provider 选择本课程中的编码作业可以并非必须配置为调用一个或多个 LLM Provider 的托管端点例如 OpenAI、Azure OpenAI、Microsoft Foundry Models、Hugging Face如果你想完全离线也可以选择 Foundry Local 或 Ollama 在本机运行开源模型。你需要使用自己的账号来完成这些练习——作业都是可选的你可以按兴趣配置其中一个、全部或一个都不配置。需要说明的是仓库中的 00-course-setup/03-providers.md 明确提示GitHub Models及其GITHUB_TOKEN变量将于 2026 年 7 月底停用官方建议改用Microsoft Foundry Models一个端点 一个 API Key 即可访问 OpenAI、Meta、Mistral、Cohere、Microsoft 等数百个模型因此本指南沿用了 Foundry 相关的变量命名。作业文件名会通过标签标明所需的 Provideraoai需要 Azure OpenAI 端点与 Keyoai需要 OpenAI 端点与 Keyhf需要 Hugging Face Tokengithubmodels需要 Microsoft Foundry Models 端点与 Key对应 GitHub Models 退役后的替代方案。你可以只配置其中一部分。未配置对应凭据的作业在运行时自然报错不影响其他课程的推进。8.1 如何获取各 Provider 的端点与密钥Azure OpenAI登录 Azure Portal在左侧菜单进入Keys and Endpoint点击Show Keys即可看到 KEY 1、KEY 2 与 Endpoint用 KEY 1 作为AZURE_OPENAI_API_KEY、Endpoint 作为AZURE_OPENAI_ENDPOINT。随后在Model deployments里点击进入 Microsoft Foundry 门户旧入口为 “Manage Deployments”查看已部署模型推荐部署一个文本生成模型如gpt-4o-mini与一个文本嵌入模型如text-embedding-3-small并把部署名填入AZURE_OPENAI_DEPLOYMENT与AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT。OpenAI在 OpenAI 平台账号页创建 API Key填入OPENAI_API_KEY。Hugging Face在个人资料的 Access Tokens 里为本项目新建一个 Token填入HUGGING_FACE_API_KEY技术上它不是 API Key 而是鉴权 Token此处沿用统一命名。请不要公开分享该 Token。Microsoft Foundry Models进入 Microsoft Foundry 创建或打开一个项目在模型目录中部署一个模型例如gpt-4o-mini然后在项目Overview页复制endpoint与API key分别填入AZURE_INFERENCE_ENDPOINT与AZURE_INFERENCE_CREDENTIAL。离线 Provider不需要任何云订阅时可选用 Foundry Local自动选择 NPU/GPU/CPU 并暴露 OpenAI 兼容端点或 Ollama本地运行 Llama、Phi、Mistral、Gemma 等开源模型的流行选择。离线方案的动手示例可参考 19-slm/README.md。每个 Provider 的注册成本、Key 获取入口、Playground 等更多细节都整理在 00-course-setup/03-providers.md 的对比表中。8.2 在等待申请期间可以做什么Azure OpenAI 这类服务有时需要先提交申请、等待审批。在等待期间每个编码课程目录下的README.md都内嵌了代码与运行结果展示你可以先阅读、理解代码逻辑等凭据到位后再实际运行 Notebook。九、验证环境是否就绪配置完成后可以用下面这个最小的 Python 片段做自检——它能确认python-dotenv可导入、.env能被加载、关键变量已读取不输出密钥本身python -c from dotenv import load_dotenv; import os; load_dotenv(); assert os.getenv(OPENAI_API_KEY) or os.getenv(AZURE_OPENAI_API_KEY) or os.getenv(AZURE_INFERENCE_CREDENTIAL); print(env OK)更进一步可以尝试调用共享模块的校验函数。仓库的单元测试也覆盖了这些逻辑见 tests/ 下的test_env_utils.py等如果你后续修改了共享代码可参考 pyproject.toml 中配置的pytest运行测试。按官方文档的约定“缺少凭据”只会让对应作业在运行时报错相关作业会给出清晰的缺失变量提示不会破坏整个课程仓库。十、学完准备后如何开始完成上述步骤后你已具备完整的运行环境。接下来推荐按 00-course-setup/README.md 的路线进入学习主线从 第 1 课生成式 AI 与 LLM 入门 开始然后一路推进到提示工程、文本/图像/搜索应用、Function Calling、RAG、微调、AI Agent 等章节目录编号01…21。如果你在学习中遇到问题官方在 AI 社区 Discord 中设有学习者频道项目团队也会在该频道协助答疑本课程同时是开源项目欢迎以 Pull Request 或 Issue 的方式提出改进——需要注意按贡献规范提交且翻译类贡献不接受机器翻译结果请只在精通的语言上参与翻译。【免费下载链接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考