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 ModelsHugging Face面向开源模型与推理服务Foundry Local / Ollama如果你希望在自有设备上完全离线运行模型无需任何云订阅。这些练习需要你使用自己的账号。练习是可选的因此你可以按兴趣选择配置其中一种、全部——或一种都不配置。以下是注册时的对比参考引自 providers 文档注册入口成本API KeyPlayground备注OpenAI按用量计费官方定价页基于项目Project-based网页版 No-Code Playground多个模型可选Azure有免费额度入口详见官方定价页见 SDK 快速上手文档Studio 快速上手文档需提前申请访问权限Microsoft Foundry见官方定价页提供免费层项目 Overview 页获取Foundry Playground模型目录页一个端点 一把 key 即可访问多家模型Hugging Face见官方定价页访问令牌Access TokensHugging ChatHugging Chat 可用模型有限Foundry Local免费运行在你自己的设备上不需要本地 CLI/SDK完全离线OpenAI 兼容端点文件名标签tag约定练习需要哪套凭据按照 providers 文档 的说明需要特定供应商的练习会在文件名中包含以下标签之一aoai— 需要 Azure OpenAI 的 endpoint 与 keyoai— 需要 OpenAI 的 endpoint 与 keyhf— 需要 Hugging Face tokengithubmodels— 需要 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 模型。下一步是配置本地环境变量在仓库根目录找到.env.copy文件。当前仓库中该文件的实际内容如下见 .env.copy# 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 ## Create/manage your resource and deployments from the Foundry portal - the env var names below are unchanged.) 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 - 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 projects Overview page.) AZURE_INFERENCE_ENDPOINTadd your Microsoft Foundry project endpoint here, e.g. https://resource-name.services.ai.azure.com/models AZURE_INFERENCE_CREDENTIALadd your Microsoft Foundry Models API key here ## Hugging Face HUGGING_FACE_API_KEYadd 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。用下面的命令把模板复制为.env。该文件已被gitignore掉可在 .gitignore 第 123 行确认.env条目从而保证密钥不会误提交到仓库cp .env.copy .env按下一节的说明填写各项值替换右侧的占位符。可选如果你使用 GitHub Codespaces可以选择不写本地.env而是把环境变量保存为与该仓库关联的Codespaces secrets。但请注意该选项只在 GitHub Codespaces 中生效——如果你改用 Docker DesktopDev Container 方式见 本地部署指南仍然需要本地.env文件。逐项理解.env中的变量以下是各变量名称的含义综合 providers 文档与当前 .env.copy 注释变量说明OPENAI_API_KEY使用非 Azure 的 OpenAI 端点服务的授权密钥AZURE_OPENAI_API_KEY使用 Azure OpenAIFoundry资源服务的授权密钥AZURE_OPENAI_ENDPOINT已部署的 Azure OpenAI 资源端点形如https://resource-name.openai.azure.comAZURE_OPENAI_DEPLOYMENT文本生成chat completion模型的部署名称AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT文本嵌入向量检索模型的部署名称AZURE_OPENAI_API_VERSIONAzure OpenAI REST API 版本模板中已默认设置为2024-10-21当前稳定 GA 版本AZURE_INFERENCE_ENDPOINT你的 Microsoft Foundry 项目端点用于访问多供应商模型目录AZURE_INFERENCE_CREDENTIAL你的 Microsoft Foundry 项目的 API keyHUGGING_FACE_API_KEY你在 Hugging Face 个人资料的 Access Tokens 中创建的访问令牌注意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 文档打开 Azure 门户进入你的 Azure OpenAI 资源点击侧边栏左侧菜单中的Keys and Endpoint选项点击Show Keys—— 你应该能看到KEY 1、KEY 2 和 Endpoint将KEY 1的值填入AZURE_OPENAI_API_KEY将Endpoint的值填入AZURE_OPENAI_ENDPOINT。接下来需要已部署模型的部署信息在 Azure OpenAI 资源的侧边栏点击Model deployments选项在目标页面点击Go to Microsoft Foundry portal或Manage Deployments具体取决于你的资源类型。这会把你带到 Microsoft Foundry 门户在那里可以找到其余的值。背景说明Azure OpenAI Service 现已并入 Microsoft Foundry。资源与部署仍然显示在 Azure 门户中但日常模型管理部署、playground、监控如今发生在 Foundry 门户中而非旧版独立的 Azure OpenAI Studio。配置 Azure OpenAI在 Foundry 门户中部署模型从你的资源出发导航到 Microsoft Foundry 门户如上一步所述点击Deployments选项卡左侧边栏查看当前已部署的模型如果你想要的模型尚未部署使用Deploy model从模型目录部署它你需要一个_文本生成_模型 —— 当前仓库推荐gpt-4o-mini意大利语版文档较早推荐的是gpt-35-turbo以当前模板注释与英文原文档为准你需要一个_文本嵌入_模型 —— 推荐text-embedding-3-small旧版推荐text-embedding-ada-002。现在更新环境变量使其反映你使用的_部署名称Deployment name_。除非你显式改过名字否则它通常与模型名相同。例如你可能会有AZURE_OPENAI_DEPLOYMENTgpt-4o-mini AZURE_OPENAI_EMBEDDINGS_DEPLOYMENTtext-embedding-3-small完成后别忘了保存.env文件。此时可以退出该文件回到运行 Notebook 的说明。配置 Microsoft Foundry Models从项目 Overview 页获取注意GitHub Models 将于 2026 年 7 月底退役Microsoft Foundry Models 是其直接替代者提供同样的免费试用模型目录以及 Azure AI Inference SDK / OpenAI SDK 的使用体验。打开 Microsoft Foundryai.azure.com创建或打开一个 Foundry 项目浏览模型目录并部署一个模型例如gpt-4o-mini在项目的Overview页面复制endpoint与API key在.env中endpoint 值填入AZURE_INFERENCE_ENDPOINTkey 值填入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.FoundryLocalWindows或brew install microsoft/foundrylocal/foundrylocalmacOS安装Ollama运行 Llama、Phi、Mistral、Gemma 等开源模型的流行本地方案。课程第 19 课使用 SLM 构建应用 中提供了两种方案的动手示例。源码纵深仓库代码如何消费这些环境变量前面的配置流程「写变量」而仓库的shared/python目录提供了「读变量」的标准实现这也是各练习代码获取凭据的底层途径。安全读取环境变量env_utils.pyshared/python/env_utils.py 提供三个核心函数用于「安全地获取与校验环境变量」get_required_env(var_name, descriptionNone)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.pyshared/python/api_utils.py 展示了.env中各变量最终如何被消费create_openai_client(api_keyNone)api_utils.py#L56-L88未显式传入 key 时回退读取OPENAI_API_KEY环境变量再构造OpenAI(api_keykey)客户端key 缺失时抛出ValueError。create_azure_openai_client(endpointNone, api_keyNone)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 与 本地部署指南 的排错表凭据配置阶段常见的问题包括症状排查方向OpenAI 返回 401 UnauthorizedOPENAI_API_KEY值错误或已过期OpenAI 返回 429触发请求速率限制降低调用频率ModuleNotFoundError: dotenv未安装依赖执行pip install -r requirements.txt或单独pip install python-dotenv练习报「缺少环境变量」错误对应供应商未配置属正常现象练习可选按文件名 tag 确认需要哪组变量后补齐.env安全底线与 本地部署指南 的告诫一致切勿把.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考