Hugging Face Catalog API 怎么创建推理端点

要通过 Hugging Face Catalog API 创建推理端点，最稳妥的做法是先用 list_inference_catalog() 筛选目录模型和部署配方，再把确认过的 recipe_id 交给 create_inference_endpoint_from_catalog()。前者是只读发现，后者会正式创建计费资源。两步分开，既能避免手填一长串硬件参数，也能在创建前确认引擎、加速器和模型修订版本。

Catalog API 的对象关系

Catalog API 的公开基础地址是 https://endpoints.huggingface.co，当前接口位于 /api/v1 下。目录模型通常包含 repo_id、任务、许可证等元数据，以及一个 recipes 集合。每个 recipe 都有公开的 recipe_id，并描述 accelerator、engine，有时还会包含 gguf_file 或 revision。

这意味着“选择模型”和“选择部署组合”是两个判断。只传 repo_id 适合接受目录默认方案的场景；需要复现同一套引擎与硬件组合时，应保存并使用 recipe_id。Catalog 配方减少了配置字段，却不会替你承担区域、权限、成本和容量决策。

官方参考入口是 https://huggingface.co/docs/inference-endpoints/en/api_reference，Python 客户端说明是 https://huggingface.co/docs/huggingface_hub/guides/inference_endpoints。Catalog API 目前仍标为实验性功能，生产代码应固定经过验证的 huggingface_hub 版本，并在升级前重新查看在线 Swagger 和变更说明。

创建前先准备账号、令牌和账单条件

创建端点前，账号需要配置有效付款方式，所用 Token 要具备相应权限，目标 namespace 也必须允许当前账号创建资源。不要把 Token 写进源码、笔记或共享命令。可以先升级客户端，再通过交互式命令登录：

# 升级到包含当前 Catalog API 封装的 huggingface_hub
python -m pip install -U huggingface_hub

# 交互式登录，避免把 Token 写进脚本或命令历史
hf auth login

公共目录的读取不要求鉴权，但部署路由需要 Authorization: Bearer 。如果查询成功、创建却返回权限错误，应优先检查 Token 范围、namespace、付款方式和账户配额，而不是反复更换模型。

先筛选目录，再锁定 recipe_id

list_inference_catalog() 支持按任务、加速器、引擎、许可证和关键词筛选。下面的例子只读取前五个文本生成候选，检查第一个候选是否存在配方，然后用配方 ID 发起正式创建：

from huggingface_hub import (
    list_inference_catalog,
    create_inference_endpoint_from_catalog,
)

# 先缩小目录范围，不要在未检查配方时直接创建资源。
models = list_inference_catalog(
    task="text-generation",
    accelerator="gpu",
    engine="vllm",
    search="Qwen",
    limit=5,
)
if not models:
    raise RuntimeError("没有找到符合筛选条件的目录模型")

model = models[0]
if not model.recipes:
    raise RuntimeError("该模型当前没有可部署配方")

# 生产代码应把许可证、模型版本和配方属性纳入人工或策略检查。
recipe = model.recipes[0]
print(model.repo_id, recipe.id, recipe.accelerator, recipe.engine)

# 这是正式创建动作，会产生云资源和费用；先确认 namespace、配方和账单设置。
endpoint = create_inference_endpoint_from_catalog(recipe_id=recipe.id)
print(endpoint.name, endpoint.status)

示例故意不写死某个会随目录变化的 recipe。实际系统可以把筛选结果展示给审核者，记录选中的 repo_id、recipe_id、引擎和加速器，再进入创建阶段。如果只想接受默认配方，也可以传入 repo_id；但默认配方以后可能调整，不适合作为严格复现凭据。

返回对象不等于端点已经可用

创建函数返回的是 InferenceEndpoint 对象，其中可以读取名称、状态和 URL 等属性。刚返回时资源可能仍在初始化，调用推理客户端之前要等待运行状态：

# 最多等待 20 分钟，每 10 秒刷新一次端点状态。
endpoint.wait(timeout=20 * 60, refresh_every=10)

# 只有状态就绪且 URL 可用后，才进入真实推理调用阶段。
print(endpoint.status, endpoint.url)

等待超时只代表客户端停止等待，并不表示云端资源被删除。此时应查看端点状态和错误信息，判断是容量不足、镜像启动、权限还是模型加载问题；不要立刻重复创建同名或同配置端点。需要停止资源时，再明确选择暂停、缩容到零或删除，并先确认业务是否允许中断。

创建、等待与成本边界

端点费用通常由计算资源和副本运行情况决定，因此成功创建后就要把生命周期管理纳入代码和运维。pause() 适合完全停止并在以后手动恢复；scale_to_zero() 可以在空闲时缩到零，并在请求到来时恢复，但会带来冷启动等待。具体能力仍应以当前端点类型和官方文档为准。

上线前的最小检查清单

• 保存目录筛选条件和最终 recipe_id，不要只记录模型名称。
• 确认 Token 权限、namespace、付款方式和账户配额，再执行创建。
• 对 wait() 设置明确超时，并为失败状态记录可追踪日志。
• 创建后立即接入暂停、缩到零或删除策略，避免测试资源长期运行。
• 由于 Catalog API 仍属实验性接口，升级 SDK 前重新核对签名和在线文档。

常见问题

为什么能列出 Catalog，却不能创建端点？

目录列表是公开读取接口，创建属于鉴权和计费动作。重点检查 Bearer Token 权限、账号付款方式、namespace 访问权和配额。

repo_id 和 recipe_id 应该选哪个？

探索阶段可以用 repo_id 接受默认配方；需要审计和复现时，优先使用经过确认的 recipe_id。

wait 超时后可以直接再创建一个吗？

不建议。超时不会清理原资源，应先刷新原端点状态并处理失败原因，否则可能产生重复资源和额外费用。