向量库开发

本章节介绍如何开发自定义向量存储插件，使 Astrsomn 支持新的向量数据库。

概述

Astrsomn 的向量存储扩展涉及三个核心接口：

接口	职责
`VecDriver`	向量驱动入口，管理数据源连接和元数据
`VecSource`	向量数据源，管理连接生命周期和 Store 创建
`VecStore`	向量存储，提供文档的增删改查操作

推荐继承 AbstractVecDriver 实现 VecDriver，然后分别实现 VecSource 和 VecStore。

开发步骤

1. 创建 Maven 模块

xml

<project>
    <groupId>com.astrsomn</groupId>
    <artifactId>astrsomn-vector-custom</artifactId>
    <version>0.2.0-SNAPSHOT</version>

    <dependencies>
        <dependency>
            <groupId>com.astrsomn</groupId>
            <artifactId>astrsomn-api-runtime</artifactId>
            <version>0.2.0-SNAPSHOT</version>
        </dependency>

        <!-- 向量数据库客户端 SDK -->
        <!-- 例如：qdrant-java-client、milvus-sdk-java 等 -->
    </dependencies>
</project>

2. 实现 VecDriver

继承 AbstractVecDriver，实现 VecDriver 接口：

java

package com.astrsomn.vector.custom;

import com.astrsomn.api.runtime.common.langchain.extension.vector.AbstractVecDriver;
import com.astrsomn.api.runtime.common.langchain.extension.vector.VecSource;
import com.astrsomn.api.vector.entity.AiVecDriverEntity;
import com.astrsomn.api.vector.entity.AiVecSourceEntity;

public class CustomVecDriver extends AbstractVecDriver {

    @Override
    public String getExtensionKey() {
        return "CUSTOM";  // 驱动唯一标识
    }

    @Override
    public VecSource bindSource(AiVecSourceEntity source) {
        // 将数据源实体绑定为具体的 VecSource 实现
        return new CustomVecSource(source);
    }

    @Override
    public AiVecDriverEntity getDriverEntity() {
        // 返回驱动元数据：名称、参数定义（如 HOST、PORT、TOKEN）
        AiVecDriverEntity entity = new AiVecDriverEntity();
        entity.setName("Custom Vector Store");
        entity.setProvider("CUSTOM");
        // 定义连接参数
        entity.setParams(defineDriverParams());
        return entity;
    }
}

3. 实现 VecSource

VecSource 管理向量数据库的连接：

java

package com.astrsomn.vector.custom;

import com.astrsomn.api.runtime.common.langchain.extension.vector.VecSource;
import com.astrsomn.api.runtime.common.langchain.extension.vector.VecStore;
import com.astrsomn.api.vector.entity.AiVecSourceEntity;
import com.astrsomn.api.vector.entity.AiVecStoreEntity;

public class CustomVecSource implements VecSource {

    private final AiVecSourceEntity sourceEntity;
    private CustomClient client;

    public CustomVecSource(AiVecSourceEntity sourceEntity) {
        this.sourceEntity = sourceEntity;
    }

    @Override
    public AiVecSourceEntity getEntity() {
        return sourceEntity;
    }

    @Override
    public boolean testConnection() {
        try {
            // 测试连接是否正常
            client.ping();
            return true;
        } catch (Exception e) {
            return false;
        }
    }

    @Override
    public void shutdown() {
        // 关闭连接，释放资源
        if (client != null) {
            client.close();
        }
    }

    @Override
    public VecStore openStore(AiVecStoreEntity store) {
        // 打开或创建一个向量存储
        return new CustomVecStore(this, store);
    }
}

4. 实现 VecStore

VecStore 提供文档的实际存储操作：

java

package com.astrsomn.vector.custom;

import com.astrsomn.api.runtime.common.langchain.extension.vector.VecSource;
import com.astrsomn.api.runtime.common.langchain.extension.vector.VecStore;
import com.astrsomn.api.vector.entity.AiVecDocEntity;
import com.astrsomn.api.vector.entity.AiVecStoreEntity;
import dev.langchain4j.data.segment.TextSegment;
import dev.langchain4j.store.embedding.EmbeddingStore;

public class CustomVecStore implements VecStore {

    private final CustomVecSource source;
    private final AiVecStoreEntity storeEntity;

    public CustomVecStore(CustomVecSource source, AiVecStoreEntity storeEntity) {
        this.source = source;
        this.storeEntity = storeEntity;
    }

    @Override
    public VecSource getSource() {
        return source;
    }

    @Override
    public AiVecStoreEntity getEntity() {
        return storeEntity;
    }

    @Override
    public void createCollection() {
        // 创建向量集合
    }

    @Override
    public void dropCollection() {
        // 删除向量集合
    }

    @Override
    public boolean exists() {
        // 检查集合是否存在
        return false;
    }

    @Override
    public long count() {
        // 返回文档数量
        return 0;
    }

    @Override
    public EmbeddingStore<TextSegment> getEmbeddingStore() {
        // 返回 LangChain4j EmbeddingStore 实现
        // 这是最核心的方法 — 框架通过此方法进行向量存储操作
        return embeddingStore;
    }
}

核心方法：getEmbeddingStore()

getEmbeddingStore() 返回 LangChain4j 的 EmbeddingStore<TextSegment> 接口实现。这是框架与向量数据库交互的关键桥梁 — 所有的文档添加、搜索、删除操作都通过这个接口完成。如果你的向量数据库客户端已有 LangChain4j 集成（如 Qdrant、Milvus、Chroma），可以直接使用。

5. 创建扩展描述符

java

package com.astrsomn.vector.custom;

import com.astrsomn.starter.system.AstroExtensionDescriptor;
import com.astrsomn.api.system.entity.SystemExtensionEnum;

public class CustomVecExtensionDescriptor extends AstroExtensionDescriptor {

    @Override
    public String getExtensionKey() {
        return "CUSTOM";
    }

    @Override
    public String getExtensionCode() {
        return "CUSTOM";
    }

    @Override
    public SystemExtensionEnum.ExtensionTypeEnum getExtensionType() {
        return SystemExtensionEnum.ExtensionTypeEnum.VECTOR_STORE;
    }
}

6. 注册 SPI

在 src/main/resources/META-INF/services/ 下创建两个文件：

文件 1： com.astrsomn.api.runtime.common.langchain.extension.vector.VecDriver

com.astrsomn.vector.custom.CustomVecDriver

文件 2： com.astrsomn.api.runtime.common.langchain.extension.AstroExtensionDescriptor

com.astrsomn.vector.custom.CustomVecExtensionDescriptor

接口规范

VecDriver

包路径： com.astrsomn.api.runtime.common.langchain.extension.vector

方法	返回值	说明
`getExtensionKey()`	`String`	驱动唯一标识
`bindSource(AiVecSourceEntity)`	`VecSource`	将数据源实体绑定为 VecSource
`getDriverEntity()`	`AiVecDriverEntity`	返回驱动元数据（名称、参数定义）
`getVersion()`	`String`	版本号（默认 `"1.0.0"`）
`getAuthor()`	`String`	作者信息（默认 `"Astrsomn"`）

VecSource

包路径： com.astrsomn.api.runtime.common.langchain.extension.vector

方法	返回值	说明
`getEntity()`	`AiVecSourceEntity`	返回数据源实体
`testConnection()`	`boolean`	测试连接是否正常
`shutdown()`	`void`	关闭连接，释放资源
`openStore(AiVecStoreEntity)`	`VecStore`	打开或创建存储

VecStore

包路径： com.astrsomn.api.runtime.common.langchain.extension.vector

方法	返回值	说明
`getSource()`	`VecSource`	返回所属数据源
`getEntity()`	`AiVecStoreEntity`	返回存储实体
`createCollection()`	`void`	创建集合
`dropCollection()`	`void`	删除集合
`exists()`	`boolean`	检查集合是否存在
`count()`	`long`	返回文档数量
`getEmbeddingStore()`	`EmbeddingStore<TextSegment>`	核心方法 — 返回 LangChain4j 存储实现

打包部署

bash

# 打包插件
mvn clean package -DskipTests

# 复制 JAR 到 plugins 目录
cp target/astrsomn-vector-custom-0.2.0-SNAPSHOT.jar /path/to/astrsomn/plugins/

参考实现

Qdrant — astrsomn-plugins/astrsomn-vector/astrsomn-vector-qdrant/
Milvus — astrsomn-plugins/astrsomn-vector/astrsomn-vector-milvus/
Chroma — astrsomn-plugins/astrsomn-vector/astrsomn-vector-chroma/
Redis — astrsomn-plugins/astrsomn-vector/astrsomn-vector-redis/

向量库开发 ​

概述 ​

开发步骤 ​

1. 创建 Maven 模块 ​

2. 实现 VecDriver ​

3. 实现 VecSource ​

4. 实现 VecStore ​

5. 创建扩展描述符 ​

6. 注册 SPI ​

接口规范 ​

VecDriver ​

VecSource ​

VecStore ​

打包部署 ​

参考实现 ​

相关文档 ​

向量库开发

概述

开发步骤

1. 创建 Maven 模块

2. 实现 VecDriver

3. 实现 VecSource

4. 实现 VecStore

5. 创建扩展描述符

6. 注册 SPI

接口规范

VecDriver

VecSource

VecStore

打包部署

参考实现

相关文档