Groq

本指南将 AISIX AI 网关连接到 Groq。应用只需要调用 AISIX，并使用调用方 API Key 认证；上游服务提供方密钥、模型别名、模型允许列表、限流和用量统计由 AISIX 管理。

Groq 使用 OpenAI 兼容协议。请使用 openai adapter，并将 api_base 指向 Groq 的 OpenAI 兼容端点。

当你不希望应用直接持有 Groq 密钥，或者希望在多个服务提供方之间统一认证、路由和策略控制时，可以使用这种配置。

准备工作

请先准备以下内容：

一个 Admin API 位于 :3001、代理 API 位于 :3000 的 AISIX 网关。
网关 config.yaml 中的 Admin Key。
Groq API Key，以及需要暴露给调用方的模型 ID，例如 llama-3.3-70b-versatile。

支持的能力

具体端点支持取决于服务提供方和 adapter。常见路径如下：

端点	支持情况	说明
`/v1/chat/completions`	支持	主要聊天入口，支持非流式和流式请求。
`/v1/embeddings`	视服务提供方而定	需要上游和 adapter 支持 embeddings。
`/v1/responses`	视服务提供方而定	按服务提供方兼容性转发或转换。
`/v1/images/generations`	视服务提供方而定	需要服务提供方支持图像生成。
`/v1/audio/*`	视服务提供方而定	需要服务提供方支持对应音频能力。
`/v1/rerank`	视服务提供方而定	仅限 rerank 允许列表中的服务提供方。

逐端点规则请参见服务提供方兼容性。

配置 Groq 上游

创建服务提供方密钥、模型别名和调用方 API Key。

创建服务提供方密钥

export AISIX_ADMIN_KEY="YOUR_ADMIN_KEY"
export GROQ_API_KEY="YOUR_PROVIDER_API_KEY"

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/provider_keys" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "groq-prod",
    "provider": "groq",
    "adapter": "openai",
    "secret": "'"${GROQ_API_KEY}"'"
  }'

如果该服务提供方不是 OpenAI 原生上游，请按服务提供方文档显式设置 api_base。secret 会保存上游 API Key，并遵循服务提供方凭证中的处理规则。

复制返回的服务提供方密钥 ID。

创建模型别名

export PROVIDER_KEY_ID="YOUR_PROVIDER_KEY_ID"

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/models" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "groq-llama-prod",
    "provider": "groq",
    "model_name": "llama-3.3-70b-versatile",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }'

display_name 是调用方在 model 中发送的别名，model_name 是 Groq 的真实模型 ID，provider_key_id 将该模型别名绑定到上一步创建的上游凭证。

创建调用方 API Key

export AISIX_API_KEY="YOUR_CALLER_API_KEY"

CALLER_KEY_HASH=$(printf '%s' "${AISIX_API_KEY}" | shasum -a 256 | awk '{print $1}')

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/apikeys" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "key_hash": "'"${CALLER_KEY_HASH}"'",
    "allowed_models": ["groq-llama-prod"]
  }'

allowed_models 必须包含调用方允许使用的模型别名。

验证上游

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

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

网关会返回 OpenAI 兼容响应，并在响应中保留调用方面向的模型别名 groq-llama-prod。如果 AISIX 返回上游认证错误，请检查服务提供方密钥的 secret 和 api_base。

行为与限制

调用方 API Key 会以 key_hash 形式保存，AISIX 不保存明文调用方密钥。服务提供方密钥在 Admin API 列表响应中会显示为 ***。

OpenAI SDK 客户端可以将 base URL 指向 http://127.0.0.1:3000/v1，并把 API Key 设置为调用方 API Key。更多信息请参见 OpenAI SDK 快速开始。

下一步

模型别名：为模型添加路由、成本元数据和限流。
服务提供方兼容性：查看逐端点支持规则。
调用方 API Key：管理调用方凭证和模型访问范围。

准备工作​

支持的能力​

配置 Groq 上游​

创建服务提供方密钥​

创建模型别名​

创建调用方 API Key​

验证上游​

行为与限制​

下一步​