通过 Microsoft Foundry 调用 Grok 模型：部署、鉴权与排错
数据截至 2026-08，价格与限额以各官网为准。本文只讲计费与接入机制，不列具体价格数字。
在 Microsoft Foundry 上用 Grok，和直连 xAI 自己的 API 是两套完全不同的运维模型：鉴权换成了 Microsoft Entra ID 的角色体系，账单并到你的 Azure 订阅里，配额和限流由 Azure 资源级别管理，端点变成了你自己那个 Foundry 项目的 OpenAI 兼容地址。代码层面反倒改得不多——官方文档说它兼容 OpenAI 的 Python/TypeScript SDK，流式、工具调用、结构化输出都支持。真正会绊住人的是三件事：部署名一旦建好就改不了而且它就是你请求里的 model 值；DefaultAzureCredential 那条链在本地和在云上走的路不一样；出问题时你要报给支持的不是堆栈而是几个 Azure 请求 ID。下面按你实际会走的顺序拆。
先分清 resource 和 project 这两层
Foundry 把工作组织成两层：resource 这一层管安全、计费和网络，project 这一层管部署和协作。官方给的顺序是先建（或选）一个 resource，然后在里面建 project，再在 project 里部署 Grok 模型实例。
这两层的名字不是摆设，它们直接拼进你的端点里。官方文档给出的端点基址形态是：
https://{resource-name}.services.ai.azure.com/api/projects/{project-name}/openai/v1
也就是说，这两个名字是端点地址本身的一部分，写错任何一个，请求打到的就不是你那个项目的地址。至于资源名或项目名写错时服务端会返回什么样的提示，官方文档里没有找到相关说明——排障对照表里唯一和「名字写错」沾边的一行讲的是部署名：404 Not Found 或模型未找到，对应的检查方向是部署名不对，必须和你在门户里创建的那个完全一致。既然文档层面拿不到资源名和项目名这一层的错误形态，就别把定位问题的希望寄托在错误文案上。官方在创建资源和项目的第 5 步就写了一句：把你的 resource name 和 project name 记下来，后面要用。这一步看着像废话，实际上它是后面所有代码里 base_url 的唯一来源，端点基址是拿这两个名字拼出来的，写代码时最好从配置里读，而不是散落在几个文件里各写一遍。
访问控制这一步官方给的配置项是：用 Microsoft Entra ID 配合基于角色的访问控制（RBAC）；给那些要调模型的身份分配 Cognitive Services OpenAI User 角色或等价角色；需要的话再通过 Azure Virtual Network 配私有网络。
开始之前的前置条件官方也列全了：一个有效的 Azure 订阅、能访问 Azure AI Foundry、有足够权限创建管理 Foundry 资源与项目并部署模型（典型是 Contributor 或带模型部署权限的自定义角色）、示例代码需要 Python 3.10 及以上。Azure CLI 是可选但推荐装的，用来做资源管理和鉴权测试。依赖装两个包就够跑通示例，官方写的是 openai 和 azure-identity；如果你要用更高层的 project client 写法，再加 azure-ai-projects。
部署那一步决定了后面所有代码
这是整条链路里最容易留下长期后遗症的一步。在 Foundry 门户里进 resource 或 project，找到 Models + endpoints，点 Deploy model 里的 Deploy base model，或者直接去模型目录里搜 Grok，选中想要的模型（官方示例里出现的部署名是 grok-4.3 这种形态）。
关键在配置部署的那一屏，官方明确写了两点：
- Deployment name：选一个清晰、稳定的名字。这个名字创建之后就不能改，而且它就是你后续请求里
model参数要填的值。文档在讲 provisioning 的时候单独强调过一次——你选的部署名会成为 API 请求model参数里传的那个值。所以不要图省事叫test1，也不要把日期塞进去。 - Deployment type / SKU：Serverless 对应按用量付费的负载，Provisioned Throughput Units（PTU）对应需要可预期吞吐的高流量场景。
点 Deploy 之后要等部署状态走到 Ready / Running。部署完成后，你可以在内置 Playground 里直接测、看自动生成的代码片段、在启用了 API key 鉴权的情况下管理密钥和端点，以及查用量和指标。
顺带说一句部署前该干的事：官方让你在模型卡上先把能力、上下文窗口、工具调用支持、安全评估、定价和部署选项都过一遍。上下文窗口这类参数不要凭印象，也别抄别人文章里的数字，模型卡上写的才算。
鉴权：优先 Entra ID，密钥是兜底
Grok on Foundry 走的是 Azure 原生鉴权。官方推荐的是 Microsoft Entra ID 的无密钥方式，用 DefaultAzureCredential；同时说明门户里的 API key 也可能可用，取决于你的资源配置。
推荐路径的写法是用 azure.identity 的 get_bearer_token_provider，拿到的 token provider 直接当作 OpenAI 客户端的 api_key 传进去，base_url 就是前面那个项目端点末尾接 /openai/v1。文档给的 token scope 是 https://ai.azure.com/.default。
这里有三条容易踩的说明，官方是用 Important 单独列出来的：
- 要给跑这段代码的那个身份分配 Cognitive Services OpenAI User 或合适的角色。注意是运行时身份，不是你本人在门户里的权限——本地开发时它可能是你 Azure CLI 登录的账号，部署到云上之后就变成托管标识了。
DefaultAzureCredential会自动处理本地开发（Azure CLI / VS Code 登录）、托管标识、服务主体等多种流程。方便归方便，代价是你不容易一眼看出它当前用的是哪一个身份，401 的时候要顺着这条链去查。- 不需要
api-version查询参数，/openai/v1这个路径本身负责兼容性。习惯了旧版 Azure OpenAI 接法的人最容易在这里多加一个参数。
密钥方式就是去资源的 Keys and Endpoint 里拷主密钥或副密钥，直接当 api_key 用。官方的态度写得很直白：生产环境优先 Entra ID 加 RBAC，密钥绝不提交到源码仓库，并且要定期轮换。密钥管理这块的通用做法可以看API 密钥安全管理。
第一个请求长什么样
官方示例统一用的是 OpenAI SDK 的 client.responses.create，model 传部署名，input 传提示，用 max_output_tokens 控制输出长度上限。工具调用的示例里，tools 是标准的 function 结构（type 为 function，里面是 name / description / parameters 的 JSON Schema），示例中还把 parallel_tool_calls 这一行写成注释形态，后面跟了一句 enable if supported in your deployment（如果你的部署支持就打开）；排障对照表里「工具调用没按预期执行」那一行，给的检查方向同样是核对工具 schema，并确认该部署是否启用或支持并行工具调用。两处措辞是一致的：并行工具调用在 Foundry 上能不能用，要按你自己那个部署的情况去确认。至于不传这个参数时的默认行为是什么，这篇文档没有写，以官方文档当前版本为准——真要依赖并行调用，就别靠猜，去模型卡和 Azure 那边确认。官方也提醒，真实的 agent 循环里你要执行这些工具调用，再把工具结果续进对话，示例本身只演示到拿回响应对象为止。
流式那段是给 responses.create 传 stream=True，然后遍历 chunk 取增量内容。官方还给了一句实操建议：先在 Foundry 门户的 Playground 里快速迭代提示，定型了再落到代码里。
能力支持方面，官方那张表列的条目是：推理、工具/函数调用、结构化输出与 JSON 模式、流式、长上下文、代码生成。结构化输出那一行写的是支持，用 response_format 或者在提示里明确要求 JSON；长上下文那一行没有给数值，而是让你去看具体模型卡上当前的上下文窗口。以上以官方文档当前版本为准。
出错了先看这几个 ID
Foundry 会在响应头里带标准的 Azure 请求标识，官方点名的有 request-id、apim-request-id、x-ms-request-id。联系微软或 xAI 支持的时候，把这些 ID 连同你的部署名和大致时间戳一起给过去。这是 Foundry 这条路径和直连 xAI API 最不一样的地方之一：你的排障入口从「看我的错误信息」变成了「给出可追溯的请求标识」，所以日志里从一开始就应该把这几个头存下来，等出事再加就晚了。
官方的排障对照表里，几种典型情况和该查的方向是：
- 401 Unauthorized：Entra 角色缺失或不对、token scope 写错、
DefaultAzureCredential那条链选错了身份。 - 404 Not Found / 模型未找到：部署名不对，它必须和你在门户里创建的那个完全一致。
- 部署卡在 Running：查区域配额、资源健康状况、门户通知，或者重新部署一次。
- 响应慢：官方给的方向是考虑 Provisioned Throughput，以及检查到该 Azure 区域的网络路径。
- 工具调用没按预期执行：核对工具 schema，并确认该部署是否启用/支持并行工具调用。
- 内容被过滤或拦截：查 Azure AI Content Safety 的配置和你的系统提示，必要时调整安全阈值。
401/403 这类鉴权失败的通用排查顺序可以参考API 401 与 403 排查。
计费与容量归 Azure 管
用量通过 Azure Marketplace 或者说你的 Azure 订阅结算，Grok 模型是通过 xAI 与微软的合作以 Azure 托管端点的形式交付的，还可以叠加 Azure AI Content Safety 层。数据处理、留存和条款的最新细节，官方让你去 Foundry 目录里看对应模型卡。
成本这块官方给的做法是三条：在 Azure Cost Management + Billing 里看花销；负载有尖峰或者还在试验阶段就用 Serverless，稳定的高吞吐用 PTU；按预期流量把模型和部署类型选到合适的规格。具体单价一律以 Foundry 目录里的模型卡和 Azure 定价页为准，本文不复述任何金额。
限流和配额官方在「限制」一节写得很明确：由 Azure 资源级别管理。这句话的含义是，你不能拿直连 xAI API 时的那套限流认知套过来——提额、并发规划都得走 Azure 那边的配额流程。限流本身的通用读法可以看API 限流 RPM 与 TPM。
可观测性方面，官方建议接 Azure Monitor、Application Insights 或 Log Analytics，按部署维度跟踪 token 用量、延迟和错误率。
迁过来之前要认的三条限制
官方在 Limitations 一节列了三条不太好听但很重要的话，外加紧跟这一节的一句收尾。
第一，Foundry 上的功能和直连 xAI API（api.x.ai）可能存在细微差异，尤其是最新的实验性功能。也就是说别默认两边一一对应。
第二，视觉与多模态支持、以及具体参数是否可用，要针对你选的那个模型和部署自行验证。官方没有在这篇里给出统一结论，所以如果你的业务依赖图片输入，这件事应该排在选型阶段验，而不是等代码写完了再发现参数传不进去。
第三，限流和配额在 Azure 资源级别管理——就是前面那一节讲的那件事。这句话在原文里就放在 Limitations 里，和「功能可能有差异」「多模态要自行验证」并列，属于迁移前要先想清楚的事，而不是上线后再调的参数。
这一节末尾还单独跟了一句：权威的参数与行为清单，以 Foundry 里的模型卡、以及目录中链接的 xAI Grok 文档为准。换句话说，这篇集成指南本身是入门路径，不是参数手册，遇到具体参数的行为分歧时，它不是最终裁判。
至于区域可用性，这篇社区集成文档没有给出可用区域清单，只说明配额和限流在 Azure 资源级别管理、排障时要查区域配额——所以国内团队要把它用到生产上，可用性和合规资质需要按你自己的 Azure 采购渠道去确认，不要靠推测。
迁移动作本身，官方在 Next steps 里给的说法是：从直连 xAI API 迁过来时，更新鉴权和端点配置，大多数提示词和工具 schema 只需很小改动就能过来。换句话说，工作量集中在身份与配置这一层，而不是业务代码。想先看直连那条路怎么走，可以对照Grok API 接入。
最后一个提醒：部署名不可修改这件事，会在半年后变成一个很难受的技术债——名字里带了环境、版本或日期的部署，一旦要换模型就只能新建一个部署再改代码，而不是原地升级。开工第一天就把命名约定定下来，比什么优化都值。