gte-base-zh模型Java集成开发指南SpringBoot构建语义搜索服务你是不是也遇到过这样的问题公司内部有海量的文档、产品说明或者用户反馈想快速找到相关内容用关键词搜索总是不准要么搜不全要么搜出一堆无关信息。传统的搜索技术比如基于关键词匹配已经有点力不从心了。最近语义搜索火了起来。简单说就是让机器理解你问话的“意思”而不是死板地匹配那几个词。比如你搜“怎么保养笔记本电脑”它也能把“如何延长笔记本电池寿命”这种说法不同但意思相近的文档找出来。今天我们就来动手解决这个问题。我会带你一步步在SpringBoot项目里集成一个叫gte-base-zh的文本向量化模型用它来搭建一个真正“懂你意思”的语义搜索服务。整个过程就像搭积木从部署模型到写代码再到最后跑起来我都会用最直白的话讲清楚。即使你之前没怎么接触过AI模型集成跟着做也能搞定。1. 第一步把模型“请”到线上——在星图平台部署要把模型用起来首先得有个地方让它“住下”并对外提供服务。我们选择在CSDN星图GPU平台部署这里提供现成的环境省去了我们自己配服务器、装驱动的麻烦。1.1 创建并部署模型服务登录与进入首先访问CSDN星图平台并登录。在控制台里找到“模型服务”或“AI应用”相关的创建入口。选择模型在创建服务的页面你会看到一个模型仓库或搜索框。在里面搜索gte-base-zh。这个模型是由阿里巴巴开源的专门针对中文文本做向量化就是把文字变成一串有意义的数字效果很不错。配置资源平台会让你选择用什么样的“电脑”来运行这个模型。对于gte-base-zh这种基础模型选择“GPU”规格通常最小的GPU实例比如配有T4或V100等显卡的就完全够用了。这能保证模型推理的速度。设置网络关键的一步在高级设置或网络配置里务必选择“公网访问”。这样部署好后平台会给我们一个能从互联网直接访问的网址API端点我们的SpringBoot应用才能调用它。部署填好服务名称点击部署。然后就是等待几分钟让平台在后台为我们准备好一切。1.2 获取你的API密钥和端点部署成功后在服务的管理页面你需要找到两个最重要的信息API端点Endpoint一个看起来像https://your-service-id.csdn.net/v1的网址。这就是我们模型服务的“门牌号”。API密钥API Key一串长长的字母数字组合的密钥。就像一把钥匙每次调用服务时都需要带上它用于验证身份。把这两个信息记下来我们等下写代码时要用到。你可以把它们先放在项目的配置文件里。好了模型已经在云端跑起来了随时待命。接下来我们就要在Java世界里学会怎么跟它“打招呼”了。2. 第二步让Java学会“说话”——调用向量化API现在模型服务已经在线我们的SpringBoot应用需要能够发送文本给它并接收它返回的向量。这里我介绍两种SpringBoot里最常用的方式RestTemplate和WebClient。你可以根据项目情况选一种。2.1 使用 RestTemplate同步调用RestTemplate是Spring家族里经典、易用的HTTP客户端采用同步阻塞式调用逻辑直白。首先我们在配置文件中定义模型服务的地址和密钥。# application.yml ai: embedding: endpoint: https://your-service-id.csdn.net/v1 # 替换为你的真实端点 api-key: your-api-key-here # 替换为你的真实密钥 model: gte-base-zh # 指定模型名称然后创建一个配置类来初始化RestTemplate并统一加上认证头。import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.web.client.RestTemplate; import org.springframework.http.client.ClientHttpRequestInterceptor; import org.springframework.http.HttpRequest; import org.springframework.http.client.ClientHttpResponse; import org.springframework.http.client.ClientHttpRequestExecution; import java.io.IOException; import java.util.Collections; Configuration public class RestTemplateConfig { Value(${ai.embedding.api-key}) private String apiKey; Bean public RestTemplate embeddingRestTemplate() { RestTemplate restTemplate new RestTemplate(); // 添加一个拦截器自动为每个请求加上Authorization头 ClientHttpRequestInterceptor interceptor new ClientHttpRequestInterceptor() { Override public ClientHttpResponse intercept(HttpRequest request, byte[] body, ClientHttpRequestExecution execution) throws IOException { request.getHeaders().add(Authorization, Bearer apiKey); request.getHeaders().add(Content-Type, application/json); return execution.execute(request, body); } }; restTemplate.setInterceptors(Collections.singletonList(interceptor)); return restTemplate; } }接下来是核心的服务类负责构造请求体并调用API。import org.springframework.beans.factory.annotation.Value; import org.springframework.stereotype.Service; import org.springframework.web.client.RestTemplate; import org.springframework.http.HttpEntity; import org.springframework.http.ResponseEntity; import java.util.List; import java.util.Map; import java.util.HashMap; Service public class EmbeddingService { Value(${ai.embedding.endpoint}/embeddings) private String apiUrl; Value(${ai.embedding.model}) private String model; private final RestTemplate restTemplate; public EmbeddingService(RestTemplate embeddingRestTemplate) { this.restTemplate embeddingRestTemplate; } /** * 将单条文本转换为向量 * param text 输入文本 * return 向量数组List of Floats */ public ListFloat getEmbedding(String text) { MapString, Object requestBody new HashMap(); requestBody.put(input, text); requestBody.put(model, model); HttpEntityMapString, Object request new HttpEntity(requestBody); // 发送POST请求 ResponseEntityMap response restTemplate.postForEntity(apiUrl, request, Map.class); // 解析响应提取向量数据 ListMapString, Object data (ListMapString, Object) response.getBody().get(data); if (data ! null !data.isEmpty()) { return (ListFloat) data.get(0).get(embedding); } throw new RuntimeException(Failed to get embedding from API response); } }这样你在业务代码里注入这个EmbeddingService调用getEmbedding(“一段文本”)就能拿到对应的向量了。2.2 使用 WebClient异步调用推荐如果你的应用是高并发的或者你想用更现代、支持异步非阻塞的API那么WebClient是更好的选择。它是Spring WebFlux的核心性能通常更好。首先添加WebFlux依赖如果项目还没有的话。dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-webflux/artifactId /dependency然后创建WebClient的配置和Service。import org.springframework.beans.factory.annotation.Value; import org.springframework.stereotype.Service; import org.springframework.web.reactive.function.client.WebClient; import reactor.core.publisher.Mono; import java.util.List; import java.util.Map; Service public class AsyncEmbeddingService { private final WebClient webClient; public AsyncEmbeddingService(Value(${ai.embedding.endpoint}) String endpoint, Value(${ai.embedding.api-key}) String apiKey) { this.webClient WebClient.builder() .baseUrl(endpoint) .defaultHeader(Authorization, Bearer apiKey) .defaultHeader(Content-Type, application/json) .build(); } /** * 异步获取文本向量 * param text 输入文本 * return 包含向量数组的Mono */ public MonoListFloat getEmbeddingAsync(String text) { MapString, Object requestBody Map.of( input, text, model, gte-base-zh ); return this.webClient.post() .uri(/embeddings) .bodyValue(requestBody) .retrieve() .bodyToMono(Map.class) .map(response - { ListMapString, Object data (ListMapString, Object) response.get(data); return (ListFloat) data.get(0).get(embedding); }) .onErrorMap(e - new RuntimeException(Failed to fetch embedding asynchronously, e)); } }使用WebClient时调用返回的是一个Mono或Flux对象你可以在需要结果的时候再“订阅”它或者方便地与其他异步流操作组合非常灵活。两种方式都介绍完了RestTemplate简单直接WebClient更强大现代。你可以根据团队习惯和技术栈来选择。有了这个基础调用能力我们就可以考虑更实际的工程问题了。3. 第三步工程化思考——批量处理与缓存在实际业务中我们很少只向量化一条文本。更常见的场景是系统初始化时批量处理存量文档或者定期处理新增数据。同时反复向量化相同的文本是浪费资源的我们需要缓存。3.1 设计一个批量处理任务假设我们有一个Document实体我们需要为它的content字段计算向量并保存。我们可以使用Spring的Async注解和CompletableFuture来实现简单的并行批量处理。import org.springframework.scheduling.annotation.Async; import org.springframework.stereotype.Component; import java.util.List; import java.util.concurrent.CompletableFuture; import java.util.stream.Collectors; Component public class BatchEmbeddingProcessor { private final AsyncEmbeddingService embeddingService; // 或用同步的 public BatchEmbeddingProcessor(AsyncEmbeddingService embeddingService) { this.embeddingService embeddingService; } /** * 异步批量处理文档向量化 * param documents 文档列表 * return 包含处理结果的Future列表 */ Async public ListCompletableFutureVoid processBatch(ListDocument documents) { return documents.stream() .map(doc - embeddingService.getEmbeddingAsync(doc.getContent()) .doOnNext(vector - { // 将向量保存到数据库或向量库 doc.setEmbedding(vector); // documentRepository.save(doc); }) .then() .toFuture() ) .collect(Collectors.toList()); } }记得在SpringBoot主类或配置类上加上EnableAsync来启用异步支持。这样处理大量文档时就不会阻塞主线程了。3.2 引入缓存避免重复计算文本向量化是比较耗时的操作即使有GPU。对于不变的文本其向量也是不变的。我们可以用Spring Cache来轻松实现缓存。首先在EmbeddingService的方法上添加Cacheable注解。Service public class EmbeddingService { // ... 其他代码 Cacheable(value textEmbeddings, key #text) public ListFloat getEmbedding(String text) { // ... 原有的调用API的逻辑 } }然后在配置类中启用缓存并配置一个缓存管理器比如使用内存缓存Caffeine。import org.springframework.cache.annotation.EnableCaching; import org.springframework.cache.caffeine.CaffeineCacheManager; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import com.github.benmanes.caffeine.cache.Caffeine; import java.util.concurrent.TimeUnit; Configuration EnableCaching public class CacheConfig { Bean public CaffeineCacheManager cacheManager() { CaffeineCacheManager cacheManager new CaffeineCacheManager(textEmbeddings); cacheManager.setCaffeine(Caffeine.newBuilder() .expireAfterWrite(7, TimeUnit.DAYS) // 缓存7天 .maximumSize(10000) // 最大缓存10000条文本 .recordStats()); return cacheManager; } }这样相同的文本第二次请求时就会直接从缓存中返回向量速度极快也大大减轻了模型服务的压力。处理好了批量任务和缓存我们的核心能力就扎实了。最后我们把这些能力包装成一个完整的、可用的搜索API。4. 第四步组装成服务——构建语义搜索REST API现在我们有了把文本变成向量的能力也有了存储的向量。语义搜索的核心就是把用户的查询也变成向量然后去数据库里找和这个查询向量最“像”余弦相似度最高的文档向量。4.1 实现内存中的向量相似度计算为了演示我们先实现一个简单的内存计算。在实际生产环境你应该使用专业的向量数据库如Milvus、Pinecone、Qdrant或Elasticsearch的向量搜索功能。import org.springframework.stereotype.Service; import java.util.List; import java.util.stream.Collectors; Service public class InMemorySearchService { // 假设这里存储了所有文档及其向量 private ListDocument indexedDocuments; /** * 计算两个向量的余弦相似度 */ private double cosineSimilarity(ListFloat vecA, ListFloat vecB) { double dotProduct 0.0; double normA 0.0; double normB 0.0; for (int i 0; i vecA.size(); i) { dotProduct vecA.get(i) * vecB.get(i); normA Math.pow(vecA.get(i), 2); normB Math.pow(vecB.get(i), 2); } if (normA 0 || normB 0) { return 0.0; } return dotProduct / (Math.sqrt(normA) * Math.sqrt(normB)); } /** * 语义搜索 * param query 查询文本 * param topK 返回最相似的前K个结果 * return 排序后的文档列表 */ public ListDocument semanticSearch(String query, ListFloat queryVector, int topK) { return indexedDocuments.stream() .map(doc - { double score cosineSimilarity(queryVector, doc.getEmbedding()); return new SearchResult(doc, score); }) .sorted((a, b) - Double.compare(b.getScore(), a.getScore())) // 按相似度降序 .limit(topK) .map(SearchResult::getDocument) .collect(Collectors.toList()); } // 内部结果类 private static class SearchResult { Document document; double score; // ... 构造方法和getter } }4.2 暴露RESTful API最后我们创建一个控制器Controller把所有的功能串联起来提供一个干净的HTTP接口。import org.springframework.web.bind.annotation.*; import lombok.Data; import java.util.List; RestController RequestMapping(/api/search) public class SearchController { private final EmbeddingService embeddingService; private final InMemorySearchService searchService; public SearchController(EmbeddingService embeddingService, InMemorySearchService searchService) { this.embeddingService embeddingService; this.searchService searchService; } PostMapping(/semantic) public SearchResponse semanticSearch(RequestBody SearchRequest request) { // 1. 将查询文本向量化 ListFloat queryVector embeddingService.getEmbedding(request.getQuery()); // 2. 执行语义搜索 ListDocument results searchService.semanticSearch(request.getQuery(), queryVector, request.getTopK()); // 3. 组装返回 return new SearchResponse(results); } Data static class SearchRequest { private String query; private int topK 10; } Data static class SearchResponse { private ListDocument documents; // 可以在这里添加搜索耗时、总匹配数等信息 public SearchResponse(ListDocument documents) { this.documents documents; } } }现在启动你的SpringBoot应用。你可以用Postman或者curl工具向http://localhost:8080/api/search/semantic发送一个POST请求Body里带上{query: 如何给笔记本电脑清灰, topK: 5}就能收到基于语义相似度排序的搜索结果了5. 总结与展望走完这一趟我们从零开始把一个AI模型集成到了熟悉的Java SpringBoot生态里构建了一个可用的语义搜索服务。整个过程其实可以分解成几个清晰的步骤先在云平台把模型服务跑起来然后在SpringBoot里用RestTemplate或WebClient去调用它接着考虑批量处理和缓存这些工程优化点最后实现搜索逻辑并暴露API。用下来感觉gte-base-zh这个模型对中文的支持确实不错向量化的质量有保障。SpringBoot那一套成熟的体系也让集成工作变得很顺畅特别是缓存和异步处理都有现成的“轮子”可以用。当然这只是一个起点。如果你想把这个服务用到生产环境还有几件事值得考虑一是把内存搜索换成专业的向量数据库比如Milvus或者Elasticsearch的向量插件它们能处理亿级数据并且有高效的近似最近邻搜索算法。二是完善整个数据管道包括文档的预处理分块、清洗、向量索引的增量更新机制。三是加入更复杂的业务逻辑比如过滤、多路召回、重排序等。不过无论如何今天搭建的这个服务已经具备了核心能力。你可以先把它用在内网知识库搜索、产品问答匹配等对实时性要求不那么极致的场景看看效果。希望这个指南能帮你打开一扇门让你看到在Java世界里玩转AI应用并没有想象中那么难。获取更多AI镜像想探索更多AI镜像和应用场景访问 CSDN星图镜像广场提供丰富的预置镜像覆盖大模型推理、图像生成、视频生成、模型微调等多个领域支持一键部署。