generative-ai-for-beginners 本地环境搭建指南:四套可选的开发方案与密钥安全配置

发布时间:2026/10/29 0:48:42

generative-ai-for-beginners 本地环境搭建指南:四套可选的开发方案与密钥安全配置 generative-ai-for-beginners 本地环境搭建指南四套可选的开发方案与密钥安全配置【免费下载链接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginnersgenerative-ai-for-beginners是微软推出的 21 课生成式 AI 入门课程仓库各章节同时提供 Python 代码、Jupyter Notebook 与 TypeScript/JavaScript 示例。本文面向希望在自己的笔记本上离线运行全部课程代码的开发者系统讲解从「克隆仓库」到「密钥安全注入」的完整本地配置流程官方提供了两条主线——(A) 原生 Python venv 与 (B) VS Code Dev ContainerDocker另有 (C) Miniconda 与 (D) 经典 Jupyter 两条进阶路径。读完本文你将掌握四种环境的搭建方法、仓库依赖清单的真实含义以及使用.env文件安全加载 API 凭据的正确姿势从而平滑接续后续每一课的动手练习。1. 前置条件确认本机工具链在开始前请确认以下工具已安装到你的机器上。下表来自课程官方本地配置文档 translations/el/00-course-setup/02-setup-local.md 与 00-course-setup/02-setup-local.md英文原文两文结构一致工具版本 / 说明Python3.10 及以上从 python.org 官方渠道下载Git最新版macOS 随 Xcode、Windows 用 Git for Windows、Linux 用发行版包管理器VS Code可选但强烈推荐Docker Desktop仅方案 B 需要免费安装提示安装完毕后建议先在终端里验证工具是否可用python --version、git --version、docker --version、code --version值得补充的是「Python 3.10」并非随意设定仓库根目录的 pyproject.toml 中requires-python 3.10且开发工具链black、mypy 等的 target-version 均指向 py310 及以上因此 3.10 是本仓库实际支持的基线版本。2. 方案 A原生 Python 虚拟环境最快捷如果你希望环境最轻、启动最快优先选择本方案。它不依赖 Docker只依赖本机 Python。步骤 1克隆仓库课程要求先 fork 再克隆便于你提交自己的练习代码随后进入仓库根目录git clone https://github.com/your-github/generative-ai-for-beginners cd generative-ai-for-beginners其中your-github请替换为你自己的 GitHub 用户名fork 流程详见 00-course-setup/README.md。步骤 2创建并激活虚拟环境Python 官方虚拟环境工具venv能在项目目录内隔离出一份独立依赖避免污染全局 Pythonpython -m venv .venv # 创建虚拟环境 source .venv/bin/activate # macOS / Linux 激活 .\.venv\Scripts\activate # Windows PowerShell 激活✅ 激活成功的标志是命令行提示符前缀出现(.venv)——这表示你已经进入了该虚拟环境。步骤 3安装依赖在激活状态下执行pip install -r requirements.txt仓库根目录的 requirements.txt 实际内容如下截至当前仓库版本可见它既覆盖了主流 LLM 交互与可视化也包含了 Notebook 运行所需的组件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若希望进入课程开发/贡献模式还可以按 pyproject.toml 中的dev可选依赖安装代码质量工具black、isort、mypy、ruff、pytest它们与本仓库 CI 的检查项保持一致。安装完成后即可跳到下文第 6 节配置 API 密钥。3. 方案 BVS Code Dev ContainerDocker本仓库自带一个基于「Universal 运行时镜像」的 development container可同时支持 Python 3、.NET、Node.js 与 Java 开发。使用该方案的收益是与 GitHub Codespaces 完全一致的环境彻底消除依赖漂移dependency drift。步骤 0安装额外组件安装 Docker Desktop并确认docker --version能正常输出安装 VS Code 扩展Remote – Containers扩展 IDms-vscode-remote.remote-containers。步骤 1在 VS Code 中打开仓库File ▸ Open Folder…选择generative-ai-for-beginners目录。VS Code 会检测到仓库根目录下的.devcontainer/文件夹并自动弹出提示。步骤 2在容器中重新打开点击弹窗中的Reopen in ContainerDocker 将基于 .devcontainer/devcontainer.json 构建镜像——首次构建约需 3 分钟。当终端提示符出现时你就已经位于容器内部了。为什么优先考虑它与 Codespaces 环境完全一致多人协作、提交 PR 时不会出现「我这能跑你那跑不了」的依赖偏差。关于这套配置仓库里的 .devcontainer/devcontainer.json 给出了源码级细节值得解读基础镜像为mcr.microsoft.com/devcontainers/universal:2.13因此容器内同时具备 Python 3 / .NET / Node.js / Java 运行时hostRequirements.cpus 4即 Docker 至少为该容器预留 4 个 CPU 核心updateContentCommand会在内容更新时执行python3 -m pip install -r requirements.txt保证依赖自动就位postCreateCommand调用 .devcontainer/post-create.sh该脚本额外补装python-dotenv、openai以及ruff black mypy pytest等开发工具customizations.vscode预装了 Python、Pylance、Jupyter、Black Formatter、Ruff、ESLint、Prettier 与 GitHub Copilot 扩展并开启editor.formatOnSave其中 Python 默认格式化器为 black、JS/TS 为 Prettier——打开仓库即可获得开箱即用的格式化体验。4. 方案 CMiniconda / CondaMiniconda 是一个轻量级安装器用于安装 Conda、Python 及若干常用包。Conda 本身是包管理器擅长创建与切换不同的 Python 虚拟环境尤其适合安装pip无法提供的二进制/平台相关包本课程场景中的azure-ai-ml即属此类可通过 Microsoft 频道获取。步骤 0安装 Miniconda按官方安装向导完成安装后验证conda --version步骤 1创建环境描述文件新建一个environment.yml文件。如果是在 Codespaces 中跟随操作请将其放在.devcontainer目录内即.devcontainer/environment.yml本仓库根目录已存在一份由官方维护的真实范例可直接对照参考 .devcontainer/environment.yml其中name: dev、Python 锁定为 3.10.0并包含openai、python-dotenv与 pip 安装的azure-ai-inference。步骤 2填写环境文件课程文档给出的模板如下name: environment-name channels: - defaults - microsoft dependencies: - pythonpython-version - openai - python-dotenv - pip - pip: - azure-ai-ml字段含义name环境名称自由指定channels软件源其中microsoft用于拉取azure-ai-ml等微软 AI 库dependenciespythonpython-version用你想要的 Python 版本号替换如3.10openai与python-dotenv为课程代码核心依赖pip:子段声明只能从 PyPI 获取的包如azure-ai-ml。步骤 3创建并激活 Conda 环境conda env create --name ai4beg --file .devcontainer/environment.yml # .devcontainer 子路径仅适用于 Codespace 场景 conda activate ai4beg提示若在 Conda 安装微软 AI 库时遇到错误可直接执行conda install -c microsoft azure-ai-ml手工补装详见下文的故障排查表。5. 方案 D经典 Jupyter / Jupyter Lab浏览器内运行适用人群偏爱传统 Jupyter 交互、或不希望依赖 VS Code 即可运行 Notebook 的开发者。步骤 1启动 Jupyter在终端导航到课程目录后执行jupyter notebook或jupyterhubJupyter 实例启动后访问 URL 会显示在命令行窗口中。进入页面后即可看到课程大纲并导航到任意*.ipynb文件例如课程 08 的完整可运行解答 08-building-search-applications/python/oai-solution.ipynb该文件在本仓库中真实存在覆盖向量搜索/嵌入检索全流程。各章 Notebook 都位于对应课程的python/目录下例如 04-prompt-engineering-fundamentals/python/。6. 配置 API 密钥用.env文件安全托管凭据无论选择以上哪种环境构建任何调用 LLM 的应用前都必须妥善保管 API 密钥。切勿把密钥硬编码进代码——提交到公开仓库可能造成安全问题甚至被恶意使用者刷出巨额费用。推荐的做法在本项目根目录创建.env文件该文件已被 .gitignore 忽略不会进入版本控制按以下步骤完成密钥注入。步骤 1进入项目根目录cd path/to/your/project步骤 2创建.env文件Unix 系系统用touchWindows 用echotouch .envWindowsecho . .env步骤 3编辑文件并写入凭据用 VS Code、Notepad 等文本编辑器打开.env将占位符替换为真实值GITHUB_TOKENyour_github_token_here步骤 4保存文件保存更改并关闭编辑器。步骤 5安装python-dotenvpython-dotenv用于把.env中的变量加载为 Python 进程的环境变量。若尚未安装pip install python-dotenv该依赖同时已被 requirements.txt版本锁定python-dotenv1.2.2与 pyproject.tomlpython-dotenv1.0.0声明因此方案 A 安装依赖后通常无需重复安装。步骤 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 应用中加载了它。仓库中的安全实践佐证密钥「只进环境变量、绝不入库」在本仓库并非停留在口头约定而是有工程实现支撑课程代码广泛使用os.getenv(...)/os.environ[...]读取密钥仓库还封装了共享工具 shared/python/env_utils.py其中的get_required_env(var_name, description)会在关键环境变量缺失时抛出带提示的ValueError如Missing required environment variable: ... Please set it in your .env file or environmentvalidate_env_vars(*var_names)则支持一次性批量校验多个变量——这正是在 Notebook 里「没配密钥先报错、配置完即可跑通」的原因根目录存在一份 .env.copy 模板也是 00-course-setup/03-providers.md 官方文档推荐的做法把模板复制为.env后再填写能避免手写变量名出错cp .env.copy .env关于凭据变量的最新变化当前英文原版文档 00-course-setup/02-setup-local.md 已更新为 Microsoft Foundry Models 凭据变量AZURE_INFERENCE_ENDPOINT与AZURE_INFERENCE_CREDENTIAL因为 GitHub Models及其GITHUB_TOKEN预计于 2026 年 7 月底退役.env.copy中还提供了 OpenAIOPENAI_API_KEY、Azure OpenAIAZURE_OPENAI_*与 Hugging FaceHUGGING_FACE_API_KEY等多套占位变量。完整的多 Provider 申请、取值与配置指引见 providers.md。再次强调永远不要提交.env——它已被仓库的 .gitignore 忽略如自行改动务必保持忽略规则不变。7. 下一步做什么环境就绪后可按需求导航到对应内容我想……前往……开始第 1 课01-introduction-to-genai配置一个 LLM Providerproviders.md系统学习各课并查看全部章节课程根目录 README.md8. 故障排查无论选择哪条路径都可能遇到环境类问题。课程文档整理了一张对症速查表症状修复方法python not found将 Python 加入 PATH或安装后重新打开终端pip无法构建 wheelsWindows执行pip install --upgrade pip setuptools wheel后重试ModuleNotFoundError: dotenv执行pip install -r requirements.txt说明虚拟环境未正确安装依赖Docker 构建失败No space leftDocker Desktop ▸Settings▸Resources增大磁盘配额VS Code 反复提示在容器中重新打开你可能同时启用了两种方案请只保留一种venv或containerOpenAI 401 / 429 错误检查OPENAI_API_KEY取值是否正确 / 是否触发请求速率限制Conda 使用报错用conda install -c microsoft azure-ai-ml安装微软 AI 库若环境长时间卡住尤其容器构建超过 10 分钟可优先执行Rebuild ContainerNotebook 内核缺失时在 Notebook 菜单中执行Kernel ▸ Select Kernel ▸ Python 3即可详见 00-course-setup/README.md 的故障排查小节。小结本文完整覆盖了在本地运行generative-ai-for-beginners课程的四条路径venv 最快、Dev Container 最一致、Conda 最擅长管理非 pip 依赖、Jupyter 最贴近 Notebook 原生体验。四条路径殊途同归——它们最终都会落到同一套仓库代码与同一个.env凭据机制上。你可以先选最顺手的一条跑通第 1 课再回到 providers.md 配置你偏好的模型供应商开启完整的生成式 AI 动手之旅。【免费下载链接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
延伸阅读

更多相关文章

2026/10/25 22:16:15

SOF源码编译与topology定制:从固件到管线部署全流程解析

先把丑话说在前面:SOF 的源码编译链路和普通内核模块完全不是一个量级,很多人卡住不是卡在 make 那句命令,而是卡在“固件编出来了、topology 也生成了、放进去却不生效”这个阶段。 这里说的 SOF 是 Sound Open Firmware,Inte…

2026/10/27 10:10:22

RISC-V自定义饱和加法指令工具链适配:从汇编器到GCC实践

先交代背景。我们自研的RISC-V内核在性能评审时被提了一个需求:算法模块缺一条有符号饱和加法,RTL 层面加指令只花了两周,真正卡住我的是后续验证——汇编器不认识新助记符,编译器不知道该怎么生成这条指令,模拟器更是…

2026/10/29 0:43:45

绿豆7.0木白动态域名版JAVA影视源码部署指南

简介:这是一套面向影视类APP开发者的高功能完整性源码,专为快速构建iOS端原生JAVA影视应用而设计,适用于具备Android Studio开发经验的中高级开发者,解决从零搭建支持广告变现、多终端播放与用户运营体系的影视平台难题。资源共20…

2026/10/29 0:43:44

信号与系统入门:从信号分类到线性时不变系统核心概念解析

简介:这份《信号与系统》第一章课件面向电子类专业学生及备考复习者,聚焦课程开篇的基本概念与分析方法,帮助读者建立信号分类、运算与系统描述的入门框架。压缩包内共1个PPT文件,约1.29MB,以电子教案形式呈现&#xf…

2026/10/29 0:43:44

医院挂号小程序毕业设计:SSM+MySQL与微信小程序全栈实践

简介:微信小程序与SSM后台结合的医院挂号系统毕业设计资源,面向计算机及相关专业毕业生、需要快速搭建完整项目的开发者。项目覆盖患者、医生、科室、专家、预约与取消预约申请等核心模块,后台基于SSM框架,数据库采用MySQL&#x…

2026/10/29 0:38:44

系统接口设计对接方案:协议选型、规范设计与安全验收

简介:围绕系统与外部系统之间如何对接这一工程难题,这份系统接口设计对接方案面向系统架构师、后端开发与集成实施人员,梳理从对接方式选型到接口规范落地的完整思路。内容以SOA体系架构与服务总线为主线,依次说明服务目录标准&am…

2026/10/28 14:42:12

全国计算机二级C语言真题PDF高效刷题指南

简介:这份PDF是全国计算机二级C语言考试的试题与答案解析,专为备考二级C语言的考生准备。内容涵盖C语言特点与设计理念、程序基本组成单位、main函数执行流程、函数嵌套调用规则、标识符命名规范、整型实型字符型数据类型、八进制十六进制数合法形式、运…

2026/10/28 15:28:56

requests+BeautifulSoup:爬虫抓取h1标题的入门实战指南

简介:一份以实战为导向的Python爬虫入门资源,面向具备基本编程基础、希望快速掌握网络数据抓取的初学者,可解决从零编写简单爬虫的常见困惑。实例以requests库发送HTTP请求、BeautifulSoup解析HTML文档,完整演示从网页中提取 标题…

2026/10/28 3:32:29

递推最小二乘参数辨识MATLAB编程:二阶系统与渐消记忆实现

简介:这是一篇面向控制系统、信号处理与机器学习等领域学习者的最小二乘参数辨识程序说明文档。资源共包含一个docx格式文档,压缩包大小七十八KB,内容围绕递推最小二乘算法和渐消记忆最小二乘算法展开:先构造一个极点位于单位圆内…

2026/10/29 0:03:42

学生选课系统DFD图绘制指南:边界划分与分层校验实战

简介:文档以顶层与第一层DFD图为核心,完整刻画学生选课系统的逻辑模型,面向软件工程课程设计、系统分析学习及毕设前期建模人群。顶层图界定系统边界,外部实体包括管理员、教师和学生三类角色;第一层图进一步细化用户登…

2026/10/29 0:03:42

JIRA敏捷落地:Scrum角色权限、Sprint与燃尽图避坑指南

简介:围绕“基于JIRA的敏捷开发项目管理”这一主题,面向产品负责人、Scrum Master及研发测试成员,梳理Scrum角色分工、迭代流程与JIRA工具配置的对应关系,适合初、中级团队导入敏捷管理时参考。压缩包共1个docx文件,大…

2026/10/29 0:03:42

SEMI S8人机工程验收实战:从条款拆解到现场实测的完整指南

简介:面向半导体设备设计、制造与运维工程师及安全合规人员,这份资料聚焦SEMI标准体系下的设备安全规范,重点收录SEMI S8-0308《半导体制造设备人体工程学工程安全指南》。内容围绕设备设计原则、错误与事故预防、人体工程学适配三大主线展开…

还想了解更多?直接咨询顾问

免费诊断 + 免费方案 + 透明报价。

全国咨询热线400-8866-253
免费获取方案
☎咨询二维码 ☎ ↑