BiRefNet

一种双边参考（bilateral-reference）网络，预测一张把主体和背景分开的柔和 alpha matte。LibreYOLO 为 BiRefNet 的 matte 任务提供推理和验证。

任务: matte
尺寸: t, l at 1024 px
安装: pip install libreyolo
支持层级: 仅推理，自 v 起。仅支持预测、验证和导出。训练相关的功能不适用。
上游: BiRefNet，由 Nankai University 发布，采用 MIT 许可。论文、源码
许可: 代码采用 MIT，权重采用 MIT。商用

安装

BiRefNet 不需要任何可选的额外依赖。它导入的所有东西都在基础安装里。

bash

pip install libreyolo

预测

权重会在首次使用时从 Hugging Face 下载，并缓存到本地。

Python

from libreyolo import LibreYOLO, SAMPLE_IMAGE model = LibreYOLO("LibreBiRefNetl-matte.pt")result = model(SAMPLE_IMAGE, save=True) matte = result.matteprint(matte.array.shape, matte.array.dtype)

CLI

libreyolo predict model=LibreBiRefNetl-matte.pt source=https://raw.githubusercontent.com/LibreYOLO/libreyolo/release/libreyolo/assets/parkour.jpg save=True

抠图

from libreyolo import LibreYOLO, SAMPLE_IMAGE model = LibreYOLO("LibreBiRefNetl-matte.pt")result = model(SAMPLE_IMAGE) # RGBA (H, W, 4) uint8：源图 RGB 加上作为 alpha 通道的 mattergba = result.cutout()result.save("subject.png")

matte 结果不带检测框；result.matte 是一个取值在 [0, 1] 之间的稠密 (H, W) float32 数组，1 表示完全前景，0 表示完全背景。和二值掩码不同，柔和的 matte 会保留头发、毛发这类抗锯齿的边缘细节。result.cutout() 会把源图和这条 alpha 通道合成为一个 RGBA 数组，result.save(path)（或者在预测调用上加 save=True）会直接把它写成一张透明背景的 PNG。模型固定在原生的 1024x1024 画布上运行；不支持其他分辨率，因为 Swin 骨干的相对位置表和它绑在一起，尺寸对不上时它会把这些表插值得很糟，而不是直接报错。输入源、流式处理和结果处理见预测。

变体

只发布了一个检查点（checkpoint）：l，也就是 Swin-L 档的 BiRefNet-general 模型，上游默认的质量选择。这个家族的代码还支持一个 Swin-T 轻量档 t，但目前还没有发布对应的 LibreYOLO 转换版本。

验证

val() 会在成对的 image/matte 目录上报告两个指标，两者都在 [0, 1] 之间，并且与分辨率无关：MAE，即相对真值（ground truth）alpha 的平均绝对误差（越低越好）；以及 S-measure（Fan 等，ICCV 2017），一种结构相似度，它会奖励保留主体形状和空洞的结果，而这正是单看像素 MAE 会漏掉的（越高越好）。验证走的是模型自己的 predict，因此用的是这个家族确切的预处理。

Python

from libreyolo import LibreYOLO model = LibreYOLO("LibreBiRefNetl-matte.pt") # 一个包含 images/ 和自动识别出的 matte 目录# （mattes/、matte/、gt/、masks/、mask/ 或 alpha/）的目录# 也可以代替数据集 YAMLmetrics = model.val(data="my-matte-dataset/") print(metrics["metrics/MAE"])print(metrics["metrics/Smeasure"])

验证只做推理；微调是记录在案的后续计划，而不是已经发布的功能（未来任何训练器都会继承的那条分辨率限制，见「预测」一节）。

导出

任务	ONNX	TorchScript	ExecuTorch	TensorRT	OpenVINO	Paddle	MNN	RKNN	ncnn	TFLite	CoreML	Core AI
matte	matte to ONNX：支持	matte to TorchScript：支持	matte to ExecuTorch：不支持	matte to TensorRT：不支持	matte to OpenVINO：不支持	matte to Paddle：不支持	matte to MNN：不支持	matte to RKNN：不支持	matte to ncnn：不支持	matte to TFLite：不支持	matte to CoreML：不支持	matte to Core AI：不支持

导出产物按文件后缀通过 LibreYOLO() 加载回来，所以一个 .onnx 文件的表现和检查点一样，返回同样的 Results。TorchScript 是已经验证过的路径；ONNX 转换能跑通，但还没有达到同样的一致性标准。导出列出了每种格式接受的参数，以及少数几种格式额外增加的参数。

Python

from libreyolo import LibreYOLO model = LibreYOLO("LibreBiRefNetl-matte.pt")model.export(format="onnx")

CLI

libreyolo export model=LibreBiRefNetl-matte.pt format=onnx

使用导出的文件

from libreyolo import LibreYOLO, SAMPLE_IMAGE # 工厂函数按文件后缀分发，所以导出产物的加载方式和普通检查点# 一样，返回的也是同一个 Results 对象model = LibreYOLO("LibreBiRefNetl-matte.onnx")result = model(SAMPLE_IMAGE) print(result.matte.array.shape)

检查点

这个家族已发布的全部权重文件。

文件	输入（px）	权重许可
matte
LibreBiRefNetl-matte.pt		mit

上面的每个文件目前都在 LibreYOLO 组织中，并会在首次使用时下载。

许可

请检查你所下载的具体权重在 Hugging Face 仓库中的许可。LibreYOLO 组织里的每个检查点都附有许可，同一家族内也不一定相同。该仓库是权威来源；以下摘要说明本页上次验证时适用的情况。

这里只说明涉及的许可证，不构成法律意见。如果答案对商用很重要，请自行阅读许可证并咨询法律顾问。

原始工作: BiRefNet, Nankai University
上游许可: MIT
上游来源: github.com/ZhengPeng7/BiRefNet
LibreYOLO 代码: MIT
权重: 采用 MIT 许可，重新发布在 huggingface.co/LibreYOLO
解读: MIT is a permissive license, so these weights can be used in commercial and closed-source products. The one standing obligation is to keep the license text and copyright notice with any copy you redistribute. It places no condition on your own application code. LibreYOLO's checkpoint is a format conversion of the official pretrained BiRefNet-general weights (the Swin-L, quality-default tier), with the learned parameters unchanged; fine-tuning is not wired into this library in v1, so there is no LibreYOLO-trained variant to license separately.

引用

@article{zheng2024birefnet,
  title={Bilateral Reference for High-Resolution Dichotomous Image Segmentation},
  author={Zheng, Peng and Gao, Dehong and Fan, Deng-Ping and Liu, Li and Laaksonen, Jorma and Ouyang, Wanli and Sebe, Nicu},
  journal={CAAI Artificial Intelligence Research},
  volume = {3},
  pages = {9150038},
  year={2024}
}

复制自作者在 github.com/ZhengPeng7/BiRefNet#citation 上提供的引用块。