跳到主要内容

Groq

Groq 为一系列开放模型提供托管推理。AISIX 为应用提供稳定的模型别名和调用方密钥，同时将 Groq 凭证保留在网关中。

准备工作​

开始前，请准备以下内容：

  • 一套 AISIX 环境：
    • 对于 AISIX Cloud，需要一个已关联网关的环境和具有写入作用域的 Admin Token。对于 On-Premises，请按照 AISIX Cloud 快速入门操作。如需申请 Hybrid Cloud 访问权限，请联系 API7。
    • 对于开源 AISIX 网关，请准备本地 AISIX 安装，或使用开源 AISIX 网关快速入门中的 Docker 环境。配置网关以加载声明式资源文件。
  • 从 Groq 控制台获取的 Groq API Key。
  • curl.

使用 AISIX Cloud 配置​

导出 AISIX Cloud 连接信息：

# AISIX_CP 是 Admin API 基础 URL；应包含 /api，且末尾不带斜杠
# 本地 On-Premises 快速入门使用 http://localhost:8080/api
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_API_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"

为 Groq 支持的 chat-completions 路由创建服务提供方密钥、模型别名和调用方 API Key。

由于 Groq 提供兼容 OpenAI 的 API，AISIX 通过 openai 适配器连接，并将 Groq API 根地址用作 api_base。

创建服务提供方密钥​

创建用于存储 Groq 凭证和 API 根地址的服务提供方密钥：

# 请替换为实际值
export GROQ_API_KEY="YOUR_PROVIDER_API_KEY"

curl -sS -X POST "$AISIX_CP/provider_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "groq-prod",
    "provider": "groq",
    "api_key": "'"${GROQ_API_KEY}"'",
    "api_base": "https://api.groq.com/openai/v1",
    "allowed_environments": ["'"${ENV_ID}"'"]
  }'

❶ provider 为 groq。AISIX Cloud Admin API 会从目录服务提供方推导适配器；适配器字段仅接受用于 BYO 服务提供方密钥。

❷ api_key 存储 Groq API Key。该值在存储前加密，读取端点绝不会返回它。它遵循服务提供方密钥中的凭证处理行为。

❸ api_base 已包含 /openai/v1 路径。AISIX 会向其追加 /chat/completions。对于此目录服务提供方，该字段是可选的，因为省略时 AISIX Cloud Admin API 会填入相同的值。示例显式设置该字段，使上游根地址在资源中保持可见。

AISIX Cloud 当前保留了将 max_completion_tokens 重命名为 max_tokens 的旧版兼容规则。Groq 仍接受 max_tokens，但现已弃用该字段，建议使用 max_completion_tokens。

下方开源配置有意省略此覆盖设置，以便当前客户端直接发送 max_completion_tokens。

从响应中复制 provider_key.id 值（例如使用 jq -r '.provider_key.id'），并将其导出：

export PROVIDER_KEY_ID="YOUR_PROVIDER_KEY_ID"

创建模型​

Groq 模型的可用性会随时间变化。创建模型别名前，请在 Groq 模型列表中查看当前模型 ID。

创建调用方将在请求中发送的模型别名：

curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "groq-gptoss-prod",
    "model_name": "openai/gpt-oss-120b",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }'

❶ display_name 是调用方在 model 中发送的别名。

❷ model_name 是 Groq 模型 ID，例如 openai/gpt-oss-120b。

❸ provider_key_id 将别名关联到 Groq 服务提供方密钥。

保存响应中的 model.id 值：

export MODEL_ID="YOUR_MODEL_ID"

创建调用方 API Key​

创建可访问该模型别名的调用方 API Key 资源。网关会生成密钥值，并仅在响应中返回一次明文：

curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/api_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "groq-caller",
    "allowed_models": ["'"${MODEL_ID}"'"]
  }'

allowed_models 的值必须引用已保存的模型 ID。从响应中复制 plaintext 值（它只会显示一次），并将其导出为调用方密钥：

export AISIX_API_KEY="YOUR_CALLER_API_KEY"

写入后，配置会自动投射到已关联的网关。

使用开源 AISIX 网关配置​

导出上游凭证，并选择应用将发送给网关的调用方 API Key：

export GROQ_API_KEY="YOUR_PROVIDER_API_KEY"
export CALLER_API_KEY="YOUR_CALLER_API_KEY"

为该服务提供方创建完整的声明式资源文件：

resources.yaml
_format_version: "1"

provider_keys:
  - display_name: "groq-prod"
    provider: "groq"
    adapter: "openai"
    api_key: ${GROQ_API_KEY}
    api_base: "https://api.groq.com/openai/v1"

models:
  - display_name: "groq-gptoss-prod"
    provider: "groq"
    model_name: "openai/gpt-oss-120b"
    provider_key: "groq-prod"

api_keys:
  - display_name: "groq-caller"
    key_env: CALLER_API_KEY
    allowed_models:
      - "groq-gptoss-prod"

如果 AISIX 安装在本地，请在加载前验证文件：

aisix validate --resources resources.yaml

验证后，在网关进程环境中提供文件引用的环境变量，再启动网关。仅当这些变量已经可供进程使用时，才重新加载现有网关；否则，请使用更新后的环境重启网关。

如果使用 Docker，请调整开源 AISIX 网关快速入门中的验证和启动命令。挂载此 resources.yaml 文件，并在两条命令中使用 -e 传入它引用的每个环境变量。资源加载后，准备下文共用的验证请求：

export AISIX_API_KEY="$CALLER_API_KEY"

验证服务提供方连接​

导出 AISIX 网关 Origin：

# 本地快速入门使用 http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_ORIGIN"

通过 AISIX 代理发送 Chat Completions 请求：

curl -sS -X POST "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "groq-gptoss-prod",
    "messages": [
      {
        "role": "user",
        "content": "Say hello from Groq."
      }
    ]
  }'

网关返回兼容 OpenAI 的响应，其中会回显面向调用方的别名 groq-gptoss-prod。如果请求失败，请检查服务提供方密钥的 api_key、api_base，以及 model_name 中的 Groq 模型 ID。

端点和兼容性边界​

Groq 在很大程度上兼容 OpenAI，但并非完全兼容。AISIX 会转发额外的 Chat 请求字段，而非过滤它们，因此 Groq 会实施自身的模型和参数规则。Groq 兼容性指南指出，logprobs、logit_bias、top_logprobs 和 messages[].name 会返回 400，且 n 必须为 1。Groq API 参考还将 frequency_penalty、presence_penalty、metadata 和 store 标记为不支持。

temperature 为 0 时，上游会将其转换为 1e-8。对于音频转录和翻译，Groq 不支持 vtt 或 srt 输出。最新列表请参阅 Groq 的 OpenAI 兼容性指南。

路由使用 groq 服务提供方密钥时的行为
/v1/chat/completions支持，包括流式传输。AISIX 会转发 tools、response_format 和 reasoning_effort 等字段；实际支持情况仍取决于所选 Groq 模型。示例 GPT-OSS 模型支持工具使用、结构化输出，以及 low、medium 或 high 推理力度。
/v1/responses通过基于 Chat 的 Responses 桥接支持，并非 Groq 原生 Beta Responses API。没有 Chat 等价项的字段和响应项不会保留。
/v1/messages通过转换为 Chat 支持，并非原生 Groq Messages API。因为配置的服务提供方不是 Anthropic，无法使用 /v1/messages/count_tokens。
/v1/audio/transcriptions、/v1/audio/translations 和 /v1/audio/speech支持，但需要为当前 Groq 语音转文本或文本转语音模型分别创建别名。配置音频别名前，请检查 Groq 模型列表。
/v1/files 和 /v1/batches通过 Groq 兼容 OpenAI 的文件和批处理 API 支持。按照批处理、文件和微调中的说明，使用 Groq 别名作为路由模型。Groq 对批处理应用折扣价格，但 AISIX 使用别名配置的同步价格估算批处理成本；请勿将该估算视为服务提供方账单。
/v1/fine_tuning/jobs与 Groq 微调不兼容。AISIX 在 api_base 下转发 OpenAI /fine_tuning/jobs 协议，而 Groq 的封闭 Beta API 使用 /openai/v1 根地址以外的 /v1/fine_tunings，且请求体不同。
/v1/embeddings 和 /v1/completions不支持，因为 Groq 不提供这些上游端点。
/v1/images/generations、/v1/videos 和 /v1/rerankGroq 或这些 AISIX 路由的服务提供方规则不支持。

规范化 Chat 响应会保留标准内容、工具调用、推理文本和 Token 总数。AISIX 会将 Groq 原生 message.reasoning 值返回为 reasoning_content，但不会保留 x_groq、用量时序详情、usage_breakdown，以及未建模的引用和注解字段等 Groq 特定元数据。

要使用 Groq 原生 Responses 协议，请调用 /passthrough/groq/responses。该路径相对于配置的 https://api.groq.com/openai/v1 基础地址。请发送确切的 Groq 模型 ID，因为透传不会重写 AISIX 别名。除非被防护栏阻止，否则 AISIX 会原样中继服务提供方响应体。透传请求记录的 Token 为零，因此不提供规范化 Token 或成本核算。配置的基础地址也意味着通用透传无法访问 Groq 同级的 /v1/fine_tunings API。

后续步骤​

现在，你已将 AISIX 连接到 Groq，并验证了模型别名。接下来可阅读以下指南：