Astrsomn 文档

中文

English

中文

English

Appearance

模型供应商开发 ​

本章节介绍如何开发自定义大模型供应商插件，使 Astrsomn 支持新的大模型平台。

概述 ​

Astrsomn 通过 SPI（Service Provider Interface） 机制加载模型供应商插件。每个供应商需要：

  1. 实现 ModelProviderHandler 接口（推荐继承 AbstractModelProviderHandler）
  2. 注册 SPI 服务描述文件
  3. 创建 AstroExtensionDescriptor 用于插件元数据管理

架构说明 ​

模型供应商的职责是将 LangChain4j 的模型接口（ChatModel / StreamingChatModel / EmbeddingModel）与具体的大模型平台对接。

开发步骤 ​

1. 创建 Maven 模块 ​

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

    <dependencies>
        <!-- 核心 API 依赖 -->
        <dependency>
            <groupId>com.astrsomn</groupId>
            <artifactId>astrsomn-api-runtime</artifactId>
            <version>0.2.0-SNAPSHOT</version>
        </dependency>

        <!-- LangChain4j 模型接口 -->
        <dependency>
            <groupId>dev.langchain4j</groupId>
            <artifactId>langchain4j</artifactId>
        </dependency>
    </dependencies>
</project>

2. 实现 ModelProviderHandler ​

推荐继承 AbstractModelProviderHandler，它提供了模型类型分发、参数校验等模板方法：

java
package com.astrsomn.provider.custom;

import com.astrsomn.api.runtime.common.constant.AiModelEnum;
import com.astrsomn.api.runtime.common.entity.AiModelEntity;
import com.astrsomn.api.runtime.common.langchain.buildParam.AstroChatParam;
import com.astrsomn.api.runtime.common.langchain.extension.model.AbstractModelProviderHandler;
import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.model.chat.StreamingChatModel;

import java.util.List;

public class CustomProviderHandler extends AbstractModelProviderHandler {

    @Override
    public AiModelEnum.ProviderEnum getProvider() {
        return AiModelEnum.ProviderEnum.CUSTOM;  // 需先在枚举中注册
    }

    @Override
    public <T> T createModel(Class<T> modelClass, AstroChatParam<?> param) {
        // 使用父类的模板方法自动分发
        return dispatchModel(modelClass, param);
    }

    @Override
    protected ChatModel getChatModel(AstroChatParam<?> param) {
        // 构建同步聊天模型
        // 从 param 中获取 apiKey、baseUrl、modelSetting 等配置
        return CustomChatModel.builder()
                .apiKey(param.getApiKey())
                .baseUrl(param.getBaseUrl())
                .modelName(resolveModelKey(param))
                .temperature(param.getModelSetting().getTemperature())
                .maxTokens(param.getModelSetting().getMaxTokens())
                .build();
    }

    @Override
    protected StreamingChatModel getStreamModel(AstroChatParam<?> param) {
        // 构建流式聊天模型
        return CustomStreamingChatModel.builder()
                .apiKey(param.getApiKey())
                .baseUrl(param.getBaseUrl())
                .modelName(resolveModelKey(param))
                .build();
    }

    @Override
    public List<AiModelEntity> getAvailableModels(String apiKey, String apiSecret) {
        // 调用供应商 API 获取可用模型列表
        // 返回 AiModelEntity 列表供前端展示
        return fetchModelsFromApi(apiKey, apiSecret);
    }
}

关于 AbstractModelProviderHandler

父类提供了以下便捷方法：

  • dispatchModel() — 根据 modelClass 类型自动分发到 getChatModel / getStreamModel / getEmbeddingModel
  • resolveModelKey() — 从参数中解析模型名称
  • validateParams() — 校验参数非空
  • toJson() — 对象转 JSON 字符串

3. 创建扩展描述符 ​

创建 AstroExtensionDescriptor 子类，用于注册插件元数据：

java
package com.astrsomn.provider.custom;

import com.astrsomn.api.runtime.common.constant.AiModelEnum;
import com.astrsomn.api.system.entity.SystemExtensionEnum;
import com.astrsomn.starter.system.AstroExtensionDescriptor;

public class CustomExtensionDescriptor extends AstroExtensionDescriptor {

    @Override
    public String getExtensionKey() {
        return AiModelEnum.ProviderEnum.CUSTOM.getCode();
    }

    @Override
    public String getExtensionCode() {
        return AiModelEnum.ProviderEnum.CUSTOM.getCode();
    }

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

    // 从 classpath 加载扩展属性文件
    // 默认名称/版本/头像等从 /extension-custom.properties 读取
}

4. 创建扩展属性文件 ​

在 src/main/resources/ 下创建 extension-custom.properties：

properties
name=Custom Model Provider
version=0.2.0-SNAPSHOT
description=自定义大模型供应商插件
changeLog=初始版本
minServerVersion=0.2.0

5. 注册 SPI ​

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

文件 1： com.astrsomn.api.runtime.common.langchain.extension.model.ModelProviderHandler

com.astrsomn.provider.custom.CustomProviderHandler

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

com.astrsomn.provider.custom.CustomExtensionDescriptor

接口规范 ​

ModelProviderHandler ​

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

方法返回值说明
getProvider()AiModelEnum.ProviderEnum返回供应商枚举标识
createModel(Class<T>, AstroChatParam<?>)<T> T创建模型实例（Chat / Streaming / Embedding）
getAvailableModels(String, String)List<AiModelEntity>获取可用模型列表
getVersion()String插件版本（默认 "1.0.0"）
getAuthor()String作者信息（默认 "Astrsomn"）

AbstractModelProviderHandler ​

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

方法说明
dispatchModel(Class<T>, AstroChatParam<?>)模板方法，按类型分发到 getChatModel / getStreamModel / getEmbeddingModel
resolveModelKey(AstroChatParam<?>)从参数解析模型名称
validateParams(Class<?>, AstroChatParam<?>)校验参数非空
getChatModel(AstroChatParam<?>)子类覆写 — 创建同步 ChatModel
getStreamModel(AstroChatParam<?>)子类覆写 — 创建流式 StreamingChatModel
getEmbeddingModel(AstroChatParam<?>)子类覆写 — 创建 EmbeddingModel

AstroExtensionDescriptor ​

包路径： com.astrsomn.starter.system

方法说明
getExtensionKey()插件唯一标识
getExtensionCode()插件编码
getExtensionType()插件类型（MODEL_PROVIDER / VECTOR_STORE / MCP）

打包部署 ​

bash
# 打包插件
mvn clean package -DskipTests

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

自动发现

框架启动时会自动扫描 plugins/ 目录，通过 SPI 加载所有扩展实现。无需修改框架源码。

参考实现 ​

查看现有 Provider 源码作为参考：

  • DeepSeek — astrsomn-plugins/astrsomn-providers/astrsomn-provider-deepseek/ — 使用 OpenAI 兼容协议，支持 Chat / Stream / Embedding
  • Zhipu — astrsomn-plugins/astrsomn-providers/astrsomn-provider-zhipu/
  • OpenAI — astrsomn-plugins/astrsomn-providers/astrsomn-provider-openai/

相关文档 ​