Fireworks AI

Fireworks AI 为生成式 AI 模型目录提供托管推理服务。应用通过稳定的 AISIX 别名调用所选模型，网关则保管 Fireworks 凭证。

准备工作

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

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

使用 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"

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

由于 Fireworks AI 提供 OpenAI 兼容 API，AISIX 会通过 openai 适配器连接，并使用 Fireworks API 根地址作为 api_base。

创建服务提供方密钥

创建用于存储 Fireworks 凭证和 API 根地址的服务提供方密钥，并允许其进入该环境：

# 请替换为实际值
export FIREWORKS_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": "fireworks-prod",
    "provider": "fireworks-ai",
    "api_key": "'"${FIREWORKS_API_KEY}"'",
    "api_base": "https://api.fireworks.ai/inference/v1",
    "allowed_environments": ["'"${ENV_ID}"'"]
  }' | jq -r '.provider_key.id')

echo "$PROVIDER_KEY_ID"

❶ provider 为目录服务提供方 ID fireworks-ai。连字符是该标识符的一部分；仅使用 fireworks 会被拒绝并返回 400 INVALID_REQUEST。

❷ api_key 存储 Fireworks API Key。其行为遵循服务提供方密钥中的凭证处理方式。

❸ api_base 指向 Fireworks 推理 API。/inference 路径段不可省略：Fireworks 在 https://api.fireworks.ai/inference/v1 下提供 OpenAI 兼容推理路由，而用于列出和创建 Fireworks API Key 的账户管理 REST API 位于 https://api.fireworks.ai/v1。删除 /inference 会让服务提供方密钥指向错误的 API 接口。

AISIX 会把端点路径追加到 api_base，因此请使用 API 根地址，末尾不要包含 /chat/completions。追加端点路径前会移除末尾斜杠，因此 https://api.fireworks.ai/inference/v1/ 和 https://api.fireworks.ai/inference/v1 的解析结果相同。

此服务提供方的 api_base 可选。省略时，AISIX Cloud Admin API 会填入 https://api.fireworks.ai/inference/v1。显式设置该值可以在资源上直观显示上游根地址。Fireworks 专用部署使用相同的推理根地址；如需更改目标，请将 model_name 指向 accounts/<ACCOUNT_ID>/deployments/<DEPLOYMENT_ID>。

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

创建模型

Fireworks 文本模型资源名称是完全限定的账户路径，而不是简单名称。由 Fireworks 发布的 Serverless 文本模型使用 accounts/fireworks/models/<name> 格式，例如 accounts/fireworks/models/gpt-oss-120b。对于此 Chat 模型，gpt-oss-120b 这样的扁平 OpenAI 风格名称无效。

其他 Fireworks 推理 API 可能使用不同的模型 ID 形式。例如 Embedding 指南使用 fireworks/qwen3-embedding-8b。请使用相应端点和模型文档中的准确标识符，不要强制将每个 ID 写成 accounts/... 形式。

请从 Fireworks 模型概览复制完整标识符，不要手动拼接。部分目录条目会将 models 路径段替换为 routers，自行部署的模型则在第一个路径段中使用你自己的账户名称。

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

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": "fireworks-gptoss-prod",
    "model_name": "accounts/fireworks/models/gpt-oss-120b",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }' | jq -r '.model.id')

echo "$MODEL_ID"

❶ display_name 是调用方在 model 中发送的别名。调用方不会看到该账户路径。

❷ model_name 是 Fireworks 模型 ID，例如 accounts/fireworks/models/gpt-oss-120b。

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

创建调用方 API Key

创建可访问该模型别名的调用方 API Key。API 会生成密钥值，并且只返回一次明文：

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

echo "$AISIX_API_KEY"

allowed_models 值通过模型 ID 引用模型。明文密钥只在此响应中返回，请安全保存。

新资源会自动投射到已关联的网关。

使用开源 AISIX 网关配置

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

export FIREWORKS_API_KEY="YOUR_PROVIDER_API_KEY"
export CALLER_API_KEY="YOUR_CALLER_API_KEY"

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

resources.yaml
_format_version: "1"

provider_keys:
  - display_name: "fireworks-prod"
    provider: "fireworks-ai"
    adapter: "openai"
    api_key: ${FIREWORKS_API_KEY}
    api_base: "https://api.fireworks.ai/inference/v1"
    request:
      param_renames:
        max_completion_tokens: max_tokens

models:
  - display_name: "fireworks-gptoss-prod"
    provider: "fireworks-ai"
    model_name: "accounts/fireworks/models/gpt-oss-120b"
    provider_key: "fireworks-prod"

api_keys:
  - display_name: "fireworks-caller"
    key_env: CALLER_API_KEY
    allowed_models:
      - "fireworks-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": "fireworks-gptoss-prod",
    "messages": [
      {
        "role": "user",
        "content": "Say hello from Fireworks AI."
      }
    ]
  }'

网关会返回 OpenAI 兼容响应，并回显面向调用方的别名 fireworks-gptoss-prod。如果请求失败，请检查服务提供方密钥的 api_key、api_base 中的 /inference/v1 路径，以及 model_name 中完整的 accounts/... 模型 ID。

了解 Token 限制参数改写

Fireworks 文档将 max_tokens 作为其 Chat Completions 路由的输出限制参数，而当前 OpenAI SDK 和许多 Agent 框架会发送 max_completion_tokens。AISIX Cloud 通过 fireworks-ai 目录条目的内置请求覆盖项处理该差异。开源 AISIX 网关不会自行添加该目录覆盖项，因此 resources.yaml 示例显式配置相同重命名。

配置该改写后，有以下三项重要影响：

调用方无需使用 Fireworks 专用代码路径。发送 max_completion_tokens 的客户端到达 Fireworks 时，max_tokens 会设置为相同的值。
如果同一个请求同时包含这两个字段，max_completion_tokens 的值会替换 max_tokens。较新的字段优先，因为它更可能是调用方有意设置的值。
重命名适用于此服务提供方密钥所服务的每个标准化路由的出站正文，而不仅是 Chat Completions。透传路由是例外，因为它会原样中继正文；在该路由上请发送 Fireworks 预期的字段名称。

对于省略该字段的请求，Fireworks 会应用自己的默认输出限制，因此长文本生成应设置显式限制。当前参数参考请参阅 Querying text models。

警告

服务提供方密钥上提供的 request 配置块会替换内置配置块，而不是与其合并。如果为此服务提供方密钥添加自己的请求覆盖项，请同时重新声明 param_renames，否则该改写将停止应用：

{
  "request": {
    "param_renames": {
      "max_completion_tokens": "max_tokens"
    },
    "default_headers": {
      "X-Team": "platform"
    }
  }
}

对于开源 AISIX 网关，添加其他请求设置时请保留该重命名：

    request:
      param_renames:
        max_completion_tokens: max_tokens
      default_headers:
        X-Team: platform

完整的覆盖配置结构请参阅服务提供方专用覆盖项。

使用推理模型

Fireworks 提供两种互斥的推理控制方式，每种方式的支持情况取决于具体模型：

reasoning_effort，可接受的推理强度因模型而异，包括 low、medium 和 high。
thinking 对象，其中 type 设置为 enabled，且 budget_tokens 至少为 1024。

请求不能同时设置两者。AISIX 会将自己未建模的顶层请求字段原样转发到上游，因此任一种控制项都能不经修改地到达 Fireworks：

{
  "model": "fireworks-gptoss-prod",
  "messages": [{ "role": "user", "content": "Plan a cache invalidation strategy." }],
  "reasoning_effort": "medium"
}

Fireworks 通常在 reasoning_content 中返回推理输出，该字段已经是 AISIX 的规范字段，但部分模型会改在 content 中返回。因此，此服务提供方不需要 response.reasoning_field 覆盖项：对于非流式响应，AISIX 会将 reasoning_content 保留为 choices[0].message.reasoning_content；对于流式响应，则保留为 delta.reasoning_content。

对于在工具调用间交错推理的模型，请保留完整的助手 reasoning_content，并在下一次工具调用请求中发送助手消息时包含它。AISIX 会保留字段，但不会管理或重放应用对话状态。请查看 Reasoning，了解所选模型的控制项和重放要求。

选择转换格式或 Fireworks 原生格式

Fireworks 提供原生 Responses API和兼容 Anthropic 的 Messages API。fireworks-ai 目录服务提供方仍使用 openai 适配器，因此规范化 AISIX 路由会通过 Chat Completions 进行转换，而非调用这些原生 API。

配置和路由	上游行为
目录别名调用 `/v1/responses`	使用基于 Chat 的 AISIX Responses 桥接。Fireworks 原生状态，包括 `previous_response_id`、已存储响应和服务器执行工具，无法通过桥接使用。
`/passthrough/fireworks-ai/responses`	调用 Fireworks 原生 Responses API。请使用 Fireworks 模型 ID，而非 AISIX 别名。Fireworks 默认存储原生响应；不需要持久化和续接时请发送 `store: false`。
目录别名调用 `/v1/messages`	AISIX 将 Anthropic 格式请求转换为 Chat Completions，不会调用 Fireworks 原生 Messages API。
`/passthrough/fireworks-ai/messages`	使用原样请求和响应体调用 Fireworks 原生兼容 Anthropic 的 Messages API。请使用 Fireworks 模型 ID，而非 AISIX 别名。
使用 `adapter: anthropic` 和 `api_base: https://api.fireworks.ai/inference` 的独立 BYO 服务提供方密钥	使规范化 `/v1/messages` 流量可调用 Fireworks 原生 Messages 路由，仍受其 Anthropic 兼容性限制。

目录服务提供方密钥不能覆盖适配器，因此 Anthropic 适配器请使用独立的自带端点服务提供方密钥。本页的 /passthrough/fireworks-ai 路径假定一条透传路由认领该前缀，target_url 设为 Fireworks 推理 API 根地址；在调用方 Key 的 allowed_routes 上授予路由名称。透传路由不会重写 AISIX 模型别名。AISIX 会从每个请求中检测 Chat、Completions 和 Responses 信封，并记录受支持的用量字段。没有可识别载体字段的请求保持不透明：缓冲响应记录零 Token，而不透明 SSE 仍可记录顶层受支持的 usage 字段。

查看端点支持情况

Fireworks 支持的别名可用于下列路由。完整端点矩阵请参阅服务提供方兼容性。

路由	使用 `fireworks-ai` 服务提供方密钥时的行为
`/v1/chat/completions`	支持，包括 `stream: true`。
`/v1/completions`	对接受旧版基于 Prompt 的 Completions 格式的 Fireworks 模型提供支持。
`/v1/embeddings`	目标是 Fireworks Embedding 模型时支持。请使用 Embedding 指南中的端点特定模型 ID，例如 `fireworks/qwen3-embedding-8b`。
`/v1/responses`	通过基于 Chat 的 Responses 桥接支持，而非 Fireworks 原生 Responses API。没有 Chat 等价项的字段会被忽略。需要原生 Responses 语义时请使用 `/passthrough/fireworks-ai/responses`。
`/v1/messages`	通过转换为 Chat Completions 支持，而非 Fireworks 原生 Messages API。由于 Token 计数要求 `anthropic` 服务提供方，`/v1/messages/count_tokens` 不可用。
`/v1/rerank`	`fireworks-ai` 不在路由允许列表中，因此不支持。请通过 `/passthrough/fireworks-ai/rerank` 调用 Fireworks 原生重排 API，并发送端点特定模型 ID。
`/v1/audio/*`	不支持。Fireworks 未在此 API Base 下提供匹配的 OpenAI 兼容语音或转录路由；受支持的音频和视频输入通过多模态 Chat 模型发送。
`/v1/images/generations`	不支持。该路由要求模型配置的服务提供方为 `openai`。Fireworks 原生图片生成工作流只能通过 `/passthrough/fireworks-ai/workflows/...` 访问。
`/v1/videos`	不支持。该路由有自己的服务提供方允许列表，其中不包含 `fireworks-ai`。
`/passthrough/fireworks-ai/*`	通过已配置的透传路由可用于 AISIX 未建模的服务提供方原生端点。

在前缀匹配的透传路由上，AISIX 会将剩余路径拼接到路由的 target_url。由于 https://api.fireworks.ai/inference/v1 目标以 API 版本路径段结尾，以 v1/ 开头的透传路径会去重，因此 /passthrough/fireworks-ai/v1/<path> 和 /passthrough/fireworks-ai/<path> 都会解析为 https://api.fireworks.ai/inference/v1/<path>。以该目标为准的路由保持在推理 API 下，无法访问 https://api.fireworks.ai/v1/accounts/... 上的 Fireworks 账号或部署管理路由。

透传授权来自调用方 API Key 的 allowed_routes 列表——它必须授予路由名称；模型允许列表不管控这些路径。在 raw 路由上 Token 数和基于 Token 的成本保持为零，但调用方 Key 的请求数限制仍会生效。请参阅透传路由。

后续步骤

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

模型别名：为此别名配置路由、重试行为或成本元数据。
路由与故障转移：在 Fireworks AI 与另一个服务提供方之间执行故障转移。
服务提供方专用覆盖项：上游 API 与其适配器不同时，调整请求和响应格式。
服务提供方兼容性：查看支持的代理端点和服务提供方特有限制。

准备工作​

使用 AISIX Cloud 配置​

创建服务提供方密钥​

创建模型​

创建调用方 API Key​

使用开源 AISIX 网关配置​

验证服务提供方连接​

了解 Token 限制参数改写​

使用推理模型​

选择转换格式或 Fireworks 原生格式​

查看端点支持情况​

后续步骤​