從零搭建本地開發環境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》課程本地環境配置的完整實戰指南。如果你更希望在自己的筆記本上運行全部課程代碼而不是使用云端的 GitHub Codespaces這篇指南將帶你走完從克隆倉庫、創建 Python 虛擬環境、安裝依賴到安全配置 LLM Provider API 密鑰的全過程。讀完本文你將能夠獨立搭建四種可選環境原生 Python venv、VS Code Dev Container、Miniconda、經典 Jupyter并掌握基于.env文件的安全密鑰管理方法為后續 21 節課的實驗做好準備。1. 環境搭建概覽與前置條件本課程倉庫當前目錄即generative-ai-for-beginners的核心實驗載體是大量 Python 腳本與 Jupyter Notebook分布在 01-introduction-to-genai 至 21-meta 各章節中因此本地環境需要一套能運行 Python 3.10、加載依賴并能安全注入 API 密鑰的開發環境。課程提供了兩條主線、四種具體路徑任選其一即可它們最終通向完全相同的課程內容方案 A原生 Python 虛擬環境venv—— 最快上手零額外依賴方案 BVS Code Dev ContainerDocker—— 與云端 Codespaces 完全一致的隔離環境杜絕依賴漂移方案 CMiniconda—— 適合需要管理多個 Python 版本與 conda 生態包的場景方案 D經典 Jupyter / Jupyter Lab—— 偏好瀏覽器內 Notebook 界面、不想使用 VS Code 的開發者。在開始之前請確認以下工具的版本符合要求工具版本 / 說明Python3.10 及以上可從 python.org 官方渠道獲取Git最新版macOS 隨 Xcode 附帶、Windows 使用 Git for Windows、Linux 使用包管理器安裝VS Code可選但推薦code.visualstudio.com 官方渠道Docker Desktop僅方案 B 需要免費安裝提示打開終端依次執行python --version、git --version、docker --version、code --version可以一次性驗證這些工具是否都已就緒。2. 方案 A原生 Python 虛擬環境最快步驟 1克隆本倉庫git clone https://github.com/your-github/generative-ai-for-beginners cd generative-ai-for-beginners步驟 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 已鎖定課程所需的核心依賴包括openai1.12.0OpenAI / 兼容 SDK、python-dotenv1.2.2加載.env文件、azure-ai-inferenceAzure AI Inference / Foundry Models 客戶端、tiktoken分詞工具以及numpy、pandas、matplotlib、scikit-learn、tqdm、ipywidgets等數據與可視化組件。安裝完成后即可跳到本文第 6 節配置 API 密鑰。3. 方案 BVS Code Dev ContainerDocker本倉庫內置了開發容器Development Container 配置其運行時Universal runtime同時支持 Python3、.NET、Node.js 和 Java 開發。相關配置定義在倉庫根目錄.devcontainer/文件夾下的devcontainer.json文件中。為什么選這個方案容器環境與云端 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 Container。首次構建鏡像大約需要 3 分鐘。當終端提示符出現時說明你已經處于容器內部所有依賴Python 3、Node.js、.NET、Java 運行時都已預裝完畢可以直接開始實驗。4. 方案 CMinicondaMiniconda 是一個輕量級安裝器用于安裝 Conda 包管理器、Python 及少量必要包。Conda 本身是包管理器可以方便地創建和切換不同的 Python 虛擬環境與包組合還能安裝pip無法提供的非 Python 依賴。步驟 0安裝 Miniconda按照官方安裝指南完成安裝后驗證conda --version步驟 1創建環境文件新建一個環境文件environment.yml。如果你正在跟隨 Codespaces 教程操作請將該文件放在.devcontainer目錄下即.devcontainer/environment.yml。步驟 2填充環境文件將以下內容寫入你的environment.ymlname: environment-name channels: - defaults - microsoft dependencies: - pythonpython-version - openai - python-dotenv - pip - pip: - azure-ai-ml注意channels中加入了microsoft頻道這是安裝微軟 Azure AI 相關庫如azure-ai-ml的前提pip小節用于安裝僅通過 PyPI 分發的包。步驟 3創建并激活 Conda 環境conda env create --name ai4beg --file .devcontainer/environment.yml # .devcontainer 子路徑僅適用于 Codespace 場景 conda activate ai4beg提示--file參數指向的環境文件路徑可根據你的實際情況調整若遇到環境創建問題可參考 Conda 官方環境管理文檔。5. 方案 D經典 Jupyter / Jupyter Lab瀏覽器內運行適合人群喜歡經典 Jupyter 界面或希望不依賴 VS Code 直接運行 Notebook 的學習者。步驟 1啟動 Jupyter打開終端 / 命令行進入課程目錄后執行jupyter notebook或者jupyterhub啟動后命令行窗口會顯示一個訪問 URL瀏覽器打開該 URL 即可看到課程大綱并可以導航到任意*.ipynb文件。例如本倉庫中的 08-building-search-applications/python/oai-solution.ipynb第 8 課《構建搜索應用》的 OpenAI 方案答案 Notebook。提示如果提示找不到jupyter命令請先確認你已在對應虛擬環境中安裝了ipywidgets等 Notebook 依賴可執行pip install -r requirements.txt一次性補齊。6. 配置 API 密鑰.env文件與 python-dotenv無論選擇哪種環境構建生成式 AI 應用時都必須妥善保管 API 密鑰。絕不建議把密鑰硬編碼進代碼——一旦提交到公開倉庫可能引發安全泄露甚至被惡意調用產生額外費用。下面是推薦的安全做法。步驟 1進入項目目錄cd path/to/your/project步驟 2創建.env文件Unix 系系統touch .envWindowsecho . .env步驟 3填入密鑰變量用 VS Code、Notepad 或任意編輯器打開.env并寫入密鑰。注意本課程原印尼語文檔中的示例使用GITHUB_TOKEN對應已退役的 GitHub Models當前倉庫已全面遷移到Microsoft Foundry Models方案。以倉庫根目錄的 .env.copy 為最新權威模板其關鍵變量如下# OpenAI Provider OPENAI_API_KEYadd your OpenAI API key here ## Azure OpenAI in Microsoft Foundry AZURE_OPENAI_API_VERSION2024-10-21 # 默認已設置當前穩定 GA 版本 AZURE_OPENAI_API_KEYadd your Foundry resource key here AZURE_OPENAI_ENDPOINTadd your Foundry resource endpoint here, e.g. https://resource-name.openai.azure.com 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, e.g. text-embedding-3-small ## Microsoft Foundry Models多廠商模型目錄一個端點 一個密鑰 AZURE_INFERENCE_ENDPOINTadd your Microsoft Foundry project endpoint here AZURE_INFERENCE_CREDENTIALadd your Microsoft Foundry Models API key here ## Hugging Face HUGGING_FACE_API_KEYadd your HuggingFace API or token here更便捷的做法是直接復制模板cp .env.copy .env然后逐一替換右側的占位符。各變量的含義如下變量說明OPENAI_API_KEY非 Azure OpenAI 端點的服務授權密鑰AZURE_OPENAI_API_KEYAzure OpenAI / Foundry 資源的授權密鑰AZURE_OPENAI_ENDPOINTAzure OpenAI 資源的已部署端點AZURE_OPENAI_DEPLOYMENT文本生成模型的部署名推薦gpt-4o-miniAZURE_OPENAI_EMBEDDINGS_DEPLOYMENT文本嵌入模型的部署名推薦text-embedding-3-smallAZURE_INFERENCE_ENDPOINTMicrosoft Foundry 項目端點用于 Foundry ModelsAZURE_INFERENCE_CREDENTIALMicrosoft Foundry 項目 API 密鑰HUGGING_FACE_API_KEYHugging Face 用戶訪問令牌Access Token各 Provider 的詳細注冊、獲取密鑰與部署模型的完整指引見 00-course-setup/03-providers.md無需云訂閱、完全離線的 Foundry Local / Ollama 方案可參考 19-slm/README.md 中的實操示例。步驟 4保存文件并安裝 python-dotenvpip install python-dotenv步驟 5在 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)完成以上步驟后密鑰即安全地注入到你的 Python 應用中。絕不要提交.env文件——它已被列入倉庫的.gitignore倉庫中的 .env.copy 才是用于共享的模板。這一安全實踐在倉庫源碼中也有對應體現共享工具模塊 shared/python/env_utils.py 提供了get_required_env()與validate_env_vars()等函數在讀取缺失的必需環境變量時會拋出帶明確提示的ValueError如Missing required environment variable: OPENAI_API_KEY. Please set it in your .env file or environment.幫助你在運行任何課程腳本前快速定位密鑰配置問題get_env_with_default()則用于為可選參數如默認模型名提供回退值。7. 下一步進入課程學習環境與密鑰就緒后你可以按需選擇我想…前往…開始第 1 課01-introduction-to-genai/README.md配置 LLM Provider00-course-setup/03-providers.md使用云端零安裝方案00-course-setup/01-setup-cloud.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 庫至此你已經掌握了本課程全部四種本地環境搭建路徑與一套安全可靠的密鑰管理流程。選擇最適合你習慣的方案即可無縫開始 21 節課的生成式 AI 實戰之旅。【免費下載鏈接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI項目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners創作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考 從零搭建本地開發環境：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》課程本地環境配置的完整實戰指南。如果你更希望在自己的筆記本上運行全部課程代碼而不是使用云端的 GitHub Codespaces這篇指南將帶你走完從克隆倉庫、創建 Python 虛擬環境、安裝依賴到安全配置 LLM Provider API 密鑰的全過程。讀完本文你將能夠獨立搭建四種可選環境原生 Python venv、VS Code Dev Container、Miniconda、經典 Jupyter并掌握基于.env文件的安全密鑰管理方法為后續 21 節課的實驗做好準備。1. 環境搭建概覽與前置條件本課程倉庫當前目錄即generative-ai-for-beginners的核心實驗載體是大量 Python 腳本與 Jupyter Notebook分布在 01-introduction-to-genai 至 21-meta 各章節中因此本地環境需要一套能運行 Python 3.10、加載依賴并能安全注入 API 密鑰的開發環境。課程提供了兩條主線、四種具體路徑任選其一即可它們最終通向完全相同的課程內容方案 A原生 Python 虛擬環境venv—— 最快上手零額外依賴方案 BVS Code Dev ContainerDocker—— 與云端 Codespaces 完全一致的隔離環境杜絕依賴漂移方案 CMiniconda—— 適合需要管理多個 Python 版本與 conda 生態包的場景方案 D經典 Jupyter / Jupyter Lab—— 偏好瀏覽器內 Notebook 界面、不想使用 VS Code 的開發者。在開始之前請確認以下工具的版本符合要求工具版本 / 說明Python3.10 及以上可從 python.org 官方渠道獲取Git最新版macOS 隨 Xcode 附帶、Windows 使用 Git for Windows、Linux 使用包管理器安裝VS Code可選但推薦code.visualstudio.com 官方渠道Docker Desktop僅方案 B 需要免費安裝提示打開終端依次執行python --version、git --version、docker --version、code --version可以一次性驗證這些工具是否都已就緒。2. 方案 A原生 Python 虛擬環境最快步驟 1克隆本倉庫git clone https://github.com/your-github/generative-ai-for-beginners cd generative-ai-for-beginners步驟 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 已鎖定課程所需的核心依賴包括openai1.12.0OpenAI / 兼容 SDK、python-dotenv1.2.2加載.env文件、azure-ai-inferenceAzure AI Inference / Foundry Models 客戶端、tiktoken分詞工具以及numpy、pandas、matplotlib、scikit-learn、tqdm、ipywidgets等數據與可視化組件。安裝完成后即可跳到本文第 6 節配置 API 密鑰。3. 方案 BVS Code Dev ContainerDocker本倉庫內置了開發容器Development Container 配置其運行時Universal runtime同時支持 Python3、.NET、Node.js 和 Java 開發。相關配置定義在倉庫根目錄.devcontainer/文件夾下的devcontainer.json文件中。為什么選這個方案容器環境與云端 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 Container。首次構建鏡像大約需要 3 分鐘。當終端提示符出現時說明你已經處于容器內部所有依賴Python 3、Node.js、.NET、Java 運行時都已預裝完畢可以直接開始實驗。4. 方案 CMinicondaMiniconda 是一個輕量級安裝器用于安裝 Conda 包管理器、Python 及少量必要包。Conda 本身是包管理器可以方便地創建和切換不同的 Python 虛擬環境與包組合還能安裝pip無法提供的非 Python 依賴。步驟 0安裝 Miniconda按照官方安裝指南完成安裝后驗證conda --version步驟 1創建環境文件新建一個環境文件environment.yml。如果你正在跟隨 Codespaces 教程操作請將該文件放在.devcontainer目錄下即.devcontainer/environment.yml。步驟 2填充環境文件將以下內容寫入你的environment.ymlname: environment-name channels: - defaults - microsoft dependencies: - pythonpython-version - openai - python-dotenv - pip - pip: - azure-ai-ml注意channels中加入了microsoft頻道這是安裝微軟 Azure AI 相關庫如azure-ai-ml的前提pip小節用于安裝僅通過 PyPI 分發的包。步驟 3創建并激活 Conda 環境conda env create --name ai4beg --file .devcontainer/environment.yml # .devcontainer 子路徑僅適用于 Codespace 場景 conda activate ai4beg提示--file參數指向的環境文件路徑可根據你的實際情況調整若遇到環境創建問題可參考 Conda 官方環境管理文檔。5. 方案 D經典 Jupyter / Jupyter Lab瀏覽器內運行適合人群喜歡經典 Jupyter 界面或希望不依賴 VS Code 直接運行 Notebook 的學習者。步驟 1啟動 Jupyter打開終端 / 命令行進入課程目錄后執行jupyter notebook或者jupyterhub啟動后命令行窗口會顯示一個訪問 URL瀏覽器打開該 URL 即可看到課程大綱并可以導航到任意*.ipynb文件。例如本倉庫中的 08-building-search-applications/python/oai-solution.ipynb第 8 課《構建搜索應用》的 OpenAI 方案答案 Notebook。提示如果提示找不到jupyter命令請先確認你已在對應虛擬環境中安裝了ipywidgets等 Notebook 依賴可執行pip install -r requirements.txt一次性補齊。6. 配置 API 密鑰.env文件與 python-dotenv無論選擇哪種環境構建生成式 AI 應用時都必須妥善保管 API 密鑰。絕不建議把密鑰硬編碼進代碼——一旦提交到公開倉庫可能引發安全泄露甚至被惡意調用產生額外費用。下面是推薦的安全做法。步驟 1進入項目目錄cd path/to/your/project步驟 2創建.env文件Unix 系系統touch .envWindowsecho . .env步驟 3填入密鑰變量用 VS Code、Notepad 或任意編輯器打開.env并寫入密鑰。注意本課程原印尼語文檔中的示例使用GITHUB_TOKEN對應已退役的 GitHub Models當前倉庫已全面遷移到Microsoft Foundry Models方案。以倉庫根目錄的 .env.copy 為最新權威模板其關鍵變量如下# OpenAI Provider OPENAI_API_KEYadd your OpenAI API key here ## Azure OpenAI in Microsoft Foundry AZURE_OPENAI_API_VERSION2024-10-21 # 默認已設置當前穩定 GA 版本 AZURE_OPENAI_API_KEYadd your Foundry resource key here AZURE_OPENAI_ENDPOINTadd your Foundry resource endpoint here, e.g. https://resource-name.openai.azure.com 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, e.g. text-embedding-3-small ## Microsoft Foundry Models多廠商模型目錄一個端點 一個密鑰 AZURE_INFERENCE_ENDPOINTadd your Microsoft Foundry project endpoint here AZURE_INFERENCE_CREDENTIALadd your Microsoft Foundry Models API key here ## Hugging Face HUGGING_FACE_API_KEYadd your HuggingFace API or token here更便捷的做法是直接復制模板cp .env.copy .env然后逐一替換右側的占位符。各變量的含義如下變量說明OPENAI_API_KEY非 Azure OpenAI 端點的服務授權密鑰AZURE_OPENAI_API_KEYAzure OpenAI / Foundry 資源的授權密鑰AZURE_OPENAI_ENDPOINTAzure OpenAI 資源的已部署端點AZURE_OPENAI_DEPLOYMENT文本生成模型的部署名推薦gpt-4o-miniAZURE_OPENAI_EMBEDDINGS_DEPLOYMENT文本嵌入模型的部署名推薦text-embedding-3-smallAZURE_INFERENCE_ENDPOINTMicrosoft Foundry 項目端點用于 Foundry ModelsAZURE_INFERENCE_CREDENTIALMicrosoft Foundry 項目 API 密鑰HUGGING_FACE_API_KEYHugging Face 用戶訪問令牌Access Token各 Provider 的詳細注冊、獲取密鑰與部署模型的完整指引見 00-course-setup/03-providers.md無需云訂閱、完全離線的 Foundry Local / Ollama 方案可參考 19-slm/README.md 中的實操示例。步驟 4保存文件并安裝 python-dotenvpip install python-dotenv步驟 5在 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)完成以上步驟后密鑰即安全地注入到你的 Python 應用中。絕不要提交.env文件——它已被列入倉庫的.gitignore倉庫中的 .env.copy 才是用于共享的模板。這一安全實踐在倉庫源碼中也有對應體現共享工具模塊 shared/python/env_utils.py 提供了get_required_env()與validate_env_vars()等函數在讀取缺失的必需環境變量時會拋出帶明確提示的ValueError如Missing required environment variable: OPENAI_API_KEY. Please set it in your .env file or environment.幫助你在運行任何課程腳本前快速定位密鑰配置問題get_env_with_default()則用于為可選參數如默認模型名提供回退值。7. 下一步進入課程學習環境與密鑰就緒后你可以按需選擇我想…前往…開始第 1 課01-introduction-to-genai/README.md配置 LLM Provider00-course-setup/03-providers.md使用云端零安裝方案00-course-setup/01-setup-cloud.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 庫至此你已經掌握了本課程全部四種本地環境搭建路徑與一套安全可靠的密鑰管理流程。選擇最適合你習慣的方案即可無縫開始 21 節課的生成式 AI 實戰之旅。【免費下載鏈接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI項目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners創作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考