Groq API 接入指南：拿 key 到 OpenAI 兼容避坑

2026-08-07

假设你手上有个已经跑起来的项目，用的是 OpenAI 的 Python SDK，调用散落在七八个文件里。现在你想加一条走 Groq 的通道——可能是想给主通道留个后备，也可能是想拿它的免费层做点非核心的批处理。最少要改几行？

答案通常是两行：一行改 base_url，一行改模型 ID。剩下的 client.chat.completions.create(...) 一个字都不用动。

但「两行改完能跑」和「两行改完能上生产」之间，隔着一份官方明确列出的不支持参数清单。这篇就把接入路径和这些坑一起讲完。

一、接入前，先摆正 Groq 在你架构里的位置

很多人接一家新平台之前会先去翻它的技术白皮书，看它用了什么芯片、什么调度。对做接入的人来说，这一步可以往后放。真正决定你改多少代码的只有一件事：它提供不提供 OpenAI 兼容端点。

Groq 提供。官方文档里专门有一页讲 OpenAI 兼容性，明确的用法是：把 OpenAI 客户端的 api_key 换成 Groq 的 key，base_url 指向 Groq 的兼容地址，其余照旧。这意味着你已有的重试逻辑、流式解析、超时封装、日志埋点，全部可以复用——这些恰恰是自己撸一遍 HTTP 客户端最容易出错的部分。

所以切换成本只落在两个地方：base_url 和模型 ID。前者是常量，后者是字符串，都是配置层的事，不该硬编码在业务代码里。如果你现在的代码里模型名是写死在某个 create() 调用里的，接 Groq 之前先把它抽成配置——这一步的收益不止于这次接入。

关于 base_url 应该填到哪一层、结尾要不要带 /v1、SDK 会不会自动补路径，这些细节在base_url 怎么填里讲得更细，接之前值得扫一眼，能省掉一轮 404 排查。

二、三步接进去

第一步：拿 key，放进环境变量

在 Groq 的控制台创建 API key，然后按官方约定放进环境变量 GROQ_API_KEY。

用官方约定的环境变量名不是形式主义。OpenAI SDK 和很多周边工具链会按约定名去读，你一旦自己起名叫 MY_GROQ_TOKEN，就得在每个入口手动传一遍，多进程、定时任务、容器里少注入一个都会变成一次线上 401。key 泄漏和 key 没读到是接入期最高频的两类事故，前者靠不进代码库，后者靠守住命名约定。

真撞上 401 也别急着重新生成 key，先按401 排查的顺序走一遍——Groq 官方对 401 的定义就是「凭据缺失或无效」，绝大多数情况是没读到，不是没权限。权限不足是单独的 403。

第二步：base_url 指向兼容端点

https://api.groq.com/openai/v1

注意路径里 openai 在前、v1 在后。这个顺序和一些平台的写法是反的，手敲容易串。

第三步：发出首个请求

Python，用 OpenAI SDK：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["GROQ_API_KEY"],
    base_url="https://api.groq.com/openai/v1",
)

resp = client.chat.completions.create(
    model="llama-3.3-70b-versatile",
    messages=[
        {"role": "user", "content": "用一句话解释什么是 OpenAI 兼容端点"}
    ],
)
print(resp.choices[0].message.content)

curl 版本，用来排除 SDK 层面的干扰：

curl https://api.groq.com/openai/v1/chat/completions \
  -H "Authorization: Bearer $GROQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-3.3-70b-versatile",
    "messages": [{"role": "user", "content": "ping"}]
  }'

我的习惯是先跑 curl 再跑 SDK。curl 通了 SDK 不通，问题在客户端配置；两个都不通，问题在 key 或网络。这个二分法能把首次接入的排查时间压掉一大半。

上面示例里的模型 ID 是官方 Python 示例中出现的 llama-3.3-70b-versatile。可用的完整模型清单请以 Groq 官方文档为准，别照着别处的博客抄模型名——推理平台的模型上下架比文档更新快，抄来的名字过期了就是一个 404 或者 400。

如果你是从 OpenAI 官方端点切过来的，用 OpenAI SDK 接入第三方平台里那套「只改两处、其余不动」的做法可以直接套用。

三、OpenAI 兼容 ≠ OpenAI 一样：这份清单值得打印出来

这是全文最该慢读的一节。

「OpenAI 兼容」是个营销词也是个工程词，它保证的是请求结构和响应结构对齐，不保证每个参数都实现。Groq 官方文档里直接列出了一份不支持参数清单，这种坦诚在推理平台里不算多见。逐条说说它们会在什么场景里咬你一口。

`logprobs`、`logit_bias`、`top_logprobs` 不支持

这三个是同一类东西：对 token 概率分布的读和写。

logprobs / top_logprobs 是读——很多做分类、意图识别、内容审核的团队，会拿返回的对数概率折算出一个置信度，低于阈值就转人工或者降级到规则引擎。这套做法在生产里相当普遍，因为它比「再让模型自评一次可信度」便宜也稳定。切到 Groq 之后这条路直接断了，你的置信度分支会拿到 None，然后要么抛异常，要么静默走进 else 分支——后者更可怕，因为它不报错。

logit_bias 是写——用来强行压低或抬高某些 token 的出现概率，典型用途是约束输出只能落在几个枚举值里，或者屏蔽特定词。没有它，你只能退回到提示词约束加输出校验，多一层解析失败的重试。

接入前的动作：全局搜一遍代码里有没有这三个参数名。有的话，先想清楚替代方案再切通道，别指望上线后再补。

`messages[].name` 不支持

OpenAI 的消息体允许在每条消息里带一个 name 字段，用来区分同一个 role 下的不同说话人。做多人会议纪要、群聊摘要、多 Agent 协作日志的项目很爱用这个字段——三个 user 消息，靠 name 区分是张三、李四还是王五。

切到 Groq 这个字段不生效，说话人信息就丢了。可行的替代是把身份写进 content 本身，比如 "张三：这个方案我有保留意见"。它有效，但要注意两点：一是所有拼装逻辑都得改，二是模型现在是从正文里「读」身份而不是从结构里「知道」身份，遇到内容本身含冒号的情况可能混淆，需要额外的分隔符设计。

`N` 必须等于 1

想一次要三个候选答案做对比、投票、或者自洽性检验（self-consistency）的，在 Groq 这边只能自己发三次请求。

这不只是多写个循环的事，它连带三个后果：请求数变三倍，会更快撞上限速；三次请求的耗时是串行叠加还是并发，取决于你怎么写；三次请求之间没有共享的前缀计算，成本模型和 n=3 完全不同。做投票类应用的，接入前先把这笔账算清楚。

`temperature` 传 0 会被转换成 `1e-8`

这条最隐蔽，也是我最想让人记住的一条。

很多团队为了让输出可复现，习惯把 temperature 设成 0，然后在心里默认「这下输出是确定的了」。Groq 的行为是：收到 0，把它转换成 1e-8。

1e-8 不是 0。它是一个极小但非零的温度值，意味着采样分布被压得极窄，绝大多数时候会选中概率最高的那个 token——但这是近似确定，不是等于确定。当两个 token 的概率贴得极近时，仍然存在翻盘的可能。

这个区别在什么时候会要命？在你拿输出当缓存 key 的时候，在你写「同样输入必须同样输出」的回归测试的时候，在你给客户承诺「相同问题答案一致」的时候。我见过不少人把偶发的输出漂移归咎于「模型不稳定」，查了三天，最后发现是自己对 temperature=0 的语义理解和平台实现对不上。

正确的姿势是：不要把可复现性建立在温度参数上。要复现，就在你自己这一层做缓存或者快照；要一致性，就在输出层做规范化和校验。这条建议对任何平台都成立，Groq 只是把这个假设的脆弱之处明明白白写了出来。

音频格式不支持 `vtt` 和 `srt`

做语音转写并直接要字幕文件的，注意这两个格式在不支持清单里。你能拿到的是结构化结果，字幕文件得自己按时间轴拼。这活儿不难但很烦，尤其是断句规则和每行字数限制，要提前排进工期。

四、跑通之后，先验证什么

首个请求返回 200，接入只完成了一半。我的顺序是这样的：

先单线程跑通全链路，再碰并发。 把你真实业务里最长的那个 prompt 拿来跑一遍，看流式输出解析对不对、超时设置合不合理、异常分支走不走得通。这个阶段任何并发都是干扰项。

然后才是压限速。 Groq 的限速有两个特点必须提前知道：

第一，官方明确说明速率限制适用于组织级别，不适用于个别用户。这句话的分量在多环境场景下才显出来——你的开发环境、CI 流水线、预发布环境、生产环境如果共用一个组织，它们是在抢同一个额度池的。CI 一跑集成测试，生产就开始吐 429，这种事故排查起来很折磨人，因为两边的日志看起来毫不相干。可行的做法是把不同环境的调用量做隔离和标记，至少让你能从监控上分辨是谁在吃额度。

第二，限速是多维的，同时存在每分钟请求数、每天请求数、每分钟 token 数、每天 token 数这几个维度，官方的说法是先撞到哪个阈值，哪个就生效。这决定了你不能只盯着 RPM 做限流。举个直观的对比：免费层里 llama-3.3-70b-versatile 的每分钟请求数和 llama-3.1-8b-instant 是同一个量级，但每天请求数和 token 额度差得很远。你按请求数算出来「够用」，实际可能先在 token 维度上被拦住——长 prompt 的应用尤其容易这样。具体数值以 Groq 官方限速页为准，这类表格是会变的，别抄进代码注释当常量。

撞上 429 之后怎么退避、怎么区分「瞬时超速」和「日额度耗尽」，429 限流排查里有一套可以直接用的处理框架。这里补一个 Groq 特有的信息：它的错误码里除了标准的 4xx / 5xx，还有两个自定义码——498 表示 Flex Tier 容量超限，499 表示调用方主动取消了请求。499 大量出现通常不是平台问题，是你自己的超时设得太短或者上游把连接断了，别往平台身上赖。

还有一条对账时用得上：官方明确 5xx 响应不计费。所以看到一堆 503 不用慌张地去算损失，但要记得 5xx 意味着维护或过载，重试策略里该带上退避。

Groq 的错误响应结构也是 OpenAI 风格的：JSON 里一个 error 对象，包含 message 描述文本和 type 分类（比如 invalid_request_error）。如果你已经有一套按 type 分流的错误处理，这部分同样可以复用。

五、把 Groq 当备用通道时，最容易犯的一个错

多通道路由是接入第二家平台之后的自然需求：主通道挂了、限速了、或者某类请求想走更便宜的通道，就切过去。

这里有个反复出现的错误：只切 key，不切 base_url 和模型 ID。

原因往往是历史包袱——早期代码里 key 是从配置读的（因为要轮换），base_url 和模型名却是写死的常量（因为「反正只有一家」）。等到要加通道的时候，最顺手的改法就是改 key，结果是拿着 Groq 的 key 去请求 OpenAI 的端点，或者拿着正确的端点去请求一个 Groq 上不存在的模型名。前者返回 401，后者返回 404 或 400，两个都会让你怀疑是不是 key 申请错了。

正确的抽象是把「通道」当成一个整体对象：base_url + key + 模型 ID 映射三件套必须一起切换，而且模型 ID 得做映射而不是直接透传——Groq 用的是扁平模型名，别的平台可能是 组织/模型 风格，同一个业务语义在不同平台对应不同字符串。

再往上一层，如果通道超过两三个，值得考虑在应用和平台之间放一个统一的兼容层，把路由、重试、降级、计量都收在一处。这套思路和取舍在OpenAI 兼容端点怎么用里展开过。至于什么时候该走 API、什么时候该考虑自建，那是另一个维度的账，自建 vs API里算过。

接入自查清单

接完之后，对着下面这几条过一遍，每条都能在五分钟内验证：

key 走环境变量 GROQ_API_KEY，代码里搜不到明文 key——git grep 一次，顺便查一下有没有误提交进历史。
base_url 是 https://api.groq.com/openai/v1，且来自配置而非硬编码——确认 openai 在 v1 前面。
全局搜过 logprobs、top_logprobs、logit_bias、messages[].name——命中的地方要么改掉，要么在通道路由里排除走 Groq。
确认没有传 n > 1——需要多候选的逻辑改成多次请求，并重新估算限速余量。
所有 temperature=0 的调用点都复查过——明确知道 Groq 会把它转成 1e-8，并且你的可复现性不依赖这个假设。
限速按最紧的那个维度做过估算——每分钟/每天的请求数和 token 数四个维度都算，取最先撞到的那个，并且记住额度是组织级共享的，把 CI 和开发环境的消耗也算进去。
重试逻辑区分了 429、5xx、499 三类——429 退避、5xx 退避且知道不计费、499 回头查自己的超时设置。

前六条过了，这条通道就可以放进生产的降级链路里；第七条过了，它才经得起半夜自动切换。

本文涉及的 base_url、参数支持情况、限速与错误码，均以 Groq 官方文档为准，平台策略会调整，上线前请以控制台和官方文档的当前版本核对一次。