03.Spring AI Embedding 实战：从向量化原理到项目落地

Embedding 介绍

**Embedding（向量化）**是指把文本、图片、音频等非结构化数据，通过模型映射为一段固定维度的浮点数向量。这段向量可以理解为数据在高维语义空间中的"坐标"，语义越接近的内容，其向量在空间中的距离也越近。

在 Spring AI 中，Embedding 由 EmbeddingModel 接口统一抽象，核心方法 embed(String text) 返回一个 float[]，embedForResponse(List<String> texts) 则支持批量向量化。不同模型输出的维度不同，例如常见的 1024 维、1536 维、3072 维等，使用时需要保证同一知识库内所有向量来自同一个模型，否则维度不一致会导致检索失败。

Embedding 的核心作用

语义检索：把用户问题和知识库文档都转成向量，通过余弦相似度或欧氏距离找出最相关的内容，这是 RAG（检索增强生成）的基础。
语义相似度计算：判断两段文本是否表达相同含义，可用于去重、聚类、意图识别等场景。
向量数据库存储：将向量写入 Redis、Milvus、PgVector、Elasticsearch 等向量库，实现大规模相似度搜索。
多模态对齐：文本与图片向量化到同一空间后，可以实现"以文搜图"等跨模态检索。

Embedding 与 LLM 的关系

Embedding 模型和对话大模型是两类不同的模型：前者负责"把内容变成向量"，后者负责"根据上下文生成回答"。在 RAG 流程中，二者配合使用------先用 Embedding 模型召回相关文档片段，再把片段拼进 Prompt 交给对话模型生成最终答案。因此，Embedding 的质量直接决定了检索的召回率，也间接影响了大模型回答的准确性。

Embedding 的典型使用场景

Embedding 并不直接产出答案，它的价值在于把"语义"变成可计算、可比较的数值。下面这些场景是工程实践中最常见的落地方向。

1. RAG 知识库问答

这是目前最主流的用法。把文档资料切分成片段后逐条向量化，写入向量数据库；用户提问时，先把问题向量化，再检索出 Top-K 个最相似的片段，拼进 Prompt 交给对话模型生成答案。相比把整篇文档塞进上下文，这种方式既节省 Token，又能显著提升回答的准确性和可追溯性。

2. 语义搜索

传统关键词搜索依赖字面匹配，用户搜"怎么退款"可能匹配不到标题为"售后流程说明"的文档。改用向量检索后，只要语义相近就能被召回，特别适合站内搜索、文档检索、代码检索等场景。实践中常把关键词检索与向量检索组合成混合检索，兼顾精确匹配和语义泛化。

3. 文本去重与聚类

把一批文本全部向量化后计算两两相似度，超过阈值即可判定为重复或高度相似内容，可用于新闻去重、评论清洗、工单归并。配合 KMeans、DBSCAN 等聚类算法，还能自动把海量用户反馈归成若干主题，帮助快速发现高频问题。

4. 推荐与召回

把用户历史行为（浏览、点击、收藏的文章或商品）向量化后取平均，得到用户兴趣向量，再与候选内容向量做相似度计算，即可实现"猜你喜欢"式的语义召回。相比基于 ID 的协同过滤，这种方式对冷启动内容更友好。

5. 分类与意图识别

为每个类别准备若干条代表性样本并向量化，新文本进来后与各类别样本比较相似度，取最相近的类别即可完成零样本或少样本分类。常见于工单自动分派、情感倾向判断、客服意图路由等场景，无需训练模型即可快速上线。

6. 多模态检索

CLIP 类模型可以把图片和文本映射到同一向量空间，从而实现"以文搜图""以图搜图"。电商商品检索、素材库管理、相册智能搜索都是典型应用。

7. 异常检测与风控

正常样本的向量往往聚集在特定区域，当新样本向量与正常簇的距离明显偏大时，可作为异常信号。这种方式可用于垃圾评论识别、刷单行为发现、日志异常聚类等场景。

场景选择建议

需要给出答案：优先考虑 RAG，Embedding 负责召回，LLM 负责生成。
只需要找到相关内容：直接用语义搜索，成本更低、响应更快。
数据量大且重复多：先做向量去重和聚类，再进入后续流程。
没有标注数据：用 Embedding 做少样本分类，比训练模型更快落地。

需要注意的是，Embedding 的效果高度依赖模型选择和数据质量。同一业务场景下，建议先用真实样本对比几个候选模型的召回效果，再决定最终方案；同时要保证入库向量和查询向量使用同一个模型、同一套预处理逻辑。

模型选择

Spring AI 通过统一的 EmbeddingModel 抽象屏蔽了不同厂商的差异，只要引入对应的 starter 依赖并完成配置，就可以在代码中无差别地调用。具体支持哪些向量化模型，可以参考官方文档：

Embeddings Model API :: Spring AI Reference

选择模型时，建议重点关注以下几个维度：

向量维度：维度越高表达能力通常越强，但存储和计算成本也越高，需要结合数据规模权衡。
语言支持：中文场景要确认模型对中文语料的语义效果，最好用真实业务样本做对比测试。
调用成本与限流：批量入库时要注意接口的 QPS 限制和计费方式，必要时做分批与重试。
可替换性：尽量通过配置切换模型，避免把模型名称硬编码在业务代码里。

项目示例

下面用一个最小可运行的 Spring Boot 工程演示如何接入 Embedding 模型，并对外提供一个向量化接口。示例使用 Spring AI 的 starter 依赖，模型通过配置文件指定。

pom

XML 复制代码

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>com.erbao</groupId>
        <artifactId>SpringAI</artifactId>
        <version>1.0-SNAPSHOT</version>
    </parent>
&lt;artifactId&gt;EmbeddingModels&lt;/artifactId&gt;
&lt;properties&gt;
&lt;maven.compiler.source&gt;17&lt;/maven.compiler.source&gt;
&lt;maven.compiler.target&gt;17&lt;/maven.compiler.target&gt;
&lt;project.build.sourceEncoding&gt;UTF-8&lt;/project.build.sourceEncoding&gt;
&lt;/properties&gt;
&lt;dependencies&gt;
&lt;dependency&gt;
&lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;
&lt;artifactId&gt;spring-boot-starter-web&lt;/artifactId&gt;
&lt;/dependency&gt;
&lt;dependency&gt;
&lt;groupId&gt;org.springframework.ai&lt;/groupId&gt;
&lt;artifactId&gt;spring-ai-starter-model-zhipuai&lt;/artifactId&gt;
&lt;/dependency&gt;
&lt;/dependencies&gt;
</project>

配置

XML 复制代码

spring.application.name=SpringAIEmbedding
server.port=8080
# Embedding 模型配置，需要在 pom.xml 中引入对应 starter 依赖
spring.ai.zhipuai.api-key=your-api-key
spring.ai.zhipuai.base-url=https://open.bigmodel.cn/api/paas
spring.ai.zhipuai.embedding.options.model=Embedding-3
# Chat 模型配置，需要在 pom.xml 中引入对应 starter 依赖
spring.ai.zhipuai.chat.options.model=GLM-4.7-Flash

配置中有两点容易踩坑：一是 api-key 不要提交到代码仓库，建议通过环境变量或配置中心注入；二是 base-url 需要按 Spring AI 的要求填写，部分厂商文档里的路径带有版本号前缀，原样配置可能导致调用报错，具体以官方文档和实际调试结果为准。

启动类

java 复制代码

package com.erbao;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class EmbeddingModelsApplication {
public static void main(String[] args) {
	SpringApplication.run(EmbeddingModelsApplication.class, args);
}
}

向量化

java 复制代码

package com.erbao.rest;
import org.springframework.ai.embedding.EmbeddingModel;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import java.util.Map;
@RestController
@RequestMapping("/embedding")
public class EmbeddingController {
@Autowired
private EmbeddingModel embeddingModel;
/**
获取文本的嵌入向量
@param message 用户输入的文本
@return 包含消息和嵌入向量的Map
*/
@GetMapping
public Map<String, Object> getEmbedding(@RequestParam(defaultValue = "给我讲个笑话") String message) {
float[] embed = embeddingModel.embed(message);
return Map.of("message", message, "embedding", embed);
}
}

启动项目后访问 http://localhost:8080/embedding?message=你好，即可看到返回的向量数组。实际业务中通常不会直接把整个向量返回给前端，而是写入向量数据库，供后续的相似度检索使用。

小结

本文从 Embedding 的基本概念出发，梳理了它在语义检索、去重聚类、推荐召回等场景中的作用，并给出了一个基于 Spring AI 的最小可运行示例。落地时建议重点关注三点：统一向量模型与预处理逻辑、用真实样本评估召回效果、把模型配置与业务代码解耦。