Java 程序员第 49 阶段11：Java 接 BERT：用 ONNX Runtime 做句向量推理

1. 为什么「Java 接 BERT：用 ONNX Runtime 做句向量推理」值得 Java 工程师专门吃透

在大模型工程落地里，这个话题绕不开。很多 Java 同学刚接触时容易只看结论、不究原理，一旦线上出问题就无从下手。先把「为什么重要」说清楚，后面才好理解它怎么用。

不要在 Java 里训练 BERT，正确姿势是 Python 侧微调后导出 ONNX，Java 用 ONNX Runtime 推理。

（见图 figure_11_1）

2. 「Java 接 BERT：用 ONNX Runtime 做句向量推理」的核心定义与能力边界

先用一句话给概念下定义，再划清它的能力边界------什么它能做、什么它做不了。边界感比死记公式更重要。

导出时把 batch=1、seq 固定或动态轴，避免线上 shape 不匹配导致崩溃。

3. Java 接 BERT：用 ONNX Runtime 做句向量推理的底层工作机制拆解

它不是黑盒，拆开看就是几个清晰的步骤。下面按执行顺序逐步说明，建议结合你自己的业务场景在脑子里走一遍。

取 [CLS] 位置隐藏向量作为句向量，再做 L2 归一化即可用于余弦相似度检索。

（见图 figure_11_2）

4. Java 工程侧如何落地（含代码示例）

对 Java 工程师来说，最终要落到代码和工程集成上。下面给出可运行的骨架，重点是理解「数据流怎么走、异常怎么兜」。

多并发下复用 OrtSession（线程安全）并控制并发数，避免显存/内存被打爆。

（见图 figure_11_4）

5. 与相近方案的对比取舍

它不是唯一解法，和它容易混淆的还有几个方案。一张表看清区别与取舍，选型时才不踩坑。

三种主流做法的取舍见下方对比表。判断标准其实很简单：团队有没有能力长期维护「ONNX」，以及业务对延迟和成本的容忍度有多高------这两个答案基本就决定了选型。

（见图 figure_11_3）

6. 生产环境踩坑与面试高频点

真正用过的人，踩过的坑都差不多。这里把最常见的几个和对应的面试追问列出来，提前避坑、也方便复盘。

最常见的坑有三个：一是把「ONNX」当银弹，完全不做兜底；二是调用不设超时，慢请求把业务线程池打满；三是线上没有埋点，出了问题无法定位。面试常追问「超时和降级怎么设计」，照下方代码的思路回答即可。

java 复制代码

// 用 ONNX Runtime 在 Java 侧跑 BERT 句向量（伪代码骨架）
public class BertEncoder {
    private final OrtSession session; // 已导出 bert.onnx
    public float[] encode(String text) throws Exception {
        // 1) tokenizer 转 inputIds / attentionMask / tokenTypeIds
        long[][] inputIds = Tokenizer.encode(text);
        // 2) 构造 OrtValue 入参
        Map<String, OnnxTensor> feeds = Map.of(
            "input_ids", tensor(inputIds),
            "attention_mask", tensor(mask(inputIds)));
        // 3) 前向，取 [CLS] 位置向量
        OrtSession.Result r = session.run(feeds);
        float[][][] hidden = (float[][][]) r.get(0).getValue();
        return hidden[0][0]; // [CLS] -> 句向量
    }
}

方案	适用场景	优点	缺点	选型建议
直接调用模型 API（自研封装）	「ONNX」场景简单、调用量小	链路最短、完全可控、无额外依赖	超时/重试/兜底都要自己补齐	起步阶段首选
框架封装（Spring AI / LangChain4j）	需要快速集成「推理」	开箱即用、生态成熟、样板代码少	抽象层不透明，排障成本高	中小团队提效首选
平台化（统一网关 + 多模型路由）	多业务线、需治理与「Java」成本核算	可观测、可限流、可切换模型	建设和维护成本最高	上规模后再做