BentoML 中 Bento 与模型管理 API 完全指南:从本地 Store 到 BentoCloud 的增删查改与导入导出
BentoML 中 Bento 与模型管理 API 完全指南:从本地 Store 到 BentoCloud 的增删查改与导入导出
BentoML 将"模型"与"Bento"(模型推理服务交付物)视为两类一等公民工件,并围绕它们提供了完整的管理 API。本文以官方参考文档 stores.rst 为骨架,结合当前仓库源码,系统讲解 Bento 与模型在本地 Store 中的增删查改、构建、导入导出,以及 BentoModel / HuggingFaceModel 的加载机制和与 BentoCloud 之间的 push / pull 协作。读完本文,你将掌握 BentoML 工件生命周期管理的全部 Python API 用法及其底层存储原理。
一、背景:BentoML 的两类工件与本地 Store
BentoML 中两类核心工件分别是:
- Bento:一个自包含的模型服务交付物,包含服务代码、模型文件、依赖配置、Docker 化所需的全部元信息,对应 src/bentoml/bentos.py 中的管理 API;
- Model:通过各框架
save系列函数持久化到本地 Model Store 的模型工件,对应 src/bentoml/models.py 与_bentoml_sdk中的BentoModel/HuggingFaceModel。
这两类工件统一存放在本地 Store 中,其根目录由环境变量 BENTOML_HOME 控制,默认值为 ~/bentoml。从 src/bentoml/_internal/configuration/containers.py 可以看到:
- Bento 存储目录:
<BENTOML_HOME>/bentos(bento_store_dir); - 模型存储目录:
<BENTOML_HOME>/models(model_store_dir); - 临时 Bento 构建目录:
<BENTOML_HOME>/tmp。
Store 的通用实现位于 src/bentoml/_internal/store.py,它提供了 list、get、delete、register 等基础能力。目录结构按 name/version 两级组织,每个工件名下还有一个特殊的 latest 文件用于记录当前最新版本指针,这保证了 bentoml.get("my_bento:latest") 这样的调用能快速定位。
Tag 约定:name:version
所有 API 都接受 Tag 或字符串形式的标识符。字符串格式为 name:version,例如 "my_bento:20240101"。根据 src/bentoml/_internal/tag.py 的实现,tag 有以下约束:
- name 和 version 各自最多 63 个字符;
- 只能包含小写字母、数字、
_、-、.,且必须以字母数字开头和结尾; - 传入非小写字符串时,BentoML 会给出警告并自动转为小写;
- 省略版本时(如
"my_bento"),API 会解析到latest指针指向的版本。
二、管理 Bentos:list / get / delete
在 src/bentoml/bentos.py 中,list、get、delete 三个函数直接代理到 BentoStore(通过依赖注入 BentoMLContainer.bento_store):
import bentoml
# 列出本地所有 Bento
bentos = bentoml.list()
# 按 tag 过滤:列出指定名称下的所有版本
bentos = bentoml.list("my_bento")
# 获取单个 Bento,支持 Tag 或字符串
bento = bentoml.get("my_bento:latest") # 最新版本
bento = bentoml.get("my_bento:20240101") # 指定版本
bento = bentoml.get(Tag("my_bento", "20240101"))
# 删除指定 Bento
bentoml.delete("my_bento:20240101")
值得注意的底层行为(来自 src/bentoml/_internal/store.py):
get在版本为None或"latest"时读取<name>/latest文件解析实际版本;若latest文件缺失,会依据工件creation_time自动重建(_recreate_latest);- 版本解析支持前缀匹配:传入的路径前缀只匹配到一个目录时会直接返回该版本,匹配到多个则会抛出
BentoMLException提示版本歧义; - 找不到工件时,异常信息会提示对应 CLI 命令(
bentoml pull或bentoml models pull); delete删除某一版本后会自动将剩余版本中创建时间最新的提升为latest;若名称目录下所有版本都被删除,则连名称目录一并清理。
三、构建 Bento:bentoml.build 与 bentoml.bentos.build_bentofile
bentoml.build 是面向代码调用的构建 API。它不读取任何 bentofile.yaml,所有构建选项都必须通过函数参数显式传入(见 src/bentoml/bentos.py):
import bentoml
bentoml.build(
service="fraud_detector.py:svc",
version="any_version_label", # 覆盖默认自动生成的版本号
description=open("README.md").read(),
include=['*'], # 默认包含 build 上下文下除排除项外的全部文件
exclude=[], # 也可用 .bentoignore 文件声明排除
labels={"foo": "bar", "team": "abc"}, # 不可变标签,携带上下文信息
python=dict(
packages=["tensorflow", "numpy"],
# requirements_txt="./requirements.txt",
index_url="http://<api token>:@mycompany.com/pypi/simple",
trusted_host=["mycompany.com"],
find_links=['thirdparty..'],
extra_index_url=["..."],
pip_args="ANY ADDITIONAL PIP INSTALL ARGS",
wheels=["./wheels/*"],
lock_packages=True,
),
docker=dict(
distro="amazonlinux2",
setup_script="setup_docker_container.sh",
python_version="3.8",
),
)
参数与 bentofile.yaml 的键一一对应,核心参数说明:
| 参数 | 作用 |
|---|---|
service |
用于定位 bentoml.Service 实例的导入字符串,如 "fraud_detector.py:svc" |
name |
覆盖 Bento 名称 |
labels |
不可变的上下文标签字典 |
description |
Markdown 格式的描述字符串 |
include / exclude |
纳入 / 排除的文件路径与通配模式 |
envs |
环境变量列表(BentoEnvSchema) |
python |
Python 依赖配置(PythonOptions,支持 packages、requirements_txt、index_url、trusted_host、wheels、lock_packages 等) |
conda |
Conda 依赖配置(CondaOptions) |
docker |
容器化配置(DockerOptions,支持 distro、setup_script、python_version 等) |
models |
构建时关联的模型引用列表(ModelSpec、字符串或字典) |
version |
覆盖默认自动生成的版本号 |
build_ctx |
构建上下文目录 |
bentoml.bentos.build_bentofile 则相反——它以 bentofile.yaml 为构建配置来源(见 src/bentoml/bentos.py)。默认在当前工作目录下依次查找 DEFAULT_BENTO_BUILD_FILES(即 bentofile.yaml 等默认文件名);找不到时会退化为仅含 service 参数的空配置。同时它支持用函数参数覆盖 YAML 中的部分选项(name、labels 会与 YAML 中的值合并),并可通过 bare=True 构建"不拷贝文件"的 Bento,reload=True 触发服务重载:
# 等价于命令行 bentoml build
bento = bentoml.bentos.build_bentofile("bentofile.yaml", version="v2.0")
构建完成后,Bento 通过 Bento.create(...).save(_bento_store) 落入本地 Bento Store,返回的 Bento 实例可用于后续 serve、containerize 或 push。
四、导入导出 Bento:import_bento / export_bento
bentoml.import_bento 与 bentoml.export_bento 支持在本地文件系统与各类远程文件系统(FS)之间迁移 Bento。底层实现位于 src/bentoml/_internal/exportable.py,它基于 fsspec 统一处理协议。
支持的格式(output_format / input_format):
- 默认格式:
bento(内部为 xz 压缩的 tar 归档,扩展名.bento); - 压缩格式:
gz(tar.gz)、xz(tar.xz)、bz2(tar.bz2)、tar、zip; - 目录格式:
folder(未压缩的完整目录)。
导出示例
# 导出为默认 .bento 格式
bentoml.export_bento("my_bento:latest", "/path/to/folder")
# 指定文件名导出
bentoml.export_bento("my_bento:latest", "/path/to/folder/my_bento.bento")
# gzip 压缩导出
bentoml.export_bento("my_bento:latest", "/path/to/folder/my_bento.tar.gz")
# 强制以 gz 格式写出到任意扩展名
bentoml.export_bento("my_bento:latest", "/path/to/folder/my_bento.ext", "gz")
# 以未压缩目录导出
bentoml.export_bento("my_bento:latest", "/path/to/folder/my_bento", "folder")
# 导出到 S3(需 pip install bentoml[aws])
bentoml.export_bento("my_bento:latest", "s3://my_bucket/folder")
bentoml.export_bento("my_bento:latest", "my_bucket/folder", protocol="s3")
导入示例
# 从默认 .bento 文件导入
bentoml.import_bento("/path/to/folder/my_bento.bento")
# 从压缩包导入
bentoml.import_bento("/path/to/folder/my_bento.tar.gz")
# 显式声明格式
bentoml.import_bento("/path/to/folder/my_bento.ext", "gz")
# 从目录导入
bentoml.import_bento("/path/to/folder/my_bento", "folder")
# 从 S3 导入
bentoml.import_bento("s3://my_bucket/folder/my_bento.bento")
对专家用户,import_bento / export_bento 还支持一组高级参数:protocol(FS 协议,如 ftp、s3)、user / passwd(认证信息)、params(透传给 FS 的参数字典)、subpath(FS 内部路径)。注意:当 path 本身是 FS URL 时(含 ://),这些参数不能再单独指定,否则会抛出 ValueError;所有信息都必须编码在 URL 中(见 src/bentoml/_internal/exportable.py)。格式推断逻辑为:无扩展名时按默认格式,识别 .bento / gz / xz / bz2 / tar / zip,其余扩展名回退到默认格式。
五、加载模型:BentoModel 与 HuggingFaceModel
bentoml.models.BentoModel 与 bentoml.models.HuggingFaceModel 是模型引用(Model Reference)的两种实现,都继承自 _bentoml_sdk.models.base.Model 抽象基类(见 src/_bentoml_sdk/models/base.py),统一实现了三个核心方法:
to_info(alias=None) -> BentoModelInfo:将模型引用转换为序列化元信息(tag、module、creation_time、alias、registry、metadata);from_info(info) -> Model:从BentoModelInfo反向还原模型引用对象;resolve(base_path=None):获取模型的实际对象。
BentoModel:本地 Model Store 引用
BentoModel 以 tag 为唯一字段(src/_bentoml_sdk/models/base.py)。它在服务定义中作为依赖注入,Bento 构建时通过 to_info 将模型信息固化进 BentoModelInfo 并写入 Bento 元数据(参见 src/bentoml/_internal/bento/bento.py)。
from bentoml.models import BentoModel
# 在服务中声明依赖
class MyService:
model = BentoModel("my_model:latest")
# 手动解析:resolve() 返回本地 StoredModel
stored_model = BentoModel("my_model:v1").resolve()
resolve 的查找优先级(src/_bentoml_sdk/models/base.py):
- 先在本地 Model Store 查找,命中则直接返回;
- 未命中时尝试从远端(BentoCloud)
pull到本地后返回; - 本地与远端都找不到则抛出
NotFound。
此外,BentoModel 实现了描述符协议 __get__:在服务类中作为类属性使用时,首次访问会自动 resolve() 并缓存结果,后续访问直接复用。传入 base_path 时还会把模型从全局 Store 拷贝到指定目录(copy_model),适用于构建隔离环境。
HuggingFaceModel:Hugging Face Hub 引用
HuggingFaceModel 直接引用 Hugging Face Hub 上的模型,不占用本地 Store 的独立模型工件(src/_bentoml_sdk/models/huggingface.py):
from bentoml.models import HuggingFaceModel
class MyService:
# model_id 形如 "google-bert/bert-base-uncased"
model = HuggingFaceModel(
"google-bert/bert-base-uncased",
revision="main", # 默认 "main"
endpoint="https://huggingface.co", # 默认官方端点,可用 HF_ENDPOINT 环境变量覆盖
include=["*.safetensors"], # 仅下载匹配文件
exclude=["*.md"], # 排除匹配文件
)
关键实现细节:
resolve(base_path=None)调用huggingface_hub.snapshot_download将快照下载到本地(默认缓存目录可用BENTOML_HF_CACHE_DIR环境变量覆盖),返回下载路径字符串;传base_path时会额外把整个模型目录拷贝到指定位置;to_info将model_id(转小写)、commit hash(revision)、endpoint、include/exclude 序列化进 metadata,并用这些字段的 JSON 计算 MD5 哈希作为 tag 版本(model_id.replace("/", "--")+ 内容哈希),保证同一引用内容的确定性;from_info从 metadata 还原HuggingFaceModel,并把冻结的 commit hash 直接写入实例缓存,避免再次请求 Hub;to_create_schema用于推送 BentoCloud 时生成模型清单,其中会通过 Hub API 估算模型大小(受 include/exclude 过滤影响)。
六、管理模型:create / list / get / delete / import_model / export_model
src/bentoml/models.py 提供了与 Bento 管理对称的模型管理 API。models.list、models.get、models.delete 直接代理到 ModelStore:
import bentoml
# 列出本地全部模型
models = bentoml.models.list()
# 按名称过滤
models = bentoml.models.list("my_model")
# 获取单个模型(get 会先查 model_aliases 映射,再查 Store)
model = bentoml.models.get("my_model:latest")
# 删除
bentoml.models.delete("my_model:20240101")
models.create:低层建模入口
bentoml.models.create 是一个上下文管理器,用于在 Model Store 中创建模型工件(src/bentoml/models.py)。注意:普通用户应优先使用各框架的 save 函数(如 bentoml.sklearn.save、bentoml.transformers.save),create 仅用于框架集成等底层场景。其 module、api_version、signatures、options、custom_objects、external_modules、context 参数均已标记为 deprecated。
import bentoml
from bentoml.models import ModelContext
with bentoml.models.create(
"my_model",
labels={"team": "ml"},
metadata={"note": "from create API"},
context=ModelContext(framework_name="custom", framework_versions={"v": "1.0"}),
) as model:
# 在 with 块内写入模型文件
model.save("artifact.bin", b"payload")
# 退出 with 块后自动 flush 并 save 到 Model Store
从源码可以看到,上下文管理器在异常时直接抛出(不落盘),正常退出时才执行 flush()、save(_model_store) 并上报 ModelSaveEvent 分析事件。
import_model / export_model:模型迁移
模型导出/导入与 Bento 的导入导出机制完全同构(同样走 Exportable),默认扩展名为 .bentomodel:
# 导出:默认 .bentomodel 格式
bentoml.models.export_model("my_model:latest", "/path/to/folder")
# 指定文件名 / gzip / 目录格式
bentoml.models.export_model("my_model:latest", "/path/to/folder/my_model.bentomodel")
bentoml.models.export_model("my_model:latest", "/path/to/folder/my_model.tar.gz", "gz")
bentoml.models.export_model("my_model:latest", "/path/to/folder/my_model", "folder")
# 导出到 S3
bentoml.models.export_model("my_model:latest", "s3://my_bucket/folder")
# 导入
bentoml.models.import_model("/path/to/folder/my_model.bentomodel")
bentoml.models.import_model("/path/to/folder/my_model.tar.gz")
bentoml.models.import_model("/path/to/folder/my_model", "folder")
bentoml.models.import_model("s3://my_bucket/folder/my_model.bentomodel")
与框架 save 函数的关系:import_model 只能导入 export_model 导出的模型工件;想要保存某个框架训练出的模型,应使用该框架模块下的 save 函数(例如 bentoml.sklearn.save),这两类入口在文档中有明确区分。
七、与 BentoCloud 协同:push / pull
当配置了 BentoCloud(通过 BentoMLContainer.bentocloud_client 注入的云客户端)时,可以将本地工件推送至云端,或从云端拉取到本地(见 src/bentoml/bentos.py 与 src/bentoml/models.py):
import bentoml
# Bento 推送 / 拉取
bentoml.push("my_bento:latest", force=False) # force=True 覆盖云端同名版本
bentoml.pull("my_bento:latest", force=False)
# 模型推送 / 拉取
bentoml.models.push("my_model:latest", force=False)
bentoml.models.pull("my_model:latest", force=False)
实现细节:
bentoml.push先从本地 Storeget到 Bento,本地不存在时抛出BentoMLException,再调用_cloud_client.bento.push(bento, force=force);bentoml.pull调用_cloud_client.bento.pull(tag, force=force, bento_store=_bento_store),将云端 Bento 落入本地 Store;bentoml.models.push内部通过BentoModel(tag)包装本地模型(stored is None时报错),再走云端推送;bentoml.models.pull返回拉取后的Model对象,若云端也不存在则返回None;force参数控制是否覆盖目标端已有的同名版本。
这套 push / pull 机制与前面提到的 BentoModel.resolve 的远端回退逻辑相辅相成:服务在本地缺失模型时,resolve 会自动尝试从 BentoCloud 拉取,实现"本地优先、云端兜底"的模型解析。
八、小结:管理 API 速查
| 目的 | Bento API | Model API |
|---|---|---|
| 列出 | bentoml.list([tag]) |
bentoml.models.list([tag]) |
| 获取 | bentoml.get(tag) |
bentoml.models.get(tag) |
| 删除 | bentoml.delete(tag) |
bentoml.models.delete(tag) |
| 构建 / 创建 | bentoml.build(...)、bentoml.bentos.build_bentofile(...) |
bentoml.models.create(...)(底层) |
| 导入 | bentoml.import_bento(path) |
bentoml.models.import_model(path) |
| 导出 | bentoml.export_bento(tag, path) |
bentoml.models.export_model(tag, path) |
| 云端推送 | bentoml.push(tag, force=...) |
bentoml.models.push(tag, force=...) |
| 云端拉取 | bentoml.pull(tag, force=...) |
bentoml.models.pull(tag, force=...) |
| 引用与解析 | — | BentoModel、HuggingFaceModel(to_info / from_info / resolve) |
所有 API 都遵循统一的 tag(name:version)约定,围绕 BENTOML_HOME 下的 bentos/ 与 models/ 目录组织数据,并共享 Store / Exportable 的底层实现。官方 API 索引位于 src/bentoml/init.py,全部函数均有对应文档与可测试示例;如需在命令行中完成等价操作,可参考 CLI 参考文档(如 bentoml list、bentoml models list、bentoml pull 等命令)。