DEV Community

Cover image for Comment utiliser l'API Groq gratuitement ?
Antoine Laurent
Antoine Laurent

Posted on Originally published at apidog.com

Comment utiliser l'API Groq gratuitement ?

Groq 不会在注册时给每个账户发放 Free Plan 密钥用于其兼容 OpenAI 的端点。问题不在于获得访问权限,而在于在应用程序实际调用模型后保持在限制范围内。Groq 在其文档中发布了各模型的 Free Plan 数据,但这些数字会发生变化,且你自己的账户可能会有所不同。一个可靠的习惯是检查你的账户设置,然后在每次调用时读取响应头(headers),因为限制可能会在会话期间发生变化。

立即尝试 Apidog

本指南涵盖了如何获取密钥、将标准 OpenAI 客户端配置为指向 Groq 的端点,以及大多数“免费层级”文章都会忽略的部分:实时监控你的限制,而不是在生产环境中通过 429 错误来发现它们。然后,你的代码代理(coding agent)会将此检查转换为 Apidog CLI 测试,这样它就是可复现的,而不是一个一次性且容易被遗忘的 curl 命令。

TL;DR

Groq 提供两种计划:Free Plan 和 Developer Plan。速率限制是组织级别的(而非每个用户单独计算);无论你先触及请求、token 还是每日总额中的哪一个上限,都会达到限制,且缓存的 token 不会计入你的使用量。Groq 发布了各模型的 Free Plan 数据,但适用于你账户的数字位于你的 console limits 页面,因此最可靠的做法是在每次调用时从 x-ratelimit-* 响应头中读取它们,而不是信任一个可能在没有通知的情况下发生变化的表格。

获取密钥并调用端点

在 console.groq.com 上创建一个账户,并从 API Keys 页面生成一个密钥。Groq 通过兼容 OpenAI 的 API 暴露此密钥,因此如果你之前调用过 OpenAI SDK,你已经了解了其结构。只需将 base URL 指向 Groq 而不是 OpenAI,其他保持不变:

curl https://api.groq.com/openai/v1/chat/completions \
  -H "Authorization: Bearer $GROQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-3.1-8b-instant",
    "messages": [{"role": "user", "content": "Summarize this ticket in one sentence."}]
  }'
Enter fullscreen mode Exit fullscreen mode

或者使用官方的 OpenAI Python 客户端:

import os
from openai import OpenAI

client = OpenAI(
    [REDACTED CREDENTIAL],
    base_url="https://api.groq.com/openai/v1",
)

response = client.chat.completions.create(
    model="llama-3.3-70b-versatile",
    messages=[{"role": "user", "content": "List three causes of API timeout errors."}],
)

print(response.choices[0].message.content)
Enter fullscreen mode Exit fullscreen mode

Groq 的 OpenAI 兼容性文档 提到了一些在复制现有代码之前值得了解的差距:logprobs、logit_bias、top_logprobs 和 messages[].name 都会返回 400 错误,如果你设置了 n,它必须等于 1,并且 temperature 为 0 会转换为一个小的正浮点数(float),而不是真正的贪婪解码(greedy decoding)。

Free Plan vs Developer Plan

Groq 的条款很直接:“升级到 Developer Plan 以获得更高的限制、批量和灵活处理等。” Free Plan 是每个新创建密钥的起点,它确实可用于测试和小型个人项目。

Groq free plan requests per day by model

以下是 Free Plan 对部分模型允许的使用量,数据来自 Groq 于 2026-09-15 咨询的 速率限制文档:

模型 RPM RPD TPM TPD 音频
groq/compound 30 250 70K - -
openai/gpt-oss-120b 30 1K 8K 200K -
openai/gpt-oss-20b 30 1K 8K 200K -
whisper-large-v3 20 2K - - 7.2K ASH / 28.8K ASD

同一页面还有一个 Developer Plan 标签页,其中列出了每个模型更高的上限,以及批量和灵活处理。将上表视为一个快照,因为 Groq 可能会在没有通知的情况下更改这些数字。你自己的数据位于你 账户设置中的限制页面:如果出现不一致,请信任该页面而不是本文。

有两个策略细节比原始数据更重要。速率限制适用于“组织级别,而非单个用户”,因此共享一个 Groq 组织的五个人共享同一个限制,而不是五个单独的限制。而且“缓存的 token 不计入你的速率限制”,这意味着具有良好缓存 prompt 结构实际上为你提供了比显示数字所暗示的更高的吞吐量。

在触及限制之前需要了解的模型

适用什么限制取决于你调用哪个模型。Groq 的文本模型和 Compound 系统支持 131,072 token 的上下文:

模型 ID 类型
llama-3.1-8b-instant 快速通用文本
llama-3.3-70b-versatile 更大的通用文本
openai/gpt-oss-120b 开放权重的推理模型
openai/gpt-oss-20b 更小的开放权重推理模型
groq/compound 智能体系统
groq/compound-mini 更轻量的智能体系统

Whisper 模型 whisper-large-v3 和 whisper-large-v3-turbo 不在此表中。它们是音频转录模型,Groq 以每小时和每天的音频秒数(ASH/ASD)来衡量其吞吐量,此外还有它们自己的 RPM 和 RPD 上限,而不是 token。

每个模型都有自己的 RPM、RPD 和 token 上限,因此不要假设适用于 llama-3.1-8b-instant 的限制也适用于 openai/gpt-oss-120b。

读取速率限制响应头,而不是靠猜

来自 api.groq.com 的每个响应都带有一组响应头,可以确切地告诉你当前的状态,而无需咨询控制台:

  • x-ratelimit-limit-requests 和 x-ratelimit-limit-tokens,你当前时间窗口的上限
  • x-ratelimit-remaining-requests 和 x-ratelimit-remaining-tokens,当前剩余额度
  • x-ratelimit-reset-requests 和 x-ratelimit-reset-tokens,时间窗口重置的时间
  • retry-after,在出现 429 时发送,告诉你需要等待多长时间

在每次调用后读取 x-ratelimit-remaining-tokens,你就有了一个实时的仪表盘,而不是你看过一次就忘记重新检查的静态数字。以下是使用 cURL 的快速检查,仅显示响应头:

curl -sD - https://api.groq.com/openai/v1/chat/completions \
  -H "Authorization: Bearer $GROQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "llama-3.1-8b-instant", "messages": [{"role": "user", "content": "hi"}]}' \
  -o /dev/null | grep -i ratelimit
Enter fullscreen mode Exit fullscreen mode

针对一个输出冗长的测试脚本循环运行几次,你会看到 x-ratelimit-remaining-tokens 逐渐减少。如果你的应用程序需要实现退避逻辑(backoff logic),请参阅我们关于如何实现 API 速率限制的指南,以了解支持 retry-after 响应头的模式,而不是靠猜测延迟时间。

让你的代码智能体(Coding Agent)使用 Apidog CLI 运行检查

在调试会话中,手动执行 curl 和 grep 的“舞蹈”是可行的。这对于团队来说无法规模化,而且没有人在每次部署前都会重新运行一次性的 shell 命令。将检查交给你的代码智能体:使用 Apidog CLI,它编写一次测试,并在你需要时随时运行。配置一次:

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com   # pick your agent when prompted
Enter fullscreen mode Exit fullscreen mode

Token 来自 Apidog,位于“账户设置”->“API 访问 Token”下。然后,给智能体一个 prompt:

Use Apidog CLI on project <id>. Create a Groq environment with base URL
https://api.groq.com/openai/v1 and add POST /chat/completions with Bearer [REDACTED]
from {{GROQ_API_KEY}}. Create one test case per model we run in production
(llama-3.1-8b-instant, openai/gpt-oss-120b) that asserts status 200 and fails
when x-ratelimit-remaining-tokens drops below 10% of x-ratelimit-limit-tokens.
Put both cases in a "Groq limits" test suite, run it, and report the headers.
Enter fullscreen mode Exit fullscreen mode

它运行的命令已通过 Apidog CLI 2.2.7 验证:

apidog environment create Groq --project <id> --base-url https://api.groq.com/openai/v1
apidog endpoint create --project <id> --file groq-chat.json
apidog cli-schema validate test-case-create --file groq-8b-case.json
apidog test-case create --project <id> --file groq-8b-case.json
apidog test-suite create --project <id> --name "Groq limits"
apidog run --test-suite <suiteId> --project <id> -e <envId> \
  --env-var "GROQ_API_KEY=$GROQ_API_KEY" -r cli,junit
Enter fullscreen mode Exit fullscreen mode

一个正在减少的预算现在会显示为测试失败,而不是在演示过程中出现意想不到的 429 错误。将最后一行放入你的预部署 CI 任务中,就像我们关于使用 Apidog CLI 的 CI/CD 管道指南中所展示的那样,或者让智能体运行 apidog scheduled-task create,它会根据 cron 在 runner 上执行测试套件。考虑到 Groq 的组织级共享资源池,这一点变得更加重要:同事运行的批处理作业可能会消耗掉你的生产端点一小时后需要的共享预算。这与我们关于测试 GPT API 速率限制的文章中的思路相同。

当你真正达到限制时该怎么办

当返回 429 时,请遵循 retry-after 而不是立即重试。针对请求级别限制的紧凑重试循环只会更快地消耗你的剩余预算,并使重置时间窗口进一步向后推移。如果你将此集成到生产服务而不是测试脚本中,我们全面的速率限制超限错误指南提供了适用于不同提供商(不仅是 Groq)的退避策略。

What to do when you hit the Groq free plan rate limit

如果你持续触及 Free Plan 的上限,最快的解决方案是升级到 Groq 文档中提到的 Developer Plan。第二快的方案,特别是对于原型开发,是将流量分散到多个提供商。我们精选的 OpenRouter 替代方案涵盖了在此类情况下值得备用的其他端点。

FAQ

Groq 的 API 是否提供免费层级? 是的。每个新账户都从 Free Plan 开始,并具有兼容 OpenAI 的端点访问权限。Groq 发布了几个模型的 Free Plan 限制示例,但实际适用于你账户的上限位于你的 console 设置中的限制页面。

如何查看我当前的 Groq 速率限制? 有两种方法:打开账户设置中的限制页面,或者读取任何 API 响应上的 x-ratelimit-limit-requests 和 x-ratelimit-limit-tokens 响应头。响应头反映了调用时你账户的实际限制,这比你只看过一次并记住的数字更可靠。

当我超过 Groq 的速率限制时会发生什么? 你会收到一个 429 响应,并带有告诉你等待多少秒的 retry-after 响应头。请查阅我们的速率限制超限指南以在代码中处理此问题,而不是靠猜测延迟。

缓存 token 是否计入我的 Groq 速率限制? 不会。Groq 明确表示缓存 token 不会计入你的速率限制,因此重用缓存系统消息的 Prompt 结构所获得的实际吞吐量比原始 token 限制所暗示的更高。

Groq 的速率限制是针对单个用户还是组织? 针对组织。同一个 Groq 组织下的每个密钥都共享一个请求和 token 池,因此同事的脚本可能会蚕食你生产应用所需的预算。

哪些 Groq 模型的上下文窗口最大? llama-3.1-8b-instant、llama-3.3-70b-versatile、openai/gpt-oss-120b、openai/gpt-oss-20b 以及 Compound 系列都支持 131,072 个上下文 token。Whisper 模型是音频转录模型,而非文本模型,因此 Groq 以音频时长来衡量它们的限制。速率限制因模型而异,即使在相同的上下文窗口内也是如此,因此请分别检查每个模型。

总结

免费使用 Groq API 的方法不是一个神秘的数字,而是一种习惯。获取密钥,将兼容 OpenAI 的端点指向它,并在每次调用时读取响应头,而不是信任你在博客文章(包括本文)中找到的数字。

让你的代码智能体使用 Apidog CLI 构建一次此检查,并对每个模型的剩余 token 进行断言(assertion),它将在随后的每次部署中运行。设置它所花的时间比阅读 Groq 文档的剩余部分还要少。为了更深入地覆盖负载下的 AI API 层测试,我们关于AI 智能体最佳 API 测试工具的指南是很好的下一步。

Top comments (0)