尧图网站设计 尧图网站设计YAOTU DESIGN
ARTICLE DETAIL

资讯详情

深耕网站设计与一线实操的经验洞察。

generative-ai-for-beginners 课程环境搭建完全指南:从 Fork 仓库、Codespaces 到 .env 密钥配置

generative-ai-for-beginners 课程环境搭建完全指南:从 Fork 仓库、Codespaces 到 .env 密钥配置 generative-ai-for-beginners 课程环境搭建完全指南从 Fork 仓库、Codespaces 到 .env 密钥配置【免费下载链接】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 仓库的课程设置文档00-course-setup/README.md 及其孟加拉语翻译版 translations/bn/00-course-setup/README.md整理完整覆盖课程上手所需的三类技术能力使用 GitHub Codespaces 在云端一键拉起开发环境并安全注入 API 密钥、在本地机器上搭建 Python或 Miniconda/Jupyter/容器运行环境、以及按仓库统一约定配置.env环境变量文件。读完并照做后你可以独立排除课程中常见的启动故障并顺利进入第一课学习生成式 AI 与 LLM 的基础概念。需要说明的一点translations/bn/00-course-setup/README.md 是通过 Co-op Translator 机器翻译服务生成的孟加拉语版本其页脚免责声明明确指出原文档才是权威来源重要信息建议以英文原版为准。下文在忠实呈现该文档全部操作内容的同时结合仓库当前实际状态如 requirements.txt、pyproject.toml、.devcontainer/ 与 shared/python/ 下的工具代码补充了可验证的实现细节。设置步骤总览Fork、Codespaces 与 Secrets要开始学习这门 21 课涵盖概念课与编码课的生成式 AI 课程需要依次完成三步设置。1. Fork 整个仓库第一步是把整个仓库 Fork 到你自己的 GitHub 账号下这样你才有权限修改任何代码、完成课程中的各项挑战challenge。同时建议给仓库加一颗 Star方便日后快速找到本仓库及相关仓库。2. 创建 Codespace为避免运行代码时遇到任何依赖问题官方推荐使用 GitHub Codespaces 来运行本课程。在你的 Fork 中按Code → Codespaces → New on main的路径操作即可。2.1 添加一个 Secret密钥不要写进代码或.env文件而是用 Codespaces 的用户级 Secret 管理点击 ⚙️ 齿轮图标 → Command Palette → Codespaces: Manage user secret → Add a new secret变量名填写OPENAI_API_KEY粘贴你的密钥值点击 Save。这一做法在仓库的 00-course-setup/01-setup-cloud.md 中同样被列为推荐方案Option A Codespaces Secrets — Recommended并且补充说明个人账号每月有 120 core-hours / 60 GB-hours 的免费额度空闲时建议及时停止或删除 CodespaceView ▸ Command Palette ▸Codespaces: Stop Codespace以保护额度。3. 下一步去哪原文档给出的分流指引如下下表链接已转换为从仓库根目录出发的路径我想…去这里开始第 1 课01-introduction-to-genai离线/本地工作setup-local.md配置一个 LLM 提供商providers.md结识其他学习者加入课程官方 Discord 社区故障排查速查表课程文档内置了一张面向 Codespaces 环境的排障表覆盖容器构建、终端、鉴权、连接与 Notebook kernel 五类典型故障原表完整保留如下症状解决办法容器构建卡住超过 10 分钟Codespaces 菜单 ➜ Rebuild Containerpython: command not found终端未附加点击➜ 选择bashOpenAI 返回401 UnauthorizedOPENAI_API_KEY错误 / 已过期VS Code 显示 Dev container mounting…刷新浏览器标签页——Codespaces 偶尔会丢失连接Notebook kernel 缺失Notebook 菜单 ➜Kernel ▸ Select Kernel ▸ Python 3本地开发场景的补充排障项pip构建 wheel 失败、ModuleNotFoundError: dotenv、Docker 磁盘空间不足、venv 与容器双重提示等见 00-course-setup/02-setup-local.md 的 Troubleshooting 章节。创建.env文件并加载环境变量仓库统一约定无论用哪条运行路径课程代码统一约定不要把 API 密钥硬编码进代码而是写入.env文件再用python-dotenv在脚本中加载。原文档的六步操作流程如下。第 1–2 步创建.env文件。Unix 系系统Linux/macOStouch .envWindowsecho . .env第 3 步编辑.env。用任意文本编辑器VS Code、Notepad 等打开写入你的凭据。原文档以 GitHub Token 为例GITHUB_TOKENyour_github_token_here注意以仓库当前状态为准英文主文档 00-course-setup/README.md 已更新——GitHub Models及其GITHUB_TOKEN变量将于 2026 年 7 月底退役课程改用 Microsoft Foundry Models。当前 00-course-setup/03-providers.md 建议的.env内容包含以下变量根目录提供了预填占位符的 .env.copy 可直接cp .env.copy .env复制使用OPENAI_API_KEY—— OpenAI 服务的授权密钥AZURE_OPENAI_API_VERSION/AZURE_OPENAI_API_KEY/AZURE_OPENAI_ENDPOINT—— Azure OpenAI现已并入 Microsoft Foundry资源版本、密钥与端点AZURE_OPENAI_DEPLOYMENT/AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT—— 文本生成与向量嵌入两个模型部署名AZURE_INFERENCE_ENDPOINT/AZURE_INFERENCE_CREDENTIAL—— Microsoft Foundry Models 项目端点与密钥即替代GITHUB_TOKEN的两个变量HUGGING_FACE_API_KEY—— Hugging Face 访问令牌。.env已被.gitignore忽略切勿提交。第 4 步保存文件并关闭编辑器。第 5 步安装python-dotenv若尚未安装pip install python-dotenv这一点可以直接在仓库中得到印证requirements.txt 中固定了python-dotenv1.2.2pyproject.toml 的依赖清单同样声明了python-dotenv1.0.0。第 6 步在 Python 脚本中加载环境变量from dotenv import load_dotenv import os # 从 .env 文件加载环境变量 load_dotenv() # 访问变量当前仓库推荐读取 Foundry Models 两个变量 endpoint os.getenv(AZURE_INFERENCE_ENDPOINT) token os.getenv(AZURE_INFERENCE_CREDENTIAL) print(endpoint)源码印证课程代码如何安全读取这些变量从源码结构看仓库在 shared/python/env_utils.py 中封装了三个取值函数课程各练习代码统一经由它们读取上述变量而不是各自直接os.getenvget_required_env(var_name, description)env_utils.py#L11-L35读取单个必需变量缺失或为空时抛出带提示的ValueError错误信息明确要求Please set it in your .env file or environmentvalidate_env_vars(*var_names)env_utils.py#L38-L71一次校验多个变量把所有缺失项汇总后一并报错get_env_with_default(var_name, default)env_utils.py#L74-L88带默认值读取例如MODEL_NAME缺省回退。这些行为有配套的单测保障见 tests/test_env_utils.py。客户端构造侧shared/python/api_utils.py 的create_azure_openai_clientapi_utils.py#L91-L144会优先读取AZURE_OPENAI_ENDPOINT与AZURE_OPENAI_API_KEY两个环境变量并将请求基址拼接为endpoint/openai/v1/create_openai_clientapi_utils.py#L56-L88则读取OPENAI_API_KEY缺失时抛出明确的ValueError。这也解释了排障表中401 Unauthorized 密钥错误/过期的判定逻辑鉴权失败几乎都发生在客户端构造或首请求阶段。如何在自己的电脑上本地运行在本地机器上运行代码前提是安装任意一个受支持的 Python 版本——注意仓库 pyproject.toml 声明requires-python 3.10并且 classifiers 中明确面向 3.10 / 3.11 / 3.12。然后用 git 克隆仓库git clone https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners cd generative-ai-for-beginners克隆完成后即可开始。进入课程目录后推荐先安装仓库声明的依赖使环境与 requirements.txt 对齐其中含openai1.12.0、python-dotenv1.2.2、azure-ai-inference、tiktoken、scikit-learn等覆盖文本、嵌入与图像课所需的库pip install -r requirements.txt00-course-setup/02-setup-local.md 还给出了一条更稳妥的路径先创建并激活 venvpython -m venv .venvLinux/macOS 用source .venv/bin/activateWindows PowerShell 用.\.venv\Scripts\activate再安装依赖避免污染系统 Python。可选路径 A安装 Miniconda原文档将 Miniconda 列为可选方案它是安装 Conda、Python 及少量包的轻量安装器。Conda 本身是包管理器方便创建与切换不同的 Python 虚拟环境也能安装pip上不可用的包。安装好 Miniconda 后若还没克隆则先克隆仓库下一步是创建虚拟环境新建一个环境文件environment.yml。如果在 Codespaces 中操作应把它放在.devcontainer目录内即.devcontainer/environment.yml仓库当前确实提供了 .devcontainer/environment.yml 与 .devcontainer/devcontainer.json。原文档给出的环境文件内容如下两个尖括号占位符分别填环境名如ai4beg与 Python 版本如3表示最新主版本name: environment-name channels: - defaults - microsoft dependencies: - pythonpython-version - openai - python-dotenv - pip - pip: - azure-ai-ml然后在命令行执行conda env create --name ai4beg --file .devcontainer/environment.yml # .devcontainer 子路径仅适用于 Codespace 设置 conda activate ai4beg如果 Conda 过程中报错可在终端手动安装 Microsoft AI 库作为兜底conda install -c microsoft azure-ai-ml可选路径 BVS Code Python 支持扩展课程推荐使用 Visual Studio Code 编辑器配合其 Python 支持扩展。需要强调这是建议而非硬性要求。原文档给出三条实践提示在 VS Code 中打开课程仓库时会提示把项目设置到容器内运行——这正是仓库里特殊的 .devcontainer 目录的作用克隆并在 VS Code 中打开目录后编辑器会自动建议安装 Python 支持扩展若 VS Code 建议在容器中重新打开仓库请选择拒绝以使用本地安装的 Python。仓库还附带了 vs.code-profile 配置文件可进一步还原课程作者推荐的工作区配置。可选路径 C在浏览器中使用 Jupyter也可以完全在浏览器里用经典 Jupyter 或 Jupyter Hub 开发二者都提供自动补全、代码高亮等体验。在终端进入课程目录后执行jupyter notebook或jupyterhub启动后命令行窗口会打印访问 URL打开即可看到课程大纲并能导航到任意*.ipynb文件例如 08-building-search-applications/python/oai-solution.ipynb。可选路径 D在容器中运行在本地或 Codespace 里手工配置一切之外还有一种选择是使用容器。课程仓库的 .devcontainer/ 目录让 VS Code 能够把项目直接搭建进容器。除了 Codespaces本地跑容器需要安装 Docker且配置有一定工作量因此原文档建议仅推荐给有容器使用经验的学习者。使用 GitHub Codespaces 时保护 API 密钥的最佳方式之一是用 Codespace Secrets 管理凭据。00-course-setup/02-setup-local.md 的 Option B 同样基于这套devcontainer.json机制并强调其价值在于与 Codespaces 环境完全一致无依赖漂移。课程结构与技术要求课程包含 6 节概念课与 6 节编码课后续章节逐步扩展到 21 课。编码课使用 Azure OpenAI 服务运行这些代码需要 Azure OpenAI 服务访问权限和一个 API 键可通过官方申请入口提交申请获取。在等待申请处理期间每个编码课目录下都附带了README.md可以直接查看代码与示例输出不必等到服务开通才能学习。首次使用 Azure OpenAI 服务与 OpenAI API原文档为两类首次使用者各给了一条入门指引首次使用 Azure OpenAI 服务按官方创建并部署 Azure OpenAI 服务资源的门户向导操作拿到资源端点、密钥与模型部署00-course-setup/03-providers.md 进一步细化了操作——在 Azure 门户侧边栏点击Keys and Endpoint → Show Keys取得 KEY 1 与 Endpoint再经Model deployments进入 Microsoft Foundry 门户查看部署名课程建议的部署组合是文本生成用gpt-4o-mini、文本嵌入用text-embedding-3-small首次使用 OpenAI API按 OpenAI 平台的 Quickstart 指引创建并使用接口取得密钥后填入.env的OPENAI_API_KEY。结识其他学习者课程团队在官方 AI Community Discord 服务器中为学员开设了专门频道这是结识志向相同的创业者、构建者、学生和所有想提升生成式 AI 技能的人的好渠道项目团队成员也会在该服务器中为学员答疑。贡献指南本课程是开源项目。如果你看到可改进之处或问题可以创建 Pull Request 或提交 GitHub issue项目团队会跟踪所有贡献。大多数贡献需要同意 CLAContributor License Agreement声明你有权授予项目使用你的贡献的权利提交 PR 后 CLA-bot 会自动判断并添加相应标签或评论按机器人指引操作即可且整个 CLA 体系只需完成一次。该项目采用 Microsoft 开源行为准则疑问可按 FAQ 处理或联系项目方。特别提示原文档加粗强调为仓库翻译时请勿使用机器翻译。翻译将由社区校验因此只为你熟练掌握的语言报名做翻译志愿者——这一点从本仓库 translations/ 目录覆盖 40 余种语言的规模上也可以看出对翻译质量的重视。让我们开始完成上述准备后就可以从 01-introduction-to-genai 这一课开始正式进入生成式 AI 与 LLM 的世界。【免费下载链接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表