AIRI 接入 NVIDIA NIM：在意识模块中配置 OpenAI 兼容聊天提供者的完整指南

NVIDIA NIM（NVIDIA NIM Console 平台）提供与 OpenAI 格式兼容的聊天 API，本文基于仓库文档 docs/content/ko/docs/manual/config/providers/consciousness/nvidia.md（对应英文版 nvidia.md），并结合 AIRI 提供者注册与验证的真实源码，讲解如何在 AIRI 桌面端把 NVIDIA NIM 配置为「意识（Consciousness）」模块的聊天提供者。读完本文，你将掌握 API Key 获取、提供者参数配置、连接验证以及模型选择的完整流程，并理解底层校验机制，能够独立排查接入失败问题。

适用前提：桌面端专属提供者

接入 NVIDIA NIM 前需明确一个关键限制：该提供者仅在 Electron 桌面应用中可用，AIRI Web 不提供此选项。

从源码层面看，这一限制由提供者的 isAvailableBy 字段强制执行。在 providers/nvidia/index.ts 中：

export const providerNvidia = defineProvider<NvidiaConfig>({
  id: 'nvidia',
  name: 'NVIDIA NIM',
  tasks: ['chat'],
  capabilities: { chat: { reasoning: { modes: ['enabled', 'disabled'] } } },
  icon: 'i-simple-icons:nvidia',
  isAvailableBy: isStageTamagotchi,
  // ...
})

其中 isStageTamagotchi 来自 packages/stage-shared/src/environment.ts，用于判定当前运行环境是否为桌面（Tamagotchi）阶段。因此在 Web 版设置页面中不会出现 NVIDIA NIM 入口，如果你使用的是 AIRI Web，请忽略本文并改用其他聊天提供者。

选择 NVIDIA NIM 的理由很直接：如果你已经在 NVIDIA NIM 平台上使用模型服务，无需更换服务商，把同一套凭据连接到 AIRI 即可复用现有模型能力。

获取 API Key

配置的第一步是在 NVIDIA 侧生成 API Key：

1. 打开 NVIDIA NIM Console（build.nvidia.com）。
2. 进入 API Keys 页面，创建一个新的 API Key。
3. 复制生成的密钥并保存在安全位置（例如密码管理器）。

API Key 是访问 NIM 模型的唯一凭据，务必遵守以下安全规范：

• 不要将 API Key 提交到 Git 仓库，不要出现在截图、日志或聊天记录中，也不要分享给任何人；
• 一旦怀疑密钥泄露，立即在 NVIDIA 控制台中吊销旧 Key 并生成新 Key。

在 AIRI 中配置 NVIDIA NIM 提供者

获取 Key 后，在桌面端 AIRI 中按以下路径完成配置：

1. 打开 设置 → 提供者 → 聊天 → NVIDIA NIM。
2. 在基本设置中将 API Key 粘贴到 API Key 输入框。
3. 保持默认 Base URL：https://integrate.api.nvidia.com/v1/。

配置字段说明

NVIDIA NIM 提供者只有两个配置字段，其约束定义在 providers/nvidia/index.ts 的 zod schema 中：

const nvidiaConfigSchema = z.object({
  apiKey: z.string('API Key'),
  baseUrl: z
    .string('Base URL')
    .optional()
    .default('https://integrate.api.nvidia.com/v1/'),
})

字段	类型	是否必填	默认值	说明
apiKey	string	是	无	NVIDIA NIM 的 API Key，输入框以密码形式展示
baseUrl	string	否	https://integrate.api.nvidia.com/v1/	OpenAI 兼容端点地址，通常无需修改

需要注意：apiKey 输入框为密码类型（源码中 type: 'password'），界面不会明文回显；baseUrl 位于高级设置（Advanced Settings）中，仅在需要自定义端点时才修改。通用提供者设置页的实现可参考 packages/stage-pages/src/pages/settings/providers/chat/[providerId].vue，其中 API Key 与 Base URL 分别通过 ProviderApiKeyInput 与 ProviderBaseUrlInput 组件双向绑定到配置存储。

底层请求适配

AIRI 并不为 NVIDIA NIM 单独实现协议客户端，而是复用统一的 OpenAI 兼容适配层。在 providers/nvidia/index.ts 中：

createProvider(config) {
  const provider = createOpenAI(config.apiKey, config.baseUrl)
  return {
    ...provider,
    chat(model: string, options?: ChatRequestOptions) {
      const request = provider.chat(model)
      if (!options?.reasoning)
        return request

      return { ...request, chatTemplateKwargs: { enable_thinking: options.reasoning === 'enabled' } }
    },
  }
}

即通过 createOpenAI 以 apiKey 与 baseUrl 构造客户端；当启用推理（思考）模式时，会在请求模板参数中加入 enable_thinking: true，这对应 NVIDIA NIM 部分推理模型（reasoning 模型）的思考开关，与意识模块中的「思考」选项一一对应。

验证配置

AIRI 会在你编辑配置的过程中自动触发校验，无需手动提交。

自动校验的三项检查

从源码 providers/nvidia/index.ts 可以看到，NVIDIA NIM 使用了 OpenAI 兼容校验器，并开启了全部三项检查：

validationRequiredWhen(config) {
  return !!config.apiKey?.trim()
},
validators: {
  ...createOpenAICompatibleValidators({
    checks: [ProviderValidationCheck.Connectivity, ProviderValidationCheck.ModelList, ProviderValidationCheck.ChatCompletions],
  }),
},

检查项	作用
Connectivity	验证 Base URL 可达、网络连接正常、凭据能被 NIM 端点接受
ModelList	调用模型列表接口，确认能拉取到该账号可用的模型
ChatCompletions	发起一次真实聊天补全请求，验证端到端可用

这三项检查的实现位于 packages/stage-ui/src/libs/providers/validators/openai-compatible.ts，并有对应的单元测试 openai-compatible.test.ts 覆盖「Connectivity check failed」等失败分支。同时，validationRequiredWhen 规定：只要 apiKey 非空（去除首尾空白后），校验即被触发——也就是说，粘贴 Key 后系统会立刻开始检查。

Ping API 手动测试

在提供者设置页面，如果界面出现 Ping API 按钮，说明该提供者支持手动测试。点击后 AIRI 会向 baseUrl 发起一次实际请求，用于在自动校验之外做一次即时连通性验证。相关状态（isValidating、isValid、validationMessage、手动测试结果等）通过 ProviderValidationAlerts 组件展示，逻辑封装在 packages/stage-ui/src/composables/use-provider-validation.ts 中，页面实现见 packages/stage-pages/src/pages/settings/providers/chat/[providerId].vue。

在意识模块中选择模型

校验通过后，点击 选择模型 → 按钮即可跳转到 设置 → 模块 → 意识 页面（源码中由 goToModelSelection 完成跳转，见 packages/stage-pages/src/pages/settings/providers/chat/[providerId].vue）。

意识页面（packages/stage-pages/src/pages/settings/modules/consciousness.vue）会：

1. 展示已配置的聊天提供者卡片，选择 NVIDIA NIM 作为活动提供者；
2. 自动调用 loadModelsForProvider 拉取该提供者的模型列表（页面挂载时通过 watch(activeProvider, ...) 触发）；
3. 在模型列表中以可搜索的卡片形式展示模型 ID，可直接点击选中。

思考模式开关

选择模型后，意识页面底部会出现「思考（Thinking）」开关，对应 NVIDIA NIM 推理模型的思考能力。该开关状态写入 consciousnessSettingsStore，并在发起聊天时通过前文提到的 enable_thinking 参数传递给 NIM 端点。capabilities.chat.reasoning.modes 声明了 ['enabled', 'disabled'] 两种取值，意味着你可以按需开启或关闭模型的思考过程。

问题排查

接入失败时，按以下清单逐项核对：

1. API Key 是否正确：重新复制 Key，确认无多余空格、未错选账号的 Key，必要时在 NVIDIA 控制台重新生成。
2. 账户余额/配额：确认 NVIDIA NIM 账号有可用额度（credit/quota），余额不足会导致请求被拒。
3. 请求限流：是否触及了该 Key 的速率限制（rate limit），可稍后重试。
4. 网络连接：确认本机可以访问 https://integrate.api.nvidia.com/v1/，代理、防火墙或 DNS 异常都会导致 Connectivity 检查失败。

模型列表无法加载时的手动输入

如果 AIRI 无法拉取 NVIDIA NIM 的模型列表（对应意识页面的 activeProviderModelError 状态），可以在 意识 页面直接手动输入 NVIDIA NIM 提供的精确模型 ID。这一回退机制同样存在于模型列表为空（providerModels.length === 0）的场景——此时页面会显示警告提示并允许通过搜索/自定义输入指定模型。具体实现见 consciousness.vue：错误状态下渲染「手动输入模型名称」输入框；无模型时提供 allow-custom 的搜索选择组件。输入时务必保证模型 ID 与 NVIDIA NIM 平台上的命名完全一致，否则聊天请求会失败。

参考文件

• 官方配置文档：docs/content/ko/docs/manual/config/providers/consciousness/nvidia.md、docs/content/en/docs/manual/config/providers/consciousness/nvidia.md
• 提供者实现：packages/stage-ui/src/libs/providers/providers/nvidia/index.ts
• 校验器实现与测试：packages/stage-ui/src/libs/providers/validators/openai-compatible.ts、openai-compatible.test.ts
• 意识模块页面：packages/stage-pages/src/pages/settings/modules/consciousness.vue
• 提供者设置页：packages/stage-pages/src/pages/settings/providers/chat/[providerId].vue
• 环境判定工具：packages/stage-shared/src/environment.ts