十年匠心定制 · 商业建站与技术教学双线并行 咨询热线:400-886-1026 service@lmnt.cn
ARTICLE DETAIL

资讯详情

深耕网站建设与运营推广的一线实战洞察。

generative-ai-for-beginners 本地开发环境搭建指南:四条路径与 API 密钥安全实践

generative-ai-for-beginners 本地开发环境搭建指南:四条路径与 API 密钥安全实践 generative-ai-for-beginners 本地开发环境搭建指南四条路径与 API 密钥安全实践【免费下载链接】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 节课、跨 Python/JavaScript/TypeScript/.NET 的多语言代码示例的学习者系统讲解从零搭建本地运行环境的四种方案原生 Python venv、VS Code Dev Container、Miniconda、经典 Jupyter以及安全配置 LLM API 密钥的完整流程。读完本文你将掌握克隆仓库、创建隔离环境、安装全部依赖、加载.env密钥并在 Notebook 中运行课程示例如08-building-search-applications/python/oai-solution.ipynb的完整实战能力。本指南对应仓库文档 translations/lt/00-course-setup/02-setup-local.md同时结合仓库根目录的.devcontainer/、requirements.txt、00-course-setup/03-providers.md 与共享工具源码进行印证与扩充。1. 前置条件确认工具链已就绪无论选择哪种方案以下工具都是必需或推荐的。先在终端中运行验证命令确保它们可用工具版本 / 说明验证命令Python3.10 及以上从 python.org 获取python --versionGit最新版macOS 自带、Git for Windows 或 Linux 包管理器安装git --versionVS Code可选但强烈推荐code.visualstudio.comcode --versionDocker Desktop仅方案 B 需要免费安装docker --version提示安装 Python 后若终端仍提示python not found请将 Python 加入 PATH或重新打开终端后再验证。2. 方案 A原生 Python 虚拟环境最快上手这是最快、依赖最少的一条路径适合只想跑通课程 Notebook、不引入 Docker 的学习者。第 1 步克隆仓库git clone https://github.com/your-github/generative-ai-for-beginners cd generative-ai-for-beginners建议先 Fork 仓库再克隆你自己的副本以便自由修改代码、完成课后挑战。第 2 步创建并激活虚拟环境python -m venv .venv # 创建虚拟环境 source .venv/bin/activate # macOS / Linux .\.venv\Scripts\activate # Windows PowerShell✅ 激活成功后命令行提示符前缀会变为(.venv)表示你已进入隔离环境后续pip安装不会污染系统 Python。第 3 步安装依赖pip install -r requirements.txt仓库根目录的 requirements.txt 实际锁定的依赖包括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-dotenv用于加载.env密钥openai与azure-ai-inference分别对应 OpenAI 与 Azure 系推理端点tiktoken用于 token 计数演示第 1、4 课会用到。依赖安装完成后直接跳到第 5 节配置 API 密钥即可开始。3. 方案 BVS Code Dev ContainerDocker本仓库与课程配套开发容器配置在根目录.devcontainer/文件夹中核心文件为 .devcontainer/devcontainer.json。它采用mcr.microsoft.com/devcontainers/universal:2.13通用运行时镜像开箱支持Python3、.NET、Node.js 和 Java开发与 GitHub Codespaces 使用完全一致的环境从根本上避免“在我机器上能跑”的依赖漂移问题。为什么选这个方案与 Codespaces 环境完全一致不存在依赖不一致适合需要同时编写 Python 与 JS/TS 代码如第 6、7、8 课的js-githubmodels/与typescript/示例的学习者。第 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 开始构建镜像首次约需 3 分钟。当终端提示符出现时即表示你已进入容器。构建过程中会依次执行两条关键命令见 devcontainer.jsonupdateContentCommandpython3 -m pip install -r requirements.txt同步安装课程全部 Python 依赖postCreateCommandbash .devcontainer/post-create.sh见 .devcontainer/post-create.sh该脚本补充安装python-dotenv、openai以及代码质量工具链ruff black mypy pytest——这些正是.github/workflows/code-quality.yml中 CI 校验所跑的同一套工具让贡献者在本地即可复现 PR 检查。容器预置的 VS Code 扩展customizations.vscode.extensions包括ms-python.python、ms-python.vscode-pylance、ms-toolsai.jupyter、ms-python.black-formatter、charliermarsh.ruff、dbaeumer.vscode-eslint、esbenp.prettier-vscode与github.copilot并默认开启保存即格式化editor.formatOnSave: truePython 使用 Black、JS/TS 使用 Prettier。4. 方案 CMinicondaMiniconda 是安装 Conda、Python 及少量包的轻量级安装器。Conda 本身是包管理器能方便地创建和切换不同的 Python虚拟环境对于pip无法提供的包如某些预编译 AI 库尤其有用。第 0 步安装 Miniconda按官方安装向导安装后验证conda --version第 1 步创建环境文件新建environment.yml。如果配合 Codespaces 使用则放在.devcontainer目录下即.devcontainer/environment.yml。仓库已内置一份真实示例可参考.devcontainer/environment.yml其内容为name: dev、python3.10.0、openai、python-dotenv、pipazure-ai-inference。第 2 步填充环境文件课程文档给出的模板如下name: environment-name channels: - defaults - microsoft dependencies: - pythonpython-version - openai - python-dotenv - pip - pip: - azure-ai-ml参数说明name你给环境起的名字如ai4begchannels包源microsoft频道用于获取微软 AI 相关库pythonpython-version指定 Python 版本如3.10.0仓库内置版本openai/python-dotenv课程代码运行所需的推理客户端与密钥加载库pip:嵌套段通过 pip 补充安装 conda 频道没有的包。注意课程文档模板为azure-ai-ml而仓库当前内置的 .devcontainer/environment.yml 已改用azure-ai-inference——后者是 Microsoft Foundry Models / Azure AI Inference 的新一代 SDK与第 6~8 课示例代码的依赖保持一致建议以仓库实际文件为准。第 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。打开该 URL 即可看到课程目录结构浏览任意*.ipynb文件例如 08-building-search-applications/python/oai-solution.ipynb。课程内还有大量按提供商命名的 Notebook如aoai-*.ipynb、oai-*.ipynb、githubmodels-*.ipynb需要先按第 6 节配置对应提供商的密钥才能运行。6. 添加你的 API 密钥安全第一构建任何 AI 应用时保护 API 密钥都至关重要。切勿把密钥直接写进代码——提交到公开仓库会带来安全隐患甚至被恶意盗用产生意外费用。正确做法是使用.env文件 python-dotenv加载。关于凭据变量名的说明本文档早期版本含 translations/lt/00-course-setup/02-setup-local.md示范使用GITHUB_TOKEN。但根据仓库当前文档 00-course-setup/03-providers.md 的说明GitHub Models及其GITHUB_TOKEN已于 2026 年 7 月底退役官方替代方案为 Microsoft Foundry Models一个端点 一个密钥即可访问 OpenAI、Meta、Mistral、Cohere、Microsoft 等数百个模型对应变量为AZURE_INFERENCE_ENDPOINT与AZURE_INFERENCE_CREDENTIAL。下文同时给出两套写法按你使用的提供商选择其一。第 1 步进入项目根目录cd path/to/your/project第 2 步创建.env文件Unix 系touch .envWindowsecho . .env第 3 步编辑.env并填入密钥用 VS Code、Notepad 等编辑器打开.env替换占位符为真实密钥。使用 Microsoft Foundry Models当前推荐AZURE_INFERENCE_ENDPOINTyour_foundry_endpoint_here AZURE_INFERENCE_CREDENTIALyour_foundry_api_key_here使用 GitHub Models旧版文档写法已退役GITHUB_TOKENyour_github_token_here仓库根目录还提供了 .env.copy 模板可直接cp .env.copy .env后填写其中完整列出了一系列可用变量及其用途包括变量用途OPENAI_API_KEYOpenAI 非 Azure 端点的鉴权密钥AZURE_OPENAI_API_KEY/AZURE_OPENAI_ENDPOINTAzure OpenAI现并入 Microsoft Foundry资源的密钥与端点AZURE_OPENAI_DEPLOYMENT文本生成模型部署名如gpt-4o-miniAZURE_OPENAI_EMBEDDINGS_DEPLOYMENT向量嵌入模型部署名如text-embedding-3-smallAZURE_INFERENCE_ENDPOINT/AZURE_INFERENCE_CREDENTIALMicrosoft Foundry 项目端点与 API 密钥HUGGING_FACE_API_KEYHugging Face 访问令牌各提供商的注册指引、免费额度与配置步骤详见 00-course-setup/03-providers.md。第 4 步保存文件保存并关闭编辑器。第 5 步安装python-dotenvpip install python-dotenv若提示ModuleNotFoundError: dotenv通常是因为环境未正确安装依赖执行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 应用。切勿将.env提交到版本库——它已被仓库根目录 .gitignore第 123 行忽略。若使用 GitHub Codespaces也可以把密钥存为仓库级 Codespaces Secrets代码会自动读取无需本地.env但 Docker Desktop 本地环境仍必须配置.env文件详见 00-course-setup/03-providers.md。源码级印证仓库如何读取这些密钥仓库共享模块 shared/python/env_utils.py 提供了三个与上述流程配套的工具函数get_required_env(var_name, description)读取必填环境变量缺失时抛出带提示的ValueError如Missing required environment variable: OPENAI_API_KEY提示语直接指向.env文件validate_env_vars(*var_names)一次校验多个变量如同时校验AZURE_OPENAI_ENDPOINT与AZURE_OPENAI_API_KEY返回变量名到值的字典供客户端初始化使用get_env_with_default(var_name, default)带默认值的读取例如模型名缺省为gpt-4o。对应测试位于 tests/test_env_utils.py覆盖了缺失变量报错与默认值回退等关键行为。课程各 Notebook 正是依赖.env 这些工具完成鉴权因此第 6 步的配置是所有实战示例可运行的前提。7. 下一步做什么我想……前往……开始第 1 课01-introduction-to-genai配置 LLM 提供商providers.md不安装任何本地依赖直接用云端环境01-setup-cloud.md8. 故障排查症状解决方案python not found安装后将 Python 加入 PATH或重新打开终端pip在 Windows 上无法构建 wheelpip install --upgrade pip setuptools wheel后重试ModuleNotFoundError: dotenv执行pip install -r requirements.txt环境未正确安装Docker 构建失败No space leftDocker Desktop ▸Settings▸Resources→ 增大磁盘空间VS Code 反复提示重新打开容器可能同时启用了多个方案只保留一个venv或容器OpenAI 401 / 429 错误检查OPENAI_API_KEY值是否正确 / 是否触发请求频率限制Conda 相关错误用conda install -c microsoft azure-ai-ml手动安装微软 AI 库结语以上四种方案殊途同归方案 A 最快、零额外依赖方案 B 与云端 Codespaces 完全一致适合多语言混编与团队协作方案 C 适合需要 conda 生态包管理的场景方案 D 适合偏好纯浏览器 Notebook 体验的用户。无论选择哪条路径请务必遵循“密钥入.env、绝不入代码”的安全铁律再配合 00-course-setup/03-providers.md 完成提供商配置即可开始第 1 课的生成式 AI 之旅。【免费下载链接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表