generative-ai-for-beginners 课程环境搭建实战指南从 GitHub Codespaces 云开发到本地 Conda/Jupyter 多方案配置【免费下载链接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners本指南以《Generative AI for Beginners》课程仓库中 21 课时的开源课程见 pyproject.toml的 00 课程设置文档为主体完整讲解搭建课程开发环境的全部路径云端首选 GitHub Codespaces本地可选原生 Python 虚拟环境、Miniconda、VS Code Dev Container 或浏览器 Jupyter并详细说明如何安全配置 OpenAI、Azure OpenAI、Microsoft Foundry Models、Hugging Face 等 LLM 提供商的 API 密钥。读完本文你将具备独立复现课程全部 Notebook 与代码练习的环境能力。课程概览与技术前提本课程包含 21 课概念课与编程课相结合涉及提示工程、文本生成、聊天应用、搜索应用、图像生成、函数调用、RAG、AI Agent、微调与小型语言模型SLM等主题。其中编程课需要调用云端 LLM 服务因此你需要一个GitHub 账号用于 Fork 仓库与创建 Codespace至少一个LLM 提供商账号及其 API 密钥OpenAI / Azure OpenAI / Microsoft Foundry Models / Hugging Face 任选其一即可练习文件按aoai、oai、hf、githubmodels前缀标注所需提供商本地运行还需Python 3.10仓库 pyproject.toml 声明requires-python 3.10.python-version 固定为 3.12.10与Git。关于 GitHub Models 的迁移提示原课程曾使用 GitHub ModelsGITHUB_TOKEN变量作为免费模型入口该服务将于2026 年 7 月底退役由 Microsoft Foundry ModelsAZURE_INFERENCE_ENDPOINT/AZURE_INFERENCE_CREDENTIAL直接取代。本文按当前仓库的最新配置见 .env.copy 与 00-course-setup/03-providers.md编写。方案一GitHub Codespaces 云端开发推荐首选00-course-setup/01-setup-cloud.md 指出如果你不想在本地安装任何东西Codespaces 是最佳选择——它提供一个免费、基于浏览器的 VS Code 实例所有依赖均已预装。为什么选择 Codespaces优势对你的意义✅ 零安装在 Chromebook、iPad、学校机房电脑上都能用✅ 预构建开发容器Python 3、Node.js、.NET、Java 开箱即用✅ 免费配额个人账号每月120 core-hours / 60 GB-hours 保持配额健康的小技巧不使用的 Codespaces 请及时停止或删除View ▸ Command Palette ▸Codespaces: Stop Codespace。创建 Codespace 的步骤Fork 本仓库点击仓库右上角Fork按钮把整个仓库复制到自己的 GitHub 账号下这样你才能修改代码并完成课程挑战建议同时 Star 收藏便于日后查找在 Fork 后的仓库页面执行Code ▸ Codespaces ▸ Create codespace on main浏览器会自动打开一个 VS Code 窗口开发容器随即开始构建首次构建约需 2 分钟。容器镜像与配置来自仓库根目录的 .devcontainer/devcontainer.json基础镜像为mcr.microsoft.com/devcontainers/universal:2.13要求至少 4 核 CPU创建容器时会执行python3 -m pip install -r requirements.txt安装依赖随后运行 .devcontainer/post-create.sh 补装python-dotenv、openai以及ruff、black、mypy、pytest等开发工具链——这些工具与.github/workflows/code-quality.yml中的 CI 检查保持一致方便你在提交 PR 前本地复现同样的校验。添加 API 密钥推荐用 Codespaces Secrets点击左下角 ⚙️ 齿轮图标 →Command Palette→Codespaces: Manage user secret→Add a new secret名称填OPENAI_API_KEY值粘贴你的密钥点击Save保存。课程代码会自动读取该密钥无需在仓库中存放任何明文。若确实需要.env文件可执行cp .env.copy .env后编辑。方案二安全配置 API 密钥.env 文件 python-dotenv在本地或容器中运行代码时切勿把 API 密钥硬编码进代码或提交到公开仓库——这可能造成安全隐患甚至被恶意调用产生费用。标准做法是使用.env文件并通过python-dotenv加载。创建.env文件Unix 系系统touch .envWindowsecho . .env编辑并填充密钥用 VS Code、Notepad 等编辑器打开.env参照仓库根目录 .env.copy 中的占位符填写你实际申请到的密钥GitHub Models 已退役改用 Microsoft Foundry Models 凭据AZURE_INFERENCE_ENDPOINTyour_foundry_endpoint_here AZURE_INFERENCE_CREDENTIALyour_foundry_api_key_here安装并加载pip install python-dotenvfrom 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已被仓库的 .gitignore 忽略不会被 Git 跟踪。源码级佐证仓库如何读取环境变量仓库在 shared/python/env_utils.py 中封装了安全读取环境变量的工具get_required_env(var_name, description)读取必填变量缺失或为空时抛出带说明的ValueErrorvalidate_env_vars(*var_names)批量校验多个变量一次性报告所有缺失项get_env_with_default(var_name, default)读取可选变量并返回默认值。对应测试见 tests/test_env_utils.py覆盖了缺失抛错空值抛错批量校验报告全部缺失项默认值回退等场景保证了密钥读取逻辑的可靠性。此外shared/python/api_utils.py 中的create_openai_client()默认从OPENAI_API_KEY读取密钥create_azure_openai_client()则从AZURE_OPENAI_ENDPOINT/AZURE_OPENAI_API_KEY读取并自动拼接endpoint/openai/v1/端点而面向 Microsoft Foundry Models 的示例代码如 06-text-generation-apps/python/githubmodels-app.py直接使用os.environ[AZURE_INFERENCE_CREDENTIAL]与os.environ[AZURE_INFERENCE_ENDPOINT]构造azure.ai.inference.ChatCompletionsClient——这正是你在.env中配置的那两个变量。方案三本地原生 Python最快上手按 00-course-setup/02-setup-local.md 的路径 A 操作克隆仓库git clone https://github.com/microsoft/generative-ai-for-beginners cd generative-ai-for-beginners创建并激活虚拟环境python -m venv .venv # 创建 source .venv/bin/activate # macOS / Linux .\.venv\Scripts\activate # Windows PowerShell激活成功后终端提示符应以(.venv)开头。安装依赖pip install -r requirements.txt根目录 requirements.txt 已锁定课程所需核心库包括openai1.12.0、python-dotenv1.2.2、azure-ai-inference、tiktoken、ipywidgets、numpy、matplotlib、pandas、scikit-learn等项目级依赖定义还可参考 pyproject.toml其中 dev 可选依赖含ruff、black、mypy、pytest等。方案四Miniconda / Conda 虚拟环境Conda 是一款包管理器方便创建、切换不同的 Python 虚拟环境也能安装pip中不存在的包如微软的azure-ai-ml。安装 Miniconda后验证conda --version创建环境文件environment.yml若用 Codespaces 则放在.devcontainer目录下内容如下name: environment-name channels: - defaults - microsoft dependencies: - pythonpython-version - openai - python-dotenv - pip - pip: - azure-ai-ml其中environment-name是你的环境名python-version填目标 Python 版本例如3代表最新的 3.x 主版本仓库 .devcontainer/environment.yml 实际锁定python3.10.0。创建并激活环境conda env create --name ai4beg --file .devcontainer/environment.yml conda activate ai4beg若 Conda 报错可手动安装微软 AI 库conda install -c microsoft azure-ai-ml方案五VS Code Dev ContainerDocker 容器开发仓库根目录的.devcontainer目录见 .devcontainer/devcontainer.json让 VS Code 可以一键在容器中打开项目容器环境与 Codespaces 完全一致杜绝依赖漂移。安装 Docker Desktop 与 VS Code Remote - Containers 扩展IDms-vscode-remote.remote-containers并确认docker --version可用File ▸ Open Folder…打开generative-ai-for-beginnersVS Code 检测到.devcontainer/后会弹出提示点击Reopen in ContainerDocker 开始构建镜像首次约 3 分钟终端出现提示符即进入容器环境。容器内预装了ms-python.python、ms-toolsai.jupyter、ms-python.black-formatter、charliermarsh.ruff、github.copilot等 VS Code 扩展并开启了 Python 默认使用 Black 格式化、保存时自动格式化等设置。⚠️ 注意若你希望使用本地已安装的 Python当 VS Code 提示在容器中重新打开项目时请选择拒绝。方案六浏览器中的 Jupyter不想使用 VS Code 也没关系可以直接在浏览器中通过 Jupyter 运行课程 Notebookjupyter notebook或jupyterhub启动后终端会显示访问 URL进入后即可看到课程目录结构打开任意*.ipynb文件例如 08-building-search-applications/python/oai-solution.ipynb。LLM Provider 选择与完整配置指南课程练习可选地依赖一个或多个 LLM 服务商。选一个、选多个、或者全部跳过都由你决定——缺少凭据的相关练习只会报错不会影响其他练习。各提供商的注册与配置对比如下详见 00-course-setup/03-providers.md服务商注册费用API 密钥位置Playground备注OpenAI官方账号注册按量计费Project-based API Keys无代码网页端提供 GPT 系列多模型Azure OpenAIAzure 账号申请按量计费资源Keys and Endpoint页Foundry Studio需提前申请开通Microsoft Foundry ModelsFoundry 项目有免费额度项目 Overview 页Foundry Playground一个端点/密钥访问数百模型取代 GitHub ModelsHugging Face官网注册部分免费Access TokensHugging Chat开源模型与推理服务Foundry Local / Ollama无需注册免费本机运行不需要本地 CLI/SDK完全离线OpenAI 兼容端点练习文件名前缀约定aoai需 Azure OpenAI、oai需 OpenAI、hf需 Hugging Face Token、githubmodels需 Microsoft Foundry Models。完整的.env.copy参考仓库根目录# OpenAI Provider OPENAI_API_KEYadd your OpenAI API key here ## Azure OpenAI in Microsoft Foundry AZURE_OPENAI_API_VERSION2024-10-21 # 默认已设置当前稳定 GA API 版本 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多提供商模型目录取代 GitHub Models 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复制为.env并填写cp .env.copy .env。各变量的含义变量说明OPENAI_API_KEY非 Azure 的 OpenAI 端点授权密钥AZURE_OPENAI_API_KEYAzure OpenAI 资源授权密钥AZURE_OPENAI_ENDPOINTAzure OpenAI 资源已部署的端点AZURE_OPENAI_DEPLOYMENT文本生成模型的部署名如gpt-4o-miniAZURE_OPENAI_EMBEDDINGS_DEPLOYMENT文本嵌入模型的部署名如text-embedding-3-smallAZURE_INFERENCE_ENDPOINTMicrosoft Foundry 项目端点Foundry Models 用AZURE_INFERENCE_CREDENTIALMicrosoft Foundry 项目 API 密钥HUGGING_FACE_API_KEYHugging Face 用户访问 Token技术上非 API Key为统一命名沿用此名各提供商的获取步骤要点Azure OpenAI从门户在 Azure 门户 左侧菜单点Keys and Endpoint→Show Keys将 KEY 1 填入AZURE_OPENAI_API_KEY、Endpoint 填入AZURE_OPENAI_ENDPOINT再到Model deployments进入 Microsoft Foundry 门户确认已部署文本生成模型推荐gpt-4o-mini与文本嵌入模型推荐text-embedding-3-small将部署名填入对应变量OpenAI在 OpenAI 账号的 API Keys 页面创建密钥填入OPENAI_API_KEYHugging Face在个人 Profile 的 Access Tokens 页面为该项目新建一个 Token填入HUGGING_FACE_API_KEY切勿公开分享Microsoft Foundry Models进入 Foundry 创建/打开项目在模型目录部署如gpt-4o-mini再从项目Overview页复制 endpoint 与 API key 分别填入AZURE_INFERENCE_ENDPOINT与AZURE_INFERENCE_CREDENTIAL。完全离线方案不想使用任何云订阅可用 Foundry LocalSLM 课程。常见故障排查症状解决方案容器构建卡住超过 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 3pip无法构建 wheelWindows先执行pip install --upgrade pip setuptools wheel再重试ModuleNotFoundError: dotenv执行pip install -r requirements.txt环境未安装依赖Docker 构建报No space leftDocker Desktop ▸ Settings ▸ Resources 增大磁盘空间OpenAI 401 / 429 错误检查OPENAI_API_KEY取值 / 请求频率限制Conda 使用报错手动安装微软 AI 库conda install -c microsoft azure-ai-ml下一步开始第一课环境就绪后请从 01-introduction-to-genai/README.md生成式 AI 与大型语言模型入门开始学习。若想离线工作可参考 00-course-setup/02-setup-local.md需要配置 LLM 提供商则查阅 00-course-setup/03-providers.md。仓库还提供了完整的共享工具库shared/python/env_utils.py、shared/python/api_utils.py与配套测试tests/可作为你理解课程代码、扩展练习的参考。【免费下载链接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考