Hugging Face Inference API 配置指南（Router OpenAI 兼容端点）

一、简介与适用场景

Hugging Face 是全球最大的开源模型社区，Inference Providers 是它提供的托管推理入口：你不用自己部署，直接用一个访问令牌就能调用社区里的开源模型，背后由 Together、Fireworks、Novita 等上游供应商实际承载算力。

它的免费额度是每月赠送一小笔推理额度，用完就得订阅 PRO 或转按量计费。所以它适合「想快速试一个冷门开源模型效果」的场景，不适合承载线上流量。如果你要找的模型在其他平台上没有，先来这里试，往往能找到。

二、注册与获取 Key

1. 注册并登录 Hugging Face，完成邮箱验证。
2. 打开 Access Tokens 页面，点「Create new token」。
3. 类型选 Read 即可调用推理接口；需要上传模型才用 Write。
4. 复制 hf_ 开头的令牌并妥善保存——页面关闭后无法再次查看。

三、Base URL 与鉴权

• Base URL：https://router.huggingface.co/v1
• 鉴权方式：Authorization: Bearer hf_xxxxxxxx
• 对话端点：/chat/completions

这里有一个高频坑：很多老教程写的是 https://api-inference.huggingface.co/models/<模型名>，那是 HF 的自有协议，请求体结构和 OpenAI 完全不同。要走 OpenAI 兼容协议，必须用上面的 router 域名。

模型标识要填仓库全名，例如 meta-llama/Llama-3.1-8B-Instruct，只写 Llama-3.1-8B 会 404。部分门禁模型（gated model）还需要先在模型页点同意协议，否则返回 403。

官方文档：huggingface.co/docs/api-inference

四、客户端接入示例

以 Cherry Studio 为例，用「自定义 OpenAI 供应商」接入：

1. 打开「设置 → 模型服务 → 添加供应商」，类型选 OpenAI。
2. API 地址填 https://router.huggingface.co/v1。
3. API 密钥填 hf_ 令牌。
4. 模型名手动添加仓库全名，不要依赖自动拉取列表。
5. 首次测试选小参数模型，额度消耗更慢。

五、代码示例

curl：

curl https://router.huggingface.co/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HF_TOKEN" \
  -d '{
    "model": "meta-llama/Llama-3.1-8B-Instruct",
    "messages": [{"role": "user", "content": "用一句话解释什么是 API"}]
  }'

Python：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["HF_TOKEN"],
    base_url="https://router.huggingface.co/v1",
)

resp = client.chat.completions.create(
    model="meta-llama/Llama-3.1-8B-Instruct",
    messages=[{"role": "user", "content": "用一句话解释什么是 API"}],
)
print(resp.choices[0].message.content)

Node.js：

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.HF_TOKEN,
  baseURL: 'https://router.huggingface.co/v1',
});

const resp = await client.chat.completions.create({
  model: 'meta-llama/Llama-3.1-8B-Instruct',
  messages: [{ role: 'user', content: '用一句话解释什么是 API' }],
});
console.log(resp.choices[0].message.content);

六、常见错误排查