企业官网建设流程全解析

• 模型推理服务
• 人工智能
• 后端
• 大模型
• MLOps
• LLMOps

本文面向希望在任意 Docker 兼容环境中复现、部署 AI/ML 服务的开发者，完整讲解 BentoML 的标准化打包格式Bento：如何通过bentoml.images.Image与@bentoml.service定义运行时环境，如何用bentoml build构建可复现的 Bento 产物，以及如何用bentoml containerize生成 Docker 镜像并本地运行。读完本文，你将掌握一套从源码到可部署镜像的完整打包流水线，并理解其底层实现原理。

什么是 Bento：BentoML 的标准化打包格式

BentoML 为打包 AI/ML 服务提供了一种标准化格式，称为Bento。一个 Bento 封装了运行 AI 服务所需的全部组件，包括：

• 源代码：服务定义（如service.py）及其业务逻辑；
• Python 依赖：运行所需的第三方包及其锁定版本；
• 模型产物（model artifacts）：训练好的模型文件与元数据；
• 运行时配置：Python 版本、基础镜像、环境变量、启动命令等。

这种"打包即标准化"的设计，确保了同一个 AI 服务在不同环境（本地、CI、Kubernetes、BentoCloud 等）中保持一致性与可复现性——这正是生产级部署的核心诉求。Bento 架构如下图所示：

从仓库源码看，Bento 的构建由 build_config.py 中的BentoBuildConfig负责驱动，bentoml build命令在 bentos.py 中通过build_bentofile完成从构建上下文到 Bento 产物的转换。整个构建流程围绕"代码 + 依赖 + 模型 + 配置"四要素展开，这与上文架构图一一对应。

定义运行时环境：Image 与 @bentoml.service

构建 Bento 之前，你需要先定义其运行时环境。BentoML 通过bentoml.images.Image描述基础镜像、Python 版本、系统包与 Python 依赖，并通过@bentoml.service装饰器中的image与envs参数将其应用到 Service 上。

最小示例：service.py

以下示例定义了一个名为Summarization的服务，使用 Python 3.11，并声明torch、transformers两个 Python 依赖：

import bentoml my_image = bentoml.images.Image(python_version="3.11") \ .python_packages("torch", "transformers") @bentoml.service( image=my_image, envs=[ {"name": "HF_TOKEN"}, # 可省略 value，在部署时再设置 {"name": "DB_HOST", "value": "localhost"} ] ) class Summarization: ...

关键环境字段说明

python_packages与requirements_file的底层实现位于 images.py 与 images.py：两者都会把依赖写入python_requirements，并置_after_pip_install = True，后续由freeze()统一生成requirements.txt。

envs：声明运行时环境变量

在@bentoml.service装饰器中，除image外还可通过envs参数指定所需环境变量。每个条目是一个字典，支持：

• 仅声明名称（省略 value）：如{"name": "HF_TOKEN"}，值在部署时再注入——适合存放 token、密钥等敏感信息；
• 声明名称与默认值：如{"name": "DB_HOST", "value": "localhost"}，为本地运行提供默认配置。

envs的底层类型为ServiceEnvConfig，在 factory.py 中通过convert_envs转换为BentoEnvSchema。该 Schema 在 build_config.py 中定义，除name、value外还支持stage字段（取值为all、build、runtime，默认all），用于区分环境变量生效的阶段——构建阶段（如私有镜像源凭据）与运行时阶段。

更多可定制字段

如需进一步定制构建，Image还提供以下链式方法（均定义在 images.py）：

• system_packages(...)：按发行版包管理器安装系统级依赖；
• requirements_file(path)/pyproject_toml(path)：从文件导入依赖；
• run(cmd)/run_script(script)：在镜像构建时执行命令或脚本；
• build_include(...)：额外纳入构建上下文的文件或目录；
• distro与base_image：选择发行版（默认debian）或完全自定义基础镜像。

构建 Bento：bentoml build

在service.py所在目录下执行：

bentoml build

构建行为说明

• 默认情况下，该命令会打包执行目录下的所有文件。如需排除特定文件或目录，可在目录中定义.bentoignore文件（语法与.gitignore一致），BentoML 使用pathspec解析忽略规则（见 build_config.py）。
• 构建完成后，每个 Bento 会被自动分配一个唯一版本号。该版本基于构建上下文内容计算生成，保证同一份代码产出的 Bento 可复现、可追溯。
• 若只想构建而不部署到 BentoCloud，应使用bentoml build；若希望构建后直接部署到 BentoCloud，则应使用bentoml deploy（详见 cloud-deployment）。

从源码看，bentoml build命令定义于 bentos.py，其完整签名包含以下常用选项：

构建成功后，命令会打印后续可执行步骤，包括bentoml deploy、bentoml containerize与bentoml push。

查看已构建的 Bento：bentoml list

bentoml list

该命令列出本地 Bento Store 中所有可用的 Bento；也可追加名称筛选某一 Bento 的全部版本，例如bentoml list Summarization。其实现位于 bentos.py，底层通过BentoStore.list读取本地存储。

容器化 Bento：bentoml containerize

构建完成后，可借助 Docker 将 Bento 容器化。只需执行：

bentoml containerize summarization:latest

• Bento 标签（tag）采用name:version格式，其中latest会自动指向最近构建的版本。
• 默认生成的 Docker 镜像 tag 与 Bento tag 相同，例如summarization:lkpxx2u5o24wpxjr。
• 可用-t / --image-tag指定自定义镜像 tag，甚至可为镜像名加上仓库主机名前缀以便推送，例如bentoml containerize summarization:latest -t myrepo.com:username/summarization。
• 可通过--backend选择 OCI 构建后端（默认docker），仓库注册的可用后端为docker、buildx、buildah、podman、nerdctl、buildctl（见 container/init.py）。
• 底层会优先启用 BuildKit；如需关闭可设置DOCKER_BUILDKIT=0。

Apple Silicon 的兼容性处理

对于搭载 Apple silicon（M 系列芯片）的 Mac，部分 Python 库可能存在兼容性问题，可通过--platform指定构建/运行平台：

bentoml containerize --platform=linux/amd64 summarization:latest

这与bentoml build --platform的行为一致：仓库源码在非 Linux x86_64 环境下会自动以DEFAULT_LOCK_PLATFORM锁定 PyPI 包版本（见 images.py），确保依赖解析面向目标平台。

查看生成的 Docker 镜像

$ docker images REPOSITORY TAG IMAGE ID CREATED SIZE summarization lkpxx2u5o24wpxjr 79a06b402644 2 minutes ago 6.66GB

注意：镜像体积较大（上例约 6.66GB）属正常现象，因为镜像内包含完整的 Python 运行时、依赖包与模型产物。

在本地运行容器化的模型服务

拿到镜像后，即可在任何 Docker 兼容环境中运行：

docker run -it --rm -p 3000:3000 summarization:lkpxx2u5o24wpxjr serve

参数说明：

• -it：以交互模式运行，便于观察日志；
• --rm：容器退出后自动清理；
• -p 3000:3000：将容器内 3000 端口映射到宿主机，BentoML 服务默认监听 3000 端口；
• serve：传入的启动命令，指示镜像以服务模式启动（镜像入口点封装在 container/frontend/dockerfile 生成的entrypoint.sh中）。

运行后，即可通过http://localhost:3000访问服务 API。由此，同一个 Bento 镜像可被推到任何 Docker 兼容环境（本地、云主机、Kubernetes）运行，实现"一次打包、随处部署"。

总结与完整流程回顾

一条完整的"打包即部署"流水线如下：

1. 定义运行时环境：在service.py中用bentoml.images.Image声明 Python 版本与依赖，用@bentoml.service(image=..., envs=...)绑定到服务；
2. 构建 Bento：在service.py目录执行bentoml build，得到带唯一版本号的 Bento（可用bentoml list查看）；
3. 容器化：执行bentoml containerize <bento_tag>，生成同 tag 的 Docker 镜像；
4. 运行与分发：docker run在本地启动服务，或将镜像推送到任意 Docker 兼容环境。

整个过程以 Bento 这一标准化格式为中枢，配合Image的声明式环境定义与envs的环境变量注入，让 AI 服务的构建、交付与运行保持高度一致性和可复现性。若你的目标是直接部署到 BentoCloud，则可跳过手动构建，参考 cloud-deployment 使用bentoml deploy一步到位。

• 模型推理服务
• 人工智能
• 后端
• 大模型
• MLOps
• LLMOps