微软生成式 AI 入门课报认证错误：三条 provider 路线密钥字段不同

2026-08-18

站内工具 AI 编程工具报错分诊器 → 把报错原文贴进去，先分清是网络、额度、配置还是上游故障，再决定往哪个方向查。

跟着 generative-ai-for-beginners 走到第六课，.env 明明填了，脚本还是起不来——这类问题里有相当一部分不是密钥填错，而是你填的字段和你运行的那个脚本读的字段不是同一个。这个课程仓的同一节课常常同时放着三份示例，文件名前缀不同，读的环境变量名也各不相同。

现象：三种报错长得完全不一样

先把三份示例摆出来。以 06-text-generation-apps/python/ 为例，目录里同时存在 oai-app.py、aoai-app.py、githubmodels-app.py。它们取凭证的写法是三种：

oai-app.py 里根本没有出现任何环境变量名：

client = OpenAI()
deployment = "gpt-5-mini"

aoai-app.py 用的是下标取值：

client = OpenAI(
  api_key=os.environ['AZURE_OPENAI_API_KEY'],
  base_url=f"{os.environ['AZURE_OPENAI_ENDPOINT'].rstrip('/')}/openai/v1/",
  )

githubmodels-app.py 又换了一套变量：

token = os.environ["AZURE_INFERENCE_CREDENTIAL"]
endpoint = os.environ["AZURE_INFERENCE_ENDPOINT"]

三种写法对应三种失败形态。下标取值 os.environ[...] 在变量缺失时抛的是 KeyError，报错里会带上那个变量名——这一点仓库自己在 docs/SECURITY_GUIDELINES.md 的「Don’ts」小节里写得很直白，它把 api_key = os.environ["OPENAI_API_KEY"] 标成反面写法，注释就是 Raises KeyError if missing。而 oai-app.py 那种不传 api_key 的构造方式，变量名压根不在脚本里，报错自然不会点名任何字段，你在代码里 grep OPENAI_API_KEY 是搜不到的，只有 06-text-generation-apps/README.md 在旁边的提示框里交代了要设 OPENAI_API_KEY。

把报错形态和取值写法对起来，就是这么一张映射：报错里带变量名的 KeyError，来自 os.environ[...] 下标写法，缺的就是它点名的那一个；报错里带变量名的 ValueError 且文案含「Missing required environment variable」，来自 shared/python/env_utils.py 的 get_required_env（或示例文件内自带的同名函数）；报错里一个变量名都不出现、由 openai 这个库自己抛出来的，那就是 OpenAI() 无参构造那条路，它要的是 OPENAI_API_KEY。认清这三种形态，比逐行读脚本快。

判定动作：先确认你跑的是哪条路线

不要凭印象。00-course-setup/03-providers.md 明确写了作业文件名里的 tag 与所需凭证的对应关系：aoai 需要 Azure OpenAI 的 endpoint 与 key，oai 需要 OpenAI 的 endpoint 与 key，hf 需要 Hugging Face token，githubmodels 需要的是 Microsoft Foundry Models 的 endpoint 与 key。

所以第一步是看你手上这个文件叫什么，第二步是在这个文件里直接搜变量名。能搜到 AZURE_ 开头的，就照那个名字去 .env 里核；一个都搜不到（比如 oai-app.py），那就是走 SDK 默认从环境里读 OPENAI_API_KEY 的路子。

这里必须说清楚一件容易踩的事：githubmodels- 这个前缀已经名不副实了。 仓库在多处逐字写明 GitHub Models 于 2026 年 7 月底退役，直接替代者是 Microsoft Foundry Models：00-course-setup/02-setup-local.md 与 00-course-setup/README.md 里的提示框都写了「GitHub Models（连同它的 GITHUB_TOKEN 变量）」将退役；AGENTS.md 的环境变量清单里写的是 AZURE_INFERENCE_CREDENTIAL 取代了正在退役的 GITHUB_TOKEN；githubmodels-app.py 的文件头注释也直接指向 Foundry 项目的 Overview 页。今天这个时间点已经过去了。因此看到 githubmodels- 别去找什么 GitHub 的 token——.env.copy 里根本没有 GITHUB_TOKEN 这一项，你要配的是 AZURE_INFERENCE_ENDPOINT 与 AZURE_INFERENCE_CREDENTIAL。

三套字段名对照

.env.copy 是唯一权威清单，03-providers.md 的变量表是它的注解版。三条路线各要什么：

路线（文件名 tag）	实际接入目标	必填变量
`oai`	OpenAI	`OPENAI_API_KEY`
`aoai`	Azure OpenAI（现属 Microsoft Foundry）	`AZURE_OPENAI_API_KEY`、`AZURE_OPENAI_ENDPOINT`、`AZURE_OPENAI_DEPLOYMENT`
`githubmodels`	Microsoft Foundry Models（原 GitHub Models 路线）	`AZURE_INFERENCE_ENDPOINT`、`AZURE_INFERENCE_CREDENTIAL`

有两处细节值得单独拎出来。其一，AZURE_OPENAI_DEPLOYMENT 填的不是模型名而是部署名，03-providers.md 说明它通常与模型名相同，除非你在 Foundry 门户里显式改过；aoai-app.py 把它读出来直接当 model 传给 responses.create，所以这个字段填错时报的是模型/部署不存在，而不是认证失败。其二，.env.copy 与 AGENTS.md 里都列了 AZURE_INFERENCE_CHAT_MODEL（注释说明它给 temperature 示例用，需要一个非 reasoning 的模型部署名），但 03-providers.md 的变量说明表里没有收录这一项。两处对不上，写在这里供你核对，具体以仓库最新内容为准。

处置：仓库自己给了统一的校验工具

shared/python/env_utils.py 里有三个现成函数，比裸写 os.environ[...] 好排查：

get_required_env(var_name, description=None)：缺失时抛 ValueError，消息是 Missing required environment variable: {var_name}...Please set it in your .env file or environment.，带上 description 参数时会把说明括在变量名后面。
validate_env_vars(*var_names)：一次校验多个，把所有缺失的变量名合并在一条消息里报出来，返回值是变量名到值的字典。
get_env_with_default(var_name, default)：有默认值的可选项走这个。

有一个语义必须记住：get_required_env 的判断是 if not value，也就是说空字符串也算缺失。tests/test_env_utils.py 里的 test_get_required_env_empty_raises 就是专门钉这条的。这解释了一类怪现象——你在 .env 里写了 AZURE_OPENAI_API_KEY=，后面什么都没跟，报错仍然是「missing」。

06-text-generation-apps/python/aoai-app-recipe.py 是仓库里把这套用法落到实处的例子，它在文件内自带了一份 get_required_env，三处凭证全部走它：

client = OpenAI(
    api_key=get_required_env('AZURE_OPENAI_API_KEY'),
    base_url=f"{get_required_env('AZURE_OPENAI_ENDPOINT').rstrip('/')}/openai/v1/",
)

想在动手改课程代码前先自查，可以按同样的接口语义拼一小段：

from shared.python.env_utils import validate_env_vars

env = validate_env_vars("AZURE_INFERENCE_ENDPOINT", "AZURE_INFERENCE_CREDENTIAL")
print(env["AZURE_INFERENCE_ENDPOINT"])

以上为按仓库代码中的接口语义组合的示例，未经实测，以仓库最新代码为准。

还有一个更隐蔽的坑：谁加载了 `.env`

.env 文件本身不会自动进环境，得靠 python-dotenv。在 06-text-generation-apps/python/ 下逐个文件看会发现：oai-*.py 与 aoai-*.py 都在开头调了 load_dotenv()，而 githubmodels-app.py 里既没有 from dotenv import load_dotenv，也没有 load_dotenv() 调用，它直接读 os.environ。这意味着走 Foundry Models 这条线时，光把值写进 .env 是不够的，变量得真的在当前终端的环境里。这是把仓库里两处代码放在一起就能看出的差异，怎么处理由你决定。

配 .env 文件本身的两个平台差异，00-course-setup 里分开给了。02-setup-local.md 的建文件命令是：Unix 系统 touch .env，Windows 用 echo . > .env。而 03-providers.md 走的是另一条路，从模板复制：

cp .env.copy .env

仓库只给了这一条形式。Windows 上如果你的终端不认 cp，直接用编辑器另存一份同样成立——这属于通用做法，不是课程官方内容。

处置后怎么验证

最省事的验证是不发请求：在项目根目录起一个 Python 交互环境，load_dotenv() 之后把目标变量 os.getenv 出来，确认拿到的不是 None、也不是空串。02-setup-local.md 第 6 步给的就是这个思路，它示范的是把 AZURE_INFERENCE_ENDPOINT 与 AZURE_INFERENCE_CREDENTIAL 读出来打印 endpoint。打印 endpoint 是安全的，别把 key 打出来。

变量到位之后再跑对应的那个示例脚本。三条路线的脚本互不依赖，配好哪条就跑哪条——03-providers.md 说得很清楚，你可以只配一条、全配、或者一条都不配，相关作业只是会因为缺凭证而报错。

什么情况说明不是这个原因

下面几类报错和密钥字段没关系，别在 .env 上浪费时间：

ModuleNotFoundError。 02-setup-local.md 的排错表里就列了 ModuleNotFoundError: dotenv 这一条，处置是装依赖而不是改配置。还有一处值得注意：githubmodels-app.py 导入的是 azure.ai.inference，但 06-text-generation-apps/python/requirements.txt 里只有 openai 与 python-dotenv 两项，azure-ai-inference 是写在仓库根目录的 requirements.txt 与 pyproject.toml 里的（pyproject.toml 里的版本下限还是个 beta 标记）。只装了课程目录那份依赖，这条路线会在 import 阶段就断掉。

「parameter not supported」这类参数报错。 06-text-generation-apps/README.md 与 AGENTS.md 都写明，当前 Foundry 上未废弃的模型是 reasoning 模型（GPT-5 家族、o 系列），它们不支持 temperature 与 top_p，也不支持 max_tokens，要改用 max_output_tokens。README 里直说，给 gpt-5-mini 传 temperature 会拿到参数不支持的错误。想试 temperature 示例，仓库的做法是指向一个仍支持采样控制的模型部署，也就是 AZURE_INFERENCE_CHAT_MODEL 那一项。这类报错改密钥没有用。

限流类错误。 02-setup-local.md 的排错表把 401 与 429 并列在一行，处置写的是「检查 OPENAI_API_KEY 的值 / 请求频率」——401 归凭证，429 归频率，这两件事别混着查。

AZURE_OPENAI_API_VERSION 没配。 这一项在 .env.copy 里带了默认值，但 aoai-app.py 从头到尾没有读它；06-text-generation-apps/README.md 解释了原因，它用的是把 /openai/v1/ 拼在 endpoint 后面的写法，README 原话是这个稳定的 v1 端点不需要管理 api_version。所以认证失败时盯着这个字段查，方向是错的。

课程会持续更新，上面提到的文件路径、变量名与依赖清单都可能随版本变动，以仓库最新内容为准。

本文依据 github.com/microsoft/generative-ai-for-beginners 仓库于 2026-08-18 的公开内容整理，事实来自仓库内的课程正文与代码示例。我们没有跑过文中涉及的代码，因此不涉及运行结果、耗时与生成质量的任何描述。该课程持续更新，文中涉及的文件路径、依赖与接口写法随版本变动，请以仓库最新内容为准。文中涉及的云端服务调用会产生费用并可能上传数据，请自行评估密钥与数据边界。

安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。