Hugging Face 免费推理 API 指南：注册领取每月额度与调用方法

Hugging Face 目前有两种接入方式：一种是 OpenAI 兼容路由，另一种是经典的单一模型端点。前者更适合对话补全，后者更适合 embedding、分类这类单任务管线。

• OpenAI 兼容路由的 base_url 形如 https://router.huggingface.co/v1，补全路径为 /chat/completions。
• 经典单模型端点的形式为 https://api-inference.huggingface.co/models/{模型ID}，是否仍对该模型开放，以模型页和官方文档的实际显示为准。

模型名从模型页右上角复制，格式固定为 作者/模型名，例如 meta-llama/Llama-3.1-8B-Instruct、sentence-transformers/all-MiniLM-L6-v2。对话类任务建议优先选择带 Instruct 后缀的模型，纯基座模型不擅长遵循指令。

用 curl 调用一次对话补全

先把令牌写入环境变量，避免把密钥写进代码或提交到仓库：

export HF_TOKEN="你的访问令牌"

随后发送一次标准的对话补全请求：

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

关键参数说明：model 填模型 ID，写错会直接返回模型不存在；messages 按 system、user、assistant 角色排列；max_tokens 限制输出长度，调小可显著省额度；temperature 控制随机性，做抽取类任务时建议调到 0 到 0.3；stream 设为 true 可流式返回增量内容。

用 Python 的 OpenAI SDK 调用

只要把 base_url 指向 Hugging Face 的兼容路由，原有 OpenAI 代码几乎不用改：

import os
from openai import OpenAI

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

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

做 embedding 或文本分类时，改用经典端点更直接，请求体只需一个 inputs 字段：

curl https://api-inference.huggingface.co/models/sentence-transformers/all-MiniLM-L6-v2 \
  -H "Authorization: Bearer $HF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"inputs": "今天天气不错，适合出门"}'

额度耗尽与限流的典型表现与排查顺序

1. 先看返回码：401 多为令牌无效或已删除；403 多为该模型不在免费范围或账号权限不足；429 表示请求过快或当月额度已用尽；503 常是模型正在冷启动加载，稍等几十秒重试即可。
2. 核对令牌权限：确认请求头里的 Bearer 令牌是当前账号新建的、权限为只读或以上，且没有多余空格与换行。
3. 确认模型可用性：到模型页看推理服务一栏，若只列出付费服务商而无可用的免费通道，说明该模型已转付费，需要换用冷门模型或研究型模型。
4. 查看用量页：在账号设置的账单或推理服务页面确认当月剩余额度与重置日期，具体数值以控制台实际显示为准。
5. 降低消耗后重试：把 max_tokens 调小、减少上下文长度、批量任务加请求间隔与指数退避，再观察是否恢复。

如果长期跑热门模型，免费额度很难支撑，可考虑开通 Pro 提升上限，或直接改用其他按量计费的推理服务；免费额度只适合验证链路与小规模实验，不建议作为生产环境的唯一依赖。