AIRI 中配置 Groq 大模型服务商:从 API Key 到 Consciousness 意识模块落地的完整实践

原创2026-10-15 16:17:541,961 阅读
文章标签:AI 应用大模型AI Agent数字人前端后端桌面应用移动开发音频

AIRI 中配置 Groq 大模型服务商:从 API Key 到 Consciousness 意识模块落地的完整实践

本文基于 AIRI 仓库的官方配置文档(docs/content/en/docs/manual/config/providers/consciousness/groq.md,中文版见 docs/content/zh-Hans/docs/manual/config/providers/consciousness/groq.md)展开,讲解如何在 AIRI 中把 Groq 配置为 Consciousness(意识)模块的对话模型服务商:从 Groq 控制台获取 API Key,到在设置页填写凭证、通过内置的 OpenAI 兼容校验(模型列表检查 + Chat Completions 实弹测试),再到进入意识模块完成模型选择与采样参数调整。读完你可以独立完成 Groq 服务商的接入与故障排查,并理解 AIRI 背后每个校验步骤的实际请求行为。

Groq 在 AIRI 服务商体系中的定位

Groq 提供兼容 OpenAI 格式的聊天 API,AIRI 因此将它实现为一个 OpenAI 兼容的 chat 类服务商。文档的 front matter 中 is_openai_compatible: true 标记说明了这一点——同一目录下还有 deepseek、mistral、moonshot 等一大批同样标记的服务商文档,它们共享同一套兼容校验逻辑。

源码层面,Groq 服务商定义位于 groq/index.ts,并通过 providers/index.ts 中的 portableProviderDefinitions 注册进全局服务商目录,保证浏览器与桌面端等宿主环境都能加载。从 attributes.ts 的目录属性看,Groq 被归类为 paidCloud(付费云端)服务商,在服务商目录的筛选器中会出现在"付费 / 云端"分类下。

定义中声明了它的任务与能力(groq/index.ts):

tasks: ['chat'],
capabilities: { chat: { reasoning: { modes: ['enabled', 'disabled'] } } },

这意味着 Groq 只承担聊天任务(不负责语音、视觉等),且支持"推理(thinking)"开关的启用/禁用两种模式——这一点会直接影响你在意识模块里能否勾选 thinking 选项。

第一步:获取 Groq API 密钥

  1. 打开 Groq 控制台(console.groq.com)。
  2. 在 API Keys 页面创建一个新的 API Key。
  3. 复制密钥并妥善保存。

API Key 安全提醒:不要将 API Key 提交到代码仓库、放进截图,或分享给任何人。一旦密钥泄露,请立即在 Groq 控制台撤销该密钥并创建新密钥。

第二步:在 AIRI 中配置 Groq

  1. 打开 设置 → 服务商 → 聊天 → Groq。
  2. 将 API Key 粘贴到基础设置。
  3. 保留默认 Base URL:https://api.groq.com/openai/v1/。

这个设置页对 Groq 是通用模板渲染的,路由为 /settings/providers/chat/[providerId],对应实现见 [providerId].vue。页面上你实际只会看到两个核心输入项:API Key 输入框(password 类型)与 Base URL 输入框(高级设置区)。这两个字段并非写死在页面里,而是由服务商定义中的 zod schema 动态生成的:

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

见 groq/index.ts。要点是:apiKey 为必填字符串;baseUrl 可选,缺省值即 https://api.groq.com/openai/v1/。createProviderConfig 会为两个字段附加本地化的 label / description / placeholder 元信息(groq/index.ts),所以不同语言环境下输入框提示文案会自动切换。除非你要把请求指向私有网关或代理,否则 Base URL 保持默认即可。

配置校验:Validate 与 Ping API 背后的实际请求

文档提到"AIRI 会在你编辑时自动校验配置,若出现 Ping API 按钮,可用它发起一次实弹测试"。这部分行为的完整逻辑在 validators/openai-compatible.ts 中,Groq 在定义里声明了启用其中两项检查(groq/index.ts):

validators: {
  ...createOpenAICompatibleValidators({
    checks: [ProviderValidationCheck.ModelList, ProviderValidationCheck.ChatCompletions],
  }),
},

同时,validationRequiredWhen 要求 apiKey 去除首尾空白后非空才会触发校验(groq/index.ts),所以未填 Key 时不会发起网络请求。具体到每次编辑保存时发生的事:

  1. 本地配置校验(validateConfig):检查 apiKey 非空、baseUrl 非空且是合法的绝对 URL(openai-compatible.ts)。这一步纯本地完成,Key 或 URL 格式不对会直接给出 API key is required.、Base URL is invalid. It must be an absolute URL. 等错误。
  2. 模型列表检查(ModelList):调用服务商的模型列表能力拉取可用模型,结果为空则报 Model list check failed: no models found(openai-compatible.ts)。这一步能验证 API Key 与 Groq 的连通性,也是"服务商卡片显示健康检查失败"的来源。
  3. Chat Completions 检查(即 Ping API 类测试,ChatCompletions):自动挑选一个模型(若配置中已有 model 则优先使用),向 Chat Completions 端点发送一条内容为 ping 的消息并限制 max_tokens: 16(openai-compatible.ts)。之所以取 16,源码注释说明是因为部分 OpenAI 兼容服务商拒绝低于该值的输出上限。该请求在 openai-compatible.ts 中还带缓存与互斥锁,同一轮校验内只发一次,避免重复计费请求。

另外,校验框架内置了可选的连通性检查(Connectivity),它直接 GET {baseUrl}models 并带 10 秒超时(openai-compatible.ts);Groq 当前声明的检查组合是 ModelList + ChatCompletions,模型列表拉取本身就覆盖了连通性语义。

校验成功后,设置页底部会显示通过状态,并提供"Select Model"入口(对应 [providerId].vue 中的 goToModelSelection:把当前服务商设为激活项后跳转到 /settings/modules/consciousness)。

第三步:在 Consciousness 中选择 Groq 模型

进入 设置 → 模块 → Consciousness(对应页面 consciousness.vue)后,你会看到已配置服务商的卡片列表,选择 Groq 卡片即完成服务商绑定(persistSelection 会把 provider/model 写入当前角色卡片的 consciousness 配置,见 consciousness.vue)。随后页面会调用 loadModelsForProvider 拉取 Groq 的模型列表供搜索选择(consciousness.vue)。

与原文档"模型列表无法加载时手动输入模型 ID"一致的,是页面上真实存在的降级交互:当模型列表请求失败时,会渲染一个错误框加一个手动模型名输入框,直接输入 Groq 提供的精确模型 ID 即可生效(consciousness.vue)。

选中模型后,页面还会暴露一组采样/推理参数(consciousness.vue):

  • Thinking(推理) 复选框:由于 Groq 定义中声明了 reasoning.modes: ['enabled', 'disabled'],这里可勾选;
  • Temperature:范围 0~2,步长 0.1,需先启用开关;
  • Top P:范围 0~1,步长 0.1,需先启用开关。

其中 thinking 开关最终如何落到 Groq 请求上?答案在 createProvider 的 chat 包装里(groq/index.ts):

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

  return { ...request, reasoningEffort: options.reasoning === 'enabled' ? 'medium' : 'none' }
}

即开启时映射为 reasoningEffort: 'medium',关闭时为 'none',未传入 reasoning 选项时不做任何修改。这解释了意识模块里该开关的实际语义:它不是"换模型",而是向请求注入 reasoning effort 字段。

故障排查

如果 API 检查失败,按以下顺序排查:

  1. API Key:确认 Key 复制完整、无多余空格(本地校验会 trim 后判空);
  2. 账户额度/配额(credit or quota) 与 速率限制(rate limits):Groq 免费额度耗尽或触发限速时,Chat Completions 检查会失败;
  3. 网络连接:能否正常访问 api.groq.com,代理/防火墙是否会拦截该域名;
  4. 模型 ID:若 AIRI 无法加载模型列表,到 Consciousness 页面手动输入 Groq 提供的精确模型 ID(即上文提到的手动输入降级路径)。

从校验错误信息的形态可以反推问题层次:Connectivity check failed: ... 多为网络层问题;Model list check failed: no models found 通常是 Key 权限或额度问题;Chat completions check failed: ... 则多为模型 ID、限速或额度问题,错误信息会附带 API 侧返回的具体报文。

小结与延伸阅读

由于 Groq 与仓库中其他 OpenAI 兼容服务商共享同一套校验与配置模板,本文所述的配置流程与排查思路同样适用于 deepseek、mistral 等同目录服务商,区别仅在于各自的默认 Base URL 与额外字段(例如 deepseek 页面会多一个 thinking mode 下拉项)。

登录后查看全文
airi