generative-ai-for-beginners 课程实战指南：LLM 供应商选型与 `.env` 凭据配置全解析

generative-ai-for-beginners 课程实战指南：LLM 供应商选型与.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 课程中「选择并配置 LLM 供应商」这一核心环节展开：你将了解课程支持的各托管模型供应商（OpenAI、Azure OpenAI / Microsoft Foundry、Hugging Face 等）的定位与选型依据，掌握从.env.copy模板创建、填充本地.env文件到在 Azure 门户 / Foundry 门户中逐项获取凭据的完整流程。读完本文后，你可以为课程中的任意一个练习（assignment）正确配置好所需的环境变量，理解仓库代码是如何读取和校验这些凭据的，从而顺畅跑通后续各章节的 Notebook 与示例脚本。

课程支持的 LLM 供应商概览

课程的各练习可以配置为运行在一种或多种大语言模型（LLM）部署之上，这些部署来自受支持的托管服务供应商。这些供应商提供一个托管端点（hosted endpoint，即 API），我们可以使用正确的凭据（API key 或 token）以编程方式访问。课程涉及的供应商包括：

• OpenAI：提供包括核心 GPT 系列在内的多种模型；
• Azure OpenAI（现已并入Microsoft Foundry）：面向企业级就绪场景的 OpenAI 模型服务；
• Microsoft Foundry Models：通过单一端点和单一 API key 访问 OpenAI、Meta、Mistral、Cohere、Microsoft 等数百家厂商的数百个模型（它替代了将于 2026 年 7 月底退役的 GitHub Models）；
• Hugging Face：面向开源模型与推理服务；
• Foundry Local / Ollama：如果你希望在自有设备上完全离线运行模型，无需任何云订阅。

这些练习需要你使用自己的账号。练习是可选的，因此你可以按兴趣选择配置其中一种、全部——或一种都不配置。以下是注册时的对比参考（引自 providers 文档）：

文件名标签（tag）约定：练习需要哪套凭据

按照 providers 文档 的说明，需要特定供应商的练习会在文件名中包含以下标签之一：

• aoai— 需要 Azure OpenAI 的 endpoint 与 key；
• oai— 需要 OpenAI 的 endpoint 与 key；
• hf— 需要 Hugging Face token；
• githubmodels— 需要 Microsoft Foundry Models 的 endpoint 与 key（当前仓库中大量练习文件即采用此命名，例如 githubmodels-app.py、githubmodels-assignment.ipynb）。

你可以只配置一种、多种或全部供应商；缺少凭据的练习在运行时只会报错退出，不会影响其他练习。

创建.env文件：从.env.copy模板开始

假设你已经完成供应商注册并拿到所需凭据（API_KEY 或 token）。对于 Azure OpenAI，我们还假设你已拥有一个有效的 Azure OpenAI 服务部署（endpoint），并且至少部署了一个用于对话补全（chat completion）的 GPT 模型。

下一步是配置本地环境变量：

1. 在仓库根目录找到.env.copy文件。当前仓库中该文件的实际内容如下（见 .env.copy）：

   # OpenAI Provider OPENAI_API_KEY='<add your OpenAI API key here>' ## Azure OpenAI in Microsoft Foundry ## (Azure OpenAI Service is now part of Microsoft Foundry: https://ai.azure.com ## Create/manage your resource and deployments from the Foundry portal - the env var names below are unchanged.) AZURE_OPENAI_API_VERSION='2024-10-21' # Default is set! (current stable GA API version) AZURE_OPENAI_API_KEY='<add your Foundry resource key here>' AZURE_OPENAI_ENDPOINT='<add your Foundry resource endpoint here, e.g. https://<resource-name>.openai.azure.com>' AZURE_OPENAI_DEPLOYMENT='<add your chat completion model deployment name here, e.g. gpt-4o-mini>' AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT='<add your embeddings model deployment name here, e.g. text-embedding-3-small>' ## Microsoft Foundry Models ## (Multi-provider model catalog - one endpoint/key for OpenAI, Meta, Mistral, Cohere, Microsoft, and more. ## Replaces GitHub Models, which retires end of July 2026. Get these from your Foundry project's "Overview" page.) AZURE_INFERENCE_ENDPOINT='<add your Microsoft Foundry project endpoint here, e.g. https://<resource-name>.services.ai.azure.com/models>' AZURE_INFERENCE_CREDENTIAL='<add your Microsoft Foundry Models API key here>' ## Hugging Face HUGGING_FACE_API_KEY='<add your HuggingFace API or token here>'

   说明：意大利语版 providers 文档 中给出的示例模板较早，仅包含OPENAI_API_KEY、五个AZURE_OPENAI_*变量与HUGGING_FACE_API_KEY，且AZURE_OPENAI_API_VERSION默认值为2024-02-01。以当前仓库根目录的 .env.copy 为准：API 版本已更新为2024-10-21，并新增了AZURE_INFERENCE_ENDPOINT/AZURE_INFERENCE_CREDENTIAL两项用于 Microsoft Foundry Models。

2. 用下面的命令把模板复制为.env。该文件已被gitignore掉（可在 .gitignore 第 123 行确认.env条目），从而保证密钥不会误提交到仓库：

   cp .env.copy .env

3. 按下一节的说明填写各项值（替换=右侧的占位符）。

4. （可选）如果你使用 GitHub Codespaces，可以选择不写本地.env，而是把环境变量保存为与该仓库关联的Codespaces secrets。但请注意该选项只在 GitHub Codespaces 中生效——如果你改用 Docker Desktop（Dev Container 方式，见 本地部署指南），仍然需要本地.env文件。

逐项理解.env中的变量

以下是各变量名称的含义（综合 providers 文档与当前 .env.copy 注释）：

注意：Azure OpenAI 的最后两个部署变量分别反映一个默认的对话补全（文本生成）模型与一个向量检索（embeddings）模型，具体如何设置会在相关练习中给出说明；当前仓库模板注释中推荐的示例是gpt-4o-mini（文本生成）与text-embedding-3-small（嵌入）。

本地 Python 如何加载.env

在 本地部署指南 中，课程给出的加载方式是安装python-dotenv（依赖已列入 requirements.txt）后在脚本开头调用：

from dotenv import load_dotenv import os # Load environment variables from .env file load_dotenv() # 访问 Microsoft Foundry Models 变量 endpoint = os.getenv("AZURE_INFERENCE_ENDPOINT") token = os.getenv("AZURE_INFERENCE_CREDENTIAL") print(endpoint)

也就是说，.env文件本身只是「变量来源」，真正让练习脚本读到处凭据的，是load_dotenv()把文件内容注入进程环境变量。

配置 Azure OpenAI：从 Azure 门户获取端点与密钥

Azure OpenAI 的 endpoint 与 key 可以在 Azure 门户中找到，步骤如下（引自 providers 文档）：

1. 打开 Azure 门户，进入你的 Azure OpenAI 资源；
2. 点击侧边栏（左侧菜单）中的Keys and Endpoint选项；
3. 点击Show Keys—— 你应该能看到：KEY 1、KEY 2 和 Endpoint；
4. 将KEY 1的值填入AZURE_OPENAI_API_KEY；
5. 将Endpoint的值填入AZURE_OPENAI_ENDPOINT。

接下来需要已部署模型的部署信息：

1. 在 Azure OpenAI 资源的侧边栏点击Model deployments选项；
2. 在目标页面点击Go to Microsoft Foundry portal（或Manage Deployments，具体取决于你的资源类型）。

这会把你带到 Microsoft Foundry 门户，在那里可以找到其余的值。

背景说明：Azure OpenAI Service 现已并入 Microsoft Foundry。资源与部署仍然显示在 Azure 门户中，但日常模型管理（部署、playground、监控）如今发生在 Foundry 门户中，而非旧版独立的 "Azure OpenAI Studio"。

配置 Azure OpenAI：在 Foundry 门户中部署模型

1. 从你的资源出发导航到 Microsoft Foundry 门户（如上一步所述）；
2. 点击Deployments选项卡（左侧边栏），查看当前已部署的模型；
3. 如果你想要的模型尚未部署，使用Deploy model从模型目录部署它；
4. 你需要一个_文本生成_模型 —— 当前仓库推荐：gpt-4o-mini（意大利语版文档较早推荐的是gpt-35-turbo，以当前模板注释与英文原文档为准）；
5. 你需要一个_文本嵌入_模型 —— 推荐text-embedding-3-small（旧版推荐text-embedding-ada-002）。

现在更新环境变量，使其反映你使用的_部署名称（Deployment name）_。除非你显式改过名字，否则它通常与模型名相同。例如，你可能会有：

AZURE_OPENAI_DEPLOYMENT='gpt-4o-mini' AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT='text-embedding-3-small'

完成后别忘了保存.env文件。此时可以退出该文件，回到运行 Notebook 的说明。

配置 Microsoft Foundry Models：从项目 Overview 页获取

注意：GitHub Models 将于 2026 年 7 月底退役，Microsoft Foundry Models 是其直接替代者，提供同样的免费试用模型目录，以及 Azure AI Inference SDK / OpenAI SDK 的使用体验。

1. 打开 Microsoft Foundry（ai.azure.com），创建（或打开）一个 Foundry 项目；
2. 浏览模型目录并部署一个模型，例如gpt-4o-mini；
3. 在项目的Overview页面复制endpoint与API key；
4. 在.env中，endpoint 值填入AZURE_INFERENCE_ENDPOINT，key 值填入AZURE_INFERENCE_CREDENTIAL。

配置 OpenAI：从账号 Profile 获取密钥

你的 OpenAI API key 位于 OpenAI 账号的 API keys 页面。如果你还没有，可以注册一个账号并创建 API key。拿到 key 后，用它填充.env文件中的OPENAI_API_KEY变量即可。

配置 Hugging Face：从 Profile 创建访问令牌

你的 Hugging Face token 位于个人资料下的Access Tokens页面。不要公开张贴或分享这些 token。正确做法是：为本项目单独创建一个新的 token，然后复制到.env文件的HUGGING_FACE_API_KEY变量下。注意：严格来说它不是 API key，而是用于认证（authentication），这里沿用这一命名约定只是为了保持一致。

配置完全离线的本地供应商（补充）

如果你希望完全不使用云订阅，可以直接在自有设备上运行兼容的开源模型：

• Foundry Local：微软的端侧运行时，会自动选择最佳执行提供器（NPU、GPU 或 CPU），并暴露一个 OpenAI 兼容端点，因此可以用极少改动复用本课程大多数示例代码。可通过winget install Microsoft.FoundryLocal（Windows）或brew install microsoft/foundrylocal/foundrylocal（macOS）安装；
• Ollama：运行 Llama、Phi、Mistral、Gemma 等开源模型的流行本地方案。

课程第 19 课：使用 SLM 构建应用 中提供了两种方案的动手示例。

源码纵深：仓库代码如何消费这些环境变量

前面的配置流程「写变量」，而仓库的shared/python目录提供了「读变量」的标准实现，这也是各练习代码获取凭据的底层途径。

安全读取环境变量：env_utils.py

shared/python/env_utils.py 提供三个核心函数，用于「安全地获取与校验环境变量」：

• get_required_env(var_name, description=None)（env_utils.py#L11-L35）：读取单个必需变量；若未设置或为空，抛出带提示信息的ValueError，明确告诉你「请在 .env 文件或环境中设置该变量」；
• validate_env_vars(*var_names)（env_utils.py#L38-L71）：一次性校验多个变量，收集所有缺失项后统一报错（例如Missing required environment variables: AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_API_KEY），这解释了文档中「缺少凭据时相关练习会报错退出」的行为；
• get_env_with_default(var_name, default)（env_utils.py#L74-L88）：读取带默认值的变量，适合非必填配置。

对应的单元测试位于 tests/test_env_utils.py，可用来验证上述函数的缺省与异常路径。

用凭据构造客户端：api_utils.py

shared/python/api_utils.py 展示了.env中各变量最终如何被消费：

• create_openai_client(api_key=None)（api_utils.py#L56-L88）：未显式传入 key 时回退读取OPENAI_API_KEY环境变量，再构造OpenAI(api_key=key)客户端；key 缺失时抛出ValueError。
• create_azure_openai_client(endpoint=None, api_key=None)（api_utils.py#L91-L144）：回退读取AZURE_OPENAI_ENDPOINT与AZURE_OPENAI_API_KEY，两者缺一即报错。从源码结构看，它把 base_url 拼装为f"{endpoint.rstrip('/')}/openai/v1/"——即走 Azure OpenAI 的 v1 端点来支撑 Responses API，因此该路径下不需要api_version参数；而AZURE_OPENAI_API_VERSION（模板默认2024-10-21）则服务于直接使用 REST 风格调用（带api-version查询参数）的 Notebook。
• make_safe_request(...)（api_utils.py#L15-L53）：为所有出站 HTTP 请求提供 30 秒超时与 3 次重试，避免练习因瞬时网络故障而挂起。

这些行为的回归测试见 tests/test_api_utils.py。

常见问题与安全注意事项

结合 课程入门 README 与 本地部署指南 的排错表，凭据配置阶段常见的问题包括：

安全底线（与 本地部署指南 的告诫一致）：切勿把.env提交到代码仓库——把 API key 直接写进代码并提交到公开仓库，既可能造成安全问题，也可能被恶意利用产生不必要的费用。.env已在 .gitignore 中，保持这一习惯即可。

小结

本文以 courses 中 providers 配置文档（英文原版见 03-providers.md）为主线，完整覆盖了：供应商选型与注册对比、文件名 tag 约定、从 .env.copy 创建.env的四步流程、各环境变量的含义与取值来源（Azure 门户 Keys and Endpoint / Foundry 门户 Deployments / OpenAI 账号 / Hugging Face Access Tokens），以及 Foundry Models 与本地离线方案两个补充路径。在此基础上，结合 shared/python/env_utils.py 与 shared/python/api_utils.py 的源码实现，说明了课程代码读取、校验凭据并构造客户端的实际机制。完成上述配置后，即可按文件名 tag 选择对应供应商，开始运行课程各章节的练习。

【免费下载链接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners