AIRI 中配置 Groq 大模型服务商:从 API Key 到 Consciousness 意识模块落地的完整实践
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 密钥
- 打开 Groq 控制台(console.groq.com)。
- 在 API Keys 页面创建一个新的 API Key。
- 复制密钥并妥善保存。
API Key 安全提醒:不要将 API Key 提交到代码仓库、放进截图,或分享给任何人。一旦密钥泄露,请立即在 Groq 控制台撤销该密钥并创建新密钥。
第二步:在 AIRI 中配置 Groq
- 打开 设置 → 服务商 → 聊天 → Groq。
- 将 API Key 粘贴到基础设置。
- 保留默认 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 时不会发起网络请求。具体到每次编辑保存时发生的事:
- 本地配置校验(
validateConfig):检查apiKey非空、baseUrl非空且是合法的绝对 URL(openai-compatible.ts)。这一步纯本地完成,Key 或 URL 格式不对会直接给出API key is required.、Base URL is invalid. It must be an absolute URL.等错误。 - 模型列表检查(
ModelList):调用服务商的模型列表能力拉取可用模型,结果为空则报Model list check failed: no models found(openai-compatible.ts)。这一步能验证 API Key 与 Groq 的连通性,也是"服务商卡片显示健康检查失败"的来源。 - 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 检查失败,按以下顺序排查:
- API Key:确认 Key 复制完整、无多余空格(本地校验会 trim 后判空);
- 账户额度/配额(credit or quota) 与 速率限制(rate limits):Groq 免费额度耗尽或触发限速时,Chat Completions 检查会失败;
- 网络连接:能否正常访问
api.groq.com,代理/防火墙是否会拦截该域名; - 模型 ID:若 AIRI 无法加载模型列表,到 Consciousness 页面手动输入 Groq 提供的精确模型 ID(即上文提到的手动输入降级路径)。
从校验错误信息的形态可以反推问题层次:Connectivity check failed: ... 多为网络层问题;Model list check failed: no models found 通常是 Key 权限或额度问题;Chat completions check failed: ... 则多为模型 ID、限速或额度问题,错误信息会附带 API 侧返回的具体报文。
小结与延伸阅读
- 官方配置文档:groq.md(英文)、groq.md(中文)
- Groq 服务商定义:packages/provider-inference/src/providers/cloud/groq/index.ts
- OpenAI 兼容校验实现:packages/provider-inference/src/validators/openai-compatible.ts
- 服务商设置页(通用模板):packages/stage-pages/src/pages/settings/providers/chat/[providerId].vue
- Consciousness 模块页:packages/stage-pages/src/pages/settings/modules/consciousness.vue
由于 Groq 与仓库中其他 OpenAI 兼容服务商共享同一套校验与配置模板,本文所述的配置流程与排查思路同样适用于 deepseek、mistral 等同目录服务商,区别仅在于各自的默认 Base URL 与额外字段(例如 deepseek 页面会多一个 thinking mode 下拉项)。