首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >Java + LLM:从接口封装到 RAG 后端服务搭建记录

Java + LLM:从接口封装到 RAG 后端服务搭建记录

原创
作者头像
IT大佬 jzit-top
发布于 2026-11-18 14:26:35
发布于 2026-11-18 14:26:35
510
举报

一、引言:Java 生态为何也要拥抱 LLM

过去一年,LLM 集成几乎成了 JavaScript/Python 开发者的专属狂欢,Java 工程师往往被贴上“古老后端”的标签。然而在真实企业场景中,Java 依然占据着核心业务系统的绝对主导地位——订单、支付、用户权限、数据中台,无一不是 Java 系。因此,如何将 LLM 能力嵌入 Java 后端,并构建出具备工程韧性的 RAG(检索增强生成)服务,是 Java 团队落地 AI 能力时无法回避的命题。

二、第一步:大模型接口封装——用 WebClient 替代 RestTemplate

业务后端与 LLM 之间通信,必须单独抽出一层“LLM Client”,避免散落一地的 RestTemplate 调用。与 Python 生态不同,Java 接入 LLM 时第一优先级是非阻塞——大模型响应动辄数秒,若用同步阻塞 I/O,线程池很快被耗尽。因此我们选择 WebClient。

代码语言:javascript
复制
@Service
public class LLMClient {
    private final WebClient webClient;

    public LLMClient(LLMProperties props) {
        this.webClient = WebClient.builder()
            .baseUrl(props.getBaseUrl())
            .defaultHeader("Authorization", "Bearer " + props.getApiKey())
            .defaultHeader("Content-Type", "application/json")
            .build();
    }

    public Mono<String> chat(String userPrompt, String systemPrompt) {
        ChatRequest req = new ChatRequest(
            props.getModel(),
            List.of(
                new ChatMessage("system", systemPrompt),
                new ChatMessage("user", userPrompt)
            ),
            true // 流式标志,此处示例关闭
        );
        return webClient.post()
            .uri("/chat/completions")
            .bodyValue(req)
            .retrieve()
            .bodyToMono(JsonNode.class)
            .map(node -> node.path("choices").get(0).path("message").path("content").asText())
            .timeout(Duration.ofSeconds(60));
    }
}

这段代码的关键点在于:返回 Mono<String>,让上游调用方通过 Reactor 异步编排,而不是 block()——除非你在 Controller 中需要直接返回同步响应。

三、第二步:RAG 核心链路——文档切割与向量化

RAG 的价值在于让模型从私有知识库中“按需阅读”,然后再回答。完整链路分为五段:文档加载 → 文本分割 → 向量化(Embedding) → 向量存储 → 相似检索。

3.1 文本分割:中文场景必须按语义边界切分

直接用正则切分容易切断语义。我们需要一个能感知段落、句号和标题的结构化切分器:

代码语言:javascript
复制
public static List<String> chunkText(String text, int maxLength) {
    List<String> chunks = new ArrayList<>();
    String[] paragraphs = text.split("\n");
    StringBuilder current = new StringBuilder();
    for (String para : paragraphs) {
        if (current.length() + para.length() > maxLength) {
            chunks.add(current.toString());
            current.setLength(0);
        }
        current.append(para).append('\n');
    }
    if (!current.isEmpty()) {
        chunks.add(current.toString());
    }
    return chunks;
}

3.2 向量化:复用 LLM 接口中的 Embedding 端点

调用大模型提供商统一的 Embedding 接口,为每个分块生成浮点向量:

代码语言:javascript
复制
public double[] embedText(String text) {
    EmbeddingRequest req = new EmbeddingRequest("text-embedding-ada-002", List.of(text));
    JsonNode resp = webClient.post()
        .uri("/embeddings")
        .bodyValue(req)
        .retrieve()
        .bodyToMono(JsonNode.class)
        .block(); // 此端点为必要同步,或也可异步
    return objectMapper.convertValue(resp.get("data").get(0).get("embedding"), double[].class);
}

注意:在实际生产环境中,建议将向量化接口封装为独立服务,并做好缓存——相同文本块不要重复调用 Embedding。

四、第三步:向量存储与检索——零依赖实现最小可用

小规模知识库(万级以下分块)不必引入向量数据库,内存中的余弦相似度实现足以应付教学或 MVP。若要落地到生产,替换为 PGVector 或 Elasticsearch 的向量索引即可。

代码语言:javascript
复制
public class VectorStore {
    private final Map<String, double[]> store = new ConcurrentHashMap<>();
    
    public void add(String docId, double[] embedding) {
        store.put(docId, embedding);
    }
    
    public List<String> search(String queryEmbedding, int topN) {
        return store.entrySet().stream()
            .sorted((a, b) -> Double.compare(
                cosineSimilarity(b.getValue(), queryEmbedding),
                cosineSimilarity(a.getValue(), queryEmbedding)))
            .limit(topN)
            .map(Map.Entry::getKey)
            .toList();
    }
    
    private double cosineSimilarity(double[] a, double[] b) {
        double dot = 0, nA = 0, nB = 0;
        for (int i = 0; i < a.length; i++) {
            dot += a[i] * b[i];
            nA += a[i] * a[i];
            nB += b[i] * b[i];
        }
        return dot / (Math.sqrt(nA) * Math.sqrt(nB) + 1e-9);
    }
}

五、第四步:检索增强生成——组装可解释的 Prompt

检索结果不能直接塞给 LLM,需要设计“上下文模板”,并明确告知模型:“只基于以下资料回答,不要编造。”

代码语言:javascript
复制
public Mono<String> ragAnswer(String question) {
    return Mono.fromCallable(() -> llmClient.embedText(question))
        .map(embedding -> vectorStore.search(embedding, 4))
        .flatMap(docIds -> {
            String context = buildContext(docIds); // 从文档库拉取原文拼接
            return llmClient.chat(
                formatRagPrompt(question, context),
                "你是企业内部助手,请严格基于资料回答,若资料不足则明确说明"
            );
        });
}

一个规范的 RAG Prompt 模板形如:

代码语言:javascript
复制
请阅读以下资料,并且回答用户问题。
资料:
{context}
问题:
{question}
要求:回答中必须注明信息来源(如[资料1],[资料2]);若资料未覆盖,请说“我无法从现有资料中找到答案”。

六、工程化优化:缓存、重试与异步

1. Embedding 缓存

同一个文本块的向量不应重复计算。用 Caffeine 缓存:

代码语言:javascript
复制
Cache<String, double[]> embedCache = Caffeine.newBuilder()
    .maximumSize(10_000)
    .expireAfterWrite(Duration.ofDays(7))
    .build();

double[] getEmbeddingCached(String text) {
    return embedCache.get(text, this::embedText);
}

2. 调用 LLM 的重试机制

大模型 API 偶尔返回 429 或超时,采用 Spring Retry 加持:

代码语言:javascript
复制
@Retryable(retryFor = WebClientRequestException.class, maxAttempts = 3, backoff = @Backoff(delay = 1000))
public Mono<String> chatRetry(String userPrompt, String systemPrompt) { ... }

注意:retry 操作要幂等,若 LLM 接口可能产生计费,最好自行确保请求体不变,或加请求追踪 ID 去重。

3. 异步化整体链路

将 RAG 的 Controller 改为返回 CompletableFuture<String>,并用 @Async 线程池执行,确保能支撑多请求并发:

代码语言:javascript
复制
@Async("ragExecutor")
public CompletableFuture<String> asyncRag(String question) {
    return ragAnswer(question).toFuture();
}

七、踩坑记录:三个容易忽略的坑

  1. 流式输出与检索无法直接结合:RAG 检索完成后,LLM 的流式响应可以接 SSE 返回前端,但中间层需要做缓冲队列,否则连接会中断。我们使用 Sinks.Many<String> 实现背压。
  2. JSON 解析异常:不同模型的响应结构略有差异,不要直接信任固定的 JsonPath。建议用 validate 和 fallback 机制。
  3. 向量维度不一致:切换 Embedding 模型时,必须清空向量库,否则相似度计算毫无意义。

八、总结

Java + LLM 不是不可调和的组合,反而因为 Java 的成熟工程基建(Spring Boot、Reactor、缓存、重试、监控),能让 RAG 后端在稳定性上比 Python 原型更有优势。整个搭建过程可总结为:封装好 LLM 调用层,搭好文档切分与向量化管道,实现可替换的向量存储,再用 Flow 串联生成。 关键不是炫技的算法,而是将每个环节做成可测试、可重用的组件。当你看到 LLM 基于企业私有知识库准确回答问题时,你会明白,Java 后端的 AI 进化才刚刚开始。

原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。

如有侵权,请联系 cloudcommunity@tencent.com 删除。

目录
  • 一、引言:Java 生态为何也要拥抱 LLM
    • 二、第一步:大模型接口封装——用 WebClient 替代 RestTemplate
    • 三、第二步:RAG 核心链路——文档切割与向量化
      • 3.1 文本分割:中文场景必须按语义边界切分
      • 3.2 向量化:复用 LLM 接口中的 Embedding 端点
    • 四、第三步:向量存储与检索——零依赖实现最小可用
    • 五、第四步:检索增强生成——组装可解释的 Prompt
    • 六、工程化优化:缓存、重试与异步
      • 1. Embedding 缓存
      • 2. 调用 LLM 的重试机制
      • 3. 异步化整体链路
    • 七、踩坑记录:三个容易忽略的坑
    • 八、总结
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档