前段时间尝试了一个很有意思的项目——原本只是想在 Spring AI 项目中顺手集成 ONNX 模型，结果一上手就停不下来，直接调试到凌晨两点，边调边感慨：整个过程也太丝滑流畅了。
今天就来深入聊聊这件事：如何在 Spring AI 中使用 ONNX 向量模型，实现本地化的文本嵌入能力。
如果你之前没有接触过 ONNX，也别担心——读完这篇文章，你不仅会理解其中的原理，还能亲手运行一个完整的 demo。
什么是 ONNX 向量模型？
先明确 ONNX 是什么。
全称 Open Neural Network Exchange，由微软和 Facebook 联合推出的开放标准。其核心目标，就是让不同 AI 框架之间的模型能够互相转换与运行。TensorFlow 的模型、PyTorch 的模型、MXNet 的模型……都可以转换为 ONNX 格式，并跨框架、跨语言、跨硬件进行推理。
打个比方，ONNX 像是 AI 模型界的“世界语”，各框架的模型都能通过它无障碍交流。
那“向量模型”呢？Spring AI 在 2024 年版本中开始原生支持 ONNX Embedding Model，这意味着：
- 你可以在本地直接运行嵌入模型，
- 完全无需依赖 OpenAI 或任何云端 API，
- 离线可用，速度快，且零成本。
经过实际的中文文本相似度任务测试，效果相当不错，延迟比在线模型低了数倍。
先决条件：动手前你需要准备什么？
先把开发环境搭建好。下面是整理出的完整清单：
1. 安装依赖
Spring AI 对 ONNX 的支持依赖于 onnxruntime 库。如果是在 Java 项目中使用 Spring Boot + Spring AI，需要在 pom.xml 中引入：
（此处为代码块，保留原文位置）
2. 模型文件
需要准备一个 ONNX 格式的向量模型，例如：
- all-MiniLM-L6-v2.onnx
- bge-small-zh-v1.5.onnx（中文场景强烈推荐）
将模型文件放入资源目录下即可，例如：src/main/resources/models/
3. Spring Boot 环境
- JDK 17+
- Spring Boot 3.3+
- Spring AI 最新版（建议 1.0.0+）
自动配置：Spring AI 已为你准备好一切
这是 Spring AI 最令人满意的地方——几乎无需额外配置。
只需在 application.yml 中简单写几行配置，Spring AI 就能自动识别并加载 ONNX 模型。例如：
（此处为代码块，保留原文位置）
启动应用时，Spring 会自动注册一个 OnnxEmbeddingModel Bean。然后在业务代码中直接注入使用：
（此处为代码块，保留原文位置）
没有密钥、没有 API 调用、没有网络延迟。本地模型，几乎零成本运行。
Embedding 属性
系统化地看一下 Spring AI 中 ONNX 向量模型的关键属性配置：
（此处为代码块，保留原文位置）
注意：
model-type用来指定模型类型，比如 text 或 image；cache.enabled可以开启嵌入结果缓存，对重复查询性能提升明显。
错误与特殊情况
开发中最怕什么？启动时一切正常，一用就立刻报错。
下面是调试 ONNX 向量模型时容易踩的几个典型坑，整理成表格：
（此处为表格，保留原文位置）
这些坑我几乎都踩过一遍。看到别人问同样的问题，总有一种“老熟人”的亲切感。
手动配置（高级玩法）
自动配置虽然方便，但某些场景需要更灵活的控制。例如：
- 动态选择不同的 ONNX 模型；
- 根据业务逻辑切换中英文模型；
- 手动管理模型的生命周期。
此时你可以选择手动配置 Bean。示例代码如下：
（此处为代码块，保留原文位置）
业务代码中的使用方式保持一致：
（此处为代码块，保留原文位置）
这种方式适合中大型项目，尤其是当需要支持多语言、多模型切换时更加得心应手。
实测心得
使用 bge-small-zh-v1.5.onnx 模型在本地进行了几组实验：
- 文本长度：20～200 字不等
- 平均嵌入耗时：0.02 秒
- 模型加载时间：约 1.5 秒（首次）
- 相似度检索准确率：与 OpenAI text-embedding-3-small 接近
最直接的感受就是：离线部署、无 token 限制、无网络延迟。尤其是在知识库问答类项目中，本地 embedding 带来的那种“自由呼吸”的体验，确实令人愉悦。
总结：ONNX，让 Spring AI 更“自由”
回过头来看，Spring AI + ONNX 的组合，确实让人眼前一亮。
过去使用 OpenAI API 做嵌入时，总是担心：
- token 消耗过快；
- 请求超时；
- 模型限速；
- 数据是否需要脱敏上传。
现在有了 ONNX，模型本地化、性能可控、成本几乎为零。这才是真正属于开发者的自由。
结尾引用一句特别喜欢的话：
ONNX 就是这样的存在——让我们不再受限于厂商，让 Spring AI 更开放、更独立。
希望你看完后，也能在某个深夜，用自己的模型跑出属于你的“向量世界”。
互动时间
你用过哪些本地 embedding 模型？有没有踩过类似的坑？欢迎在评论区聊聊。
