Apache Beam 多语言推理实战:用 Java 管道调用 Python BERT 推理转换(multi-language inference)

原创2026-10-09 22:55:191,464 阅读

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 会被编码为 Beam Row(通过 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() 可以看到跨语言调用的完整决策逻辑:

  1. 若未显式指定外部扩展服务地址,框架会检查三个条件:useTransformService 选项、系统是否有可用的 python3/python 可执行文件、是否有 Docker。
  2. 当显式请求使用 Transform Service,或本机没有 Python 但存在 Docker 时,框架启动基于 Docker Compose 的 Transform Service(TransformServiceLauncher),并以独立项目名保证扩展实例隔离。
  3. 否则,框架直接启动本机 Python 扩展服务:运行 apache_beam.runners.portability.expansion_service_main,附带 --port、--fully_qualified_name_glob=*、--pickle_library=cloudpickle,若存在 extra packages 则追加 --requirements_file 指向临时生成的依赖文件,并通过端口就绪探测(最长等待 60 秒)确认服务可用。
  4. 参数最终封装为 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 上的 .pth state_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-runner profile 会引入 Dataflow Runner 相关依赖;
  • 由于推理在 cuda:0 上执行,Dataflow 工作节点(Worker)需配置 GPU 规格,Python 侧依赖(transformers、torch)会随扩展服务自动安装。

八、小结

本示例完整展示了 Apache Beam 多语言推理的标准范式:Java 管道负责 I/O 与编排,Python 端以自定义 PTransform 形式封装机器学习推理,双方通过 PythonExternalTransform 与自动启动的扩展服务无缝衔接。关键知识点可归纳为:

  1. 跨语言参数传递:Java 侧 withKwarg 传入的参数,经 payload 编码后由 Python 侧 from_runner_api_parameter 接收并重建转换实例。
  2. 依赖管理:withExtraPackages 会把第三方包写入临时 requirements.txt,在扩展服务的构建期与运行期统一安装;用户自建 Python 转换则通过 --localPackage 指定的 tarball 分发。
  3. 推理组件复用:Python 侧直接使用 apache_beam.ml.inference 的 RunInference、KeyedModelHandler、PytorchModelHandlerKeyedTensor,仅在需要控制批大小时通过子类覆盖 batch_elements_kwargs。
  4. 端到端运行:从 Maven archetype 生成工程,到 Dataflow 参数化运行,形成了一条可复制到其他模型/数据集的通用流水线模板。

如需深入阅读,可继续查看 MultiLangRunInference.java、composite_transform.py 以及 PythonExternalTransform.java 的完整实现。

登录后查看全文
beam