SpringAI集成本地嵌入模型：从Ollama到RAG实战指南-代码聚汇网

SpringAI集成本地嵌入模型：从Ollama到RAG实战指南

投研帮·2026-08-29·阅读 22 GEO检测（免费）

SpringAI本地嵌入模型Ollama

|难度：普通|阅读约 34 分钟

自己跑过几个SpringAI项目之后，我越来越觉得嵌入模型这块是很多人的分水岭。聊到RAG、知识库问答，大家默认就去找OpenAI或各类云端嵌入接口，但一落地就发现三个很现实的问题：费用、数据合规、网络延迟。于是本地向量嵌入模型成了绕不开的话题。这篇文章是我在做SpringAI实践系列第07篇时整理出来的集成指南，目标是帮你在SpringAI里把本地嵌入模型完整跑起来，从模型选型、环境准备到代码打通，一条龙说清楚。

我这里以Spring AI 1.0.0版本、Spring Boot 3.3.x作为基础环境来演示。整个过程我已经在本地跑通，代码结构不复杂，重点是理解嵌入模型在整个RAG链路里的位置，以及为什么本地方案越来越吃香。

1. 为什么要集成本地向量嵌入模型

1.1 嵌入模型到底在解决什么问题

先聊个基础认知。向量嵌入（Embedding）是一片文本经过模型推理之后得到的一组浮点数，这组数字可以理解为文本在语义空间里的坐标。两段语义相近的文本，它们的坐标距离会非常近。RAG（检索增强生成）的核心就依赖这一步：你先把文档切成片段，每段做嵌入存进向量库；用户提问时，把问题也转成向量，在库里找最相近的片段，丢给大模型做参考回答。

你如果不用嵌入模型，RAG就是空中楼阁，大模型只能凭自己的训练知识瞎猜，没法回答你的私有文档。所以，嵌入模型是整个检索链路里最基础、也最不能出错的一环。

SpringAI把嵌入模型统一抽象成了EmbeddingModel接口。好处体现得很直接：你上午用OpenAI的嵌入接口做验证，下午想换成本地模型，代码基本不用动，只改配置和依赖即可。这种抽象设计让本地嵌入模型的集成门槛降了很多。

1.2 本地方案和云端API的本质区别

云端API的嵌入模型用起来确实简单——申请个Key，调个接口，完事。但真实的项目当中，这套路经常卡壳。

首先是数据隐私问题。你的文档内容全都要发给第三方服务，等于把企业内部的合同、客服对话、业务数据递到了别人手里。很多金融、政务类项目在这一步就过不了合规评审。其次是成本问题，别以为嵌入接口很便宜，文档量一大，一次性处理几十万条文本，账单数字还是很刺激的。最后是延迟和稳定性，每次检索都要走网络，一次请求多几百毫秒，链路的体验差距就出来了。

本地方案把这三个问题一次性解决。模型跑在你自己的机器上，数据完全不出内网，调用走本地端口，延迟稳定在毫秒级，一次部署后没有按量计费的压力。当然，代价是你需要一块能跑的硬件，以及花点心思处理模型的部署与维护。

1.3 本地方案适合哪些项目和团队

我个人的判断是：如果你的项目满足下面任意一条，本地嵌入模型就值得优先考虑。

企业内部知识库问答系统，文档涉及内部数据或客户隐私；
面向国内业务场景，需要稳定可控的调用链路；
文档规模较大，长期调用云端API费用肉疼；
离线环境运行，整个系统不接触公网；
刚入门学习RAG，想省掉API费用反复做实验。

反过来，如果你只是做个演示Demo，本地有几张GPU或者普通CPU，临时验证流程，那用云端嵌入接口也不冲突。我自己的习惯是学习和测试阶段都用本地，线上才根据场景定。不过说句实话，本地嵌入模型的精度已经追得很紧了，多数业务场景完全够用。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 本地嵌入模型选型与知识点储备

2.1 主流的本地嵌入模型选哪个

先看市面上能用的本地嵌入模型。我按实际使用的频率和场景列一下。

模型名称	参数规模	向量维度	语言能力	硬件要求	推荐场景
BGE系列（如bge-large-zh-v1.5）	约3.3亿	1024	中英文强	中低显存CPU可跑	中文文档、知识库
BGE-M3	约5.7亿	1024（可调）	多语言强	中高配置	多语言混合文档
nomic-embed-text	约1.37亿	768	英文强中文一般	低配即可	英文场景、通用测试
M3E（m3e-base）	约1亿	768	中英文均衡	极低配即可	入门学习、轻量场景
all-MiniLM-L6-v2	约2200万	384	英文为主	极低配	快速验证、英文RAG
bge-small-zh-v1.5	约2400万	512	中文为主	极低配	中文轻量场景

表格仅供参考，真正选型时还要看你的文档语言和精度要求。中文项目我一般直接从BGE系起步。bge-m3是目前综合能力很强的模型，多语言检索、文档切分重排序都能做，不过体积不算小。如果机器配置紧张，bge-small-zh是很好的入门选择。

nomic-embed-text是Ollama上最容易拉下来跑通的模型之一，英文效果好，中文效果确实一般，纯中文项目我不推荐拿它当主力。我试过一次用它处理中文客服工单的检索，Top5命中率比BGE明显差一个档次，所以别图省事随便拉个模型就跑中文场景。

2.2 向量维度和上下文长度怎么理解

向量维度影响的是存储空间和检索精度之间的平衡。维度越高，语义表达越精细，但向量库占用越大，检索时的计算量也越大。一个经典的公式是这样算的：如果向量维度是1024，float32类型存储每个向量占4KB（1024×4字节），一万条文档就是40MB左右，看起来不大，但文档一旦到了百万级别，存储和检索压力就体现出来了。

上下文长度决定了模型处理文本的“截断策略”。嵌入模型大多有最大输入长度限制，比如512个token或2048个token。超过这个长度，文本会被截断或报错。所以做文档切分时，片段大小要跟模型的输入上限对齐。我常用的切分策略是300到500个token一段，既保证语义相对完整，又不至于超过模型限制。

2.3 模型部署方式：Ollama、ONNX、Transformers

本地嵌入模型跑起来有几种常见姿势，选哪种取决于你的SpringAI版本和使用场景。

Ollama方案（最推荐）

Ollama是我日常用得最多的本地模型管理工具，一条命令即可拉模型、起服务。你只需要先安装Ollama，然后拉取嵌入模型：

bash复制ollama pull bge-m3

然后它会自动在本地11434端口起一个OpenAI兼容的API服务，SpringAI通过spring-ai-ollama模块直接对接。优点很突出：模型管理、依赖处理、API兼容都帮你处理好了，不用写一堆加载代码。缺点是比较吃系统资源，模型常驻内存。

ONNX Runtime方案

如果你的项目里不想依赖Ollama，需要用代码层面严格控制模型加载，ONNX Runtime是个轻量选择。SpringAI官方提供了spring-ai-onnx-extension模块，配合ONNX格式的嵌入模型使用。这个方案的好处是无外部服务依赖，缺点是配置相对繁琐，模型转换过程对新手不太友好。

Transformers方案

Java生态里完全复刻Python的Transformers不现实，但SpringAI可以通过一些桥接项目加载HuggingFace格式模型。这个路线配置更重，还需要处理Python侧的依赖，我一般不在生产环境里推荐。

我的建议很明确：普通SpringBoot项目，优先走Ollama；对部署形态要求严格、无法装额外服务的，再考虑ONNX。

3. SpringAI集成实战：从依赖到第一个向量

3.1 工程结构与依赖引入

我以一个标准的SpringBoot项目为例，假设你已经用Spring Initializr建好了工程，Java版本17以上，Spring Boot版本3.3.x。

先加依赖。我用的是Maven，核心就两个：

xml复制<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-bom</artifactId>
    <version>1.0.0</version>
    <type>pom</type>
    <scope>import</scope>
</dependency>

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-ollama-spring-boot-starter</artifactId>
</dependency>

第一段是SpringAI的BOM依赖管理，统一锁版本。第二段是Ollama的Starter，它会自动装配OllamaEmbeddingModel所需的全部Bean，内部依赖包括SpringAI核心的spring-ai-client-chat和spring-ai-model。

如果你的项目里之前用过OpenAI或DashScope的starter，这俩可以共存。SpringAI按spring.ai.model.embedding配置决定装配哪个实现，不冲突。

3.2 配置Ollama本地嵌入模型

依赖加好之后，在application.yml里面加配置：

yaml复制spring:
  ai:
    ollama:
      base-url: http://localhost:11434
      init:
        pull-model-strategy: when-missing
        timeout: 60s
      embedding:
        options:
          model: bge-m3

逐项解释一下：

base-url：Ollama服务的地址，默认就是localhost:11434，如果你把Ollama装在另一台机器上，改成对应IP。
init.pull-model-strategy：这里设置成when-missing，意思是在本机没有对应模型时自动拉取。这个配置在测试环境很实用，不用手动去命令行拉模型。
init.timeout：拉取模型时的超时时间。bge-m3体积不小，首次拉取可能耗时较长，超时设短了容易失败。
embedding.options.model：指定嵌入模型名称，这里我用的是bge-m3，确保和Ollama里拉取的模型保持一致。

有一点要提醒：如果是首次启动，Ollama拉取模型需要一些时间，日志里会出现下载进度。如果网络状况不太好，下载可能失败，建议先手动执行ollama pull bge-m3确保模型已就绪，再把pull-model-strategy改成never避免重复检查。

3.3 代码实现与调用验证

SpringAI的自动装配把EmbeddingModel这个Bean放进容器里了。你直接注入就能用，不用手写任何客户端初始化代码。

写一个测试接口：

java复制@RestController
@RequestMapping("/embedding")
public class EmbeddingController {

    private final EmbeddingModel embeddingModel;

    public EmbeddingController(EmbeddingModel embeddingModel) {
        this.embeddingModel = embeddingModel;
    }

    @GetMapping("/test")
    public Map<String, Object> test(@RequestParam(defaultValue = "SpringAI本地嵌入模型实践") String text) {
        EmbeddingResponse response = embeddingModel.embedForResponse(List.of(text));
        Embedding embedding = response.getResult().getOutput();
        return Map.of(
                "dimensions", embedding.getDimension(),
                "vector", embedding.getVector()
        );
    }
}

启动项目，访问/embedding/test?text=你好，返回结果大概是这样的：

json复制{
  "dimensions": 1024,
  "vector": [0.0234, -0.0156, 0.0877, "..."]
}

看到dimensions为1024，说明你的bge-m3模型已经成功跑起来了。这里有个小细节：embedForResponse返回的是EmbeddingResponse，里面可能包含多个向量结果，当传入多个文本时，可以一次性批量嵌入。如果你只需要单个文本的向量，用embed方法更简洁：

java复制float[] vector = embeddingModel.embed("要转换的文本");

两个方法在源码里都有，使用频率上来看，批量场景用embedForResponse更多。

4. 向量存储与检索链路打通

4.1 向量库选型：从内存到生产级

嵌入模型只负责把文本变成向量，真正干活还得靠向量库。SpringAI对向量库做了统一的VectorStore抽象，支持的实现有内存版、PGVector、Milvus、Redis、Elasticsearch等。我按项目不同阶段给你选型建议：

学习验证阶段：直接用SimpleVectorStore，数据全在内存里，重启即丢失，适合跑通流程。
小型项目或内网工具：用PGVector，PostgreSQL插件方案，不引入额外中间件，运维成本低，中等数据量完全够用。
中大型生产项目：Milvus或Qdrant，支持分布式、大规模检索、混合索引。

我这里用SimpleVectorStore做演示，因为它不用额外安装任何中间件，可以把注意力集中在嵌入和检索链路上。

4.2 基于SimpleVectorStore的快速检索演示

配置方式很简单。先加依赖：

xml复制<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-vector-store</artifactId>
</dependency>

然后注册一个SimpleVectorStore的Bean：

java复制@Configuration
public class VectorStoreConfig {

    @Bean
    public VectorStore vectorStore(EmbeddingModel embeddingModel) {
        return SimpleVectorStore.builder(embeddingModel).build();
    }
}

接着就可以往里面写文档和做检索了。我写一个完整的服务示例：

java复制@Service
public class KnowledgeService {

    private final VectorStore vectorStore;

    public KnowledgeService(VectorStore vectorStore) {
        this.vectorStore = vectorStore;
    }

    public void addDocument(String content, String docId) {
        Document document = new Document(content, Map.of("docId", docId));
        vectorStore.add(List.of(document));
    }

    public List<Document> search(String query, int topK) {
        return vectorStore.similaritySearch(query, topK);
    }
}

调用示例：

java复制knowledgeService.addDocument("SpringAI是Spring生态中的AI应用开发框架。", "doc1");
knowledgeService.addDocument("本地嵌入模型可以把文本转换为向量表示。", "doc2");
knowledgeService.addDocument("向量数据库支持近似的语义相似检索。", "doc3");

List<Document> results = knowledgeService.search("有没有办法做语义搜索", 2);

返回结果会按相似度从高到低排列，doc3和doc2应该在前面，因为它们的语义和“语义搜索”更接近。这里可能有人会问：similaritySearch内部是怎么工作的？其实就是把你传进去的query也做一次嵌入，然后跟库里所有的向量做余弦相似度计算，按分数排序返回TopK。SimpleVectorStore是暴力计算，数据量过万时会变慢，生产场景建议换成PGVector或Milvus。

4.3 与本地LLM组合成标准RAG链路

既然嵌入和向量库都打通了，我们把它和本地大模型串起来，形成一个最简单的RAG问答链路。这里我同时配置一个Ollama上的ChatModel，比如qwen2.5或deepseek-r1。

java复制@Service
public class RagService {

    private final ChatModel chatModel;
    private final VectorStore vectorStore;

    public RagService(ChatModel chatModel, VectorStore vectorStore) {
        this.chatModel = chatModel;
        this.vectorStore = vectorStore;
    }

    public String ask(String question) {
        List<Document> docs = vectorStore.similaritySearch(question, 3);
        String context = docs.stream()
                .map(Document::getText)
                .reduce((a, b) -> a + "\n" + b)
                .orElse("");

        String prompt = """
                请基于以下资料回答问题，如果资料中没有答案，请直接说不知道。
                资料：
                %s
                问题：%s
                """.formatted(context, question);

        return chatModel.call(prompt);
    }
}

这里我用Ollama作为ChatModel，配置同样是走spring-ai-ollama-spring-boot-starter，ChatModel和EmbeddingModel自动装配不冲突，一个端口两种模型。

代码逻辑不复杂，但有几个细节需要注意。文档切分粒度、检索TopK值、Prompt模板，这三样东西直接决定最终回答质量。TopK太小容易漏信息，TopK太大又会在Prompt里塞入无关片段干扰模型判断。我实测下来，知识库问答场景3到5是个合适的区间，你可以根据自己的文档情况慢慢试。

5. 常见问题与排查实录

5.1 向量维度不匹配导致写入失败

本地嵌入模型换过之后，最容易踩的坑就是维度不匹配。比如之前用nomic-embed-text，向量维度是768，向量库里的Collection也是按768建的，后来换成bge-m3，维度变成1024，再写入就报错。

这个问题在PGVector上尤其常见，因为表结构里向量列的维度是建表时定死的。解决办法分两步：先确认当前模型的维度，再用新维度重建Collection。SpringAI的VectorStore在写入时不会自动升级维度，这个设计其实是合理的，避免你无意识改坏线上数据结构。我的建议是：项目初期就确定好嵌入模型，尽量别中途切换。如果必须换，记得同步清理旧向量数据。

5.2 中文检索效果差，哪些环节最容易出问题

中文效果差，很多人第一反应是“模型不行”，但排查下来往往是其他环节的问题。

第一，切分粒度过粗或过细。过粗的切分导致一个片段里包含多个主题，向量被“平均”了，检索时哪边都不挨着；过细的切分导致单个片段语义不完整。中文文本我建议每段控制在200到400字之间，根据实际内容调整。

第二，查询词和文档的表述差异太大。比如文档里写“退款政策”，用户问“我怎么把钱要回来”，两者字面上八竿子打不着，但语义上是一回事。要解决这个问题，除了换更强的模型，还可以在查询侧做一层Query改写，把口语问题转成更接近文档风格的表达。这个技巧在中文RAG里非常有效。

第三，停用词干扰。有些标点、语气词会把向量拉偏。我在处理客服类文本时，会先做简单的清洗，去掉无意义字符，再送进嵌入模型，效果会有可见提升。

5.3 连接DeepSeek等远程ChatModel时无content输出

这个热搜词我盯了很久：“springai连接deepseek不输出content”。虽然DeepSeek不是本地模型，但很多人把本地嵌入模型和DeepSeek组合使用，正好容易碰到这个问题。

我复现过几次，现象是请求不报错，但响应里的content字段是空的，或者只有reasoning_content没有正文。根因基本出在两条：一是模型本身输出了较长的思考内容，在响应解析时被SpringAI误判为最终回答；二是使用了一些兼容OpenAI格式的代理服务，响应结构里没有按标准填充content字段。

排查思路是这样：先用curl直接调DeepSeek接口，看原始返回的JSON结构对不对。如果choices[0].message.content确实有值，那就是SpringAI解析层的问题，检查一下你用的ChatModel客户端版本；如果原始返回里content就是空的，那问题出在模型调用参数上，比如参数stream设置不当或temperature设置过低。实际项目里，还有一例是用了自定义的RestClient拦截器把响应体空转了，这需要逐个环节排查。

如果你也在搞这个组合，我提一句：调用本地模型和云端模型时，最好把Prompt模板和响应解析分开测试，先确认ChatModel和EmbeddingModel各自独立工作，再合到一起看，不然问题定位会非常痛苦。

5.4 模型加载慢、内存占用过高怎么办

本地嵌入模型虽然比生成式大模型轻量不少，但也不是没有资源压力。bge-m3跑起来大概要占2GB到4GB内存，如果是小内存机器，建议换更小的bge-small-zh或m3e-base。可以在Ollama的环境变量里配置并发限制，比如同时最多加载两个模型：

bash复制OLLAMA_MAX_LOADED_MODELS=2

还有个实用技巧：用OLLAMA_KEEP_ALIVE控制模型在内存里的驻留时间。默认情况下，模型空闲5分钟会从内存卸载。如果你的应用请求频率比较高，可以把驻留时间调长，避免频繁加载拖慢响应：

bash复制OLLAMA_KEEP_ALIVE=30m

启动后可以用ollama ps查看当前哪些模型在内存里，占用多大，实时确认资源情况。

5.5 批量嵌入性能优化

批量嵌入是容易忽略的性能优化点。很多人写循环逐条调用embed方法，一次存一万条文档就调一万次HTTP接口，慢得出奇。SpringAI的EmbeddingModel支持传入List<String>批量调用，Ollama侧也会做并行推理，效率能提升好几倍。

正确姿势：

java复制List<String> texts = documents.stream()
        .map(Document::getText)
        .toList();

EmbeddingResponse response = embeddingModel.embedForResponse(texts);

还要注意批量大小，我实测Ollama在每批32到64条左右表现比较稳定，再大可能出现超时或内存峰值。分批提交、每批确认返回后继续下一批，比一次性塞几千条要稳得多。

写在最后的个人体会

做本地嵌入模型这块，前前后后踩了不少坑，最深的感受是：嵌入模型是RAG里最不起眼但最值得花时间选型的环节。很多人把精力全放在Prompt和大模型调优上，轮到嵌入模型就随便选一个，结果检索阶段就漏了关键信息，后面再怎么调Prompt都救不回来。嵌入质量决定召回上限，大模型只是在召回结果基础上做精炼和回答，这个逻辑一定要想清楚。

另外一个建议是，本地嵌入模型部署好之后，一定要做一套固定测试集验证效果。每次更换模型或参数，把同一批测试文档和问题跑一遍，记录TopK命中率。没有这个底座，你很难判断改动到底变好了还是变差了。

如果你正打算把SpringAI项目里的嵌入链路切到本地，或者刚开始接触这块，希望这篇指南能帮你少走点弯路。有问题欢迎在评论区聊聊，人多的话我再整理一份关于本地嵌入模型与PGVector结合生产的配置细节。