Apache Beam 多语言推理实战:用 Java 管道调用 Python BERT 推理转换(multi-language inference)
Apache Beam 多语言推理实战:用 Java 管道调用 Python BERT 推理转换(multi-language inference)
本指南基于 Apache Beam 仓库中的官方示例 sdks/python/apache_beam/examples/inference/multi_language_inference,讲解如何构建一条跨语言(Java + Python)推理管道:Java 侧编写主管道,通过 PythonExternalTransform 调用一个 Python 侧自定义的推理 PTransform,后者基于 BERT 模型(bert-base-uncased)对 IMDB 影评执行"预测句末被掩码单词"的推理任务。读完本文,你将掌握 Beam 跨语言扩展的完整链路:Maven 工程生成、Java 端外部转换 API 用法、Python 端 RunInference 自定义转换的编写与打包、以及基于 Dataflow 的端到端运行方式。
一、示例整体架构:跨语言推理链路
该示例的核心价值在于演示 Beam 的 cross-language(跨语言)扩展能力:管道的入口与出口都由 Java SDK 实现,而中间的机器学习推理逻辑则完全由 Python SDK 实现,二者通过跨语言 Transform 桥接。整体数据流如下:
TextIO.read (Java 读取 IMDB 影评 CSV)
│
▼
PythonExternalTransform ──► Python 侧 InferenceTransform(跨语言调用)
│ ├── Preprocess:清洗文本 + 掩码句末单词 + Tokenize
│ ├── RunInference:KeyedModelHandler + PyTorch BERT 推理
│ └── Postprocess:解码预测词并格式化输出
▼
TextIO.write (Java 写出预测结果)
- Java 侧主类:MultiLangRunInference.java,位于 Maven archetype 生成的工程
last_word_prediction中。 - Python 侧自定义转换:composite_transform.py,位于独立 Python 包
multi-language-custom-transform中。 - Python 包配置:setup.py,用于把 Python 转换打包成可分发安装的 tarball。
这种架构的优势在于:Java 团队可以专注于 I/O 与管道编排,Python 团队则可以复用 apache_beam.ml.inference 提供的 RunInference、ModelHandler 等成熟推理组件,互不阻塞。
二、环境准备
1. Python 虚拟环境
首先为 Python 侧配置虚拟环境,并安装全部依赖。Beam Python SDK 及推理相关依赖(如 apache_beam[gcp]、torch、transformers)都应装进该环境中,因为跨语言扩展服务会在该环境内启动并导入 Python 转换模块。常规做法:
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install apache_beam[gcp]
2. Java 与 Maven
运行 Java 管道前需满足两个条件:
- Maven 已安装并加入
PATH; JAVA_HOME指向正确的 Java 版本(与 Beam 当前发布版本所要求的 JDK 版本一致)。
由于管道运行在 Dataflow 上并依赖跨语言扩展,请确认环境变量已就绪:
mvn -version
echo $JAVA_HOME
三、使用 Maven Archetype 生成 Java 工程
Beam 提供了官方 Maven archetype beam-sdks-java-maven-archetypes-examples,可直接生成包含全部依赖的 Java 示例工程。运行以下命令:
export BEAM_VERSION=<Beam version>
mvn archetype:generate \
-DarchetypeGroupId=org.apache.beam \
-DarchetypeArtifactId=beam-sdks-java-maven-archetypes-examples \
-DarchetypeVersion=$BEAM_VERSION \
-DgroupId=org.example \
-DartifactId=multi-language-beam \
-Dversion="0.1" \
-Dpackage=org.apache.beam.examples \
-DinteractiveMode=false
参数说明:
| 参数 | 含义 | 示例值 |
|---|---|---|
-DarchetypeGroupId |
archetype 的 GroupId | org.apache.beam |
-DarchetypeArtifactId |
示例 archetype 构件 | beam-sdks-java-maven-archetypes-examples |
-DarchetypeVersion |
要使用的 Beam 版本(与 BEAM_VERSION 一致) |
如 2.59.0 |
-DgroupId |
生成工程的 GroupId | org.example |
-DartifactId |
生成工程名 | multi-language-beam |
-Dversion |
工程版本 | 0.1 |
-Dpackage |
Java 包名 | org.apache.beam.examples |
-DinteractiveMode |
关闭交互模式,便于脚本化执行 | false |
生成成功后,将 MultiLangRunInference.java 放入 src/main/java/org/apache/beam/examples/ 目录(与 -Dpackage 对应),即可获得运行所需的所有 Java 依赖。
四、Java 端管道实现:PythonExternalTransform 用法
Java 侧管道源码位于 MultiLangRunInference.java,核心逻辑分为三部分。
1. 定义 Pipeline Options
示例通过自定义 MultiLanguageOptions 接口声明 5 个必填参数,均标注 @Required 以开启参数校验(PipelineOptionsFactory...withValidation() 会在缺少参数时直接报错):
| Options 方法 | 对应命令行参数 | 说明 |
|---|---|---|
getInputFile() |
--inputFile |
IMDB 影评数据集输入文件路径 |
getModelPath() |
--modelPath |
已存储模型的路径(state_dict),用于推理 |
getOutputFile() |
--outputFile |
预测结果输出文件路径 |
getModelName() |
--modelName |
HuggingFace 上的模型名称 |
getLocalPackage() |
--localPackage |
本地 Python 包编译后的 tarball 路径 |
public interface MultiLanguageOptions extends PipelineOptions {
@Description("Path to an input file that contains the IMDB review dataset.")
@Required
String getInputFile();
void setInputFile(String value);
// ... 其余参数同理
}
2. 组装跨语言外部转换
Java 端通过 PythonExternalTransform 调用 Python 侧转换,这是整个示例的关键:
List<String> local_packages = new ArrayList<String>();
local_packages.add("transformers==4.26.0");
local_packages.add("torch==1.13.1");
local_packages.add(options.getLocalPackage());
input.apply("Predict", PythonExternalTransform
.<PCollection<String>, PCollection<String>>from(
"multi_language_custom_transform.composite_transform.InferenceTransform")
.withKwarg("model", options.getModelName())
.withKwarg("model_path", options.getModelPath())
.withExtraPackages(local_packages))
.apply("Write Output", TextIO.write().to(options.getOutputFile()));
三个 API 的含义(对应 PythonExternalTransform.java 中的实现):
from(String transformName):传入 Python 侧PTransform类的全限定名multi_language_custom_transform.composite_transform.InferenceTransform。框架会导入并实例化该类,名称即模块路径包名.模块名.类名。withKwarg(name, value):指定传入 Python 构造器的关键字参数,此处为model和model_path。可多次调用追加多个 kwarg(见源码withKwarg的实现,kwargs 被收集进kwargsMap)。kwargs 会被编码为 BeamRow(通过generateSchemaFromFieldValues推断字段 Schema)后随跨语言 payload 传输。withExtraPackages(List<String>):声明运行所需的 Python 第三方包,如transformers==4.26.0、torch==1.13.1,以及用户自建包options.getLocalPackage()。这些包会被写入临时requirements.txt,并在构建期与运行期的 Python 环境中一并安装(源码注释:"cause them to be installed in both the construction-time and execution time environment")。注意:源码中该 API 要求expansionService为空,即只适用于自动启动的扩展服务。
3. 底层执行原理
从 PythonExternalTransform.expand() 可以看到跨语言调用的完整决策逻辑:
- 若未显式指定外部扩展服务地址,框架会检查三个条件:
useTransformService选项、系统是否有可用的python3/python可执行文件、是否有 Docker。 - 当显式请求使用 Transform Service,或本机没有 Python 但存在 Docker 时,框架启动基于 Docker Compose 的 Transform Service(
TransformServiceLauncher),并以独立项目名保证扩展实例隔离。 - 否则,框架直接启动本机 Python 扩展服务:运行
apache_beam.runners.portability.expansion_service_main,附带--port、--fully_qualified_name_glob=*、--pickle_library=cloudpickle,若存在 extra packages 则追加--requirements_file指向临时生成的依赖文件,并通过端口就绪探测(最长等待 60 秒)确认服务可用。 - 参数最终封装为
ExternalTransforms.ExternalConfigurationPayload(包含constructor全限定名、args、kwargs三部分),以beam:transforms:python:fully_qualified_named这一标准跨语言 URN 应用。
Java 侧对应的测试见 PythonExternalTransformTest.java:trivialPythonTransform 用 PythonExternalTransform.from("apache_beam.GroupByKey") 调用 Python 原生转换;pythonTransformWithDependencies 演示了 withArgs(PythonCallableSource) 与 withExtraPackages(安装 inflection 包后对单词求复数)的组合用法,可作为理解本示例 API 的最小可运行参照。
五、Python 端自定义推理转换
Python 侧转换位于 composite_transform.py,核心类是继承 ptransform.PTransform 的 InferenceTransform,内部串联了预处理、推理、后处理三个阶段。
1. 构造器与 ModelHandler
def __init__(self, model, model_path):
self._model = model
self._model_config = BertConfig.from_pretrained(self._model)
self._tokenizer = BertTokenizer.from_pretrained(self._model)
self._model_handler = self.PytorchModelHandlerKeyedTensorWrapper(
state_dict_path=(model_path),
model_class=BertForMaskedLM,
model_params={'config': self._model_config},
device='cuda:0')
model:HuggingFace 模型名(对应 Java 端--modelName=bert-base-uncased),用于加载BertConfig与BertTokenizer。model_path:模型权重文件路径(对应 Java 端--modelPath,即 GCS 上的.pthstate_dict),传给PytorchModelHandlerKeyedTensor的state_dict_path。device='cuda:0':推理在 GPU 上进行,运行环境需具备 CUDA 支持。
2. 控制批大小的 ModelHandler 包装
PytorchModelHandlerKeyedTensorWrapper 重写了 batch_elements_kwargs(),将 max_batch_size 限制为 1:
class PytorchModelHandlerKeyedTensorWrapper(PytorchModelHandlerKeyedTensor):
def batch_elements_kwargs(self):
return {'max_batch_size': 1}
源码注释给出了原因:BertTokenizer 生成的 tokenized 字符串长度各不相同,而当前 RunInference 实现中的 torch.stack() 要求同一批次的张量尺寸一致,因此把批大小限制为 1,保证每次 run_inference() 调用只处理一个样本。
3. Preprocess:文本清洗与掩码
Preprocess 是一个 beam.DoFn,逐条处理影评文本:
- 移除不可用标记:
"、*、<br />、'、(、); - 只取第一句话:按
.、!、?切分后取首段; - 在句末补一个句点(
text + ' .'); - 掩码句末倒数第二个词:
text_list[:-2] + ['[MASK]', text_list[-1]],即保留句尾句点,把其前一个词替换为[MASK],交给 BERT 做掩码语言建模; - 丢弃超长句子(BERT 输入长度上限 512),并跳过 CSV 表头行
"review,sentiment"; - 用 tokenizer 转成 PyTorch 张量字典,
torch.squeeze去掉批维度后,以(text, tokens)形式输出。
4. RunInference:掩码词预测
| 'Inference' >> RunInference(KeyedModelHandler(self._model_handler))
这里使用 apache_beam.ml.inference.base 中的 RunInference 转换与 KeyedModelHandler:KeyedModelHandler 将 (key, example) 中的 key 与推理结果绑定,输出 (key, PredictionResult) 二元组,从而让后处理阶段能同时拿到原始文本与预测结果。推理由 PyTorch 执行 BERT BertForMaskedLM 前向计算,输出包含 logits。
5. Postprocess:解码预测词
Postprocess 接收 (text, PredictionResult):
logits = prediction_result.inference['logits']
mask_token_index = (inputs['input_ids'] == self.bert_tokenizer.mask_token_id).nonzero(as_tuple=True)[0]
predicted_token_id = logits[mask_token_index].argmax(axis=-1)
decoded_word = self.bert_tokenizer.decode(predicted_token_id)
即在输入 token 序列中定位 [MASK] 位置,取该位置 logits 的 argmax 得到预测 token id,再用 tokenizer 解码为单词,最终输出:
{清洗后的影评文本}
Predicted word: {预测词.upper()} -- Actual word: {真实句末词.upper()}
6. 跨语言反序列化钩子
由于该转换需要被 Java 端跨语言实例化,InferenceTransform 还实现了静态方法 from_runner_api_parameter:
@staticmethod
def from_runner_api_parameter(unused_ptransform, payload, unused_context):
return InferenceTransform(payload['model'], payload['model_path'])
这正是 Java 端 withKwarg("model", ...) 与 withKwarg("model_path", ...) 传入的两个参数在 Python 侧的接收入口:跨语言 payload 到达后,框架据此重建 InferenceTransform 实例。
六、将 Python 转换打包为 tarball
Java 端 --localPackage 要求传入由用户自行构建的本地 Python 包 tarball,其中必须包含管道所需的 Python 转换模块。示例工程已提供打包配置 setup.py:
import setuptools
setuptools.setup(
name='multi-language-custom-transform',
version='0.1',
packages=setuptools.find_packages(),
)
包内结构为:
multi_language_custom_transform/
├── setup.py
└── multi_language_custom_transform/
├── __init__.py # 包标记(仅含 ASF License 头)
└── composite_transform.py # InferenceTransform 实现
构建 tarball 的命令:
cd multi_language_custom_transform
python setup.py sdist
产物(如 dist/multi-language-custom-transform-0.1.tar.gz)即 LOCAL_PACKAGE 的值。运行时扩展服务会将其与其他 extra packages 一并 pip 安装,因此包名 multi-language-custom-transform 与 Java 端引用的全限定名 multi_language_custom_transform.composite_transform.InferenceTransform 必须严格对应。
七、运行 Java 管道(Dataflow)
在 last_word_prediction 目录下设置环境变量并执行:
export GCP_PROJECT=<your gcp project>
export GCP_BUCKET=<your gcp bucket>
export GCP_REGION=<region of bucket>
export MODEL_NAME=bert-base-uncased
export LOCAL_PACKAGE=<path to tarball>
cd last_word_prediction
mvn compile exec:java -Dexec.mainClass=org.apache.beam.examples.MultiLangRunInference \
-Dexec.args="--runner=DataflowRunner \
--project=$GCP_PROJECT \
--region=$GCP_REGION \
--gcpTempLocation=gs://$GCP_BUCKET/temp/ \
--inputFile=gs://$GCP_BUCKET/input/imdb_reviews.csv \
--outputFile=gs://$GCP_BUCKET/output/output.txt \
--modelPath=gs://$GCP_BUCKET/input/bert-model/bert-base-uncased.pth \
--modelName=$MODEL_NAME \
--localPackage=$LOCAL_PACKAGE" \
-Pdataflow-runner
各参数与前述 Pipeline Options 一一对应:
| 命令行参数 | 对应 Options | 说明 |
|---|---|---|
--runner=DataflowRunner |
运行器 | 在 Google Cloud Dataflow 上执行 |
--project |
— | GCP 项目 ID |
--region |
— | GCS bucket 所在区域 |
--gcpTempLocation |
— | GCS 临时目录(gs://bucket/temp/) |
--inputFile |
getInputFile |
输入 CSV(imdb_reviews.csv) |
--outputFile |
getOutputFile |
输出文件 |
--modelPath |
getModelPath |
BERT 权重 .pth 的 GCS 路径 |
--modelName |
getModelName |
HuggingFace 模型名 bert-base-uncased |
--localPackage |
getLocalPackage |
本地 Python 包 tarball 路径 |
需要注意的前置条件:
- 必须在
last_word_prediction目录内执行该命令(README 明确要求),以便mvn解析到正确的工程与依赖; inputFile、outputFile、modelPath均指向 GCS,需要 Dataflow 与跨语言扩展服务有相应读写权限;- 运行
mvn compile exec:java ... -Pdataflow-runner时,-Pdataflow-runnerprofile 会引入 Dataflow Runner 相关依赖; - 由于推理在
cuda:0上执行,Dataflow 工作节点(Worker)需配置 GPU 规格,Python 侧依赖(transformers、torch)会随扩展服务自动安装。
八、小结
本示例完整展示了 Apache Beam 多语言推理的标准范式:Java 管道负责 I/O 与编排,Python 端以自定义 PTransform 形式封装机器学习推理,双方通过 PythonExternalTransform 与自动启动的扩展服务无缝衔接。关键知识点可归纳为:
- 跨语言参数传递:Java 侧
withKwarg传入的参数,经 payload 编码后由 Python 侧from_runner_api_parameter接收并重建转换实例。 - 依赖管理:
withExtraPackages会把第三方包写入临时requirements.txt,在扩展服务的构建期与运行期统一安装;用户自建 Python 转换则通过--localPackage指定的 tarball 分发。 - 推理组件复用:Python 侧直接使用
apache_beam.ml.inference的RunInference、KeyedModelHandler、PytorchModelHandlerKeyedTensor,仅在需要控制批大小时通过子类覆盖batch_elements_kwargs。 - 端到端运行:从 Maven archetype 生成工程,到 Dataflow 参数化运行,形成了一条可复制到其他模型/数据集的通用流水线模板。
如需深入阅读,可继续查看 MultiLangRunInference.java、composite_transform.py 以及 PythonExternalTransform.java 的完整实现。