更新 big-AGI 的 Groq 模型定义：官方文档驱动的模型清单维护完整指南-平芜编程栈

更新 big-AGI 的 Groq 模型定义：官方文档驱动的模型清单维护完整指南

【免费下载链接】big-AGIAI suite powered by state-of-the-art models and providing advanced AI/AGI functions. Includes AI personas, AGI functions, world-class Beam multi-model chats, text-to-image, voice, response streaming, code highlighting and execution, PDF import, presets for developers, much more. Deploy on-prem or in the cloud.项目地址: https://gitcode.com/GitHub_Trending/bi/big-AGI

big-AGI 内置了对 Groq 这一高性能推理平台的完整接入，其模型清单（价格、上下文窗口、能力接口、推理档位）由服务端一个手工维护的定义文件驱动。本文以仓库中的维护指令文档为主线，结合 groq.models.ts 及相关源码，完整讲解"从 Groq 官方文档拉取数据 → 校验 → 写入模型定义 → 落地验证"的更新工作流，读者完成后可以独立完成一次准确、diff 友好的 Groq 模型清单同步。

一、背景：Groq 模型清单在 big-AGI 中扮演的角色

big-AGI 通过 OpenAI 兼容的openai访问层接入 20 余种方言服务，Groq 是其中之一（见 openai.access.ts 中的方言枚举）。Groq 的默认接入点是https://api.groq.com/openai，密钥来自GROQ_API_KEY环境变量或用户在界面配置的oaiKey。

与其他"只返回模型 ID"的服务类似，Groq 的/v1/models列表只给出非常有限的字段，模型的价格、上下文窗口、最大输出、能力标签（视觉/推理/工具调用）、推理档位枚举、发布时间等 UI 展示与计费所需信息，全部来自仓库内手工维护的模型定义表。这张表在运行期通过groqModelToModelDescription与 API 返回的模型 ID 进行前缀匹配后注入到描述对象中（见 listModels.dispatch.ts 中dialect === 'groq'的分支：先做 DEV 校验，再依次filter → map → sort）。

因此，Groq 模型清单的"事实来源"不是 API，而是这份定义文件本身。维护它是一项需要精确、定期执行的编辑任务——这正是本指南要解决的问题。

二、理解主文件：groq.models.ts 的内部结构

更新前必须先读懂目标文件的骨架。groq.models.ts由以下几个部分组成：

类型推导：type LlmsGroqModelId = typeof _knownGroqModels[number]['idPrefix']从模型表自动推导 Groq 模型 ID 的联合类型，供前端类型系统使用——新增条目会自动扩展该类型。
模型表_knownGroqModels：用llmsDefineModels<_GroqModelDef>()（定义见 models.mappings.ts）包裹的数组，元素类型为(KnownModel & { pubDate: string }) | KnownLink。表内按区块组织：
- Preview 模型：如qwen/qwen3.8-27b、qwen/qwen3.6-27b、minimaxai/minimax-m2.7，带isPreview: true标记；
- 已移除模型注释块：以注释形式保留历史移除记录（日期 + 替代模型），例如llama-3.3-70b-versatile在 2026-08-16 关停、由gpt-oss-120b或qwen3.6-27b接替；
- Production 复合系统：groq/compound、groq/compound-mini（agentic 系统，透传定价，hidden: true）；
- GPT-OSS 家族：openai/gpt-oss-120b、openai/gpt-oss-20b、openai/gpt-oss-safeguard-20b（Preview）。
拒绝列表groqDenyList与groqModelFilter：用model.id.includes(prefix)过滤掉 TTS（whisper-、playai-tts、canopylabs/orpheus）、文本分类（llama-prompt-guard）以及"已从文档和定价移除但 API 仍返回"的模型（如allam-2-7b）。
映射函数groqModelToModelDescription：解析 API 返回的 wire 结构（schema 见 groq.wiretypes.ts，字段含id/object/created/owned_by/active/context_window/max_completion_tokens），进行前缀匹配、字段一致性告警、未收录模型的兜底描述生成、owned_by前缀标注与pubDate回退。
DEV 校验groqValidateModelDefs_DEV：仅 Node 开发构建启用（Release.IsNodeDevBuild，staging 不输出），调用 models.mappings.ts 中的llmDevCheckModels_DEV检查"本地定义但 API 不再返回"（stale）与"API 返回但本地未定义"（unknown）两种情况，并将企业专属模型minimaxai/minimax-m2.7加入ignoreStale——因为标准 key 永远列不出它。
排序函数groqModelSortFn：隐藏模型排最后，其余按模型表内顺序，未收录的按 ID 字典序兜底。

新模型条目的每个字段（chatPrice、contextWindow、maxCompletionTokens、interfaces、parameterSpecs、benchmark、pubDate）都会被fromManualMapping逐步应用到最终描述对象上。

三、数据源选型：为什么必须使用 .md 端点

更新 Groq 模型定义的核心约束是数据源纪律。维护指令明确以下几点，这直接决定了工作流的正确性：

console.groq.com/docs/models.md是主清单：官方文档提供 markdown 格式端点，可直接抓取结构化内容，不要使用网络搜索去拼凑信息，搜索既慢又容易命中过期二手资料。
价格只能从单模型卡片的### PRICING块读取：每行一个$X.XX，分别对应 input / cached input / output。groq.com/pricing页面由 JS 渲染、不携带表格，而/docs/pricing.md直接 404，两者都不可依赖。
/docs/deprecations.md是移除的唯一权威：包含精确的关停日期与替代模型。只要未到关停日，模型就仍然留在 API 与 models.md 中标记为 "Production"——每次更新都必须检查。
单模型能力卡片/docs/model/<model-id>.md：描述能力、图片/文件限制、最大输出与最佳实践；但复合系统（compound）没有单模型卡片（访问会 404），它们统一记录在/docs/compound.md与/docs/compound/built-in-tools.md。
能力矩阵要会取舍：/docs/reasoning.md记录各家族支持的reasoning_effort枚举；/docs/vision.md的图片上限经常过期，以模型卡片上的MAX INPUT IMAGES为准（必要时用超限请求实测确认）；/docs/prompt-caching.md说明哪些模型享受 50% 缓存输入折扣。
changelog 不可用于"新模型"判断：官方 changelog 滞后模型上线数月，只适合回溯，不能用来判断"什么是新的"。

这套数据源分工与groq.models.ts头部注释中的链接备注一一对应，属于长期沉淀下来的经验规则。

四、更新工作流分步详解

1. 拉取官方模型清单

直接抓取console.groq.com/docs/models.md的 markdown，拿到当前全量模型列表。随后逐项审查完整列表，找出三类变化：新增模型、移除模型、价格变动。

2. 价格解析：以 PRICING 卡片块为唯一真相

对每个涉及价格变更的模型，打开其单模型卡片/docs/model/<model-id>.md，解析### PRICING块。以 GPT-OSS 家族为例，groq.models.ts中记录的计费结构是：

// openai/gpt-oss-120b chatPrice: { input: 0.15, output: 0.60, cache: { read: 0.075 } }, // openai/gpt-oss-20b 与 gpt-oss-safeguard-20b chatPrice: { input: 0.075, output: 0.30, cache: { read: 0.0375 } },

cache.read正是 prompt-caching 矩阵（50% 缓存输入折扣）在代码中的落地形式。注意并非所有模型都有缓存折扣：例如qwen/qwen3.8-27b的注释明确指出"prompt caching stays gpt-oss-only"，尽管列表 API 会对部分模型宣传input_cache_read价格，但groq.models.ts仍选择以文档为准不记录缓存价——维护时应保持这种"以权威源为准、不被 API 表象带偏"的谨慎。

3. 退役与替换：以 deprecations 为准

每次更新都要检查/docs/deprecations.md。关停日期之前，模型保留在 API 与 models.md 中；到期后则从_knownGroqModels移除，并在文件上方的已移除模型注释块中追加一行记录，格式为：

// - (Jul 17, 2026) qwen/qwen3-32b, meta-llama/llama-4-scout-17b-16e-instruct (announced Jun 17, shut down Jul 17 -> gpt-oss-120b / qwen3.6-27b)

这种注释记录了日期、关联公告与替代模型，是后续审阅 diff 时理解"为什么删除"的关键上下文，必须保留。同时注意特殊情况：例如llama-3.3-70b-versatile虽然面向免费/开发者套餐关停，但仍作为groq/compound-mini的内部底座继续运行，企业承诺支出合同不受影响——这类"文档与直觉相悖"的信息值得用注释显式标注。

4. 单模型能力卡片：补齐能力与限制

新模型需要从/docs/model/<model-id>.md提取：上下文窗口、最大输出、图片/文件限制、能力接口。以groq.models.ts中的 Preview 条目为例，一个完整的新模型定义包含：

{ isPreview: true, idPrefix: 'qwen/qwen3.8-27b', label: 'Qwen 3.8 · 27B (Preview)', pubDate: '20260805', // upstream 权重发布时间，而非 Groq 上架时间 description: 'Qwen3.8 27B by Alibaba Cloud. Multimodal (vision + text, max 3 images / 20MB), ...', contextWindow: 131042, // 列表 API 与模型卡片一致的特殊值 maxCompletionTokens: 16384, interfaces: [LLM_IF_OAI_Chat, LLM_IF_OAI_Fn, LLM_IF_OAI_Vision, LLM_IF_OAI_Reasoning], parameterSpecs: [ { paramId: 'llmVndOaiEffort', enumValues: ['none', 'low', 'medium', 'high'] }, ], chatPrice: { input: 0.80, output: 4.00 }, },

其中pubDate遵循一个已沉淀的约定：优先使用上游权重/API 发布时间而非 Groq 列表日期（如 Qwen3.8-27B 用 HF 仓库的 2026-08-05 而非 Groq 上架的 2026-08-17），该字段驱动 UI 的 "new" 徽标。

5. 能力矩阵交叉核对：reasoning / vision / prompt-caching

推理档位：从/docs/reasoning.md获取各模型家族的reasoning_effort枚举。代码注释记录了重要差异：qwen/qwen3.8-27b支持完整的none/low/medium/high阶梯，而qwen/qwen3.6-27b只接受none；GPT-OSS 家族则拒绝none，只允许low/medium/high。这些枚举值直接进入parameterSpecs，写错会导致 UI 提供不可用的档位。
视觉限制：/docs/vision.md的图片上限容易过期，以卡片MAX INPUT IMAGES为准，必要时用超过限制的请求实测确认。
缓存折扣：以/docs/prompt-caching.md为准决定是否填写cache.read，不要轻信列表 API 广告的缓存价。

6. 现场 API 交叉校验（可选但强烈推荐）

若.env.api-keys中存在GROQ_API_KEY，可把在线模型列表作为"什么是新/可用"的 ground truth，与文档交叉核对：

curl https://api.groq.com/openai/v1/models -H "Authorization: Bearer $GROQ_API_KEY"

三条硬性纪律：

绝不提交或回显密钥（Never commit or echo the key）；
用curl而非 pythonurllib探测——Cloudflare 会对非浏览器特征客户端返回 403（错误码 1010）；
区分企业专属模型：如 MiniMax 只出现在文档中，标准 key 请求会 404，这正是groqValidateModelDefs_DEV需要ignoreStale: ['minimaxai/minimax-m2.7']的原因，否则每次开发运行都会误报 stale。

五、写入文件的规范与技巧

维护指令给出了三条明确的编辑纪律，目的是让变更可审阅、可回溯：

审查全量列表，不只盯新增——移除与价格变动同样重要，漏掉任何一类都会造成 UI 展示过期价格或失效模型；
最小化空白与注释改动，专注内容本身，避免无关的格式化噪音污染 diff；
保留既有注释，并追加必要的背景注释（如移除原因、数据源说明、特殊值说明），让审阅者无需翻文档就能理解每条改动的依据。

另外，遇到以下情况应显式标记问题：文档中的坏链接、数据自相矛盾（如上下文窗口不一致）、API 行为与文档不符等。这些标记会成为后续维护的重要线索。

六、落地验证：DEV 检查、映射逻辑与测试

映射逻辑：未收录模型如何兜底

groqModelToModelDescription对每个 API 返回的模型做前缀匹配（model.id.startsWith(base.idPrefix)）。匹配失败的模型走 fromManualMapping 的 fallback 分支，得到一条"未精选"描述：标签加[?]前缀（llmsLabelUncurated）、能力未验证、hidden: true隐藏处理。这意味着新模型即使没来得及人工收录，也不会让列表崩溃，但它不会出现在精选位；只有写入_knownGroqModels才被正式收录。

一致性告警

映射过程中会做两项防御性检查并输出console.warn：

context_window不一致：API 解析值与本地定义不符；
max_completion_tokens不一致。

这类告警提示"API 与文档漂移"，通常意味着某侧已经更新，值得核对后同步。

DEV 校验与测试

groqValidateModelDefs_DEV在开发构建下列出 stale（应移除）与 unknown（应新增）清单；测试套件 listModels.test.ts 会捕获[DEV]前缀的告警输出，把"stale/unknown 静默存在"升级为响亮且可见的失败信号——因此每次模型更新后都应跑一遍测试确认没有遗留。
该测试文件还包含openai-compat/groq: live listing用例：配置了GROQ_API_KEY时对真实 API 做在线列表冒烟测试（无 key 自动 skip），可直接验证映射管线的整体健康度。

七、常见陷阱清单

把维护过程中最容易踩的坑集中成清单，方便每次更新时自查：

陷阱	正确做法
用`groq.com/pricing`或`/docs/pricing.md`取价	只用单模型卡片`### PRICING`块
依赖 changelog 判断新模型	changelog 滞后数月，以 models.md 与在线 API 为准
删除未到关停日期的模型	以 deprecations.md 的精确日期为准，到期前保留
对 compound 系统尝试抓单模型卡片	走`/docs/compound.md`与 built-in-tools 文档
信`vision.md`的图片上限	以卡片`MAX INPUT IMAGES`为准并实测
给不支持的模型写错推理档位枚举	逐家族核对 reasoning.md 枚举
忽略未收录模型的兜底表现	记得新模型会以`[?]`隐藏条目出现，不是 bug
用 python urllib 探测 API	用`curl`，避免 Cloudflare 1010 错误
提交或回显 API 密钥	密钥只存在于本地`.env.api-keys`
误报企业专属模型为 stale	加入`ignoreStale`（如`minimaxai/minimax-m2.7`）
忘记把移除记录写进注释块	每次移除都追加"日期 + 替代模型"注释，保持 diff 可读

八、小结

Groq 模型清单的维护本质上是一场"官方文档纪律"与"仓库结构纪律"的双重实践：数据上，严格遵循.md端点分工——models.md 定全量、PRICING 卡片块定价格、deprecations.md 定移除、能力矩阵定接口与档位；代码上，遵循groq.models.ts的区块结构、注释约定与groqModelFilter → groqModelToModelDescription → groqModelSortFn的映射管线，再辅以 DEV 校验与在线列表测试兜底。掌握这套工作流后，你可以在十几分钟内完成一次准确、可审阅、不污染 diff 的 Groq 模型定义同步，并让 UI 的价格、能力标签与新模型"new"徽标始终与官方口径保持一致。

关键代码入口：groq.models.ts ｜ models.mappings.ts ｜ groq.wiretypes.ts ｜ listModels.dispatch.ts ｜ listModels.test.ts

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考