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-beginners21 Lessons 入门课程中的作业assignments可以被配置为经由服务商提供的hosted endpointAPI运行一个或多个大语言模型LLM部署。所谓 hosted endpoint就是服务商在云端托管模型并以 HTTP API 形式暴露的调用入口我们只需要持有正确凭据API Key 或 Token即可通过编程方式调用而无需在本地部署模型。本课程围绕三个主要服务商展开各自定位如下OpenAI提供多样化的模型阵容覆盖核心 GPT 系列适合直接体验官方模型能力Azure OpenAI将 OpenAI 模型带入微软 Azure 平台强调企业级就绪性安全、合规、托管并提供 Azure 门户与 Studio 两套管理界面Hugging Face面向开源模型与推理服务器生态通过 Access Token 鉴权调用。你需要使用自己的账户完成这些练习。由于作业是可选的你可以根据兴趣配置其中一个、全部、甚至一个都不配置。下表汇总了三家服务商在注册、计费、密钥获取、Playground 等维度的差异内容来自课程文档维度OpenAIAzure OpenAIHugging Face注册入口官方平台注册Azure 账户注册官方社区注册计费按模型使用量定价按服务使用量定价提供免费/付费层级API Key项目级Project-based密钥资源级密钥KEY 1 / KEY 2Access Token细粒度权限令牌Playground网页版无代码 PlaygroundStudio / 门户内 PlaygroundHugging Chat模型数量有限备注可用模型较多需提前申请访问权限注意 Hugging Chat 仅支持有限模型从文件名标签识别练习所需的 Provider配置完成后仓库内凡是针对特定服务商的作业文件名都带有如下标签之一作为“该练习依赖哪套凭据”的约定aoai—— 需要 Azure OpenAI 的 endpoint 与 key例如 06-text-generation-apps/python/aoai-app.pyoai—— 需要 OpenAI 的 endpoint 与 key例如 06-text-generation-apps/python/oai-app.pyhf—— 需要 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 模型。随后按以下步骤配置本地环境变量在仓库根目录找到 .env.copy 模板文件其内容形如下方代码块。请注意这是当前仓库实际版本的模板已将AZURE_OPENAI_API_VERSION默认值设为2024-10-21当前稳定 GA 版本并增加了 Microsoft Foundry 相关的两个变量较旧课程版本中2024-02-01的默认值已不再使用请以仓库实际模板为准# OpenAI Provider OPENAI_API_KEYadd 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_VERSION2024-10-21 # Default is set! (current stable GA API version) 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 (multi-provider model catalog, replaces GitHub Models, which retires end of July 2026) 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执行下述命令把模板复制为.envcp .env.copy .env之所以需要这一步是因为.env已被写入仓库根目录的 .gitignore其中包含.env条目该文件不会进入版本控制密钥由此得到保护而.env.copy作为可提交的模板保留在仓库中。按照下一节的说明替换每个右侧的占位符如add your OpenAI API key here为真实取值。可选如果你使用 GitHub Codespaces也可以把环境变量保存为该仓库关联的Codespaces Secrets这样无需创建本地.env文件。但请注意此方案只对 GitHub Codespaces 生效如果改用 Docker Desktop 等本地环境仍然必须创建.env文件。.env变量清单与含义速查.env采用典型的KEYvalue键值对格式。下表逐个说明各变量的语义来自课程文档并对照 .env.copy 注释整理变量含义HUGGING_FACE_API_KEY你在 Hugging Face 个人主页中创建的用户访问令牌user access tokenOPENAI_API_KEY调用非 Azure 的 OpenAI 端点时使用的授权密钥AZURE_OPENAI_API_KEY调用 Azure OpenAI 服务时使用的授权密钥AZURE_OPENAI_ENDPOINT已部署的 Azure OpenAI 资源的 endpoint 地址AZURE_OPENAI_DEPLOYMENT文本生成Chat Completion模型的部署名AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT文本嵌入Embeddings模型的部署名AZURE_INFERENCE_ENDPOINTMicrosoft Foundry 项目的 endpoint多 Provider 模型目录AZURE_INFERENCE_CREDENTIALMicrosoft Foundry 项目的 API Key需要特别说明的是最后两个 Azure OpenAI 变量分别指向“默认的对话补全模型文本生成”与“默认的向量检索模型嵌入”。二者对应两类截然不同的任务——前者用于聊天与生成类作业后者用于基于向量的搜索类作业可参考 08-building-search-applications 中检索应用的用法具体如何取值会由相关作业各自给出部署指引。配置 Azure OpenAI从 Azure 门户获取 endpoint 与 KeyAzure OpenAI 的 endpoint 和 Key 位于 Azure 门户中因此从门户开始进入 Azure 门户从左侧菜单点击Keys and Endpoint点击Show Keys页面会展示KEY 1、KEY 2与Endpoint三项内容将KEY 1的值填入.env的AZURE_OPENAI_API_KEY将Endpoint的值填入.env的AZURE_OPENAI_ENDPOINT。拿到资源级凭据后还需要进一步获取具体已部署模型的名称。需要注意的是按 .env.copy 顶部注释说明Azure OpenAI 服务现已纳入 Microsoft Foundry 体系资源的日常模型管理部署、Playground、监控主要在 Foundry 门户中完成而资源与部署仍会在 Azure 门户中展示在 Azure OpenAI 资源的左侧菜单点击Model deployments在目标页面点击Manage Deployments或按资源类型跳转至 Microsoft Foundry 门户。配置 Azure OpenAI在 Studio / Foundry 门户完成模型部署进入模型管理页面后我们需要的剩余取值都从这里获得按照上文入口进入 Azure OpenAI Studio / Microsoft Foundry 门户点击左侧Deployments标签页查看当前已部署的模型列表如果所需模型尚未部署使用Create new deployment / Deploy model功能从模型目录中部署你需要一个文本生成模型——当前仓库模板与示例代码推荐gpt-4o-mini你还需要一个文本嵌入模型——推荐text-embedding-3-small。随后把.env中的两个变量更新为实际的Deployment name部署名。部署名通常与模型名一致除非你显式修改过例如AZURE_OPENAI_DEPLOYMENTgpt-4o-mini AZURE_OPENAI_EMBEDDINGS_DEPLOYMENTtext-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 用于读取某个必填变量缺失或为空时抛出带提示信息的ValueErrorvalidate_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()加载.env06-text-generation-apps/python/oai-app.py 直接OpenAI()SDK 自动读取OPENAI_API_KEY随后以client.responses.create(...)调用 Responses API06-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/KeyHugging 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考