ARTICLE DETAIL

资讯详情

深耕网站建设、视觉设计与SEO优化的一线实战洞察。

generative-ai-for-beginners 本地环境配置实战:venv、Dev Container、Miniconda 与 Jupyter 四种部署路径及 .env 密钥管理

generative-ai-for-beginners 本地环境配置实战:venv、Dev Container、Miniconda 与 Jupyter 四种部署路径及 .env 密钥管理 generative-ai-for-beginners 本地环境配置实战venv、Dev Container、Miniconda 与 Jupyter 四种部署路径及 .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 课程的《Local Setup》指南意大利语版 02-setup-local.md系统讲解如何在自有笔记本上搭建课程所需的开发环境从四种运行方式原生 Python 虚拟环境、VS Code Dev Container、Miniconda、经典 Jupyter的完整操作步骤到.env文件创建与 API 密钥安全管理。读完本文你可以任选一条路径完成从零到可运行 Notebook 的全部配置并理解仓库中 requirements.txt、.devcontainer/devcontainer.json 等配置文件背后的一致性设计。1. 前置条件Prerequisites文档要求读者优先在终端中验证工具链就绪四条路径共享同一组前置条件工具版本 / 说明Python3.10 及以上Git最新版本macOS 随 Xcode / Git for Windows / Linux 包管理器提供VS Code可选但推荐Docker Desktop仅选项 B 需要免费安装在终端中执行以下命令逐一确认python --version git --version docker --version code --version仓库根目录还包含 .python-version 与 pyproject.toml前者是 pyenv 等工具读取的 Python 版本锁定文件后者是仓库的 Python 项目配置它们与文档要求的 Python 3.10 共同界定了课程的运行环境前提。2. 选项 A原生 Python 虚拟环境最快路径2.1 克隆仓库课程要求先 Fork 仓库到自己的账号以便修改代码并完成挑战然后克隆git clone https://github.com/your-github/generative-ai-for-beginners cd generative-ai-for-beginners2.2 创建并激活虚拟环境python -m venv .venv # 创建一个虚拟环境 source .venv/bin/activate # macOS / Linux .\.venv\Scripts\activate # Windows PowerShell激活成功后命令提示符应以(.venv)开头表示当前 shell 已处于虚拟环境内部。2.3 安装依赖pip install -r requirements.txt这一步是整个本地部署的核心。从 requirements.txt 的实际内容看课程锁定的依赖集覆盖了 Notebook 交互、数据处理与模型调用三类场景ipywidgets8.1.8 # Jupyter 交互式组件 numpy2.4.2 # 数值计算 matplotlib3.10.8 # 绑图 pandas3.0.0 # 表格数据处理 tqdm4.68.4 # 进度条 python-dotenv1.2.2 # 加载 .env 环境变量第 3 节密钥管理的基础 openai1.12.0 # OpenAI SDK兼容 Azure / Foundry 端点 tiktoken # Token 计数课程中讲解分词器原理 azure-ai-inference # Azure 推理 SDK scikit-learn # 机器学习第 08 课 RAG/检索相关练习用到值得注意的是python-dotenv被显式锁定版本1.2.2且版本较高说明课程把.env加载视为运行时的一等公民而非可选依赖——这也是后文排查ModuleNotFoundError: dotenv的直接依据。3. 选项 BVS Code Dev ContainerDocker 容器化课程为仓库预置了 Dev Container使用Universal runtime官方镜像同一容器内支持 Python3、.NET、Node.js 与 Java 开发与 GitHub Codespaces 环境完全一致杜绝本地依赖漂移dependency drift。3.1 配置文件源码解析相关配置定义在仓库根目录 .devcontainer/devcontainer.json 中关键字段如下image: mcr.microsoft.com/devcontainers/universal:2.13采用微软官方 Universal 开发容器镜像版本 2.13这正是文档所说支持多种语言运行时的底层原因hostRequirements: { cpus: 4 }要求宿主机至少 4 核 CPU资源不足时容器无法启动waitFor: onCreateCommand等待创建命令完成后才标记容器就绪updateContentCommand: python3 -m pip install -r requirements.txt工作区内容更新时自动重新安装 requirements.txt 中的依赖保证代码与依赖版本同步postCreateCommand: bash .devcontainer/post-create.sh容器创建后执行 .devcontainer/post-create.sh 做初始化customizations.vscode.extensions预装 Python、Pylance、Jupyter、black-formatter、ruff、ESLint、Prettier、GitHub Copilot 等扩展并配置保存时自动格式化editor.formatOnSave: truePython 默认格式化器为 black。从源码结构看容器每次内容更新都会重跑pip install -r requirements.txt因此选项 B 天然避免了文档依赖与容器实际依赖不一致的问题——这是它与选项 A 最大的工程差异。3.2 操作步骤Step 0 — 安装附加组件Docker Desktop确认docker --version可用 VS Code 扩展 Remote – Containers扩展 IDms-vscode-remote.remote-containers。Step 1 — 在 VS Code 中打开仓库File ▸ Open Folder… → 选择generative-ai-for-beginners目录。VS Code 检测到.devcontainer/目录后会弹出提示。Step 2 — 在容器中重开点击 Reopen in Container。Docker 首次构建镜像约需 3 分钟当终端提示符出现时说明你已进入容器内部。此时容器会自动执行updateContentCommand与postCreateCommand无需手动pip install。4. 选项 CMinicondaMiniconda 是安装 Conda 与 Python 的轻量级安装包Conda 本身是包管理器便于在不同 Python 虚拟环境与包之间创建和切换也可安装pip渠道之外的包如预编译二进制。4.1 Step 0 — 安装 Miniconda按官方 MiniConda 安装指南完成安装后验证conda --version4.2 Step 1 — 创建环境文件新建environment.yml。若你在 Codespaces 中跟练应放在.devcontainer目录下即.devcontainer/environment.yml。4.3 Step 2 — 填写环境文件文档给出的模板如下name: environment-name channels: - defaults - microsoft dependencies: - pythonpython-version - openai - python-dotenv - pip - pip: - azure-ai-ml其中environment-name为环境名、python-version为期望的 Python 主版本号如3。作为对照仓库中真实提交的 .devcontainer/environment.yml 是这份模板的具体实例name: dev channels: - defaults dependencies: - python3.10.0 - openai - python-dotenv - pip - pip: - azure-ai-inference可以观察到两点实际演进真实环境精确锁定python3.10.0pip 子依赖使用的是azure-ai-inference与 requirements.txt 第 9 行保持一致而文档模板中的azure-ai-ml是较早的 Azure Machine Learning 包按当前仓库依赖集应优先以azure-ai-inference为准。4.4 Step 3 — 创建并激活 Conda 环境conda env create --name ai4beg --file .devcontainer/environment.yml # .devcontainer 子路径仅适用于 Codespace 配置 conda activate ai4beg遇到 Conda 报错时可参考文档的排障表见第 8 节用conda install -c microsoft azure-ai-ml手动补装微软 AI 库。5. 选项 D经典 Jupyter / JupyterLab浏览器内运行适合偏爱经典 Jupyter 界面、或不想依赖 VS Code 的读者。进入课程目录后执行jupyter notebook或jupyterhub命令启动一个 Jupyter 实例终端窗口会打印访问 URL。打开该 URL 后可看到课程目录树能直接导航到任意*.ipynb文件例如 08-building-search-applications/python/oai-solution.ipynb。6. 添加 API Keys.env 文件与密钥安全6.1 为什么必须用 .env构建任何类型的应用时保障 API 密钥安全都至关重要。课程明确建议不要把 API key 直接写进代码把这些凭据提交到公开仓库若被恶意者利用会造成安全问题乃至意料之外的账单费用。6.2 六步创建 .env文档完整步骤进入项目目录cd path/to/your/project创建.env文件Unix 系统用touchWindows 用echotouch .env # Unixecho . .env # Windows编辑.env用任意文本编辑器VS Code、Notepad 等打开添加凭据行替换占位符GITHUB_TOKENyour_github_token_here注意版本差异意大利语版本文档此处以GITHUB_TOKEN为例而仓库当前主干英语版 02-setup-local.md 与 00-course-setup/README.md已改用 Microsoft Foundry Models 凭据。仓库根目录提供了权威的模板文件 .env.copy内容覆盖三类提供方# OpenAI Provider OPENAI_API_KEYyour OpenAI API key # Azure OpenAI in Microsoft Foundry AZURE_OPENAI_API_VERSION2024-10-21 AZURE_OPENAI_API_KEYyour Foundry resource key AZURE_OPENAI_ENDPOINThttps://resource-name.openai.azure.com AZURE_OPENAI_DEPLOYMENTgpt-4o-mini AZURE_OPENAI_EMBEDDINGS_DEPLOYMENTtext-embedding-3-small # Microsoft Foundry Models多提供方目录OpenAI、Meta、Mistral、Cohere 等 AZURE_INFERENCE_ENDPOINThttps://resource-name.services.ai.azure.com/models AZURE_INFERENCE_CREDENTIALyour Foundry Models API key # Hugging Face HUGGING_FACE_API_KEYyour HuggingFace token从 .env.copy 的注释看GitHub Models 及其GITHUB_TOKEN变量将于 2026 年 7 月底退役因此实际操作时建议直接以.env.copy为模板创建.env而非沿用文档中较旧的GITHUB_TOKEN示例。保存文件保存修改并关闭编辑器。安装python-dotenv若尚未安装pip install python-dotenv在 Python 脚本中加载变量from dotenv import load_dotenv import os # 从 .env 文件加载环境变量 load_dotenv() # 读取变量 github_token os.getenv(GITHUB_TOKEN) print(github_token)6.3 源码佐证仓库如何消费这些环境变量仓库在 shared/python/env_utils.py 中提供了标准化的环境变量访问层把漏配 .env从晦涩的None值变成显式报错get_required_env(var_name, description)读取必填变量未设置时抛出ValueError并提示 Please set it in your .env file or environment见 env_utils.pyvalidate_env_vars(*var_names)批量校验多个变量一次性列出所有缺失项env_utils.pyget_env_with_default(var_name, default)读取带默认值的变量env_utils.py。配套的 shared/python/api_utils.py 则展示凭据如何落到客户端create_openai_client()从OPENAI_API_KEY读取密钥构造 OpenAI 客户端api_utils.pycreate_azure_openai_client()从AZURE_OPENAI_ENDPOINT/AZURE_OPENAI_API_KEY读取并拼接endpoint/openai/v1/作为 base_urlapi_utils.py。这正是.env中AZURE_OPENAI_*变量的消费方可帮助读者把配置文件里的每个变量名与课程代码一一对应。安全底线.env永远不要提交到版本库——它已被 .gitignore 覆盖。各提供方的完整申请说明见 00-course-setup/03-providers.md。7. 下一步Whats next?我想……前往开始第 1 课01-introduction-to-genai/README.md配置 LLM 提供方00-course-setup/03-providers.md了解整体入门路径00-course-setup/README.md8. 故障排查Troubleshooting文档给出的完整排查表覆盖从 Python 基础到 Docker 磁盘的典型症状症状解决方案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 库补充两条与源码证据相关的判断依据ModuleNotFoundError: dotenv之所以指向pip install -r requirements.txt是因为 requirements.txt 已将python-dotenv1.2.2列为锁定依赖而VS Code 反复提示重开容器的根因是本地 venv 与.devcontainer/容器方案同时生效在 VS Code 中应显式只采用其中一种。9. 小结本文完整继承了课程《Local Setup》指南的四条本地部署路径与密钥管理流程并结合仓库源码补充了三处关键细节依赖清单 requirements.txt 的逐项用途、.devcontainer/devcontainer.json 中镜像、CPU 要求与依赖自更新命令的真实配置以及 shared/python/env_utils.py 展示的环境变量校验机制。按任一路径完成配置后即可直接进入 01-introduction-to-genai/README.md 开始学习遇到凭据问题先查阅 00-course-setup/03-providers.md。【免费下载链接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表