Hugging Face

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

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

本指南介绍共享的 Inference Providers 路由器。专用 Hugging Face Inference Endpoint 具有独立的部署主机名，无法通过路由器 URL 访问。仅当其服务引擎提供应用所需的 OpenAI 路由（例如 /v1/chat/completions 或 /v1/embeddings）时，才将该部署配置成私有 OpenAI 兼容端点。自定义端点或任务原生端点并不会自动兼容 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。
• 仍有 Inference Providers Credit 的 Hugging Face 账号。
• 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 文档。

后缀会改变延迟、价格以及实际运行模型的后端，因此请将固定服务商和策略路由的变体视为不同上游。请为每个变体创建一个模型别名，不要原地切换后缀，使限流和用量记录仍可归属到该路由选择。

如果准确的 AISIX 成本和预算计算很重要，请固定推理服务商。使用 :fastest、:cheapest 或 :preferred 时，所选服务商和价格都可能变化，因此请验证或覆盖别名成本元数据。相关字段请参阅模型别名。

创建调用方 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 权限且账号仍有 Inference Providers Credit。服务商可用性还因模型而异，因此请在支持的模型列表中确认该模型当前仍在提供服务。

控制推理输出

路由器上的推理模型在 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 和 delta.reasoning，并将后者规范化为 reasoning_content。由于同一个 Hub 仓库 ID 可以由不同推理服务商提供，固定的服务商可能会在其他 delta 路径下流式返回推理内容。此时，请在固定别名专用的服务提供方密钥上设置 response.reasoning_field，不要在其他所有别名都会继承的共享路由器服务提供方密钥上设置。

支持的代理路由

Hugging Face 服务提供方值会解析到 openai 适配器，但共享路由器只实现更广泛 OpenAI API 的一部分，其后的服务商和模型能力也可能不同。

路由	使用 huggingface 服务提供方密钥时的行为
/v1/chat/completions	支持，包括流式传输。AISIX 会转发函数工具、response_format、reasoning_effort 和 VLM image_url 内容。实际工具使用、结构化输出、推理和视觉支持取决于 Hub 模型及本次请求选择的推理服务商。
/v1/responses	通过 AISIX Responses 桥接支持，而非 Hugging Face 原生 Responses API。桥接会通过 Chat Completions 携带文本、本地函数调用及结果、采样字段和流式传输，但会丢弃非文本图片和文件输入块、远程 MCP 等托管工具、reasoning 和结构化输出 text 配置，以及 previous_response_id 和 store 等状态字段。重新编码 Chat 结果时也会省略推理输出。
/v1/messages	通过转换为 Chat Completions 支持，而非原生 Hugging Face Messages API。由于配置的服务提供方不是 Anthropic，/v1/messages/count_tokens 不可用。
/v1/embeddings	路由器的 OpenAI 兼容 /v1 接口不提供。Hugging Face 通过任务特定的特征提取接口提供 Embedding，但 AISIX 不会将 OpenAI Embeddings 请求体转换到该接口。专用 Inference Endpoint 只有在 Text Embeddings Inference 等服务引擎提供 /v1/embeddings 时才可用。
/v1/completions、/v1/audio/*、/v1/files、/v1/batches 和 /v1/fine_tuning/jobs	配置的共享路由器根地址上不可用。Hugging Face 另有文本生成和语音等任务原生接口，但这些 AISIX 路由不会转换到或访问它们。
/v1/images/generations、/v1/videos 和 /v1/rerank	不支持 huggingface 服务提供方值。Hugging Face 可能提供相关原生任务，但这些 AISIX 路由会在转发前拒绝该服务提供方。

规范化 Chat 响应会保留内容、本地函数调用、规范化推理和基本 Token 用量，但不会保留所有路由器或服务商字段，例如 created、system_fingerprint、选项索引和 Log Probabilities，或任意服务商特定元数据。

要使用 Hugging Face 原生 Responses 协议，请发送 POST /passthrough/huggingface/responses，并在 model 中使用确切的 Hugging Face 模型 ID；透传不会重写 AISIX 别名。除非被安全护栏阻止，否则 AISIX 会原样中继响应体。AISIX 会从 input 检测 Responses 信封，并在响应包含受支持的 input_tokens 和 output_tokens 字段时记录 Token 用量。

本页的 /passthrough/huggingface 路径假定一条透传路由认领该前缀，target_url 设为配置的 https://router.huggingface.co/v1 根地址；在调用方 Key 的 allowed_routes 上授予该路由。这样的路由可以访问 /v1/responses 和 /v1/models，但无法跳出该根地址访问 /hf-inference/models/<model> 等同级任务原生路径。由于目标已以 /v1 结尾，AISIX 会移除重复的前导 v1 路径段，因此 /passthrough/huggingface/models 和 /passthrough/huggingface/v1/models 都会到达 https://router.huggingface.co/v1/models。

后续步骤

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

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