SpringAI实践07 - 本地向量嵌入模型集成指南1.概述本文档详细说明如何在 SpringBoot 应用中集成本地部署的 ONNX 格式向量嵌入模型如bge-small-zh通过spring-ai-starter-model-transformers模块调用 ONNX Runtime 进行文本向量化并对接Milvus向量数据库实现语义检索能力。相比调用远程API 或托管服务本地模型部署具备显著工程与业务优势详见下文专项分析。2.本地向量嵌入模型的核心优势在企业级 AI 应用中选择本地运行向量嵌入模型而非依赖云厂商 API可带来以下关键收益2.1.数据隐私与合规保障敏感文本如用户身份、医疗记录、合同条款无需离开内网或私有云环境规避GDPR、《个人信息保护法》等监管风险模型权重与tokenizer 文件完全由团队自主管控杜绝第三方访问或日志留存隐患。2.2. 离线可用性与业务连续性不依赖外部网络或云服务稳定性在断网、防火墙策略收紧、跨境访问受限等场景下仍可持续提供向量化能力适用于边缘计算、信创环境、金融/政务专网等强隔离要求场景。2.3. 推理延迟与资源可控性本地 CPU/GPU 推理延迟更稳定无网络往返、无排队等待尤其适合高并发低延迟检索如实时客服知识库可精确控制模型加载内存、批处理大小、线程数等参数避免云服务突发限流导致的 QPS 波动。2.4.部署成本长期优化一次性模型下载后零调用费用对比按 Token计费的云API年均成本可显著降低2.5. 模型可定制性与演进能力支持无缝切换不同开源模型无需修改业务代码可基于自有语料微调模型并导出 ONNX实现领域适配如法律文书、医疗报告专用嵌入。3.环境准备与依赖配置3.1. 添加Spring AI Transformers Starter依赖在pom.xml中引入官方支持模块lt;dependencygt;lt;groupIdgt;org.springframework.ailt;/groupIdgt;lt;artifactIdgt;spring-ai-starter-model-transformerslt;/artifactIdgt;lt;/dependencygt;3.2.下载并校验 ONNX模型资源推荐模型BAAI/bge-small-zh中文优化512 维轻量高效下载内容model.onnxONNX 格式模型权重tokenizer.jsonSentencePiece 分词器配置-存放路径示例src/main/resources/onnx/bge-small-zh/3.3.系统兼容性检查Linux 环境ONNX Runtime 依赖特定 GLIBC 版本。执行以下命令验证# 检查GLIBC 版本需 ge; 2.26ldd--version# 检查 libstdc 版本需含 GLIBCXX_3.4.26strings/usr/lib/x86_64-linux-gnu/libstdc.so.6|grepGLIBCXX 若不满足请升级系统或使用 Docker容器如ubuntu:22.04运行应用。4.本地嵌入模型配置与向量库构建4.1.声明TransformersEmbeddingModelBeanBean public TransformersEmbeddingModel getTransformersEmbeddingModel() { TransformersEmbeddingModel transformersEmbeddingModel new TransformersEmbeddingModel(); transformersEmbeddingModel.setModelResource(quot;classpath:/onnx/bge-small-zh/model.onnxquot;); transformersEmbeddingModel.setTokenizerResource(quot;classpath:/onnx/bge-small-zh/tokenizer.jsonquot;); transformersEmbeddingModel.setResourceCacheDirectory(quot;/tmp/onnx-cachequot;); transformersEmbeddingModel.setTokenizerOptions(Map.of(quot;paddingquot;, quot;truequot;)); transformersEmbeddingModel.setModelOutputName(quot;token_embeddingsquot;); return transformersEmbeddingModel; }4.2.构建 Milvus 向量存储BeanBean(name quot;vectorStoreLocalquot;) public VectorStore vectorStoreLocal(MilvusServiceClient milvusServiceClient) { try { TransformersEmbeddingModel transformersEmbeddingModel getTransformersEmbeddingModel(); transformersEmbeddingModel.afterPropertiesSet(); log.info(quot;dimensions : {}quot;, transformersEmbeddingModel.dimensions()); MilvusVectorStore vectorStore MilvusVectorStore.builder(milvusServiceClient, transformersEmbeddingModel) .collectionName(quot;agent_localquot;) .embeddingDimension(transformersEmbeddingModel.dimensions()) .initializeSchema(true) .build(); vectorStore.afterPropertiesSet(); return vectorStore; } catch (Exception e) { throw new RuntimeException(e); } }5.数据写入与语义检索示例5.1.批量写入向量数据库Test void stringReader() { // 添加向量 Document document documentReaderService.stringReader(quot;quot;quot; 我的名字是刘大壮 quot;quot;quot;); Document document1 documentReaderService.stringReader(quot;quot;quot; 我是一个Javaer quot;quot;quot;); Document document2 documentReaderService.stringReader(quot;quot;quot; 我喜欢画画 quot;quot;quot;); Document document3 documentReaderService.stringReader(quot;quot;quot; 我的性别是男 quot;quot;quot;); vectorStore.add(List.of(document, document1, document2, document3)); } public Document stringReader(String doc) { String id UUID.randomUUID().toString(); Document document Document .builder() .text(doc) .id(id) .metadata(quot;idquot;, id) .build(); return document; }5.2.语义相似度查询Test void filterExpressionSearch() { SearchRequest searchRequest SearchRequest.builder() .query(quot;我是女的吗quot;) // .query(quot;我的职业是什么quot;) // .query(quot;我的姓名是什么quot;) // .query(quot;我的爱好是什么quot;) .topK(1) .similarityThreshold(0.5) .build(); // 查询向量 Listlt;Documentgt; documents vectorStore.similaritySearch(searchRequest); for (Document doc : documents) { log.info(quot;doc:{}quot;, doc); log.info(quot;doc.scope:{}quot;, doc.getScore()); } }