让 Agent 学会使用 Hugging Face：从安装 hf CLI 到浏览器端 AI 应用落地

胡琦

发布于 2026-05-20 15:47:28

1500

文章被收录于专栏：胡琦胡琦

大家好，我是胡琦。

最近在 Agent 使用各种服务的 CLI，那是真的一个字--“真香”。这次我在 codex 中用到了 Github CLI gh、 HuggingFace CLI hf 以及 Vercel CLI vercel ，它直接就给我怼出了一个 clearmatte-studio：基于浏览器的背景消除工作台。令人惊叹的是全过程不到 30 分钟～

源码： https://github.com/hu-qi/clearmatte-studio / https://atomgit.com/huqi/clearmatte-studio

体验：https://clearmatte.huqi.host/

clearmatte

过去我们说 Agent，更多是在说：

它能不能帮我写代码？

现在这个问题要升级了。

真正有用的 Agent，不只是会写代码，而是要会使用工具、调用生态、检索模型、下载权重、管理数据集、部署 Space、跑 Job，甚至帮你判断一个 AI 应用应该用什么模型落地。

这篇文章讲一个非常具体的实践：

如何让你的 Agent 使用 Hugging Face。

也就是，让 Codex、Claude Code、Cursor Agent 这类工具，真正接入 Hugging Face 的模型生态。

不是概念。

是能跑的那种。

01 为什么要让 Agent 使用 Hugging Face？

Hugging Face 对 AI 开发者来说，已经不只是一个“模型下载网站”。

它更像是 AI 时代的基础设施入口。

你想找模型，去 Hugging Face。

你想找数据集，去 Hugging Face。

你想看别人怎么部署 demo，去 Hugging Face Space。

你想做浏览器端 AI 应用，还是绕不开 Hugging Face 上的 ONNX、Transformers.js、WebGPU 模型。

以前我们自己去搜模型、看 README、查 license、试推理、改代码。

现在这件事可以交给 Agent。

但前提是：

Agent 得先会用 hf。

这里的 hf，指的是 Hugging Face 官方 CLI。

它可以做很多事情，比如：

hf auth login
hf download
hf upload
hf repo create
hf jobs run
hf space

你可以把它理解成 Hugging Face 的命令行入口。

一旦 Agent 能使用 hf CLI，它就不再只是“知道 Hugging Face 上有模型”，而是可以开始真正操作模型仓库、下载文件、管理 repo、运行任务。

这就像给 Agent 接了一只手。

02 第一步：安装 hf CLI

Hugging Face 官方现在提供了非常方便的安装方式。

macOS / Linux 可以直接用：

curl -LsSf https://hf.co/cli/install.sh | bash

Windows PowerShell 可以用：

powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"

安装完成后，可以检查一下版本：

hf version

如果安装正常，会看到类似：

hf version 1.15.0

我这边安装后的结果是：

hf CLI ready!
Binary: /Users/huqi/.local/bin/hf
Virtualenv: /Users/huqi/.hf-cli
Current version: 1.15.0

hf CLI 安装成功

注意一点：

有时候安装完之后，当前终端可能还找不到 hf 命令。

这通常是 PATH 还没刷新。

你可以按照提示临时执行：

env PATH="/Users/yourname/.local/bin:$PATH" hf --help

或者把路径写进 shell 配置里。

03 第二步：登录 Hugging Face

安装完成以后，下一步是登录。

命令是：

hf auth login

执行后，CLI 会提示你去 Hugging Face 的 token 页面生成一个 token。

地址类似：

https://huggingface.co/settings/tokens

然后把 token 粘贴到终端里。

如果你后续希望 Agent 能创建 repo、上传模型、下载 gated model，建议 token 至少具备对应权限。

登录成功后，会看到类似：

The token `hf` has been saved
Login successful.
The current active token is: `hf`

hf auth login 登录成

这一步非常关键。

因为没有登录，Agent 最多只能访问公开资源。

但很多真实开发场景里，你可能需要访问私有仓库、受限模型、团队资源，或者上传自己的模型和数据集。

04 第三步：给 Agent 安装 hf skill

现在 hf CLI 已经装好了。

但对 Agent 来说，还需要告诉它：

以后遇到 Hugging Face 相关任务，你可以使用这个工具。

如果你使用的是支持 skills 的 Agent，可以执行：

hf skills add

如果你的网络环境访问 Hugging Face 不稳定，这一步可能需要全局代理。

安装完成后，我这里的结果是：

Installed 'hf-cli' to central location: /Users/huqi/.agents/skills/hf-cli

hf skills add 安装成功

这就代表本地已经有了一个 hf-cli skill。

Agent 后续就可以基于这个 skill 去使用 hf CLI。

05 第四步：测试 Agent 是否真的能用

装完以后，不要急着开始幻想。

先测试。

比如我直接问 Codex：

看看你能使用 hf-cli skill 吗

Codex 返回：

可以用。已确认：

- 本地 skill 存在：/Users/huqi/.agents/skills/hf-cli/SKILL.md
- hf CLI 可调用，版本是 1.15.0

后续你说 Hugging Face、hf、模型/数据集下载上传、Space、repo、endpoint、jobs 等，我就可以按这个 hf-cli skill 来处理。网络相关操作如果被沙箱拦住，我会按需请求授权。

询问 Codex 是否能使用 hf-cli skill

这就说明 Agent 已经不是“嘴上知道 Hugging Face”。

而是真的能检测本地 skill，调用 CLI，并理解后续相关任务应该怎么处理。

这一步很重要。

因为很多 AI 工具的失败点不是“不会回答”，而是“没有真实操作能力”。

我们要的是能干活的 Agent。

不是搜索引擎换皮。

06 让 Agent 进入真实任务：我要做浏览器端 AI 应用

接下来，我问了一个更接近实际产品的问题：

我想做浏览器就能运行的 AI 应用，比如图片水印移除、去背景，有哪些模型可以使用？

这个问题其实很典型。

它不是简单问“有哪些模型”。

它背后包含了几个判断：

模型能不能在浏览器跑？
是否支持 ONNX / Transformers.js？
WebGPU 能不能加速？
模型体积会不会爆？
License 能不能商用？
水印移除是否涉及版权风险？

一个真正好用的 Agent，应该能把这些信息组织成落地方案。

Codex 的回答大概是这样的：

浏览器端 AI 应用可以做，但“去背景”比“水印移除”更适合先落地。

因为水印移除本质上是：

检测 / 手动画出水印 mask + inpainting 修复

而且它应该只用于你拥有版权或已经获得授权的图片。

这个提醒很重要。

技术上能做，不代表产品上可以随便做。

询问浏览器端 AI 应用模型选型

接着我继续和 Codex 交流：

可以，先实现一个能够直接商用的产品

开发应用

Codex 毫不吝啬地快速开发并验证了这个应用。

最后就让它帮我提交代码、部署到 vercel：

非常棒，帮我上传到 github 吧，然后我还想部署，你看 vercel 合不合适

提交代码并部署

小小的插曲是我之前 vercel 的 token 过期了，需要重新尝试部署。

07 看看Codex都说了啥、干了啥

查找hf 版本

可以用。已确认：

- 本地 skill 存在：`/Users/huqi/.agents/skills/hf-cli/SKILL.md`
- `hf` CLI 可调用，版本是 `1.15.0`

后续你说 Hugging Face、`hf`、模型/数据集下载上传、Space、repo、endpoint、jobs 等，我就可以按这个 `hf-cli` skill 来处理。网络相关操作如果被沙箱拦住，我会按需请求授权。

查找模型

可以做，而且“去背景”比“水印移除”更适合纯浏览器端先落地。水印移除建议只用于你拥有版权或获授权的图片，本质是“检测/手动画出水印 mask + inpainting 修复”。

**推荐技术栈**
- 最省事：`@huggingface/transformers` / Transformers.js。官方说明它可以直接在浏览器跑模型，并用 ONNX Runtime 做推理；WebGPU 只要加载模型时设 `device: "webgpu"` 就能启用。参考：[Transformers.js](https://huggingface.co/docs/transformers.js/en/index)、[WebGPU guide](https://huggingface.co/docs/transformers.js/en/guides/webgpu)。
- 更可控：`onnxruntime-web`。适合你自己处理预处理/后处理、mask、canvas、worker。它支持 `wasm`、`webgpu`、`webnn`、`webgl` 等后端；大模型可用 WebGPU，小模型可用 WASM 兜底。参考：[ONNX Runtime Web](https://onnxruntime.ai/docs/tutorials/web/)。

**去背景 / 抠图模型**
- `briaai/RMBG-2.0`：效果强，支持 Transformers.js / ONNX，适合高质量通用去背景。注意它是非商用开放权重，商用要看 BRIA 授权。[模型页](https://huggingface.co/briaai/RMBG-2.0)
- `briaai/RMBG-1.4`：更轻一些，很多浏览器 demo 用过，适合 MVP。
- `studioludens/birefnet-lite-512`：我会优先考虑的浏览器端 BiRefNet 方案，512 输入、ONNX、MIT，模型页明确说是为解决浏览器 OOM 做的版本。[模型页](https://huggingface.co/studioludens/birefnet-lite-512)
- `Xenova/modnet`：人像/视频会议背景替换非常合适，Apache-2.0，Transformers.js 直接可用。[模型页](https://huggingface.co/Xenova/modnet)
- `jellybox/u2net` / `jellybox/u2net-human-seg` / `BritishWerewolf/U-2-Netp`：老牌 U²-Net 系列，模型小、容易跑，质量不如 RMBG/BiRefNet 但适合轻量场景。
- `onnx-community/mediapipe_selfie_segmentation`：如果只做人像背景移除，速度和体积通常更友好。

**水印移除 / 物体擦除**
- `Carve/LaMa-ONNX` 或 `IsGarrido/LaMa-ONNX`：LaMa 是更适合浏览器端的 inpainting 方向，ONNX 版可用；`IsGarrido/LaMa-ONNX` 页面标注 Apache-2.0、固定 512x512 输入。[模型页](https://huggingface.co/IsGarrido/LaMa-ONNX)
- `OpenCV.js inpaint`：不是深度学习，但对小面积、规则水印很实用，加载小、速度快。可以作为 MVP 的第一版。
- Stable Diffusion / SDXL inpainting：效果上限高，但浏览器端太重，启动慢、显存/内存压力大。更适合作为服务端能力，或者只面向高配桌面 Chrome/Edge 的实验功能。

**我会这样选**
1. 去背景 MVP：`Xenova/modnet` 做人像版，或 `RMBG-1.4/RMBG-2.0` 做通用商品图版。
2. 高质量通用抠图：`studioludens/birefnet-lite-512` + WebGPU，WASM 兜底。
3. 水印/杂物擦除：先做用户画笔 mask + `LaMa-ONNX`；小水印加一个 OpenCV.js 快速模式。
4. 商用产品：优先避开非商用权重，选 MIT/Apache-2.0 模型，或单独采购 BRIA 授权。

花的时间最长的是编写代码、验证效果：

编写代码及验证

已做出第一版可商用取向的浏览器端产品：**ClearMatte Studio**。默认只做“本地去背景/主体抠图”，没有把水印移除作为默认卖点，降低版权和平台合规风险。

核心文件：
- [index.html](/Users/huqi/Develop/opensource/Agent/mdwriter/index.html)
- [app.js](/Users/huqi/Develop/opensource/Agent/mdwriter/app.js)
- [styles.css](/Users/huqi/Develop/opensource/Agent/mdwriter/styles.css)
- [THIRD_PARTY_NOTICES.md](/Users/huqi/Develop/opensource/Agent/mdwriter/THIRD_PARTY_NOTICES.md)

本地预览服务已启动： [http://127.0.0.1:5173](http://127.0.0.1:5173)

验证过：
- `node --check app.js` 通过
- 本地静态服务返回 `200`
- 桌面/移动首屏浏览器检查通过，控制台无 error/warn
- 默认模型 `studioludens/birefnet-lite-512`：HF metadata 显示 MIT；`@huggingface/transformers@4.2.0`：npm 显示 Apache-2.0  
  来源：[HF 模型](https://huggingface.co/studioludens/birefnet-lite-512)、[Transformers.js](https://www.npmjs.com/package/@huggingface/transformers)

第一次点击处理会在浏览器里下载约 94MB 的 ONNX 模型，之后走浏览器缓存。

桌面预览：

![ClearMatte desktop](/private/tmp/clearmatte-desktop.png)

部署

已经上传到 GitHub 了：

[hu-qi/clearmatte-studio](https://github.com/hu-qi/clearmatte-studio)

状态：
- 仓库：`PRIVATE`
- 分支：`main`
- 本地 remote：`origin -> https://github.com/hu-qi/clearmatte-studio.git`
- 本地工作区干净
- 已补 `vercel.json` 和 README 里的 Vercel 部署说明

Vercel 很合适这个产品：它是纯静态站、无后端推理、HTTPS 默认开启，正好满足 WebGPU 在非 localhost 环境下的要求。成本上也友好，因为模型推理跑在用户浏览器里，Vercel 主要承担静态文件/CDN 流量。注意一点：Vercel 官方当前说明 Hobby 更偏个人/非商业，商业产品建议用 Pro 或团队/企业计划。参考：[Vercel Plans](https://vercel.com/docs/plans)、[Vercel Pricing](https://vercel.com/pricing)。

我尝试继续部署，但本机 Vercel CLI 的 token 已失效：

```text
Error: The specified token is not valid. Use `vercel login` to generate a new token.
```

你先在这个目录运行一次：

```bash
vercel login
```

登录完成后，我就可以继续帮你跑：

```bash
vercel deploy --prod --yes
```