跳至主要內容

拓展指南

BladeX大约 7 分钟vectortool

向量库拓展指南

拓展概述

BladeX AI平台目前支持Milvus、Redis Stack、PgVector三种向量库。基于LangChain4j框架的统一接口设计，开发者可以轻松添加对新向量库的支持。本指南详细介绍前后端扩展新向量库的完整流程。

扩展能力

  • 完整的向量库生态：支持LangChain4j生态中的所有向量库
  • 统一的抽象封装：基于AbstractEmbeddingStoreTemplate的统一接口
  • 灵活的配置管理：支持数据库配置和属性文件配置
  • 无缝集成：新向量库可无缝集成到现有业务流程

🔧 一、技术架构了解

1.1 向量库模块结构

rag/engine/provider/
├── AbstractEmbeddingStoreTemplate.java     # 抽象模板基类
├── EmbeddingStoreTemplate.java             # 向量库接口
├── RagFactory.java                         # 向量库工厂
├── builder/
│   └── BladeEmbeddingStoreBuilder.java     # 向量库构建器
└── store/
    ├── MilvusEmbeddingStoreTemplate.java   # Milvus实现
    ├── RedisEmbeddingStoreTemplate.java    # Redis实现
    ├── PgVectorEmbeddingStoreTemplate.java # PgVector实现
    └── ChromaEmbeddingStoreTemplate.java   # 新增Chroma实现

1.2 LangChain4j向量库支持

BladeX AI平台基于LangChain4j框架，支持以下向量库：

向量库状态特点适用场景
Milvus✅ 已支持高性能分布式大规模生产环境
Redis Stack✅ 已支持内存高速访问实时查询场景
PgVector✅ 已支持SQL生态兼容传统数据库环境
Chroma🔨 示例扩展轻量级部署开发测试环境
Pinecone⏳ 可扩展云端托管服务云原生应用
Weaviate⏳ 可扩展语义搜索优化知识图谱应用
Qdrant⏳ 可扩展Rust高性能高并发场景

🚀 二、后端扩展开发

2.1 添加向量库常量

首先在RagConstant.java中添加新向量库类型常量：

// 在 RagConstant.java 中添加
/**
 * 向量库类型常量
 */
String STORE_TYPE_CHROMA = "chroma";
String STORE_TYPE_PINECONE = "pinecone";
String STORE_TYPE_WEAVIATE = "weaviate";
String STORE_TYPE_QDRANT = "qdrant";

2.2 扩展向量库构建器

在BladeEmbeddingStoreBuilder.java中添加新的构建方法：

/**
 * 构建Chroma向量库模板
 *
 * @return Chroma向量库模板
 */
public ChromaEmbeddingStoreTemplate buildChroma() {
    return new ChromaEmbeddingStoreTemplate(this);
}

/**
 * 构建Pinecone向量库模板
 *
 * @return Pinecone向量库模板
 */
public PineconeEmbeddingStoreTemplate buildPinecone() {
    return new PineconeEmbeddingStoreTemplate(this);
}

2.3 创建向量库实现类

以Chroma为例，创建ChromaEmbeddingStoreTemplate.java：

package org.springblade.modules.aigc.rag.engine.provider.store;

import dev.langchain4j.data.segment.TextSegment;
import dev.langchain4j.store.embedding.EmbeddingStore;
import dev.langchain4j.store.embedding.chroma.ChromaEmbeddingStore;
import lombok.extern.slf4j.Slf4j;
import org.springblade.modules.aigc.rag.engine.provider.AbstractEmbeddingStoreTemplate;
import org.springblade.modules.aigc.rag.engine.provider.builder.BladeEmbeddingStoreBuilder;

/**
 * Chroma向量库模板
 *
 * @author BladeX
 */
@Slf4j
public class ChromaEmbeddingStoreTemplate extends AbstractEmbeddingStoreTemplate {

    /**
     * 使用构建器创建Chroma向量库模板
     *
     * @param builder 向量库构建器
     */
    public ChromaEmbeddingStoreTemplate(BladeEmbeddingStoreBuilder builder) {
        super(
            builder.getName(),
            builder.getDimension(),
            createChromaEmbeddingStore(
                builder.getHost(),
                builder.getPort(),
                builder.getTableName()
            )
        );
    }

    /**
     * 创建Chroma向量库实例
     */
    private static EmbeddingStore<TextSegment> createChromaEmbeddingStore(
        String host, Integer port, String collectionName) {
        try {
            return ChromaEmbeddingStore.builder()
                .baseUrl(buildBaseUrl(host, port))
                .collectionName(collectionName != null ? collectionName : "default_collection")
                .build();
        } catch (Exception e) {
            throw new RuntimeException("创建Chroma向量库失败: " + e.getMessage(), e);
        }
    }

    /**
     * 构建Chroma服务地址
     */
    private static String buildBaseUrl(String host, Integer port) {
        if (host == null || host.trim().isEmpty()) {
            host = "localhost";
        }
        if (port == null) {
            port = 8000; // Chroma默认端口
        }
        return String.format("http://%s:%d", host, port);
    }
}

2.4 扩展工厂类

在RagFactory.java的switchType方法中添加新的case：

private EmbeddingStoreTemplate switchType(String vdbType, BladeEmbeddingStoreBuilder builder) {
    return switch (vdbType) {
        case RagConstant.STORE_TYPE_REDIS -> builder.buildRedis();
        case RagConstant.STORE_TYPE_MILVUS -> builder.buildMilvus();
        case RagConstant.STORE_TYPE_PGVECTOR -> builder.buildPgVector();
        case RagConstant.STORE_TYPE_CHROMA -> builder.buildChroma(); // 新增
        case RagConstant.STORE_TYPE_PINECONE -> builder.buildPinecone(); // 新增
        default -> {
            log.warn("不支持的向量库类型: {}", vdbType);
            yield null;
        }
    };
}

2.5 添加Maven依赖

在pom.xml中添加新向量库的依赖：

<!-- Chroma向量库支持 -->
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-chroma</artifactId>
    <version>1.0.1-beta6</version>
</dependency>

<!-- Pinecone向量库支持 -->
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-pinecone</artifactId>
    <version>1.0.1-beta6</version>
</dependency>

📈 三、前端扩展开发

3.1 扩展向量库类型枚举

在前端的向量库配置组件中，添加新的向量库类型选项：

// 向量库类型选项
const vectorStoreTypes = [
  { label: 'Milvus', value: 'milvus' },
  { label: 'Redis Stack', value: 'redis' },
  { label: 'PgVector', value: 'pgvector' },
  { label: 'Chroma', value: 'chroma' },        // 新增
  { label: 'Pinecone', value: 'pinecone' },    // 新增
  { label: 'Weaviate', value: 'weaviate' },    // 新增
  { label: 'Qdrant', value: 'qdrant' }         // 新增
]

3.2 扩展配置表单

在向量库配置表单中添加新向量库的特定配置项：

<template>
  <!-- 现有的通用配置项 -->
  <el-form-item label="向量库类型" prop="type">
    <el-select v-model="form.type" @change="onTypeChange">
      <el-option 
        v-for="item in vectorStoreTypes" 
        :key="item.value" 
        :label="item.label" 
        :value="item.value" 
      />
    </el-select>
  </el-form-item>

  <!-- Chroma特定配置 -->
  <template v-if="form.type === 'chroma'">
    <el-form-item label="服务地址" prop="host">
      <el-input v-model="form.host" placeholder="localhost" />
    </el-form-item>
    <el-form-item label="端口" prop="port">
      <el-input-number v-model="form.port" :min="1" :max="65535" />
    </el-form-item>
    <el-form-item label="集合名称" prop="tablename">
      <el-input v-model="form.tablename" placeholder="default_collection" />
    </el-form-item>
  </template>

  <!-- Pinecone特定配置 -->
  <template v-if="form.type === 'pinecone'">
    <el-form-item label="API Key" prop="password">
      <el-input v-model="form.password" type="password" show-password />
    </el-form-item>
    <el-form-item label="Environment" prop="host">
      <el-input v-model="form.host" placeholder="us-west1-gcp" />
    </el-form-item>
    <el-form-item label="Index Name" prop="tablename">
      <el-input v-model="form.tablename" placeholder="my-index" />
    </el-form-item>
  </template>
</template>

3.3 扩展表单验证规则

为新向量库添加特定的验证规则：

const getValidationRules = (type) => {
  const commonRules = {
    name: [{ required: true, message: '请输入向量库名称', trigger: 'blur' }],
    type: [{ required: true, message: '请选择向量库类型', trigger: 'change' }],
    dimension: [{ required: true, message: '请输入向量维度', trigger: 'blur' }]
  }

  const typeSpecificRules = {
    chroma: {
      host: [{ required: true, message: '请输入Chroma服务地址', trigger: 'blur' }],
      port: [{ required: true, message: '请输入Chroma端口', trigger: 'blur' }]
    },
    pinecone: {
      password: [{ required: true, message: '请输入Pinecone API Key', trigger: 'blur' }],
      host: [{ required: true, message: '请输入Pinecone Environment', trigger: 'blur' }],
      tablename: [{ required: true, message: '请输入Pinecone Index Name', trigger: 'blur' }]
    }
  }

  return { ...commonRules, ...typeSpecificRules[type] }
}

3.4 扩展默认配置

为新向量库提供默认配置值：

const getDefaultConfig = (type) => {
  const defaults = {
    chroma: {
      host: 'localhost',
      port: 8000,
      tablename: 'default_collection'
    },
    pinecone: {
      host: 'us-west1-gcp',
      port: null,
      tablename: 'my-index'
    },
    weaviate: {
      host: 'localhost',
      port: 8080,
      tablename: 'MyClass'
    }
  }
  
  return defaults[type] || {}
}

🛠️ 四、测试验证指南

4.1 单元测试

为新向量库创建单元测试：

@SpringBootTest
class ChromaEmbeddingStoreTemplateTest {

    @Test
    void testChromaEmbeddingStoreCreation() {
        // 构建测试配置
        BladeEmbeddingStoreBuilder builder = BladeEmbeddingStoreBuilder.builder()
            .name("test-chroma")
            .dimension(768)
            .host("localhost")
            .port(8000)
            .tableName("test_collection")
            .build();

        // 创建Chroma向量库模板
        ChromaEmbeddingStoreTemplate template = builder.buildChroma();

        // 验证基本属性
        assertThat(template.getName()).isEqualTo("test-chroma");
        assertThat(template.getDimension()).isEqualTo(768);
        assertThat(template.getEmbeddingStore()).isNotNull();
    }

    @Test
    void testAddAndSearchEmbedding() {
        // 测试向量添加和检索功能
        // ... 测试代码
    }
}

4.2 集成测试

创建端到端的集成测试：

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
@TestPropertySource(properties = {
    "blade.rag.embedding-stores.test-chroma.type=chroma",
    "blade.rag.embedding-stores.test-chroma.host=localhost",
    "blade.rag.embedding-stores.test-chroma.port=8000",
    "blade.rag.embedding-stores.test-chroma.dimension=768"
})
class ChromaIntegrationTest {

    @Autowired
    private RagFactory ragFactory;

    @Test
    void testChromaIntegration() {
        // 测试工厂创建
        EmbeddingStoreTemplate template = ragFactory.createEmbeddingStoreTemplate(
            "test-chroma", getTestConfig());
        
        assertThat(template).isNotNull();
        assertThat(template).isInstanceOf(ChromaEmbeddingStoreTemplate.class);
    }
}

4.3 配置验证

验证新向量库配置的正确性：

# 1. 启动向量库服务（以Chroma为例）
docker run -d --name chroma-server -p 8000:8000 chromadb/chroma:latest

# 2. 验证服务可用性
curl http://localhost:8000/api/v1/heartbeat

# 3. 运行集成测试
mvn test -Dtest=ChromaIntegrationTest

💡 五、最佳实践建议

5.1 开发规范

编码规范

  • 命名一致性：向量库实现类命名遵循{VectorStore}EmbeddingStoreTemplate格式
  • 异常处理：统一使用RuntimeException包装底层异常，提供清晰的错误信息
  • 日志记录：在关键操作点添加适当的日志记录
  • 配置验证：在构造函数中验证必要的配置参数

5.2 性能优化

性能考虑

  • 连接池管理：对于需要连接池的向量库，合理配置连接池参数
  • 批量操作：充分利用向量库的批量插入和查询能力
  • 缓存策略：对于频繁查询的向量，考虑添加缓存层
  • 监控指标：添加性能监控指标，跟踪向量库操作的延迟和吞吐量

5.3 文档维护

为新添加的向量库完善文档：

  1. 更新配置文档：在operation.md中添加新向量库的配置说明
  2. 补充FAQ：在faq.md中添加新向量库的常见问题
  3. 性能对比：提供不同向量库的性能对比数据
  4. 迁移指南：提供从其他向量库迁移到新向量库的指南

🔍 六、常见问题排查

6.1 编译问题

❓ Maven依赖冲突

  • 检查LangChain4j版本兼容性
  • 使用mvn dependency:tree分析依赖冲突
  • 排除冲突的传递依赖

❓ 类加载异常

  • 确认新向量库的Maven依赖已正确添加
  • 检查是否存在类路径冲突

6.2 运行时问题

❓ 向量库连接失败

  • 验证向量库服务是否正常运行
  • 检查网络连接和防火墙设置
  • 确认配置参数的正确性

❓ 性能问题

  • 检查向量维度配置是否合理
  • 监控向量库服务的资源使用情况
  • 考虑调整批处理大小和并发参数

6.3 配置问题

❓ 前端配置项不显示

  • 检查向量库类型枚举是否正确添加
  • 验证表单组件的条件渲染逻辑
  • 确认默认配置是否正确设置

通过遵循本指南，开发者可以快速、安全地为BladeX AI平台添加新的向量库支持，充分利用LangChain4j生态系统的强大能力。

上次编辑于:
贡献者: smallchill