generative-ai-for-beginners 本地环境搭建完全指南Python venv、Dev Container、Miniconda 与 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》的本地搭建Local Setup一课即 translations/et/00-course-setup/02-setup-local.md其英文原版见 00-course-setup/02-setup-local.md面向希望在自己笔记本上跑通全部 21 节课、而不依赖云端环境的开发者。读完本文你可以在原生 Python 虚拟环境、VS Code Dev Container Docker、Miniconda、经典 Jupyter四条路径中任选其一完成课程环境准备并学会用.envpython-dotenv安全加载各类 LLM 提供商的 API 密钥最后能对照仓库内置的.gitignore、requirements.txt 与 .env.copy 自行排障。1. 总览四条本地路线怎么选原文档的核心观点是你有两种以上可选路径选你认为简单的即可殊途同归、通向同一批课程。除去 VS Code 的偏好差异仓库给出的本地方案实际包含四套方案适合场景关键依赖环境隔离方式A. Native Python venv想最快跑起来、机器上已有 PythonPython 3.10、Git标准库venvB. VS Code Dev Container想与 Codespaces 环境完全一致Docker Desktop VS Code Remote-ContainersDocker 镜像C. Miniconda / Conda需要pip之外的包、习惯 Conda 生态MinicondaConda 虚拟环境D. Jupyter / Jupyter Lab喜欢浏览器内经典 Notebook 界面Jupyter随 Python 解释器无论选哪条最终都会到达相同的课程 Notebook*.ipynb与示例代码因此不必纠结——先确认前置条件再挑一条最顺手的路。2. 前置条件与工具自检工具版本 / 说明Python3.10 及以上从 python.org 获取Git最新版macOS 一般随 Xcode 附带Windows 用 Git for WindowsLinux 用系统包管理器VS Code可选但强烈推荐code.visualstudio.com 下载Docker Desktop仅方案 B 需要提供免费安装版本小技巧在终端里一次性验证四个工具是否就绪python --version git --version docker --version code --version关于云端环境若你不希望在本机安装任何东西也可以先看本目录的云端路线 translations/et/00-course-setup/01-setup-cloud.md基于 GitHub Codespaces。本文则专注本地。3. 方案 A原生 Python venv最快3.1 克隆仓库课程仓库默认可执行如下克隆并进入目录git clone https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners cd generative-ai-for-beginners如果你已经 fork 了仓库把地址换成你自己的 fork 即可后续所有步骤不受影响。3.2 创建并激活虚拟环境python -m venv .venv # 创建一次即可 source .venv/bin/activate # macOS / Linux .\.venv\Scripts\activate # Windows PowerShell✅ 激活成功后命令提示符前缀会出现(.venv)——这代表你已经进入该虚拟环境后续pip安装的包只属于这个环境不会污染系统 Python。3.3 安装依赖pip install -r requirements.txt仓库根目录的 requirements.txt 已锁定课程全部 Python 依赖实测内容既包含数据科学基础库也包含 AI 客户端库ipywidgets8.1.8 numpy2.4.2 matplotlib3.10.8 pandas3.0.0 tqdm4.68.4 python-dotenv1.2.2 openai1.12.0 tiktoken azure-ai-inference scikit-learn值得注意的几点工程细节python-dotenv1.2.2被锁定这是后面第 7 节用.env加载 API 密钥的基础openai1.12.0采用 Python SDK v1.x 的新版接口from openai import AzureOpenAI / OpenAIazure-ai-inference用于接入 Microsoft Foundry Models 等多提供商推理端点直接呼应仓库 .env.copy 中的AZURE_INFERENCE_*变量课程用到的 embedding、搜索、绘图等能力由 numpy/pandas/scikit-learn 等支撑。从源码结构看整仓 21 课中大量 Python 示例如 06-text-generation-apps/python、07-building-chat-applications/python、08-building-search-applications/python 等都依赖这套统一的依赖清单因此强烈建议在同一个 venv 里一次性装完而不是逐课装包。3.4 验证并继续安装完成后可以直接跳到本文第 7 节完成 API 密钥配置再开始第 1 课。4. 方案 BVS Code Dev ContainerDocker这是仓库作者团队实际使用的开发形态仓库根部放置了真实的 devcontainer.json选用通用开发容器镜像mcr.microsoft.com/devcontainers/universal:2.13原生支持 Python 3、.NET、Node.js 与 Java并且与 Codespaces 使用同一套配置——环境 100% 一致、不会出现依赖漂移dependency drift是它的最大卖点。4.1 你需要额外准备的两样东西Docker Desktop先确认docker --version能正常输出版本号VS Code Remote – Containers 扩展扩展 ID 为ms-vscode-remote.remote-containers。4.2 操作步骤Step 1打开 VS Code执行File ▸ Open Folder…选择克隆下来的generative-ai-for-beginners目录。VS Code 检测到仓库根部的.devcontainer/后会自动弹出提示。Step 2点击“Reopen in Container”。Docker 会开始构建镜像首次大约需要 3 分钟。当终端提示符重新出现时说明你已经身处容器内部可以直接使用 Python、运行 Notebook。4.3 仓库实际配置里藏着什么对照仓库的 devcontainer.json可以看到三个关键生命周期钩子hostRequirements.cpus: 4第 6~8 行容器要求宿主机至少提供 4 核构建前可自查机器规格updateContentCommand第 10 行容器内容更新后自动执行python3 -m pip install -r requirements.txtpostCreateCommand第 11 行创建后执行bash .devcontainer/post-create.sh。而后置脚本 .devcontainer/post-create.sh 承担了自动装环境 装开发者工具链的职责pip install python-dotenv pip install openai # 与 .github/workflows/code-quality.yml 中的检查对齐便于贡献者本地复现 CI pip install ruff black mypy pytest即容器内会自动完成环境依赖安装 → 安装python-dotenv、openai→ 再装rufflint、black格式化、mypy类型检查、pytest测试四个与仓库 CI 保持一致的开发者工具。此外仓库在 .devcontainer/environment.yml 中准备了真实的 Conda 环境声明见第 5 节镜像的 VS Code 侧还预置了 Python / Pylance / Jupyter / Black / Ruff / ESLint / Prettier / GitHub Copilot 等扩展并开启editor.formatOnSave与各语言的默认格式化器——这些设置都能在devcontainer.json的customizations.vscode段第 16~38 行中逐一核对。⚠️ 注意如果你同时启用了方案 A 的 venv 和方案 B 的容器VS Code 会反复提示重新打开排障见第 9 节。5. 方案 CMinicondaConda 虚拟环境Miniconda 是 Conda 的精简安装器用来安装 Python 与基础包。Conda 本身是一个包管理器除了像pip一样管理 Python 包外还能创建并切换不同的 Python 虚拟环境并且能安装一些pip中拿不到的包。5.1 Step 0安装 Miniconda 并确认版本按 Miniconda 官方命令行安装说明装好后执行conda --version能输出版本号即安装成功。5.2 Step 1创建环境文件environment.yml新建一个environment.yml。若你在 Codespaces 中跟随本课则把该文件建在仓库的.devcontainer目录内即.devcontainer/environment.yml。5.3 Step 2填写环境文件把下面这段写入你的environment.yml其中environment-name、python-version需替换为实际值name: environment-name channels: - defaults - microsoft dependencies: - pythonpython-version - openai - python-dotenv - pip - pip: - azure-ai-ml字段含义说明name环境名Conda 用它区分多个虚拟环境channels包源其中microsoft通道用于拉取微软出品的 AI 库如azure-ai-mldependencies直接依赖pythonpython-version可以精确锁 Python 大版本例如python3.10.0嵌套的pip:段允许 Conda 环境内再通过 pip 安装纯 PyPI 包这里即azure-ai-ml。仓库自身在 .devcontainer/environment.yml 使用的真实声明可作为参考模板name: dev channels: - defaults dependencies: - python3.10.0 - openai - python-dotenv - pip - pip: - azure-ai-inference注意仓库实际文件锁定的是python3.10.0并在 pip 段使用azure-ai-inference对接 Foundry 推理与本文档演示的azure-ai-ml略有差异——你可以按自己的任务需求取舍。5.4 Step 3创建并激活 Conda 环境conda env create --name ai4beg --file .devcontainer/environment.yml # 其中的 .devcontainer 子路径仅适用于 Codespace 配置 conda activate ai4beg--name ai4beg会在environment.yml的name之外显式指定环境名为ai4beg若在 Codespaces 中文件路径带.devcontainer前缀创建或激活遇到问题时可参考 Conda 官方环境管理文档排查换源、清缓存、删除后重建环境通常能解决大多数问题。6. 方案 D经典 Jupyter / Jupyter Lab浏览器内运行适合谁喜欢经典 Jupyter 界面、或不想借助 VS Code 运行 Notebook 的任何人。6.1 启动 Jupyter在终端/命令行进入课程目录后执行jupyter notebook或jupyterhubJupyter 实例启动后访问地址URL会直接打印在命令行窗口中。6.2 打开 Notebook在浏览器打开该 URL 后你应能看到课程总览并能导航到任意*.ipynb文件例如仓库中的 08-building-search-applications/python/oai-solution.ipynb。这门课的 21 个课程目录内分布着大量按python/、js-githubmodels/、typescript/等组织好的练习与解答 Notebook浏览器里逐级点进去即可运行。 提示本方案不会自动创建虚拟环境建议先按方案 A 或 C 装好解释器与依赖含ipywidgets等内核依赖再启动 Jupyter以免内核报缺包。7. 配置 API 密钥.envpython-dotenv关键步骤勿省略构建任何 AI 应用前安全存放 API 密钥都至关重要。强烈不建议把密钥硬编码进代码——一旦提交到公开仓库既埋下安全风险也可能因被恶意盗用而产生不必要的费用。下面以创建.env文件并向 Python 应用注入密钥为例给出完整可复现的六步流程。Step 1进入项目目录打开终端cd到你希望创建.env的项目根目录cd path/to/your/projectStep 2创建.env文件Unix 系macOS/Linux用touchWindows 用echo# Unix touch .env:: Windows echo . .envStep 3编辑.env文件用 VS Code、Notepad 等编辑器打开.env写入下面这行并把占位符换成你的真实令牌GITHUB_TOKENyour_github_token_hereStep 4保存文件并关闭编辑器。Step 5安装python-dotenv若尚未安装通过 pip 安装课程根 requirements.txt 已锁定python-dotenv1.2.2也可统一执行pip install -r requirements.txtpip install python-dotenvStep 6在 Python 脚本中加载环境变量from dotenv import load_dotenv import os # 从 .env 文件加载环境变量 load_dotenv() # 访问 GITHUB_TOKEN 变量 github_token os.getenv(GITHUB_TOKEN) print(github_token)运行后能打印出你的令牌值即表示.env→ Python 的链路已经打通。永远不要 commit.env文件——它已被仓库根部的 .gitignore 忽略这也解释了为什么仓库里只有供复制用的模板 .env.copy而没有真实的.env。7.1 与仓库实际模板的衔接.env.copy才是全量变量清单本译文演示的是最通用的密钥注入机制GITHUB_TOKEN。而仓库真正随课程演进的全量模板在 .env.copy 中它覆盖了本课程 21 节课会用到的所有提供商首次配置时建议直接照抄并按需填值# 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 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 ## Microsoft Foundry Models多提供商模型目录一套端点/密钥覆盖 OpenAI、Meta、Mistral 等 AZURE_INFERENCE_ENDPOINTadd your Foundry project endpoint here AZURE_INFERENCE_CREDENTIALadd your Foundry Models API key here ## Hugging Face HUGGING_FACE_API_KEYadd your HuggingFace API or token here配置完成后即可进入课程正文——不同作业文件会根据文件名后缀oai、aoai、hf等读取对应的密钥。完整的提供商选型与注册指引见本目录配套文档 translations/et/00-course-setup/03-providers.md其中列出了 OpenAI / Azure OpenAI / Hugging Face 三种提供商以及.env变量含义对照表按模板做法直接cp .env.copy .env再逐项填空是最不容易出错的方式。 需要留意的版本差异英文原版 00-course-setup/02-setup-local.md 的第 3 节已注明 GitHub Models 及其GITHUB_TOKEN将于 2026 年 7 月底退役并将示例切换为 Microsoft Foundry 的AZURE_INFERENCE_ENDPOINT/AZURE_INFERENCE_CREDENTIAL。因此GITHUB_TOKEN的六步流程在本译文里用于演示通用的密钥注入机制而对接新课程实践时请以 .env.copy 中 Foundry/Azure 变量为准两者并不冲突。8. 接下来做什么我想……请前往……开始第 1 课translations/et/01-introduction-to-genai/README.md配置 LLM 提供商translations/et/00-course-setup/03-providers.md与其他学习者交流加入课程社区本课配套 Discord 频道如果前面四个方案你都不太确定推荐顺序是先 A最快需要与团队/Codespaces 保持一致性时再切 B追求多语言环境或pip之外的包时选 C纯 Notebook 重度用户选 D。9. 常见问题排查Troubleshooting症状解决方案python not found安装后将 Python 加入 PATH或安装完成后重新打开终端再试pip无法构建 wheelWindows先执行pip install --upgrade pip setuptools wheel再重试安装ModuleNotFoundError: dotenv说明该环境没装过依赖执行pip install -r requirements.txtDocker 构建失败报No space leftDocker Desktop ▸Settings▸Resources→ 增大磁盘配额VS Code 一直提示重新打开容器你可能同时启用了两个方案二选一即可venv或containerOpenAI 报 401 / 429 错误检查OPENAI_API_KEY取值是否正确 / 是否触发请求速率限制使用 Conda 时报错用conda install -c microsoft azure-ai-ml安装 Microsoft AI 相关库除上表外补充两条仓库相关的自查建议确认没有误提交密钥git status后若发现.env出现在待提交列表说明本地 .gitignore 规则未生效应先修复再提交排查依赖来源本课所有 Python 依赖以根 requirements.txt 为唯一事实源报缺包时优先与它比对版本而不是随手pip install latest以免版本漂移导致课程示例行为不一致。⚠️ 仓库为只读本文所有操作克隆到本地、创建 venv/容器、编辑你自己的.env、运行 Notebook都应在你自己的工作副本中完成。10. 小结完成本地搭建后你的工作台应当具备四件事一个可运行的 Python 环境venv / 容器 / Conda 三选一或更多、一份来自根 requirements.txt 的完整依赖、一份基于 .env.copy 生成的私密.env密钥文件以及一条通往 第 1 课 的路径。之后无论跑01-introduction-to-genai起步课程还是跳到08-building-search-applications之类的实战课都能直接进入正文、免去反复折腾环境的时间。【免费下载链接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考