generative-ai-for-beginners 环境配置实战：为课程练习接入 OpenAI、Azure OpenAI 与 Hugging Face 多 LLM 服务商

generative-ai-for-beginners 环境配置实战：为课程练习接入 OpenAI、Azure OpenAI 与 Hugging Face 多 LLM 服务商

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

本教程对应本仓库00-course-setup/03-providers.md（含芬兰语翻译 translations/fi/00-course-setup/03-providers.md）的核心内容：课程中大量实验 Notebook 与脚本通过三家“托管式大语言模型服务商”（OpenAI、Azure OpenAI、Hugging Face）提供的hosted endpoint（托管 API）运行。完成本教程后，你将能够：读懂课程练习文件名的aoai/oai/hf标签、正确创建并填充仓库根目录的.env配置文件、从各平台门户安全获取 API Key / Token，并理解仓库源码实际读取这些环境变量的机制，从而零障碍地运行课程中的示例代码。

为什么课程需要自行配置 LLM 服务商

本仓库（generative-ai-for-beginners，21 Lessons 入门课程）中的作业（assignments）可以被配置为经由服务商提供的hosted endpoint（API）运行一个或多个大语言模型（LLM）部署。所谓 hosted endpoint，就是服务商在云端托管模型并以 HTTP API 形式暴露的调用入口，我们只需要持有正确凭据（API Key 或 Token）即可通过编程方式调用，而无需在本地部署模型。

本课程围绕三个主要服务商展开，各自定位如下：

• OpenAI：提供多样化的模型阵容，覆盖核心 GPT 系列，适合直接体验官方模型能力；
• Azure OpenAI：将 OpenAI 模型带入微软 Azure 平台，强调企业级就绪性（安全、合规、托管），并提供 Azure 门户与 Studio 两套管理界面；
• Hugging Face：面向开源模型与推理服务器生态，通过 Access Token 鉴权调用。

你需要使用自己的账户完成这些练习。由于作业是可选的，你可以根据兴趣配置其中一个、全部、甚至一个都不配置。下表汇总了三家服务商在注册、计费、密钥获取、Playground 等维度的差异（内容来自课程文档）：

从文件名标签识别练习所需的 Provider

配置完成后，仓库内凡是针对特定服务商的作业，文件名都带有如下标签之一，作为“该练习依赖哪套凭据”的约定：

• aoai—— 需要 Azure OpenAI 的 endpoint 与 key（例如 06-text-generation-apps/python/aoai-app.py）；
• oai—— 需要 OpenAI 的 endpoint 与 key（例如 06-text-generation-apps/python/oai-app.py）；
• hf—— 需要 Hugging Face token。

你可以配置一个、零个或全部 Provider。相关的作业在缺少对应凭据时会直接报错（“missing credentials”），而不会悄悄跳过——这正是本教程要你先把.env配好的原因。此外，仓库中还存在基于 Azure AI Inference SDK 的githubmodels类型示例（如 06-text-generation-apps/python/githubmodels-app.py），它们在根目录 .env.copy 中以AZURE_INFERENCE_ENDPOINT、AZURE_INFERENCE_CREDENTIAL两变量承载凭据，属于同一套配置思路的扩展，将在下文变量清单中一并说明。

第一步实操：创建.env文件

在动手之前，请先确认你已经：阅读了上文指引、在对应服务商完成注册、拿到了所需凭据；若使用 Azure OpenAI，还需要已有一个有效的 Azure OpenAI 服务部署（endpoint），并且至少部署了一个用于 Chat Completion 的 GPT 模型。

随后按以下步骤配置本地环境变量：

1. 在仓库根目录找到 .env.copy 模板文件，其内容形如下方代码块。请注意：这是当前仓库实际版本的模板，已将AZURE_OPENAI_API_VERSION默认值设为2024-10-21（当前稳定 GA 版本），并增加了 Microsoft Foundry 相关的两个变量；较旧课程版本中2024-02-01的默认值已不再使用，请以仓库实际模板为准：

# 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, replaces GitHub Models, which retires end of July 2026) AZURE_INFERENCE_ENDPOINT='<add your Microsoft Foundry project endpoint here>' AZURE_INFERENCE_CREDENTIAL='<add your Microsoft Foundry Models API key here>' ## Hugging Face HUGGING_FACE_API_KEY='<add your HuggingFace API or token here>'

2. 执行下述命令把模板复制为.env：

cp .env.copy .env

之所以需要这一步，是因为.env已被写入仓库根目录的 .gitignore（其中包含.env条目），该文件不会进入版本控制，密钥由此得到保护；而.env.copy作为可提交的模板保留在仓库中。

3. 按照下一节的说明，替换每个=右侧的占位符（如<add your OpenAI API key here>）为真实取值。

4. （可选）如果你使用 GitHub Codespaces，也可以把环境变量保存为该仓库关联的Codespaces Secrets，这样无需创建本地.env文件。但请注意：此方案只对 GitHub Codespaces 生效；如果改用 Docker Desktop 等本地环境，仍然必须创建.env文件。

.env变量清单与含义速查

.env采用典型的KEY='value'键值对格式。下表逐个说明各变量的语义（来自课程文档并对照 .env.copy 注释整理）：

需要特别说明的是：最后两个 Azure OpenAI 变量分别指向“默认的对话补全模型（文本生成）”与“默认的向量检索模型（嵌入）”。二者对应两类截然不同的任务——前者用于聊天与生成类作业，后者用于基于向量的搜索类作业（可参考 08-building-search-applications 中检索应用的用法）；具体如何取值，会由相关作业各自给出部署指引。

配置 Azure OpenAI：从 Azure 门户获取 endpoint 与 Key

Azure OpenAI 的 endpoint 和 Key 位于 Azure 门户中，因此从门户开始：

1. 进入 Azure 门户，从左侧菜单点击Keys and Endpoint；
2. 点击Show Keys，页面会展示KEY 1、KEY 2与Endpoint三项内容；
3. 将KEY 1的值填入.env的AZURE_OPENAI_API_KEY；
4. 将Endpoint的值填入.env的AZURE_OPENAI_ENDPOINT。

拿到资源级凭据后，还需要进一步获取具体已部署模型的名称。需要注意的是，按 .env.copy 顶部注释说明，Azure OpenAI 服务现已纳入 Microsoft Foundry 体系，资源的日常模型管理（部署、Playground、监控）主要在 Foundry 门户中完成，而资源与部署仍会在 Azure 门户中展示：

1. 在 Azure OpenAI 资源的左侧菜单点击Model deployments；
2. 在目标页面点击Manage Deployments（或按资源类型跳转至 Microsoft Foundry 门户）。

配置 Azure OpenAI：在 Studio / Foundry 门户完成模型部署

进入模型管理页面后，我们需要的剩余取值都从这里获得：

1. 按照上文入口进入 Azure OpenAI Studio / Microsoft Foundry 门户；
2. 点击左侧Deployments标签页，查看当前已部署的模型列表；
3. 如果所需模型尚未部署，使用Create new deployment / Deploy model功能从模型目录中部署；
4. 你需要一个文本生成模型——当前仓库模板与示例代码推荐gpt-4o-mini；
5. 你还需要一个文本嵌入模型——推荐text-embedding-3-small。

随后把.env中的两个变量更新为实际的Deployment name（部署名）。部署名通常与模型名一致，除非你显式修改过，例如：

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

兼容性提示：较旧的课程版本中曾以gpt-35-turbo、text-embedding-ada-002作为推荐值。若你的账号/区域仅能部署这些早期模型，把部署名填入变量同样可行；但本仓库当前的示例代码与模板默认使用gpt-4o-mini系列，部署新模型可以获得与教程代码一致的体验。

完成修改后务必保存.env文件，随后即可关闭文件，回到对应 Notebook 的指引继续执行。

配置 OpenAI 与 Hugging Face：从个人 Profile 获取密钥

OpenAI

你的 OpenAI API Key 可在 OpenAI 账户中查看。如果还没有密钥，请先注册账户并创建一个 API Key。拿到密钥后，将其填入.env文件的OPENAI_API_KEY变量即可。OpenAI 采用**项目级（Project-based）**密钥体系，创建时注意归属正确的项目。

Hugging Face

你的 Hugging Face Token 位于个人主页的Access Tokens设置中。请勿把 Token 公开张贴或分享。正确做法是：为本项目单独创建一个新 Token，再把它复制到.env的HUGGING_FACE_API_KEY变量下。

备注：HUGGING_FACE_API_KEY严格来说并不是 API Key，而是用于鉴权的 Access Token，此处沿用“key”命名是为了与课程其它变量保持一致的命名习惯。

仓库源码如何消费这些配置：从.env到 API 客户端

理解了配置项的含义之后，再看仓库源码就能明白“填好.env后一切是如何串起来的”。这一机制可以从三个层面印证：

1. 统一的环境变量读取工具。仓库在 shared/python/env_utils.py 中提供了标准化读取函数：get_required_env 用于读取某个必填变量，缺失或为空时抛出带提示信息的ValueError；validate_env_vars 可一次性校验多个变量并汇总所有缺失项；get_env_with_default 则用于带默认值的读取。它们抛出的“Missing required environment variable ... Please set it in your .env file or environment”错误信息，正是课程文档所述“缺少凭据时作业直接报错”的源码级体现。对应的单元测试见 tests/test_env_utils.py，覆盖了“缺失抛错”“空值抛错”“默认值回退”等边界场景。

2. 不同 Provider 的客户端工厂。shared/python/api_utils.py 中的 create_openai_client 在未显式传入api_key时会回退读取OPENAI_API_KEY环境变量；create_azure_openai_client 则要求AZURE_OPENAI_ENDPOINT与AZURE_OPENAI_API_KEY同时存在，并把base_url拼接为<endpoint>/openai/v1/形式。从中可以看出.env变量名与代码中的os.getenv调用是一一对应的约定。

3. 课程示例的直接用法。各课示例代码均先用python-dotenv的load_dotenv()加载.env：

• 06-text-generation-apps/python/oai-app.py 直接OpenAI()（SDK 自动读取OPENAI_API_KEY），随后以client.responses.create(...)调用 Responses API；
• 06-text-generation-apps/python/aoai-app.py 显式读取AZURE_OPENAI_API_KEY、AZURE_OPENAI_ENDPOINT、AZURE_OPENAI_DEPLOYMENT三个变量构造客户端并指定部署名；
• 06-text-generation-apps/python/githubmodels-app.py 通过azure.ai.inference.ChatCompletionsClient读取AZURE_INFERENCE_CREDENTIAL与AZURE_INFERENCE_ENDPOINT。

这些示例共同说明：配置工作只发生在.env，业务代码只按固定变量名取用。因此只要变量名与仓库模板一致、值真实有效，同一份代码即可在不同 Provider 之间切换运行。

常见问题与安全注意事项

• .env不要提交到版本库：.env已被 .gitignore 忽略，请勿通过git add -f强制提交；密钥泄露后应立即在对应平台吊销并重建。
• 报 “Missing required environment variable”：说明代码需要读取的变量未在.env中定义或为空，先对照上文变量清单核对拼写（例如OPENAI_API_KEY与AZURE_OPENAI_API_KEY是两套不同变量，不要混填）。
• Azure 变量全填了仍报 401/404：优先核对AZURE_OPENAI_DEPLOYMENT是否与门户中实际的 Deployment name 完全一致（含大小写），并确认 endpoint 未遗漏https://前缀。
• 分别创建独立 Token/Key：Hugging Face 建议按项目创建独立 Token、OpenAI 使用项目级密钥，避免单一凭据权限过大。
• 想在本地全离线运行：课程文档的后续内容（见 19-slm/README.md）提供了完全离线的本地推理方案（Foundry Local / Ollama），可在无云订阅的情况下复用本仓库大部分示例代码。

至此，你已完整掌握本仓库 Provider 配置的全流程：识别文件标签 → 从 .env.copy 创建.env→ 在 OpenAI / Azure OpenAI / Hugging Face 获取凭据并逐项填充 → 通过源码理解配置的消费链路。接下来即可回到 00-course-setup 中选定的作业，启动你的第一个 Generative AI 练习。

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