Spring AI 整合火山引擎豆包向量库搭建企业知识库：我踩过的 10 个致命坑与终极解决方案

一、背景与问题引入

大模型时代，向量知识库已经成为企业级AI应用的标配。它能将非结构化的文档、图片、视频转换为向量表示，通过语义相似度检索实现精准的上下文问答，解决大模型"幻觉"和知识时效性问题。

Spring AI作为Spring官方推出的AI开发框架，提供了统一的API抽象，屏蔽了不同大模型厂商的差异，极大降低了AI应用的开发门槛。然而，在实际整合国内主流大模型厂商的过程中，我们会遇到大量兼容性问题，尤其是向量模型的整合，几乎是所有开发者的噩梦。

本文将完整记录我在使用Spring AI 1.1.2整合火山引擎豆包向量模型过程中遇到的所有问题，从最基础的404错误到最隐蔽的空指针异常，每个问题都包含完整的报错信息、根因分析和可直接使用的解决方案。

二、环境准备

2.1 核心依赖

<?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 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.2.5</version>
        <relativePath/>
    </parent>
    <groupId>com.jam.demo</groupId>
    <artifactId>doubao-vector-kb</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>doubao-vector-kb</name>
    <description>豆包向量知识库</description>
    <properties>
        <java.version>17</java.version>
        <spring-ai.version>1.1.2</spring-ai.version>
        <okhttp.version>4.12.0</okhttp.version>
        <fastjson2.version>2.0.52</fastjson2.version>
        <lombok.version>1.18.30</lombok.version>
        <pdfbox.version>2.0.32</pdfbox.version>
    </properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-pdf-reader</artifactId>
        </dependency>
        <dependency>
            <groupId>org.apache.pdfbox</groupId>
            <artifactId>pdfbox</artifactId>
            <version>${pdfbox.version}</version>
        </dependency>
        <dependency>
            <groupId>com.squareup.okhttp3</groupId>
            <artifactId>okhttp</artifactId>
            <version>${okhttp.version}</version>
        </dependency>
        <dependency>
            <groupId>com.alibaba.fastjson2</groupId>
            <artifactId>fastjson2</artifactId>
            <version>${fastjson2.version}</version>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>${lombok.version}</version>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>com.google.guava</groupId>
            <artifactId>guava</artifactId>
            <version>33.1.0-jre</version>
        </dependency>
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
            <version>2.5.0</version>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>
    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.ai</groupId>
                <artifactId>spring-ai-bom</artifactId>
                <version>${spring-ai.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <excludes>
                        <exclude>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                        </exclude>
                    </excludes>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

2.2 基础配置

spring:
  application:
    name: doubao-vector-kb
  ai:
    openai:
      base-url: https://ark.cn-beijing.volces.com/api/v3
      api-key: 你的火山引擎API密钥
      chat:
        options:
          model: 你的对话模型接入点ID
          temperature: 0.3
          max-tokens: 4096
server:
  port: 8080
springdoc:
  swagger-ui:
    path: /swagger-ui.html
  api-docs:
    path: /v3/api-docs
kb:
  version: v2

三、核心架构设计

整个系统分为三个核心模块：

1. 文档处理模块：负责PDF解析、文本提取和智能分块
2. 向量处理模块：负责文本向量化和向量存储检索
3. 问答模块：负责问题理解、上下文检索和大模型回答生成

四、致命坑点全解析与解决方案

4.1 坑1：Spring AI自带OpenAiEmbeddingModel调用404

报错信息

org.springframework.ai.retry.NonTransientAiException: HTTP 404 - No response body available
 at org.springframework.ai.retry.autoconfigure.SpringAiRetryAutoConfiguration$2.handleError(SpringAiRetryAutoConfiguration.java:126)

根因分析 Spring AI自带的OpenAiEmbeddingModel是严格按照OpenAI官方接口规范实现的，它会自动拼接/embeddings路径。然而，火山引擎的纯文本向量模型和多模态向量模型使用的是完全不同的接口地址，且参数格式与OpenAI不兼容。

火山引擎向量模型接口规范：

• 纯文本向量模型：https://ark.cn-beijing.volces.com/api/v3/embeddings
• 多模态向量模型：https://ark.cn-beijing.volces.com/api/v3/embeddings/multimodal

解决方案 完全抛弃Spring AI自带的Embedding实现，自己编写原生HTTP调用代码，直接对接火山引擎官方接口。

4.2 坑2：方法签名冲突

报错信息

embed(List<String>) in com.jam.demo.service.VolcEmbeddingModel clashes with embed(List<String>) in 'org.springframework.ai.embedding.EmbeddingModel'; incompatible return type

根因分析 Spring AI 1.1.2版本的EmbeddingModel接口方法签名与后续版本不兼容，强行继承会导致返回值类型冲突。

解决方案 不继承任何Spring AI的Embedding接口，编写完全独立的向量服务类，彻底避免版本冲突。

4.3 坑3：模型ID填错

报错信息

{"error":{"code":"InvalidParameter","message":"The parameter `model` specified in the request are not valid: the requested model doubao-seedream-5-0-260128 does not support this api.. Request id: xxx"}}

根因分析 火山引擎方舟平台提供了多种类型的模型，不同模型支持的接口完全不同：

• 对话模型：支持/chat/completions接口，用于文本生成
• 纯文本向量模型：支持/embeddings接口，用于纯文本向量化
• 多模态向量模型：支持/embeddings/multimodal接口，用于文本、图片、视频向量化

很多开发者会误将对话模型的ID填入向量模型的配置中，导致接口调用失败。

解决方案 严格区分不同类型模型的接入点ID，在代码中添加明确的注释，避免混淆。

4.4 坑4：API Key含中文

报错信息

java.lang.IllegalArgumentException: Unexpected char 0x4f60 at 7 in Authorization value

根因分析 HTTP请求头不允许包含中文字符，如果复制API Key时不小心带入了中文注释或空格，就会导致这个错误。

解决方案 在代码中对API Key进行trim处理，去除首尾空格和不可见字符。

4.5 坑5：纯文本向量模型接口不兼容

报错信息

{"error":{"code":"InvalidParameter","message":"The parameter `model` specified in the request are not valid: the requested model doubao-embedding does not support this api.. Request id: xxx"}}

根因分析 火山引擎的纯文本向量模型接口存在兼容性问题，部分区域和账号无法正常使用。

解决方案 使用多模态向量模型doubao-embedding-vision替代纯文本向量模型，它完全支持纯文本输入，且接口更加稳定。

4.6 坑6：多模态向量模型请求体格式错误

报错信息

{"error":{"code":"InvalidParameter","message":"we could not parse the JSON body of your request. Request id: xxx"}}

根因分析 多模态向量模型的请求体格式与纯文本向量模型完全不同，它要求输入必须是一个数组，每个元素必须包含type字段指定输入类型。

错误请求体

{
    "model": "ep-xxx",
    "input": "需要向量化的文本"
}

正确请求体

{
    "model": "ep-xxx",
    "input": [
        {
            "type": "text",
            "text": "需要向量化的文本"
        }
    ]
}

解决方案 严格按照火山引擎官方文档构造请求体，确保格式完全正确。

4.7 坑7：接入点未启动

报错信息

{"error":{"code":"InvalidEndpoint.ClosedEndpoint","message":"The request targeted an endpoint that is currently closed or temporarily unavailable. Request id: xxx"}}

根因分析 火山引擎方舟平台的模型接入点默认是关闭状态，需要手动启动才能使用。

解决方案 登录火山引擎方舟控制台，找到对应的模型接入点，点击启动按钮，等待30秒到1分钟启动完成。

4.8 坑8：JSON解析字段不匹配

报错信息

com.fasterxml.jackson.databind.exc.UnrecognizedPropertyException: Unrecognized field "created" (class com.jam.demo.service.VolcEmbeddingService$ArkResponse), not marked as ignorable

根因分析 火山引擎返回的响应体中包含一些额外字段，如created、id、usage等，如果实体类没有定义这些字段，Jackson解析时会抛出异常。

解决方案 使用Jackson的树形解析方式，直接提取需要的字段，避免实体类与响应体完全绑定。

4.9 坑9：空指针异常

报错信息

java.lang.NullPointerException: Cannot invoke "com.fasterxml.jackson.databind.JsonNode.get(String)" because the return value of "com.fasterxml.jackson.databind.JsonNode.get(int)" is null

根因分析 接口调用成功但返回的数据结构不符合预期，可能是data数组为空，或者embedding字段缺失。

解决方案 添加全层级的空指针防护，任何可能为null的地方都进行判断，失败时返回默认向量，保证流程不中断。

4.10 坑10：接口返回空数据

报错信息

java.lang.RuntimeException: data 数组为空！

根因分析 火山引擎接口偶尔会出现调用成功但返回空数据的情况，这是平台本身的问题。

解决方案 添加异常捕获机制，失败时返回默认向量，同时打印详细日志方便后续排查。

五、完整代码实现

5.1 多模态向量服务

package com.jam.demo.service;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import okhttp3.*;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Service;
import org.springframework.util.StringUtils;
import java.util.List;
import java.util.Map;
import java.util.concurrent.TimeUnit;
/**
 * 火山引擎多模态向量服务
 * @author ken
 * @date 2026-04-13
 */
@Slf4j
@Service
public class VolcEmbeddingService {
    private final String apiKey = "你的火山引擎API密钥";
    private final String modelId = "你的多模态向量模型接入点ID";
    private final OkHttpClient client;
    private final ObjectMapper objectMapper;
    public VolcEmbeddingService() {
        this.client = new OkHttpClient.Builder()
                .connectTimeout(60, TimeUnit.SECONDS)
                .readTimeout(60, TimeUnit.SECONDS)
                .writeTimeout(60, TimeUnit.SECONDS)
                .build();
        this.objectMapper = new ObjectMapper();
    }
    /**
     * 将文本转换为向量
     * @param text 输入文本
     * @return 向量数组
     */
    public float[] embed(String text) {
        if (!StringUtils.hasText(text)) {
            return new float[1024];
        }
        try {
            Map<String, Object> inputItem = Map.of(
                    "type", "text",
                    "text", text.trim()
            );
            Map<String, Object> requestBody = Map.of(
                    "model", modelId,
                    "input", List.of(inputItem)
            );
            String json = objectMapper.writeValueAsString(requestBody);
            Request request = new Request.Builder()
                    .url("https://ark.cn-beijing.volces.com/api/v3/embeddings/multimodal")
                    .header("Authorization", "Bearer " + apiKey.trim())
                    .header("Content-Type", "application/json")
                    .post(RequestBody.create(json, MediaType.parse("application/json")))
                    .build();
            try (Response response = client.newCall(request).execute()) {
                String respBody = response.body().string();
                if (!response.isSuccessful()) {
                    log.error("向量接口调用失败，状态码：{}，响应：{}", response.code(), respBody);
                    return new float[1024];
                }
                JsonNode root = objectMapper.readTree(respBody);
                JsonNode dataArray = root.has("data") ? root.get("data") : null;
                if (dataArray == null || !dataArray.isArray() || dataArray.isEmpty()) {
                    log.error("向量接口响应无数据，响应：{}", respBody);
                    return new float[1024];
                }
                JsonNode firstData = dataArray.get(0);
                if (firstData == null || !firstData.has("embedding")) {
                    log.error("向量接口响应无embedding字段，响应：{}", respBody);
                    return new float[1024];
                }
                return objectMapper.convertValue(firstData.get("embedding"), float[].class);
            }
        } catch (Exception e) {
            log.error("向量化失败", e);
            return new float[1024];
        }
    }
}

5.2 自定义向量存储

package com.jam.demo.service;
import org.springframework.stereotype.Component;
import org.springframework.util.ObjectUtils;
import java.util.ArrayList;
import java.util.List;
/**
 * 内存向量存储
 * @author ken
 * @date 2026-04-13
 */
@Component
public class MyVectorStore {
    public static class DocVector {
        private final String text;
        private final float[] vector;
        public DocVector(String text, float[] vector) {
            this.text = text;
            this.vector = vector;
        }
        public String getText() {
            return text;
        }
        public float[] getVector() {
            return vector;
        }
    }
    private final List<DocVector> store = new ArrayList<>();
    /**
     * 添加文档向量
     * @param text 文档文本
     * @param vector 文档向量
     */
    public void add(String text, float[] vector) {
        if (!ObjectUtils.isEmpty(text) && !ObjectUtils.isEmpty(vector)) {
            store.add(new DocVector(text, vector));
        }
    }
    /**
     * 向量相似度检索
     * @param queryVector 查询向量
     * @param topK 返回结果数量
     * @return 最相似的文本列表
     */
    public List<String> search(float[] queryVector, int topK) {
        List<String> result = new ArrayList<>();
        if (ObjectUtils.isEmpty(queryVector) || topK <= 0) {
            return result;
        }
        List<DocVector> sorted = new ArrayList<>(store);
        sorted.sort((a, b) -> Float.compare(cosine(b.getVector(), queryVector), cosine(a.getVector(), queryVector)));
        for (int i = 0; i < Math.min(topK, sorted.size()); i++) {
            result.add(sorted.get(i).getText());
        }
        return result;
    }
    /**
     * 计算余弦相似度
     * @param v1 向量1
     * @param v2 向量2
     * @return 余弦相似度值
     */
    private float cosine(float[] v1, float[] v2) {
        if (v1.length != v2.length) {
            return 0.0f;
        }
        float dot = 0.0f;
        float norm1 = 0.0f;
        float norm2 = 0.0f;
        for (int i = 0; i < v1.length; i++) {
            dot += v1[i] * v2[i];
            norm1 += v1[i] * v1[i];
            norm2 += v2[i] * v2[i];
        }
        if (norm1 == 0.0f || norm2 == 0.0f) {
            return 0.0f;
        }
        return (float) (dot / (Math.sqrt(norm1) * Math.sqrt(norm2)));
    }
    /**
     * 清空向量库
     */
    public void clear() {
        store.clear();
    }
    /**
     * 获取向量库大小
     * @return 向量数量
     */
    public int size() {
        return store.size();
    }
}

5.3 文档处理服务

package com.jam.demo.service;
import lombok.extern.slf4j.Slf4j;
import org.apache.pdfbox.pdmodel.PDDocument;
import org.apache.pdfbox.text.PDFTextStripper;
import org.springframework.ai.document.Document;
import org.springframework.ai.transformer.splitter.TokenTextSplitter;
import org.springframework.stereotype.Service;
import org.springframework.web.multipart.MultipartFile;
import java.io.IOException;
import java.util.List;
import java.util.Map;
/**
 * 文档处理服务
 * @author ken
 * @date 2026-04-13
 */
@Slf4j
@Service
public class DocumentV2Service {
    private final MyVectorStore myVectorStore;
    private final VolcEmbeddingService embeddingService;
    private final TokenTextSplitter textSplitter;
    public DocumentV2Service(MyVectorStore myVectorStore, VolcEmbeddingService embeddingService) {
        this.myVectorStore = myVectorStore;
        this.embeddingService = embeddingService;
        this.textSplitter = new TokenTextSplitter();
    }
    /**
     * 上传并处理PDF文档
     * @param file PDF文件
     * @param fileName 文件名
     * @return 处理结果
     * @throws IOException IO异常
     */
    public Map<String, Object> uploadPdf(MultipartFile file, String fileName) throws IOException {
        log.info("开始处理PDF文档: {}", fileName);
        PDDocument document = PDDocument.load(file.getInputStream());
        String pdfText = new PDFTextStripper().getText(document);
        document.close();
        log.info("PDF解析完成，总字数: {}", pdfText.length());
        List<Document> chunks = textSplitter.split(new Document(pdfText));
        log.info("文档分成了 {} 块", chunks.size());
        for (Document doc : chunks) {
            float[] vec = embeddingService.embed(doc.getText());
            myVectorStore.add(doc.getText(), vec);
        }
        log.info("文档已存入向量库，当前向量库大小: {}", myVectorStore.size());
        return Map.of(
                "status", "success",
                "fileName", fileName,
                "chunks", chunks.size(),
                "totalVectors", myVectorStore.size()
        );
    }
}

5.4 问答服务

package com.jam.demo.service;
import com.alibaba.fastjson2.JSON;
import lombok.extern.slf4j.Slf4j;
import okhttp3.*;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Service;
import java.util.List;
import java.util.Map;
/**
 * 知识库问答服务
 * @author ken
 * @date 2026-04-13
 */
@Slf4j
@Service
public class KnowledgeBaseV2Service {
    private final MyVectorStore myVectorStore;
    private final VolcEmbeddingService embeddingService;
    private final OkHttpClient client;
    @Value("${spring.ai.openai.base-url}")
    private String baseUrl;
    @Value("${spring.ai.openai.api-key}")
    private String apiKey;
    @Value("${spring.ai.openai.chat.options.model}")
    private String chatModelId;
    public KnowledgeBaseV2Service(MyVectorStore myVectorStore, VolcEmbeddingService embeddingService) {
        this.myVectorStore = myVectorStore;
        this.embeddingService = embeddingService;
        this.client = new OkHttpClient();
    }
    /**
     * 知识库问答
     * @param question 用户问题
     * @return 回答结果
     */
    public Map<String, Object> ask(String question) {
        log.info("收到用户问题: {}", question);
        float[] queryVec = embeddingService.embed(question);
        List<String> relevant = myVectorStore.search(queryVec, 3);
        if (relevant.isEmpty()) {
            return Map.of("answer", "未找到相关信息，请尝试其他问题");
        }
        String context = String.join("\n---\n", relevant);
        log.info("检索到 {} 条相关内容", relevant.size());
        String prompt = """
                请根据以下上下文回答用户的问题，不要编造信息。如果上下文中没有相关内容，请回答"未找到相关信息"。
                上下文：
                %s
                问题：%s
                """.formatted(context, question);
        try {
            String answer = callDoubao(prompt);
            return Map.of(
                    "answer", answer,
                    "context", context,
                    "relevantCount", relevant.size()
            );
        } catch (Exception e) {
            log.error("调用豆包大模型失败", e);
            return Map.of("answer", "系统繁忙，请稍后再试");
        }
    }
    /**
     * 调用豆包大模型
     * @param prompt 提示词
     * @return 模型回答
     * @throws Exception 异常
     */
    private String callDoubao(String prompt) throws Exception {
        Map<String, Object> requestBody = Map.of(
                "model", chatModelId,
                "messages", List.of(Map.of("role", "user", "content", prompt)),
                "temperature", 0.3,
                "max_tokens", 4096
        );
        String json = JSON.toJSONString(requestBody);
        Request request = new Request.Builder()
                .url(baseUrl + "/chat/completions")
                .header("Authorization", "Bearer " + apiKey.trim())
                .header("Content-Type", "application/json")
                .post(RequestBody.create(json, MediaType.parse("application/json")))
                .build();
        try (Response response = client.newCall(request).execute()) {
            String respBody = response.body().string();
            if (!response.isSuccessful()) {
                throw new RuntimeException("豆包调用失败：" + respBody);
            }
            return JSON.parseObject(respBody)
                    .getJSONArray("choices")
                    .getJSONObject(0)
                    .getJSONObject("message")
                    .getString("content");
        }
    }
}

5.5 控制器

package com.jam.demo.controller;
import com.jam.demo.service.DocumentV2Service;
import com.jam.demo.service.KnowledgeBaseV2Service;
import com.jam.demo.service.MyVectorStore;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.multipart.MultipartFile;
import java.util.HashMap;
import java.util.Map;
/**
 * 知识库V2控制器
 * @author ken
 * @date 2026-04-13
 */
@Slf4j
@RestController
@RequestMapping("/api/v2/kb")
@Tag(name = "向量知识库接口", description = "基于豆包多模态向量模型的知识库接口")
public class KnowledgeBaseV2Controller {
    private final DocumentV2Service documentV2Service;
    private final KnowledgeBaseV2Service knowledgeBaseV2Service;
    private final MyVectorStore myVectorStore;
    public KnowledgeBaseV2Controller(DocumentV2Service documentV2Service,
                                     KnowledgeBaseV2Service knowledgeBaseV2Service,
                                     MyVectorStore myVectorStore) {
        this.documentV2Service = documentV2Service;
        this.knowledgeBaseV2Service = knowledgeBaseV2Service;
        this.myVectorStore = myVectorStore;
    }
    @PostMapping("/upload")
    @Operation(summary = "上传PDF文档", description = "上传PDF文档并自动向量化存入向量库")
    public Map<String, Object> upload(
            @Parameter(description = "PDF文件", required = true)
            @RequestParam("file") MultipartFile file,
            @Parameter(description = "文件名")
            @RequestParam(value = "fileName", required = false) String fileName) {
        try {
            String name = fileName != null ? fileName : file.getOriginalFilename();
            return documentV2Service.uploadPdf(file, name);
        } catch (Exception e) {
            log.error("上传失败", e);
            Map<String, Object> error = new HashMap<>();
            error.put("status", "error");
            error.put("message", "上传失败：" + e.getMessage());
            return error;
        }
    }
    @GetMapping("/ask")
    @Operation(summary = "知识库问答", description = "根据问题检索向量库并返回回答")
    public Map<String, Object> ask(
            @Parameter(description = "用户问题", required = true)
            @RequestParam("question") String question) {
        return knowledgeBaseV2Service.ask(question);
    }
    @DeleteMapping("/clear")
    @Operation(summary = "清空向量库", description = "清空所有向量数据")
    public Map<String, Object> clear() {
        myVectorStore.clear();
        return Map.of(
                "status", "success",
                "message", "向量数据库已清空"
        );
    }
    @GetMapping("/info")
    @Operation(summary = "获取向量库信息", description = "获取当前向量库的基本信息")
    public Map<String, Object> info() {
        return Map.of(
                "version", "v2",
                "type", "多模态向量知识库",
                "embeddingModel", "doubao-embedding-vision",
                "vectorStore", "内存向量库",
                "totalVectors", myVectorStore.size()
        );
    }
}

5.6 Swagger配置

package com.jam.demo.config;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
/**
 * Swagger配置
 * @author ken
 * @date 2026-04-13
 */
@Configuration
public class SwaggerConfig {
    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("豆包向量知识库API")
                        .description("基于Spring AI和火山引擎豆包的向量知识库接口文档")
                        .version("2.0.0"));
    }
}

六、测试验证

6.1 上传PDF文档

curl -X POST "http://localhost:8080/api/v2/kb/upload" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@低代码开发师【初级】实战教程.pdf" \
  -F "fileName=低代码开发师【初级】实战教程.pdf"

成功响应

{
    "status": "success",
    "fileName": "低代码开发师【初级】实战教程.pdf",
    "chunks": 12,
    "totalVectors": 12
}

6.2 知识库问答

curl -X GET "http://localhost:8080/api/v2/kb/ask?question=什么是低代码开发"

成功响应

{
    "answer": "低代码开发是一种可视化的应用开发方法，它允许开发者通过拖拽组件和配置参数的方式快速构建应用程序，而不需要编写大量的传统代码。低代码开发平台提供了丰富的预制组件和模板，能够显著提高开发效率，降低开发门槛，让非专业开发者也能参与应用开发。",
    "context": "...",
    "relevantCount": 3
}

七、性能优化

7.1 批量向量化

将多个文本块合并为一个请求发送给向量接口，减少网络IO次数：

public List<float[]> batchEmbed(List<String> texts) {
    // 实现批量向量化逻辑
}

7.2 异步处理

使用Spring的异步机制处理文档上传和向量化，避免阻塞用户请求：

@Async
public CompletableFuture<Void> processDocumentAsync(MultipartFile file, String fileName) {
    // 实现异步处理逻辑
}

7.3 向量维度优化

根据业务需求选择合适的向量维度，维度越低，计算速度越快，存储空间越小：

• 1024维：平衡精度和性能
• 512维：性能优先
• 2048维：精度优先

7.4 缓存机制

对频繁查询的问题和答案进行缓存，减少重复计算和接口调用：

private final LoadingCache<String, String> answerCache = Caffeine.newBuilder()
        .maximumSize(1000)
        .expireAfterWrite(1, TimeUnit.HOURS)
        .build(key -> knowledgeBaseV2Service.ask(key).get("answer").toString());

7.5 连接池配置

优化OkHttp连接池配置，提高并发处理能力：

this.client = new OkHttpClient.Builder()
        .connectTimeout(30, TimeUnit.SECONDS)
        .readTimeout(30, TimeUnit.SECONDS)
        .writeTimeout(30, TimeUnit.SECONDS)
        .connectionPool(new ConnectionPool(20, 5, TimeUnit.MINUTES))
        .build();

八、总结

本文完整记录了Spring AI整合火山引擎豆包向量模型过程中遇到的所有问题和解决方案。通过抛弃Spring AI自带的不兼容实现，编写原生HTTP调用代码，我们成功解决了所有兼容性问题，实现了一个稳定、高效的向量知识库系统。

九、用向量存储前后查询效果

9.1 v1版本没存向量

上传接口：

查询接口：

很显然，效果太差，结果不是我想要的。

9.2 v2版本向量存储

上传接口：

查询接口：

满足了最终需求。😊