Groq 是一家专注于 AI 推理加速的硬件与云服务公司，其自研的 LPU（Language Processing Unit） 芯片专为大语言模型推理设计，在低延迟与高吞吐方面具有显著优势。Groq API 提供与 OpenAI API 高度兼容的接口，开发者可通过标准 HTTP 请求或 SDK 快速接入，利用 LPU 的加速能力完成文本生成、对话等任务。本文将从环境准备、核心用法、常见集成方式到避坑指南，系统介绍 Groq API 的使用。

环境准备与认证

获取 API Key

访问 console.groq.com 注册账号，在控制台生成 API Key。密钥以 gsk_ 开头，请妥善保管。Groq 提供免费额度，具体限额与价格以官网最新公告为准。建议为每个项目创建独立的 API Key，便于权限管理和用量追踪。

安装 SDK

Groq 官方提供 Python SDK，通过 pip 安装：

bash
pip install groq

SDK 默认从环境变量 GROQ_API_KEY 读取密钥。建议在 .env 文件或 shell 配置中设置：

bash
export GROQ_API_KEY="gsk_your_actual_key_here"

在代码中，直接初始化客户端即可：

python
from groq import Groq
client = Groq()  # 自动读取 GROQ_API_KEY

若需显式传入密钥（如用于多账号管理），可：

python
client = Groq(api_key="gsk_your_actual_key_here")

常见坑：不要将 API Key 硬编码在代码中，尤其是提交到版本控制时。使用环境变量或密钥管理服务（如 HashiCorp Vault、AWS Secrets Manager）是更安全的选择。密钥泄露后立即在控制台吊销并重新生成。

核心 API 调用：文本生成

Groq 的核心端点是 chat.completions.create，支持流式与非流式输出。以下为最简示例：

python
response = client.chat.completions.create(
    model="llama-3.3-70b-versatile",
    messages=[
        {"role": "system", "content": "你是一个有用的助手。"},
        {"role": "user", "content": "请用中文解释什么是 LPU。"}
    ],
    temperature=0.7,
    max_tokens=1024
)
print(response.choices[0].message.content)

参数说明

model：指定模型名称。可用模型列表以 console.groq.com 官方页面为准。常见模型包括：

- llama-3.3-70b-versatile（Llama 3.3 70B，通用型） - llama-3.1-8b-instant（Llama 3.1 8B，低延迟） - openai/gpt-oss-120b（OpenAI 开源模型 120B） - openai/gpt-oss-20b（OpenAI 开源模型 20B）

messages：对话历史列表，支持 system、user、assistant 角色。

temperature：采样温度，范围 0~2，默认 1。较低值使输出更确定。

max_tokens：本次生成的最大输出 token 数（不含输入）。设置合理上限既能控制成本，也能避免异常的长输出。

常见坑：模型名拼写错误是新手最常遇到的问题。Groq 的模型名格式为 {provider}/{model}-{variant}，例如 llama-3.3-70b-versatile。常见错误包括：漏写版本号（如只写 llama-3.3）、大小写错误（Groq 模型名全小写）、使用 OpenAI 模型名（如 gpt-4）——Groq 不支持 OpenAI 闭源模型。解决方案：始终从 console.groq.com 的模型列表复制名称。

流式输出（Streaming）

LPU 的低延迟特性在流式输出中尤为突出。设置 stream=True 后，API 会逐 token 返回结果，适合实时展示：

python
stream = client.chat.completions.create(
    model="llama-3.1-8b-instant",
    messages=[{"role": "user", "content": "讲一个关于程序员的笑话。"}],
    stream=True
)
for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

流式响应中，每个 chunk 的 choices[0].delta 包含增量内容。注意：流式模式下 response 是一个迭代器，不可直接访问 choices。

常见坑：流式模式下，chunk.choices[0].delta.content 可能为 None（如最后一条 chunk 只有 finish_reason）。务必做空值检查，否则会抛出 AttributeError。另外，流式输出时需自行拼接所有 chunk 的 delta.content 以获取完整响应。

使用 OpenAI SDK 兼容接入

Groq API 完全兼容 OpenAI 的端点格式，因此可直接使用 OpenAI 的 Python SDK，仅需修改 base_url 和 api_key：

bash
pip install openai

python
import os
from openai import OpenAI
client = OpenAI(
    base_url="https://api.groq.com/openai/v1",
    api_key=os.environ.get("GROQ_API_KEY")
)
response = client.chat.completions.create(
    model="llama-3.3-70b-versatile",
    messages=[{"role": "user", "content": "Hello, Groq!"}]
)
print(response.choices[0].message.content)

此方式适用于已使用 OpenAI SDK 的项目，只需替换 base_url 即可切换后端。注意：Groq 的模型列表与 OpenAI 不同，需使用 Groq 支持的模型名。这种兼容性使得迁移成本极低，尤其适合在 API 集成教程 中作为后端替换方案。

使用 cURL 调用

对于非 Python 环境，可直接通过 HTTP 请求调用：

bash
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": "你好，Groq！"}],
    "temperature": 0.7,
    "max_tokens": 256
  }'

流式输出需添加 "stream": true 参数，并设置 -N 选项以禁用 curl 的缓冲：

bash
curl -N 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": "讲一个笑话。"}],
    "stream": true
  }'

常见坑：cURL 调用时，如果未设置 -N，流式输出会被缓冲，导致客户端看到的是整段文本而非逐 token 输出。另外，确保 $GROQ_API_KEY 环境变量已正确设置，否则会返回 401 认证错误。

LPU 加速原理与优势

Groq 的 LPU 是一种专为序列化推理设计的处理器架构，不同于 GPU 的并行矩阵计算，LPU 采用确定性执行与数据流架构，能显著降低 token 生成延迟。实际体验中，其响应速度远快于同等规模的 GPU 推理服务，尤其适合需要实时交互的场景，如聊天机器人、代码补全、实时翻译等。LPU 的另一个优势是可预测的延迟——每次请求的延迟波动极小，这对生产环境至关重要。

对于需要自定义模型部署的场景，可参考 模型部署指南，了解如何将 Groq 集成到现有推理管线中。

进阶用法：多轮对话与系统提示

Groq 支持多轮对话，只需在 messages 中按顺序包含历史记录：

python
messages = [
    {"role": "system", "content": "你是一个幽默的助手。"},
    {"role": "user", "content": "什么是递归？"},
    {"role": "assistant", "content": "递归就是函数调用自身。"},
    {"role": "user", "content": "能举个例子吗？"}
]
response = client.chat.completions.create(
    model="llama-3.3-70b-versatile",
    messages=messages
)

注意：长对话会消耗更多输入 token，建议定期截断历史或使用 token 计数工具（如 tiktoken）来管理上下文窗口。

常见坑：多轮对话中，如果 messages 列表过长（超过模型上下文窗口），API 会返回 400 错误。解决方案是：1) 使用 max_tokens 参数限制输出长度；2) 定期截断历史消息，只保留最近几轮对话；3) 使用 token 计数工具预估输入长度。

错误处理与指数退避重试

生产环境中，网络抖动和速率限制不可避免。对 429（限流）和 5xx（服务端错误）应做带抖动的指数退避重试，而 400（参数错误）、401（认证失败）这类错误重试无意义，应直接抛出：

python
import time
import random
from groq import Groq, RateLimitError, InternalServerError
client = Groq()
def chat_with_retry(messages, model="llama-3.3-70b-versatile", max_attempts=5):
    for attempt in range(max_attempts):
        try:
            return client.chat.completions.create(model=model, messages=messages)
        except (RateLimitError, InternalServerError) as e:
            if attempt == max_attempts - 1:
                raise
            wait = min(2 ** attempt, 30) + random.uniform(0, 1)
            print(f"请求失败（{type(e).__name__}），{wait:.1f}s 后重试…")
            time.sleep(wait)

要点：退避时间按 2 的指数增长并加随机抖动（jitter），避免大量客户端在同一时刻同时重试形成"重试风暴"；2 ** attempt 封顶 30 秒，防止无限等待。更完整的容错设计（多提供商降级、熔断器）可结合站点内相关主题实践。

常见坑与避坑指南

1. Rate Limit 与配额

Groq 免费额度有请求频率限制（如每分钟请求数、每日 token 数）。超出限制会返回 429 Too Many Requests。建议：

在代码中实现指数退避重试。

监控 X-RateLimit-* 响应头。

生产环境升级付费套餐。

2. 密钥管理

不要将 API Key 硬编码在代码中，使用环境变量或密钥管理服务。

密钥泄露后立即在控制台吊销并重新生成。

区分开发与生产环境的密钥。

3. 流式输出未正确处理

流式模式下，chunk.choices[0].delta.content 可能为 None（如最后一条 chunk 只有 finish_reason）。务必做空值检查。

4. 模型名拼写错误

始终从 console.groq.com 的模型列表复制名称，避免手动输入。

FAQ

Q：Groq API 是否支持函数调用（Function Calling）？ A：部分模型支持函数调用，具体以官方文档为准。目前 llama-3.3-70b-versatile 等模型已支持。

Q：免费额度用完后会怎样？ A：请求会因超出配额被拒绝（返回 429 类的限流错误，响应体中会说明具体配额类型）。可在控制台查看用量、等待额度重置（按分钟/按天计的配额会自动恢复）或升级付费套餐。

Q：Groq 的 LPU 与 GPU 相比，在哪些场景优势明显？ A：LPU 在低延迟、可预测延迟方面优势显著，适合实时对话、代码补全等交互式场景。对于批量处理大量长文本，GPU 可能更经济。

Q：能否在 Groq 上部署自己的模型？ A：目前 Groq 仅提供预训练模型的 API 服务，不支持自定义模型部署。如需私有部署，可考虑其他平台。

Q：流式输出时如何获取完整响应？ A：流式模式下需自行拼接所有 chunk 的 delta.content。也可同时使用非流式请求获取完整结果（但会牺牲实时性）。

Q：新手应该从哪个模型开始？ A：通用对话与推理任务，默认用 llama-3.3-70b-versatile；对延迟敏感的功能（如自动补全、实时改写），用 llama-3.1-8b-instant，以部分能力换取速度。选型后建议用自己的真实 prompt 做一次对比测试。

*最后更新：2026 年 7 月。请以各工具官方文档为准。*