使用 OpenAI SDK 调用 Groq GPT-OSS 120B：Base URL、定价与缓存

Groq 的 OpenAI 兼容端点确实只需改一行：将 base_url 设为 https://api.groq.com/openai/v1，然后继续使用 OpenAI SDK。截至 2026 年 6 月 17 日，Groq 在其定价页面上列出的 openai/gpt-oss-120b 价格为：每 1M 未缓存输入 token 0.15 美元、每 1M 已缓存输入 token 0.075 美元，以及每 1M 输出 token 0.60 美元（Groq 定价）。

这是有用的部分。陷阱在于以为“OpenAI 兼容”就意味着“行为完全一致、计费完全一致”。事实并非如此。你仍然需要选择 Groq 模型 ID、关注缓存命中、避免不受支持的 OpenAI 参数，并单独统计内置工具调用。

你实际切换的是什么

Groq 文档称其 API “基本兼容 OpenAI 的客户端库”，并展示了准确的 OpenAI 客户端配置方式：传入你的 Groq key，并设置 base_url="https://api.groq.com/openai/v1"（Groq OpenAI 兼容性）。

安装 OpenAI Python SDK：

pip install openai
export GROQ_API_KEY="gsk_..."

然后通过 Groq 调用 GPT-OSS 120B：

import os
from openai import OpenAI

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

response = client.chat.completions.create(
    model="openai/gpt-oss-120b",
    messages=[
        {"role": "system", "content": "You are a concise senior backend engineer."},
        {"role": "user", "content": "Write a PostgreSQL index plan for a slow user_events query."},
    ],
)

print(response.choices[0].message.content)
print(response.usage)

关键区别是 model。在 OpenAI 自家平台上，你可能会使用 OpenAI 托管的模型名称。在 Groq 上，GPT-OSS 的调用名称是 openai/gpt-oss-120b 或 openai/gpt-oss-20b。

OpenAI 于 2025 年 8 月 5 日发布了 gpt-oss-120b 和 gpt-oss-20b，它们是基于 Apache 2.0 许可的开放权重推理模型（OpenAI）。OpenAI 表示，gpt-oss-120b 总参数量为 117B，每个 token 激活 5.1B 参数，包含 128 个专家，每个 token 激活 4 个专家，并原生支持最高 128k 的上下文长度（OpenAI）。Groq 的模型页面列出的托管版 openai/gpt-oss-120b 上下文窗口为 131,072 token，最大输出 token 为 65,536（Groq 模型卡）。

选择 120B 还是 20B

当质量比原始成本更重要时使用 120B：智能体规划、更难的编码任务、复杂抽取或多步推理。当你需要更便宜的吞吐用于路由、摘要、分类、短助手或高容量后台任务时使用 20B。

Groq 模型 ID	标称速度	未缓存输入	已缓存输入	输出
openai/gpt-oss-120b	500 TPS	$0.15 / 1M	$0.075 / 1M	$0.60 / 1M
openai/gpt-oss-20b	1,000 TPS	$0.075 / 1M	$0.0375 / 1M	$0.30 / 1M

这些价格来自 Groq 当前的定价表和提示缓存表（Groq 定价）。20B 模型的标称 token 价格正好是 120B 的一半。这使它很适合作为“先试试”的工作流默认选项。如果回答质量不够好，再把那条路径升级到 120B。

这里有一个可以放在配置里的极简切换：

import os
from openai import OpenAI

MODEL = os.getenv("GROQ_MODEL", "openai/gpt-oss-20b")

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

def ask(prompt: str) -> str:
    response = client.chat.completions.create(
        model=MODEL,
        messages=[
            {"role": "system", "content": "Answer with practical developer steps."},
            {"role": "user", "content": prompt},
        ],
    )
    return response.choices[0].message.content

print(ask("Give me a minimal Redis rate limiter design."))

用 20B 运行：

GROQ_MODEL=openai/gpt-oss-20b python app.py

用 120B 运行：

GROQ_MODEL=openai/gpt-oss-120b python app.py

按缓存命中为请求定价

Groq 提示缓存会对受支持模型自动启用，包括 openai/gpt-oss-20b 和 openai/gpt-oss-120b。Groq 表示无需修改代码，缓存命中使用精确前缀匹配，已缓存部分可获得 50% 的输入 token 折扣，且缓存数据在 2 小时未使用后会自动过期（Groq 提示缓存）。

实用规则：把稳定文本放在前面。

好的顺序：

1. 系统提示
2. 工具定义
3. Few-shot 示例
4. 共享文档或 schema
5. 用户特定输入
6. 时间戳、ID、每次请求不同的数据

不好的顺序：在 20,000 token 的共享提示之前放时间戳、请求 ID 或用户特定字段。这会破坏前缀。

这里是一个用于 GPT-OSS 120B 的成本辅助函数：

def groq_gpt_oss_120b_cost(prompt_tokens, cached_tokens, completion_tokens):
    uncached_tokens = max(prompt_tokens - cached_tokens, 0)

    return (
        uncached_tokens / 1_000_000 * 0.15
        + cached_tokens / 1_000_000 * 0.075
        + completion_tokens / 1_000_000 * 0.60
    )

下面是一个可运行调用，如果 Groq 返回缓存用量，就打印出来：

import os
from openai import OpenAI

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

STATIC_POLICY = """
You are an internal code review assistant.
Always check correctness, security, performance, and migration risk.
Return JSON with keys: summary, risks, suggested_patch.
"""

def review(diff: str):
    response = client.chat.completions.create(
        model="openai/gpt-oss-120b",
        messages=[
            {"role": "system", "content": STATIC_POLICY},
            {"role": "user", "content": diff},
        ],
        response_format={"type": "json_object"},
    )

    usage = response.usage
    details = getattr(usage, "prompt_tokens_details", None)
    cached = getattr(details, "cached_tokens", 0) if details else 0

    print("prompt_tokens:", usage.prompt_tokens)
    print("cached_tokens:", cached)
    print("completion_tokens:", usage.completion_tokens)
    print("estimated_cost_usd:", groq_gpt_oss_120b_cost(
        usage.prompt_tokens,
        cached,
        usage.completion_tokens,
    ))

    return response.choices[0].message.content

Groq 的缓存文档显示 cached_tokens 位于 usage.prompt_tokens_details 下，并将缓存命中率定义为 cached_tokens / prompt_tokens × 100%（Groq 提示缓存）。不要假设每第二次请求都会更便宜。精确前缀很重要。

单独统计工具调用

如果你启用了内置工具，token 价格并不是全部账单。Groq 的定价页面将 GPT-OSS 的 Built-In Tools 单独列出：Browser Search basic search 为每 1000 次请求 5 美元，Browser Search visit website 为每 1000 次请求 1 美元，Code Execution Python 为每小时 0.18 美元（Groq 定价）。

这会改变你设计智能体的方式。每条用户消息都调用一次搜索的客服机器人，其成本形态不同于只使用提示 token 的摘要器。缓存有助于重复的工具 schema，但不会让外部工具调用免费。

在复制粘贴 OpenAI 代码之前，也要检查兼容性。Groq 的 OpenAI 兼容性文档列出了可能返回 400 的不受支持字段，包括 logprobs、logit_bias、top_logprobs、messages[].name，以及非 1 的 n 值（Groq OpenAI 兼容性）。Groq 还表示 temperature=0 会被转换为 1e-8。

一个安全的最小请求如下：

response = client.chat.completions.create(
    model="openai/gpt-oss-120b",
    temperature=0.2,
    messages=[
        {"role": "system", "content": "Be precise. If unsure, say so."},
        {"role": "user", "content": "Explain this stack trace and suggest a fix: ..."},
    ],
)

避免在一个 commit 里迁移整个应用。把 provider 设置放到环境变量后面：

LLM_BASE_URL=https://api.groq.com/openai/v1
LLM_API_KEY=$GROQ_API_KEY
LLM_MODEL=openai/gpt-oss-120b

然后把它们接入 SDK：

client = OpenAI(
    api_key=os.environ["LLM_API_KEY"],
    base_url=os.environ["LLM_BASE_URL"],
)

response = client.chat.completions.create(
    model=os.environ["LLM_MODEL"],
    messages=[{"role": "user", "content": "Summarize this incident report."}],
)

一个实用的多 provider 退路

如果你要把它接入生产环境，不要把 provider 假设硬编码到整个代码库里。把 base_url、api_key 和 model 放在配置里。这样 Groq 很容易测试，也能让 provider 路由变得平淡无奇。

对于想要用一个 OpenAI 兼容端点调用 Claude、GPT 和 Gemini 的团队，onehop 是简单路径：把 base URL 改为 https://api.onehop.ai/v1。它兼容 OpenAI/Anthropic，价格低于一方官方，新账号可获得 10 美元免费额度，且无需绑卡。

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ONEHOP_API_KEY"],
    base_url="https://api.onehop.ai/v1",
)

response = client.chat.completions.create(
    model=os.environ["ONEHOP_MODEL"],
    messages=[
        {"role": "user", "content": "Compare this API design against common REST mistakes."}
    ],
)

print(response.choices[0].message.content)

当你明确需要快速的 GPT-OSS 推理以及 Groq 的工具/缓存栈时，使用 Groq。当你希望在 Claude、GPT、Gemini 和其他托管模型之间拥有统一集成面，且无需重写客户端代码时，使用 onehop。你可以在 onehop 上调用 Claude 和其他模型，或注册领取 10 美元免费额度。

生产检查清单

上线前，执行这份检查清单：

• 固定模型 ID：质量优先用 openai/gpt-oss-120b，降低成本用 openai/gpt-oss-20b。
• 将稳定的提示部分放在前面，以便 Groq 复用缓存前缀。
• 为每个请求记录 prompt_tokens、cached_tokens 和 completion_tokens。
• 为 Browser Search、Visit Website 和 Code Execution 增加单独核算。
• 在将流量路由到 Groq 之前，移除不受支持的 OpenAI 参数。
• 保持 base_url 可配置，这样你可以在不改业务逻辑的情况下测试 Groq、一方 API 或 onehop。

整个迁移可以只改一行。可靠的迁移则是三行加核算：base URL、模型 ID 和成本遥测。从这里开始，然后再决定在应用的每条路径上，120B 的质量是否值得对应的输出 token 开销。如果你希望用同样的 base-URL 模式访问更广泛的模型，可以在 onehop 上调用 Claude 和其他模型，并注册领取 10 美元免费额度。