企业官网建设流程全解析

AIRI 接入 Azure AI Foundry 聊天模型完整指南：资源配置、Provider 配置与意识模块验证

【免费下载链接】airi💖🧸 Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-sama's altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi

AIRI 是自托管的 AI 伴侣/数字生命桌面项目，其“意识（Consciousness）”模块的聊天能力完全由底层的大模型 Provider 驱动。本文以docs/content/en/docs/manual/config/providers/consciousness/azure-ai-foundry.md为骨架，讲解如何在 AIRI 中接入 Azure AI Foundry（原 Azure AI Studio）上已完成部署与访问控制的模型：从 Azure 侧准备资源、在 AIRI 设置页填写四项关键参数，到在 Consciousness 模块中完成端到端验证与常见故障排查。读完本文，你将能独立完成 Azure AI Foundry 模型在 AIRI 中的配置、校验与排错全流程。

为什么选择 Azure AI Foundry

如果你的模型部署与访问控制已经在 Azure AI Foundry（ai.azure.com，并在 packages/stage-ui/src/libs/providers/providers/index.ts 中统一注册导出。

注意：Azure AI Foundry 与 Azure OpenAI 是两个不同的 Provider。前者基于https://<prefix>.services.ai.azure.com的 Foundry 服务端点，后者对应独立的 Azure OpenAI 资源，二者的配置字段与验证逻辑并不相同。

准备 Azure AI Foundry 资源

在 AIRI 中配置之前，需要先从 Azure 侧收集以下三项信息：

1. 登录 Azure AI Foundry 门户；
2. 创建或打开目标项目；
3. 在项目中获取API Key、资源名称（resource name）与模型部署信息（model deployment）。

API Key 安全须知

Azure API Key 属于敏感凭据。请勿将其提交到代码仓库、包含在截图或分享给任何人。AIRI 的配置 UI 会将 API Key 字段以密码输入框（type: 'password'）呈现，并在表单数据中持久化到本地配置存储，但仓库层面不会内置任何真实密钥，你仍需自行保护本地配置。

在 AIRI 中配置 Azure AI Foundry

配置入口

进入Settings → Providers → Chat → Azure AI Foundry，对应的设置页面实现位于 packages/stage-pages/src/pages/settings/providers/chat/azure-ai-foundry.vue。

页面由ProviderBasicSettings（基础设置）与ProviderAdvancedSettings（高级设置）两部分组成，四个配置项如下：

在 Provider 定义源码 packages/stage-ui/src/libs/providers/providers/azure-ai-foundry/index.ts 中，这四项由 zod schema 约束：

const azureAIFoundryConfigSchema = z.object({ apiKey: z.string('API Key'), resourceName: z.string('Resource Name'), modelId: z.string('Model ID'), apiVersion: z.string('API Version').optional(), })

其中resourceName的元数据明确标注为Prefix used in https://<prefix>.services.ai.azure.com，apiVersion则被归类到section: 'advanced'（高级设置），与设置页面的布局完全对应。

部署名与模型名的区别

配置时不要把常见的模型名误当作部署名。Azure AI Foundry 门户中展示的模型名（如gpt-4o）仅用于展示（presentation only），真正用于 API 调用的必须是你在项目中创建的部署名称（deployment name）。AIRI 将modelId直接作为部署名透传给底层请求，因此填错会导致调用失败。如果控制台要求特定的 API 版本，请在高级设置中补充apiVersion。

验证配置

自动校验：只检查字段是否齐全

填写完必填字段后，AIRI 会自动触发校验。useProviderValidation组合式函数（packages/stage-ui/src/composables/use-provider-validation.ts）以 500ms 防抖监听凭据变化并调用校验逻辑；对 Azure AI Foundry 而言，其validateConfig校验器只做三项判断（见 packages/stage-ui/src/libs/providers/providers/azure-ai-foundry/index.ts 的validators.validateConfig）：

• apiKey非空（trim 后）；
• resourceName非空；
• modelId非空。

也就是说，自动校验并不测试网络连接或凭据真实性，仅仅确认三个字段已填写。校验通过后，Provider 状态会被标记为configured并出现在模型选择器中（markProviderAdded）。

手动连接测试

由于自动校验会跳过真实请求以避免意外计费（源码注释明确说明skipChatPingCheck: true），若要确认部署能真正响应，需要在设置页点击手动测试（runManualTest，对应onlyChatPingCheck: true的真实 ping 检查），或在 Consciousness 模块中发送一条测试消息。

在 Consciousness 模块中端到端验证

1. 进入Settings → Modules → Consciousness（页面实现见 packages/stage-pages/src/pages/settings/modules/consciousness.vue）；
2. 在 Provider 单选卡片列表中选中Azure AI Foundry；
3. 选择对应的部署模型（Azure AI Foundry 通过extraMethods.listModels返回配置的modelId作为模型列表，见 packages/stage-ui/src/libs/providers/providers/azure-ai-foundry/index.ts）；
4. 发送一条测试消息，确认部署能够正常响应。

Consciousness 模块的状态由 packages/stage-ui/src/stores/modules/consciousness.ts 管理，activeProvider与activeModel均持久化到本地存储（settings/consciousness/active-provider、settings/consciousness/active-model）。切换 Provider 时会通过loadModelsForProvider拉取该 Provider 的模型列表；若模型列表加载失败，页面会回退到手动模型名输入框，此时可直接填写部署名。

此外，Consciousness 页面还提供一个Thinking（推理）开关：当开启时，Azure AI Foundry Provider 会在请求中附加reasoningEffort: 'medium'，关闭时为'none'（见 packages/stage-ui/src/libs/providers/providers/azure-ai-foundry/index.ts 中createProvider的chat包装逻辑），这对应其capabilities.chat.reasoning.modes: ['enabled', 'disabled']的能力声明。

故障排查

当校验或测试失败时，请按以下顺序核查：

1. 信息是否来自同一个项目：API Key、资源名称、部署名、API 版本必须全部来自同一个 Azure AI Foundry 项目；混用不同项目的凭据是最高频的失败原因。
2. 使用部署名而非模型名：modelId应填写部署名称（deployment name），模型名仅用于展示，填错会直接导致 404/401 类错误。
3. API 版本是否匹配：如果控制台或部署要求特定的 API 版本（如2025-04-01-preview），必须在高级设置中补齐apiVersion。
4. 字段完整性：确认apiKey、resourceName、modelId均已填写且无多余空格（源码校验会先trim）。

从底层实现看，Provider 创建时通过createAzure将apiKey、resourceName、apiVersion解析为 Azure 认证客户端（该过程是异步解析的，运行时会对 Provider 实例进行await），随后以modelId作为模型标识发起chat请求。因此任何一项与 Azure 侧实际值不一致，都会在真实调用（手动测试或 Consciousness 测试消息）阶段暴露。

小结

• Azure AI Foundry 接入的核心是四个配置项：apiKey、resourceName、modelId（部署名）、apiVersion（可选）；
• 自动校验只做字段存在性检查，不会测试网络与凭据，必须通过手动测试或 Consciousness 模块发消息完成端到端确认；
• 排错时优先核对四项信息是否同源、部署名是否填对、API 版本是否匹配；
• 相关源码入口：Provider 定义 packages/stage-ui/src/libs/providers/providers/azure-ai-foundry/index.ts、设置页面 packages/stage-pages/src/pages/settings/providers/chat/azure-ai-foundry.vue、校验逻辑 packages/stage-ui/src/composables/use-provider-validation.ts、意识模块页面 packages/stage-pages/src/pages/settings/modules/consciousness.vue。

【免费下载链接】airi💖🧸 Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-sama's altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi