BentoML 中 Bento 与模型管理 API 完全指南:从本地 Store 到 BentoCloud 的增删查改与导入导出

原创2026-09-24 13:11:501,377 阅读
文章标签:人工智能模型推理服务MLOpsLLMOps后端云原生API网关

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):

  1. 先在本地 Model Store 查找,命中则直接返回;
  2. 未命中时尝试从远端(BentoCloud)pull 到本地后返回;
  3. 本地与远端都找不到则抛出 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 先从本地 Store get 到 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 等命令)。

登录后查看全文
BentoML