版本：Dev

Groq

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

准备工作

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

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

使用 AISIX Enterprise 或 AISIX Cloud 配置

导出控制面连接信息：

# AISIX_CP 是 Admin API 基础 URL；应包含 /api，且不含尾部斜杠
# 本地 AISIX Enterprise 快速入门使用 http://localhost:8080/api
export AISIX_CP="YOUR_AISIX_CONTROL_PLANE_API_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"

为 Groq 支持的 Chat Completions 和原生 Responses 创建服务提供方密钥、模型别名和调用方 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",
    "apis": {
      "responses": {}
    },
    "allowed_environments": ["'"${ENV_ID}"'"]
  }'

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

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

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

❹ apis.responses 声明 Groq 在同一根地址提供 Responses API。这样，AISIX 就能使用 Groq 的原生请求和响应格式，而不必通过 Chat Completions 转换。

控制面当前保留了将 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"
    apis:
      responses: {}

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：

# AISIX_PROXY 不含尾部斜杠或端点路径
# 本地快速入门使用 http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_URL"

通过 AISIX 代理发送 Responses 请求：

curl -sS -X POST "$AISIX_PROXY/v1/responses" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "groq-gptoss-prod",
    "input": "Say hello from Groq."
  }'

AISIX 会将请求发送至 Groq 的原生 Responses 端点，在上游请求中把 AISIX 别名替换为配置的 Groq 模型 ID，并在响应中恢复该别名。如果请求失败，请检查服务提供方密钥凭证、API 根地址和 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`	由于本指南声明了 `apis.responses`，请求会发送到 Groq 原生 Responses API。Groq 目前将该 API 标记为 Beta，且并不支持 OpenAI Responses 的所有字段。如果没有此声明，AISIX 会使用基于 Chat 的 Responses 桥接。
`/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/rerank`	Groq 或这些 AISIX 路由的服务提供方规则不支持。

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

原生声明会在规范化的 AISIX 路由上保留模型别名重写和模型访问控制，因此 Groq Responses 不再需要单独的透传路由。对于 AISIX 未规范化、但位于同一 API 根地址下的其他 Groq 端点，可配置一条使用自选前缀并以 https://api.groq.com/openai/v1 为 target_url 的透传路由。请在调用方 Key 的 allowed_routes 中授予该路由名称，并发送上游模型 ID，因为透传不会重写别名。

后续步骤

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

模型别名：为此别名配置路由、重试行为或成本元数据。
路由和故障转移：在 Groq 和第二个服务提供方之间配置故障转移。
服务提供方特定覆盖项：当上游 API 与其适配器不同时，调整请求和响应形态。
服务提供方兼容性：查看支持的代理端点和服务提供方特定边界。

准备工作​

使用 AISIX Enterprise 或 AISIX Cloud 配置​

创建服务提供方密钥​

创建模型​

创建调用方 API Key​

使用开源 AISIX 网关配置​

验证服务提供方连接​

端点和兼容性边界​

后续步骤​