Cerebras

Cerebras Inference 在 Cerebras 推理系统上托管开放权重模型。AISIX 将这些模型置于统一的 OpenAI 兼容 API 之后，并集中管理上游凭证、调用方访问权限、限流和用量核算。

准备工作

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

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

使用 AISIX Cloud 配置

导出 AISIX Cloud 连接信息：

# AISIX_CP 是 Admin API 基础 URL；应包含 /api，且不含尾部斜杠
# 本地私有化部署快速入门使用 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"

为 Cerebras 支持的 Chat Completions 路由创建服务提供方密钥、模型别名和调用方 API Key。

Cerebras API 与 OpenAI 兼容，因此 AISIX 通过 openai 适配器连接，并使用 Cerebras API 根路径作为 api_base。

创建服务提供方密钥

创建用于存储 Cerebras 凭证和 API 根路径的服务提供方密钥：

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

PROVIDER_KEY_ID=$(curl -sS -X POST "$AISIX_CP/provider_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "cerebras-prod",
    "provider": "cerebras",
    "api_key": "'"${CEREBRAS_API_KEY}"'",
    "api_base": "https://api.cerebras.ai/v1",
    "allowed_environments": ["'"${ENV_ID}"'"]
  }' | jq -r '.provider_key.id')

echo "$PROVIDER_KEY_ID"

❶ provider 为 cerebras。AISIX Cloud Admin API 从目录服务提供方派生适配器；adapter 字段仅接受 BYO 服务提供方密钥。

❷ api_key 存储 Cerebras API Key。Cerebras 使用 HTTP Bearer 身份认证，这正是 openai 适配器已经发送的形式。该值遵循服务提供方密钥中的凭证处理行为。

❸ api_base 为 https://api.cerebras.ai/v1，与 Cerebras 为 OpenAI 客户端库记录的 baseURL 根路径相同。它已包含 /v1 路径，因此 AISIX 会直接向其追加 /chat/completions 等端点路径。对于 cerebras 目录服务提供方，此字段为可选项；省略时 AISIX Cloud Admin API 会填入相同的值。示例仍显式设置该字段，使配置中始终可以看到每个密钥指向的根路径。

该命令会把返回的服务提供方密钥 ID 保存到 PROVIDER_KEY_ID。

创建模型

Cerebras 模型 ID 是不带厂商前缀的裸标识符，即使权重来自其他厂商也是如此。OpenAI 开放权重模型在 Cerebras 上为 gpt-oss-120b，Google 模型为 gemma-4-31b。创建别名前，请在 Cerebras 模型目录中查看当前列表；该目录较短，并会随模型的新增和退役而轮换。当前 ID 包括 gpt-oss-120b、gemma-4-31b 和 zai-glm-4.7。

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

MODEL_ID=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "cerebras-gptoss-prod",
    "model_name": "gpt-oss-120b",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }' | jq -r '.model.id')

echo "$MODEL_ID"

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

❷ model_name 是 Cerebras 模型 ID，例如 gpt-oss-120b 或 gemma-4-31b。不要从托管相同权重的其他服务提供方沿用 openai/gpt-oss-120b 等带前缀的 ID。

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

创建调用方 API Key

创建能够访问该模型别名的调用方 API Key。明文密钥由服务器生成，并只在创建响应中返回一次，因此请立即保存：

AISIX_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": "cerebras-caller",
    "allowed_models": ["'"${MODEL_ID}"'"]
  }' | jq -r '.plaintext')

echo "$AISIX_API_KEY"

allowed_models 值必须引用上一步保存的模型 ID。写入后，配置会自动投射到已关联的网关。

使用开源 AISIX 网关配置

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

export CEREBRAS_API_KEY="YOUR_PROVIDER_API_KEY"
export CALLER_API_KEY="YOUR_CALLER_API_KEY"

对于新网关，请使用此完整资源文件。对于现有网关，请将这些条目合并到其当前文件中，并保留其他资源：

resources.yaml

_format_version: "1"

provider_keys:
  - display_name: "cerebras-prod"
    provider: "cerebras"
    adapter: "openai"
    api_key: ${CEREBRAS_API_KEY}
    api_base: "https://api.cerebras.ai/v1"

models:
  - display_name: "cerebras-gptoss-prod"
    provider: "cerebras"
    model_name: "gpt-oss-120b"
    provider_key: "cerebras-prod"

api_keys:
  - display_name: "cerebras-caller"
    key_env: CALLER_API_KEY
    allowed_models:
      - "cerebras-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 代理发送 Chat Completions 请求：

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

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

发送 Token 限制

Cerebras 遵循当前 OpenAI 参数命名，并在 Chat Completions 中使用 max_completion_tokens 表示生成 Token 上限。因此 AISIX 服务提供方目录中的 Cerebras 条目不会配置参数重命名，AISIX 会把调用方发送的 max_completion_tokens 原样转发给 Cerebras。其他一些 OpenAI 兼容上游仍要求旧的 max_tokens 名称，并为其配置了重命名，因此可用于 Cerebras 的请求体不一定能直接用于每个 openai 适配器服务提供方。

如果现有客户端发送旧的 max_tokens 名称，而你需要以上游当前名称传递它，请在服务提供方密钥上添加重命名：

{
  "request": {
    "param_renames": {
      "max_tokens": "max_completion_tokens"
    }
  }
}

该重命名适用于引用此服务提供方密钥的每个模型。请参阅服务提供方特定覆盖项。

控制推理强度

Cerebras 接受 Chat Completions 正文顶层的标准 OpenAI reasoning_effort 参数。AISIX 不会剥离无法识别的顶层参数，因此该值会原样到达上游：

{
  "model": "cerebras-gptoss-prod",
  "messages": [
    {
      "role": "user",
      "content": "Plan a three-step migration."
    }
  ],
  "reasoning_effort": "low"
}

接受的值因模型而异：

模型	reasoning_effort 值	默认值
gpt-oss-120b	low, medium, high	medium
gemma-4-31b	none, low, medium, high	none
zai-glm-4.7	使用 none 禁用推理	启用推理

请在 Cerebras 推理文档中确认所配置模型接受的值，因为某个模型接受的值可能会被另一模型拒绝。

Cerebras 目录条目未设置推理字段覆盖项，因此 AISIX 会保留上游已在规范 reasoning_content 字段中返回的流式和非流式推理。如果 Cerebras 模型在其他 delta 路径上传输推理，请在服务提供方密钥上设置 response.reasoning_field。

路由延迟敏感流量

在按观测延迟对目标排序的路由模型中，Cerebras 别名是一个实用目标。创建 strategy 设为 least_latency 的路由模型，并将 Cerebras 别名与回退目标一同列出。AISIX 按近期上游延迟的移动平均值对目标排序，流式请求使用首 Token 时间，并在排序前探测尚无样本的目标。请参阅按成本、延迟或负载路由。

端点支持

Cerebras 是仅提供推理的上游，因此只有部分代理界面适用于 Cerebras 支持的别名。

路由	Cerebras 别名的行为
/v1/chat/completions	支持，包括 stream: true。
/v1/responses	通过聊天适配器路径上的 Responses 桥接提供支持。没有对应聊天语义的 OpenAI Responses 专用字段会被忽略。
/v1/messages	通过转换支持 Anthropic 形态的调用方。/v1/messages/count_tokens 的 Token 计数要求使用 Anthropic 支持的模型。
/v1/embeddings	不可用。Cerebras 提供语言模型，但不发布 Embedding 模型，因此请把 Embedding 路由到其他服务提供方。请参阅 Embedding。
/v1/images/generations	拒绝。该路由只接受服务提供方为 openai 的模型。
/v1/rerank	拒绝。该路由只接受 openai、cohere 和 jina 服务提供方值。
/v1/videos	拒绝。该路由仅接受自身服务提供方允许列表，其中不包含 cerebras。
/passthrough/cerebras/*	通过已配置的透传路由可用：路由认领此前缀，target_url 设为 https://api.cerebras.ai/v1 根地址；在调用方 Key 的 allowed_routes 上授予该路由。服务提供方原生路径以有限的网关标准化中继。

后续步骤

你已将 AISIX 接入 Cerebras，并验证了模型别名。接下来可以阅读：

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