Hugging Face

Hugging Face Inference Providers 会将请求路由到由多个推理服务商提供的开放权重模型。AISIX 将该目录置于统一的 OpenAI 兼容 API 之后，并由网关管理凭证、调用方访问权限、限流和用量核算。

Hugging Face 与单一服务商上游不同，它使用路由层：由请求中的模型 ID 而不是 URL 决定哪个推理服务商提供该模型。

本指南介绍共享的 Inference Providers 路由器。专用 Hugging Face Inference Endpoint 具有独立的部署主机名，无法通过路由器 URL 访问。请改为将该部署配置成私有 OpenAI 兼容端点。

准备工作

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

一套 AISIX 环境：
- 对于 AISIX Cloud，需要一个已关联网关的环境和具备写入权限的 Admin Token。对于 On-Premises，请按照 AISIX Cloud 快速入门操作。如需申请 Hybrid Cloud 访问权限，请联系 API7。
- 对于开源 AISIX 网关，请准备本地 AISIX 安装，或使用开源 AISIX 网关快速入门中的 Docker 环境。配置网关以加载声明式资源文件。
在 Access Tokens 中创建、具备 Make calls to Inference Providers 权限的 Hugging Face Access Token。
curl 和 jq。

Hugging Face Access Token 是账户级凭证，而不是针对单个服务商的 API Key。一个 Token 可以授权调用路由器可选择的所有推理服务商，因此 AISIX 中的一个服务提供方密钥即可覆盖整个路由器目录。请将 Token 的权限限制为 Inference Providers，确保 AISIX 中存储的凭证不能同时读取或写入 Hub 仓库。

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

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

由于 Hugging Face 提供 OpenAI 兼容 API，AISIX 会通过 openai 适配器连接，并使用 Inference Providers 路由器作为 api_base。

创建服务提供方密钥

创建用于存储 Hugging Face Token 和路由器根地址的服务提供方密钥：

# 请替换为实际值
export HF_TOKEN="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": "huggingface-prod",
    "provider": "huggingface",
    "api_key": "'"${HF_TOKEN}"'",
    "api_base": "https://router.huggingface.co/v1",
    "allowed_environments": ["'"${ENV_ID}"'"]
  }' | jq -r '.provider_key.id')

echo "$PROVIDER_KEY_ID"

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

❷ api_key 存储 Hugging Face Access Token。其行为遵循服务提供方密钥中的凭证处理方式。

❸ api_base 是 Inference Providers 路由器的根地址。其主机为 router.huggingface.co，而不是某个模型专用的主机；/v1 是位于所有路由推理服务商之前的 OpenAI 兼容接口。AISIX 会追加端点路径，因此 Chat 路由会解析为 https://router.huggingface.co/v1/chat/completions。如果省略 api_base，AISIX Cloud 会从目录中填入相同的路由器 URL；显式设置该值可使资源内容自解释。

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

创建模型

Hugging Face 模型 ID 是 <org>/<model> 格式的 Hub 仓库 ID，不同发布方的大小写并不统一：openai/gpt-oss-120b 全部为小写，而 Qwen/Qwen3-235B-A22B-Thinking-2507 和 deepseek-ai/DeepSeek-V4-Pro 使用混合大小写。请从支持的模型列表原样复制 ID，不要手动输入；创建模型别名前，还应在该列表中确认模型当前仍在提供服务。

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

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

echo "$MODEL_ID"

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

❷ model_name 是 Hugging Face 模型 ID，例如 openai/gpt-oss-120b 或 deepseek-ai/DeepSeek-V4-Pro。AISIX 会将此字符串原样转发到路由器。

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

固定推理服务商

Hugging Face 接受模型 ID 上的可选后缀，用于控制由哪个推理服务商处理请求。该后缀是模型字符串的一部分，因此应设置在 model_name 中：

`model_name` 值	路由行为
`openai/gpt-oss-120b`	自动路由，默认选择当前可用且速度最快的推理服务商。
`openai/gpt-oss-120b:groq`	固定到指定的推理服务商。
`openai/gpt-oss-120b:cheapest`	按每个输出 Token 的价格路由到成本最低的服务商。
`openai/gpt-oss-120b:fastest`	路由到吞吐量最高的服务商。这是默认策略。
`openai/gpt-oss-120b:preferred`	按 Hugging Face Inference Providers 设置中配置的偏好顺序路由。

当前后缀语法请参阅 Hugging Face Chat Completion 文档。

后缀会改变延迟、价格以及实际运行模型的后端，因此请将固定服务商和自动路由的变体视为不同上游。请为每个变体创建一个模型别名，不要原地切换后缀，以确保每个别名的成本元数据、限流和用量记录仍然有明确含义。相关别名字段请参阅模型别名。

创建调用方 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": "huggingface-caller",
    "allowed_models": ["'"${MODEL_ID}"'"]
  }' | jq -r '.plaintext')

echo "$AISIX_API_KEY"

allowed_models 值必须引用上一步保存的模型 ID。

网关会自动获取新资源，无需重启。

使用开源 AISIX 网关配置

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

export HF_TOKEN="YOUR_PROVIDER_API_KEY"
export CALLER_API_KEY="YOUR_CALLER_API_KEY"

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

resources.yaml
_format_version: "1"

provider_keys:
  - display_name: "huggingface-prod"
    provider: "huggingface"
    adapter: "openai"
    api_key: ${HF_TOKEN}
    api_base: "https://router.huggingface.co/v1"

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

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

网关会返回 OpenAI 兼容响应，并回显面向调用方的别名 hf-gptoss-prod。如果请求失败，请检查服务提供方密钥的 api_key 和 api_base、model_name 中 Hub 仓库 ID 的精确大小写，以及 Token 是否具备 Inference Providers 权限。路由器可用性按模型而不是按账户确定，因此还需在支持的模型列表中确认该模型当前仍在提供服务。

控制推理输出

路由器上的推理模型在 Chat Completions 请求体中接受顶层 reasoning_effort 字段：

{
  "reasoning_effort": "low"
}

常见值包括 none、minimal、low、medium、high 和 xhigh，但是否支持、默认值以及哪些值有实际含义，取决于模型及为其提供服务的推理服务商。路由器没有记录统一的启用或禁用开关，也没有数字形式的推理预算字段，因此在依赖某项具体设置前，请在 Hugging Face Chat Completion 文档中确认模型接受的值。AISIX 会将该字段转发到路由器，而不进行解释。

AISIX 的 huggingface 目录条目没有 response.reasoning_field 覆盖项，因此 AISIX 会从规范的 delta.reasoning_content 路径读取流式推理内容，并将其保留在响应中。由于同一个 Hub 仓库 ID 可以由不同推理服务商提供，固定的服务商可能会在不同的 delta 路径下流式返回推理内容。此时，请在固定别名专用的服务提供方密钥上设置 response.reasoning_field，不要在其他所有别名都会继承的共享路由器服务提供方密钥上设置。

支持的代理路由

Hugging Face 服务提供方值会解析到 openai 适配器，该适配器决定由 huggingface 支持的别名可使用哪些路由：

Chat Completions。 /v1/chat/completions 是主要路由，并支持流式传输。
Responses。 /v1/responses 通过 AISIX Responses 桥接提供，因为只有服务提供方为 openai 的模型才适用 Responses 原样转发。桥接请求会到达路由器的 Chat Completions 路由。
Embeddings。 路由器不提供该功能。Hugging Face 将 OpenAI 兼容 /v1 接口记录为只提供 Chat Completion，并指引 Embedding 工作负载使用特定任务的推理客户端或专用部署。AISIX 会将 /v1/embeddings 转发到 https://router.huggingface.co/v1/embeddings，但路由器并不提供该路由。如需将 Embedding 置于网关之后，请将模型部署为 Hugging Face Inference Endpoint，并将其配置为私有 OpenAI 兼容端点。
服务提供方透传。 /passthrough/huggingface/<path> 会原样转发请求，并使用 Hugging Face Token 替换调用方密钥。由于 api_base 已以 /v1 结尾，AISIX 会移除重复的前导 v1 路径段，因此 /passthrough/huggingface/models 和 /passthrough/huggingface/v1/models 都会到达 https://router.huggingface.co/v1/models。请参阅服务提供方透传。
不可用。 图像生成和视频生成仅限其他服务提供方值，重排序路由则只接受 openai、cohere 和 jina 服务提供方值。由 huggingface 支持的别名在这三个路由上都会被拒绝。

后续步骤

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

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

准备工作​

使用 AISIX Cloud 配置​

创建服务提供方密钥​

创建模型​

固定推理服务商​

创建调用方 API Key​

使用开源 AISIX 网关配置​

验证服务提供方连接​

控制推理输出​

支持的代理路由​

后续步骤​