在 AIRI 中接入 Groq：为“意识“配置高速 OpenAI 兼容聊天服务商-平芜编程栈

在 AIRI 中接入 Groq：为"意识"配置高速 OpenAI 兼容聊天服务商

【免费下载链接】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

Groq 提供与 OpenAI 格式兼容的聊天 API，以极低的推理延迟著称。本文是 AIRI 项目的 Groq 服务商配置指南，围绕官方手册中的 Groq 页面展开，完整覆盖从获取 API Key、在"设置 → 服务商"中填入凭据、验证配置到常见问题排查的实战流程，并深入到 AIRI 的 provider 注册与校验源码，说明 Groq 在"意识"模块中的接入原理。读完本文，你将能够在 AIRI 中独立完成 Groq 的接入、验证与模型选择，让 AIRI 的对话"意识"跑在 Groq 的低延迟推理上。

为什么选择 Groq

在 AIRI 中接入聊天服务商，本质上是为它的"意识"（consciousness）模块挑选一个能理解并生成对话的"大脑"。AIRI 支持数十个云端与本地服务商（见服务商注册表），每个服务商都有不同的延迟、价格与模型生态。

如果你重视对话响应速度，并且目标模型在 Groq 中可用，可以尝试此服务商。Groq 的 LPU（Language Processing Unit）推理平台以极低的 token 输出延迟著称，非常适合对首字响应（TTFT）敏感的实时对话场景——这与 AIRI 强调实时语音对话的产品定位天然契合。

从实现层面看，Groq 是 AIRI 中"标准的 OpenAI 兼容服务商"：它不引入任何私有协议，而是复用createOpenAI工厂与 OpenAI 兼容校验器，这保证了接入流程的简单与可预测。

第一步：获取 API 密钥

Groq 使用 API Key 进行身份认证，获取方式如下：

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

::: warning API Key 安全不要将 API Key 提交到仓库、放入截图，或发送给他人。密钥泄露后，请立即在 Groq 控制台撤销它并创建新密钥。AIRI 的凭据保存在当前设备的本地设置中，切勿在截图、日志、Issue 或聊天记录中公开 API Key。 :::

第二步：在 AIRI 中配置 Groq

获取密钥后，在 AIRI 中完成以下三步：

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

从源码看 Groq 的配置结构

在 AIRI 的 provider 实现 packages/provider-inference/src/providers/cloud/groq/index.ts 中，Groq 的配置 schema 只有两个字段：

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

apiKey：必填的访问令牌，对应设置页中的 API Key 字段。在 UI 中它以type: 'password'的密码框形式呈现（index.ts），避免密钥在界面上明文展示。
baseUrl：可选，默认值为https://api.groq.com/openai/v1/（源码中带尾部斜杠，文档与设置页中显示时可能省略，两者等价）。只有当 Groq 官方文档明确要求变更时才需要修改。

Groq 的服务商定义

继续看 groq/index.ts，Groq 被声明为：

id: 'groq'，全局唯一标识，注册表靠它来路由配置与请求；
tasks: ['chat']，即仅用于聊天任务，不承担 TTS/ASR；
capabilities.chat.reasoning支持enabled/disabled两种推理模式：开启时请求会附加reasoningEffort: 'medium'，关闭时为'none'；
icon: 'i-lobe-icons:groq'，在设置页中显示 Groq 品牌图标。

该定义通过defineProvider注册，并随 portableProviderDefinitions 一起导出。注册表（registry.ts）会对所有 provider 按order与名称排序，并保证id唯一——这保证了"意识"设置页中服务商列表的稳定与确定性。

OpenAI 兼容的底层实现

createProvider内部通过createOpenAI(config.apiKey, config.baseUrl)构造请求客户端（groq/index.ts），这意味着 AIRI 与 Groq 之间走的是标准 OpenAI Chat Completions 协议，无需任何供应商专用 SDK。这也解释了为什么配置只需要 API Key 与 Base URL 两个字段。

第三步：验证配置

配置完成后，通过验证来确认一切就绪：

Ping API：点击此按钮测试网络是否连通以及 API Key 是否填写正确。
选择模型：测试成功后，点击此处选择你想要使用的具体模型。

验证过程在源码中做了什么

Groq 复用了createOpenAICompatibleValidators（validators/openai-compatible.ts），并启用了ModelList与ChatCompletions两项检查（groq/index.ts）。点击验证时，实际执行了三类检查：

配置检查（check-config）：校验 API Key 非空、Base URL 为合法的绝对 URL。Base URL 必须是https://或http://开头的完整地址，否则直接判定为无效。

连接检查（check-connectivity）：向${baseUrl}/models发起带Authorization: Bearer <apiKey>头的 GET 请求（超时 10 秒）。这对应界面上的Ping API按钮——它验证的是网络连通性与密钥有效性，而非真正发起对话。

聊天完成检查（check-chat-completions）：调用generateText发送一条user: "ping"的探测消息（openai-compatible.ts），并携带max_tokens: 16的输出上限。该检查会消耗少量 Groq 额度，且结果会被缓存以避免重复扣费。Groq 模型列表由/models接口实时拉取，因此"选择模型"下拉中的选项始终与服务商当前可用模型保持一致。

在"意识"中选择 Groq 模型

验证通过后，还需要在"意识"页面完成最后一步启用：

打开设置 → 意识。
选择服务商Groq与刚才验证过的具体模型。

注意：仅保存服务商凭据不会自动启用 Groq。必须在"意识"页面同时选中服务商和模型，AIRI 的对话才会真正走 Groq 通道。

Groq 官方文档会列出形如llama-3.3-70b-versatile、llama-3.1-8b-instant等精确模型 ID。建议优先从 AIRI 下拉列表中选择；若列表加载失败，可在"意识"页面手动输入Groq 提供的精确模型 ID——模型 ID 必须与服务商文档完全一致，展示名称不是模型 ID。

排查指南

Ping API 失败

按以下顺序排查：

确认账户已开通 Groq 服务且有可用额度（免费额度过期或超额会返回 429/403）。
重新复制 API Key，检查是否带有多余的空格或换行；密钥泄露后及时在控制台撤销并重建。
将 Base URL 恢复为https://api.groq.com/openai/v1，并与 Groq 官方文档逐字核对。
确认网络、代理和防火墙允许访问api.groq.com——连接检查对 5xx 状态码与网络错误都会报"Connectivity check failed"（openai-compatible.ts）。

模型列表无法加载

如果"选择模型"下拉为空，先确认 API Key 拥有模型列表权限；部分服务商不提供模型列表或密钥权限受限。此时可在"意识"页面手动输入Groq 提供的精确模型 ID。

验证报错时对照源码提示

"API key is required."：apiKey 为空或被 trim 后为空（check-config）。
"Base URL is invalid. It must be an absolute URL."：Base URL 不是合法绝对地址。
"No model available for validation."：模型列表为空且未配置手动模型，需要先在意识页填入模型 ID（openai-compatible.ts）。