generative-ai-for-beginners 课程指南：LLM 服务提供者选型与 .env 凭证配置实战

本篇技术指南围绕 generative-ai-for-beginners 课程的课程准备文档 03-providers 展开，讲解如何为课程中的编程作业选择并配置 LLM 服务提供者（OpenAI、Azure OpenAI、Hugging Face 等），以及如何安全地创建和填写 .env 环境变量文件。读完本文后，你将能够独立完成凭证获取、.env 配置、Azure 门户/Studio 端点与模型部署名称的填写，并能结合仓库源码理解这些环境变量在示例代码中是如何被读取和校验的。

课程支持哪些 LLM 提供者

课程的编程作业可以通过一个或多个受支持的服务提供者接入大语言模型（LLM）部署。这些提供者都提供托管端点（API），我们可以在持有正确凭证（API Key 或 Token）的前提下以编程方式访问。课程讨论的主要提供者包括：

• OpenAI：提供多样的模型，包括核心的 GPT 系列；
• Azure OpenAI：同样提供 OpenAI 模型，但侧重于企业级就绪能力；
• Hugging Face：面向开源模型与推理服务器；
• 此外，当前仓库的英文原版文档 00-course-setup/03-providers.md 还补充了两类选项：Microsoft Foundry Models（用一个端点和一个 API Key 访问 OpenAI、Meta、Mistral、Cohere、Microsoft 等数百个模型，取代将于 2026 年 7 月底退役的 GitHub Models）以及离线/本地提供者（Foundry Local 或 Ollama，可完全离线在本机运行模型，无需云订阅）。

完成这些练习需要使用你自己的账户。所有编程作业都是可选的，你可以根据自己的兴趣选择配置其中一个、全部或者一个都不配置。各提供者的注册指引概览如下：

注册入口	成本	API Key 获取	Playground	备注
OpenAI	按量计费（见其定价页）	基于项目（Project）管理	网页端免代码体验	提供多种模型
Azure	按量计费（有免费额度）	通过 SDK 快速入门	通过 Azure AI Studio 快速入门	需要提前申请访问权限
Hugging Face	按量计费	访问令牌（Access Token）	Hugging Chat	Hugging Chat 可用的模型数量有限

通过文件名识别作业所需的提供者

按照下面的步骤配置本仓库以适配不同的提供者。需要特定提供者的作业，其文件名中会包含相应的标记，这是本课程仓库的命名约定：

• aoai —— 需要 Azure OpenAI 端点与密钥（endpoint, key）
• oai —— 需要 OpenAI 端点与密钥（endpoint, key）
• hf —— 需要 Hugging Face 令牌
• githubmodels —— 需要 Microsoft Foundry Models 端点与密钥（GitHub Models 将于 2026 年 7 月底退役）

你可以在仓库中直接验证这一约定，例如：

• 06-text-generation-apps/python/aoai-app.py、09-building-image-applications/python/aoai-app.py 等 aoai-* 脚本依赖 Azure OpenAI；
• 同目录下的 oai-* 脚本（如 06-text-generation-apps/python/oai-app.py）依赖 OpenAI；
• 06-text-generation-apps/js-githubmodels/app.js 等 js-githubmodels 目录下的脚本依赖 Microsoft Foundry Models（原 GitHub Models）。

可以只配置一个、不配置、或全部配置提供者。缺少凭证时，相关作业会直接报错退出，而不会影响其他作业的运行——这正是采用环境变量隔离凭证的设计意图。

创建 .env 文件

在开始之前，假设你已经注册了相应提供者，并拿到了所需的认证凭证（API_KEY 或 Token）。对于 Azure OpenAI，我们进一步假设你拥有一个有效的 Azure OpenAI 服务部署（端点），且上面至少部署了一个用于聊天补全的 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)
   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.)
   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>'
   

   翻译版文档中的模板与当前仓库模板略有差异：翻译版记录的是 AZURE_OPENAI_API_VERSION='2024-02-01' 且未包含 Foundry 变量，而当前仓库实际提交的 .env.copy 已将默认 API 版本更新为 2024-10-21，并新增了 AZURE_INFERENCE_ENDPOINT / AZURE_INFERENCE_CREDENTIAL 两个变量。实操时应以仓库中的模板为准。

2. 用下面的命令把该文件复制为 .env。.env 已被 .gitignore 忽略，从而保证密钥不会随代码一起提交：

   cp .env.copy .env
   

3. 填写具体值（替换 = 右侧的占位符），方法见下一节。

4. （可选）如果你使用 GitHub Codespaces，可以把这些环境变量作为 Codespaces secrets 保存在与该仓库关联的密钥库中，此时就不需要本地 .env 文件了。注意：该选项仅在 GitHub Codespaces 中有效；如果你改用 Docker Desktop，则仍然需要配置本地 .env。

课程入门页 00-course-setup/README.md 中还给出了 Codespaces 下添加 secret 的配套操作（齿轮图标 → 命令面板 → Codespaces: Manage user secret → Add a new secret，命名为 OPENAI_API_KEY），以及使用 python-dotenv 在脚本中加载 .env 的最小示例：

from dotenv import load_dotenv
import os

load_dotenv()  # 从 .env 文件加载环境变量

endpoint = os.getenv("AZURE_INFERENCE_ENDPOINT")
token = os.getenv("AZURE_INFERENCE_CREDENTIAL")

逐变量解析 .env

先看一眼变量名，理解它们分别代表什么：

变量	说明
HUGGING_FACE_API_KEY	你在 Hugging Face 个人资料中创建的用户访问令牌
OPENAI_API_KEY	用于访问非 Azure 的 OpenAI 端点的授权密钥
AZURE_OPENAI_API_KEY	用于访问 Azure OpenAI（Foundry）资源的授权密钥
AZURE_OPENAI_ENDPOINT	已部署的 Azure OpenAI 资源端点
AZURE_OPENAI_DEPLOYMENT	文本生成模型的部署端点名称
AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT	文本嵌入模型的部署端点名称
AZURE_INFERENCE_ENDPOINT	Microsoft Foundry 项目的端点（用于 Foundry Models 目录）
AZURE_INFERENCE_CREDENTIAL	Microsoft Foundry 项目的 API Key

说明：其中两个 Azure OpenAI 部署变量分别对应聊天补全（文本生成）与向量检索（嵌入）的默认模型。它们的具体设置方法会在相关作业的说明中定义。

Azure 与 OpenAI 的关键区别：OpenAI 只需一个 API Key 即可用模型名（如 gpt-4o-mini）直接调用；而 Azure OpenAI 要求你在资源上显式部署模型，调用时使用的是部署名（deployment name）而非模型名——这就是 AZURE_OPENAI_DEPLOYMENT 与 AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT 存在的意义。

源码视角：环境变量如何被读取与校验

配置完成后，这些变量在课程代码中是如何被消费的？仓库提供了两层实现证据。

示例脚本的直接消费方式

以 06-text-generation-apps/python/aoai-app.py 为例，典型的 aoai 作业脚本采用如下模式（见 aoai-app.py#L7-L15）：

from openai import OpenAI
import os
from dotenv import load_dotenv

load_dotenv()  # 从 .env 文件加载环境变量

# 把 OpenAI 客户端指向 Azure OpenAI (Microsoft Foundry) 的 v1 端点
client = OpenAI(
    api_key=os.environ['AZURE_OPENAI_API_KEY'],
    base_url=f"{os.environ['AZURE_OPENAI_ENDPOINT'].rstrip('/')}/openai/v1/",
)

deployment = os.environ['AZURE_OPENAI_DEPLOYMENT']

prompt = "Complete the following: Once upon a time there was a"
response = client.responses.create(model=deployment, input=prompt, store=False)
print(response.output_text)

从源码结构看，这里体现了两个要点：其一，base_url 被拼成 <endpoint>/openai/v1/ 形式，走的是兼容的 v1 端点，因此脚本中不再需要传递 api_version；其二，请求中的 model 参数填的是 .env 里的部署名，而不是模型名——这与上文变量表的设计一一对应。

共享工具库：缺失凭证时报错的可读性

课程在 shared/python/env_utils.py 中抽出了一套环境变量工具函数，用于“安全地获取并校验环境变量”：

• get_required_env：读取单个必需变量；若未设置或为空，抛出带提示信息的 ValueError（提示你在 .env 文件或环境中设置它）；
• validate_env_vars：批量校验多个变量，并把所有缺失的变量名一并列在错误信息中，方便一次性补齐；
• get_env_with_default：读取带默认值的变量。

相应地，shared/python/api_utils.py 提供了客户端工厂函数：

• create_openai_client：从 OPENAI_API_KEY 读取密钥创建 OpenAI 客户端，缺失时报错；
• create_azure_openai_client：从 AZURE_OPENAI_ENDPOINT 与 AZURE_OPENAI_API_KEY 构建指向 <endpoint>/openai/v1/ 的客户端，端点或密钥缺失时会分别抛出指向对应环境变量的错误信息。

这套校验逻辑的行为有完整的测试覆盖，见 tests/test_env_utils.py：例如 test_get_required_env_empty_raises 验证空字符串也会被判定为缺失，test_validate_env_vars_reports_all_missing 验证多个变量缺失时错误信息会包含全部变量名。也就是说，“配置不完整时作业直接报错”这句话在仓库里不仅是约定，而且有测试背书。

配置 Azure OpenAI：从门户（Portal）

Azure OpenAI 的端点与密钥值可以在 Azure 门户中找到，操作如下：

1. 进入 Azure 门户；
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：从 Foundry 门户 / Studio

1. 按照上文从你的资源进入 Microsoft Foundry 门户（旧称 Azure OpenAI Studio）；
2. 点击左侧边栏的 Deployments（部署）选项卡，查看当前已部署的模型；
3. 若目标模型尚未部署，使用 Deploy model / 创建新部署 从模型目录中部署它；
4. 你需要一个文本生成模型——翻译版文档推荐 gpt-35-turbo，当前仓库模板注释中推荐 gpt-4o-mini；
5. 你需要一个文本嵌入模型——翻译版文档推荐 text-embedding-ada-002，当前仓库模板注释中推荐 text-embedding-3-small。

然后把环境变量更新为实际使用的部署名称。部署名通常与模型名相同，除非你显式改过。示例：

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

完成后别忘了保存 .env 文件，然后就可以退出编辑器、回到课程说明去运行 Notebook 了。

配置 OpenAI：从个人资料

OpenAI 的 API Key 可以在你的 OpenAI 账户资料页（API keys 页面）中找到。如果还没有，可以先注册账户并创建一个 API Key。拿到密钥后，将其填入 .env 中的 OPENAI_API_KEY 变量即可。OpenAI 侧没有“部署”概念，脚本中直接以模型名发起请求，因此配置最简单。

配置 Hugging Face：从个人资料

Hugging Face 的令牌（Token）可以在个人资料的 Access Tokens 页面找到。不要公开粘贴或分享这些令牌。正确做法是为本课程的使用场景新建一个令牌，再把它复制到 .env 的 HUGGING_FACE_API_KEY 变量下。

命名说明：严格来说它不是 API Key 而是访问令牌，但由于其用途是身份认证，仓库沿用 API_KEY 的命名以保持各提供者配置的一致性。

配置 Microsoft Foundry Models（原 GitHub Models）

仓库当前英文文档与 .env.copy 注释中还新增了 Foundry Models 的配置路径（GitHub Models 将于 2026 年 7 月底退役，Foundry Models 是直接的替代品）：

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

离线/本地提供者（补充）

如果完全不使用云订阅，也可以在本机直接运行兼容的开放模型：

• Foundry Local：微软的端侧运行时，自动选择最佳执行提供者（NPU、GPU 或 CPU），并暴露 OpenAI 兼容端点，因此可以用最小改动复用课程大部分示例代码；
• Ollama：在本地运行 Llama、Phi、Mistral、Gemma 等开放模型的流行选择。

课程第 19 课（19-slm/README.md）提供了这两种方案的实操示例。

小结：配置自检清单

检查项	验证方式
.env 已由 .env.copy 复制并填入真实凭证	确认 .env 存在于仓库根目录，且未被 Git 跟踪（.gitignore）
Azure 四要素齐全	AZURE_OPENAI_ENDPOINT、AZURE_OPENAI_API_KEY、AZURE_OPENAI_DEPLOYMENT、AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT 均非空
部署名与模型一致	部署名通常等于模型名（如 gpt-4o-mini、text-embedding-3-small）
缺失变量时的报错可读	参考 shared/python/env_utils.py 与 tests/test_env_utils.py，空值与未设置都会触发带变量名的 ValueError
作业与提供者匹配	按文件名标记 aoai / oai / hf / githubmodels 选择已配置提供者的作业

完成以上配置后，你就可以按照各课程章节的说明开始运行对应的 Notebook 与脚本，而不必担心密钥泄漏到版本库中。