前言

企业智能知识库系统集成了 AI 对话、AI 写作、AI 文档处理、知识库增强检索(RAG)、图谱增强推理(KAG)等多种 AI 能力。不同场景对模型的需求不同:对话需要流畅自然,写作需要创意丰富,代码生成需要逻辑严密,文档摘要需要准确精炼。

本系统支持多模型接入与运行时切换:用户可以在前端自由选择"通义千问"或"DeepSeek",也可以由后端根据场景自动选择最合适的模型。所有模型通过统一的 LangChain4j 接口接入,增加新模型只需修改配置和一处 switch 分支,无需改动业务逻辑。

本文将介绍系统的多模型架构设计、模型生命周期管理、前端切换交互和扩展新模型的方法。

1.一次模型切换走完发生了什么

用户在前端将模型从"通义千问"切换到"DeepSeek",发送一条消息,后端执行以下流程:

用户选择"DeepSeek",输入"Spring Boot 事务管理器如何获取数据库连接?"
  → 前端 aiService.askStream({ model: "deepseek", content: "...", enableRag: true })
  → POST /ai/chat/stream → AiChatController
  → AiChatServiceImpl.chatStream()
       ├── 读取 requestDTO.getModel() → "deepseek"
       ├── RAG 开关打开 → RagChatService.chatWithContextStream()
       │     ├── 向量检索(ES BM25 + kNN + RRF 融合)
       │     ├── 构建 RAG Prompt
       │     └── modelProvider.getModel("deepseek") → 获取 DeepSeek ChatLanguageModel
       ├── ChatLanguageModel.generate(prompt) → 调用 DeepSeek API
       └── SseEmitter → 流式返回前端
  → 前端解析 SSE 事件流,逐 Token 展示回答
  → 回答标注来源:[DeepSeek] + 引用编号
完整模型切换序列图见 5.2 运行时模型切换序列图。

这条链路涉及 1 个核心组件(ModelProvider)、7 个服务类、2 个外部 LLM API、以及前端的模型选择交互。下面逐层拆解。


2. 配置体系:application.yml 与环境变量

2.1 配置类全景

系统将所有模型配置集中管理,不使用 Spring @ConfigurationProperties 绑定,而是通过 ModelProvider 中的 @Value 注入:

# kb-ai/src/main/resources/application.yml

# ======================== 通义千问(阿里云 DashScope) ========================
qwen:
  api-key: ${QWEN_API_KEY:}
  base-url: ${QWEN_BASE_URL:https://dashscope.aliyuncs.com/compatible-mode/v1}
  chat:
    options:
      model: ${QWEN_MODEL:qwen3-max}
      temperature: 0.3
      max-tokens: 4000

# ======================== DeepSeek ========================
deepseek:
  api-key: ${DEEPSEEK_API_KEY:}
  model: deepseek-chat
  base-url: https://api.deepseek.com/v1
  max-tokens: 4096
  temperature: 0.7

# ======================== 默认模型 ========================
ai:
  default-model: qwen

# ======================== RAG 嵌入模型(通义千问 text-embedding-v3) ========================
rag:
  embedding:
    model: text-embedding-v3

# ======================== KAG 抽取模型 ========================
kag:
  extraction:
    model: qwen

2.2 环境变量覆盖

通过 .env 文件或系统环境变量传入 API Key,避免硬编码:

# .env.example
QWEN_API_KEY=your-qwen-api-key-here
QWEN_MODEL=qwen3-max
DEEPSEEK_API_KEY=your-deepseek-api-key-here
AI_DEFAULT_MODEL=qwen

2.3 配置设计考量

维度选择理由
API Key 注入@Value + 环境变量不在配置文件中暴露密钥,部署时通过环境变量注入
默认值策略api-key: ${VAR:} — 空字符串为未配置空字符串表示 Skip,不注册该模型
base-url 可配置Qwen 支持自定义允许内网代理或 DashScope 地域切换
服务级模型差异RAG/KAG 有独立模型配置RAG 可始终使用响应最快/最便宜的模型,无需跟随对话切换

3. ModelProvider:核心模型路由器

3.1 组件职责

图片.png

ModelProvider 是整个模型体系的中心组件,承担三个职责:

  1. 注册:启动时扫描配置,只注册 API Key 已配置的模型
  2. 缓存:按 ConcurrentHashMap 懒加载模型实例,重复请求不重复创建
  3. 路由:根据请求中的 model 字段返回对应的 ChatLanguageModel

3.2 核心代码

// kb-ai/src/main/java/com/knowledge/base/ai/config/ModelProvider.java
@Slf4j
@Component
public class ModelProvider {

    // ======================== 配置注入 ========================

    @Value("${qwen.api-key:}")
    private String qwenApiKey;

    @Value("${qwen.base-url:https://dashscope.aliyuncs.com/compatible-mode/v1}")
    private String qwenBaseUrl;

    @Value("${qwen.chat.options.model:qwen3-max}")
    private String qwenModel;

    @Value("${qwen.chat.options.temperature:0.3}")
    private Double qwenTemperature;

    @Value("${qwen.chat.options.max-tokens:4000}")
    private Integer qwenMaxTokens;

    @Value("${deepseek.api-key:}")
    private String deepseekApiKey;

    @Value("${deepseek.model:deepseek-chat}")
    private String deepseekModel;

    @Value("${deepseek.base-url:https://api.deepseek.com/v1}")
    private String deepseekBaseUrl;

    @Value("${deepseek.max-tokens:4096}")
    private Integer deepseekMaxTokens;

    @Value("${deepseek.temperature:0.7}")
    private Double deepseekTemperature;

    @Value("${ai.default-model:qwen}")
    private String defaultModel;

    // ======================== 三张内部表 ========================

    /** 模型实例缓存:key=模型名, value=ChatLanguageModel */
    private final Map<String, ChatLanguageModel> instanceCache = new ConcurrentHashMap<>();

    /** 模型可用性:按注册顺序排列 */
    private final Map<String, Boolean> modelAvailable = new LinkedHashMap<>();

    /** 模型展示信息:供前端 API 查询 */
    private final Map<String, ModelVO> modelInfoMap = new LinkedHashMap<>();

    // ======================== 初始化:注册所有模型 ========================

    @PostConstruct
    public void init() {
        checkAndRegister("qwen", "通义千问",
            "阿里云大语言模型,支持多轮对话、文本生成等", qwenApiKey);
        checkAndRegister("deepseek", "DeepSeek",
            "深度求索大语言模型,擅长代码生成和深度推理", deepseekApiKey);

        if (modelAvailable.isEmpty()) {
            log.error("FATAL: 没有可用的 AI 模型(所有 API Key 都未配置)");
        }
    }

    /**
     * 注册模型:仅当 apiKey 非空时注册
     */
    private void checkAndRegister(String key, String displayName,
                                   String description, String apiKey) {
        if (apiKey != null && !apiKey.trim().isEmpty()) {
            modelAvailable.put(key, true);
            modelInfoMap.put(key, new ModelVO(
                key, displayName, description, key.equals(defaultModel)));
            log.info("已注册 AI 模型:{} ({})", displayName, key);
        } else {
            log.warn("AI 模型未配置 API Key,跳过注册:{} ({})", displayName, key);
        }
    }

    // ======================== 模型获取 ========================

    /**
     * 获取指定模型实例(不带参数则返回默认模型)
     */
    public ChatLanguageModel getModel(String modelName) {
        String key = resolveModelKey(modelName);
        if (!modelAvailable.containsKey(key)) {
            throw new IllegalStateException(
                "模型 " + key + " 的 API Key 未配置,请检查环境变量");
        }
        return instanceCache.computeIfAbsent(key, this::buildModel);
    }

    /**
     * 模型名解析:空 → 默认模型
     */
    private String resolveModelKey(String modelName) {
        if (modelName == null || modelName.trim().isEmpty()) {
            return getDefaultModelName();
        }
        return modelName.trim().toLowerCase();
    }

    /**
     * 默认模型名:配置值 → 第一个可用模型 → "qwen"
     */
    public String getDefaultModelName() {
        if (modelAvailable.containsKey(defaultModel)) {
            return defaultModel;
        }
        if (!modelAvailable.isEmpty()) {
            return modelAvailable.keySet().iterator().next();
        }
        return "qwen";
    }

    /**
     * 获取可用模型列表(供前端下拉框使用)
     */
    public List<ModelVO> getAvailableModels() {
        return new ArrayList<>(modelInfoMap.values());
    }
}

3.3 关键设计点

  • 懒加载策略:instanceCache.computeIfAbsent() 确保只有在第一次调用 getModel() 时才创建模型实例,应用启动时不依赖 API Key 可达性
  • LinkedHashMap 维护顺序:modelAvailable 使用 LinkedHashMap,保证前端模型列表按注册顺序排列
  • 空 API Key 跳过注册:没有配置 API Key 的模型不会出现在 modelAvailable 中,前端看不到,后端也不会尝试调用
  • FATAL 日志:所有模型都不可用时打印 FATAL 级别日志,方便运维发现配置遗漏

4. 模型实例化:buildModel 工厂方法

4.1 工厂方法

// ModelProvider.buildModel() —— 模型实例构造
private ChatLanguageModel buildModel(String modelName) {
    switch (modelName) {
        case "qwen" -> {
            return OpenAiChatModel.builder()
                .apiKey(qwenApiKey)
                .baseUrl(qwenBaseUrl)
                .modelName(qwenModel)
                .temperature(qwenTemperature)
                .maxTokens(qwenMaxTokens)
                .build();
        }
        case "deepseek" -> {
            return OpenAiChatModel.builder()
                .apiKey(deepseekApiKey)
                .baseUrl(deepseekBaseUrl)
                .modelName(deepseekModel)
                .temperature(deepseekTemperature)
                .maxTokens(deepseekMaxTokens)
                .build();
        }
        default -> throw new IllegalArgumentException(
            "不支持的模型:" + modelName);
    }
}

4.2 为什么都用 OpenAiChatModel

通义千问和 DeepSeek 都提供了 OpenAI 兼容 API,这意味着它们接受与 OpenAI 相同的请求/响应格式(POST /v1/chat/completions)。LangChain4j 的 OpenAiChatModel 正是针对这种协议的聊天模型实现,只需传入不同的 baseUrl 和 apiKey,即可适配不同的模型供应商。

图片.png

这种设计的一个直接好处是:新增任何 OpenAI 兼容的模型供应商(如 GPT-4o、Claude via Bedrock、Ollama 本地模型等),只需要在 switch 分支中添加一个 buildModel 用例,无需改动任何业务代码。

4.3 Embedding 模型

嵌入模型也用了同样的模式,但它是条件装配的:

// kb-ai/src/main/java/com/knowledge/base/ai/config/EmbeddingConfig.java
@Configuration
@ConditionalOnProperty(name = "rag.enabled", havingValue = "true", matchIfMissing = true)
@ConditionalOnExpression("!'${qwen.api-key:}'.isBlank()")
public class EmbeddingConfig {

    @Value("${qwen.api-key}")
    private String qwenApiKey;

    @Value("${qwen.base-url:https://dashscope.aliyuncs.com/compatible-mode/v1}")
    private String qwenBaseUrl;

    @Value("${rag.embedding.model:text-embedding-v3}")
    private String embeddingModel;

    @Bean
    @ConditionalOnMissingBean
    public EmbeddingModel embeddingModel() {
        return OpenAiEmbeddingModel.builder()
            .apiKey(qwenApiKey)
            .baseUrl(qwenBaseUrl)
            .modelName(embeddingModel)
            .build();
    }
}

@ConditionalOnProperty + @ConditionalOnExpression 双重条件确保:RAG 关闭或 Qwen API Key 未配置时,不创建 Embedding Bean,系统退化为纯对话模式。


5. 运行时模型切换:从请求到 LLM 调用

5.1 请求数据传输

// kb-ai/src/main/java/com/knowledge/base/ai/dto/ChatRequestDTO.java
public class ChatRequestDTO implements Serializable {
    @NotBlank(message = "对话内容不能为空")
    @Schema(description = "用户输入的问题")
    private String content;

    @Schema(description = "AI模型名称:qwen(通义千问)| deepseek(DeepSeek)")
    private String model;

    @Schema(description = "对话标识ID(首次为空,后端自动创建)")
    private Long conversationId;

    @Schema(description = "是否启用知识库增强(RAG)")
    private Boolean enableRag;

    @Schema(description = "是否启用知识图谱推理(KAG)")
    private Boolean enableKag;
}

model 字段是可选的。如果前端不传,后端自动使用 ai.default-model 配置的默认模型。

5.2 运行时模型切换序列图

图片.png

5.3 各服务中的模型解析模式

所有服务类使用统一的模型解析模式,三步走:

// 标准模式 —— AiChatServiceImpl
public ChatResponseVO chat(ChatRequestDTO requestDTO, Long userId) {
    // Step 1: 解析模型名(空 → 默认)
    String modelName = requestDTO.getModel() != null
        ? requestDTO.getModel()
        : modelProvider.getDefaultModelName();

    // Step 2: 获取模型实例
    ChatLanguageModel chatModel = modelProvider.getModel(modelName);

    // Step 3: 调用生成
    Response<AiMessage> response = chatModel.generate(
        SystemMessage.from(systemPrompt),
        UserMessage.from(userPrompt)
    );
    return buildResponse(response);
}

// 简化模式 —— AiDocumentServiceImpl(文档处理不提供用户选择)
// 始终使用默认模型:
ChatLanguageModel chatModel = modelProvider.getDefaultModel();

// KAG 抽取使用独立模型配置 —— LLMExtractionServiceImpl
// 不走用户选择,使用 kag.extraction.model 配置:
ChatLanguageModel chatModel = modelProvider.getModel(extractionModel);

6. 各服务中的模型使用模式

6.1 服务总览

服务模型选择方式场景特点
AiChatService用户选择 → 默认对话需要跟随用户偏好
AiWritingService用户选择 → 默认写作需要多样化的模型风格
AiDocumentService固定默认模型摘要/大纲/扩写,需要稳定输出
RagChatService用户选择 → 默认知识库增强对话
KAGChatService用户选择 → 默认图谱推理增强对话
LLMExtractionServicekag.extraction.model 配置KAG 实体抽取,独立配置

6.2 AiChatService:对话服务

// kb-ai/src/main/java/com/knowledge/base/ai/service/impl/AiChatServiceImpl.java
public ChatResponseVO chat(ChatRequestDTO requestDTO, Long userId) {
    // RAG 路由:如果启用 RAG 且 ragChatService 可用,委托给 RAG 服务
    if (requestDTO.isEnableRag() && ragChatService != null) {
        try {
            return ragChatService.chatWithContext(requestDTO, userId);
        } catch (Exception e) {
            log.warn("RAG 检索失败,降级为标准对话", e);
        }
    }

    // 标准对话
    ChatLanguageModel chatModel = modelProvider.getModel(requestDTO.getModel());
    // ... 构建 Prompt、调用 LLM、构建响应
}

RAG 优先级:enableRag=true 时优先走 RAG 路径,RAG 失败则降级为标准对话。KAG 同理。

6.3 AiWritingService:写作服务

// kb-ai/src/main/java/com/knowledge/base/ai/service/impl/AiWritingServiceImpl.java
public SseEmitter generateStream(WritingRequestDTO dto) {
    // 写作默认使用 DeepSeek 的高温度(0.7),创意性强
    String modelName = dto.getModel() != null ? dto.getModel()
        : modelProvider.getDefaultModelName();
    ChatLanguageModel chatModel = modelProvider.getModel(modelName);

    // 构建写作 Prompt(含角色设定、风格要求、字数限制)
    String prompt = buildWritingPrompt(dto);

    // 流式生成(字符级分块,每块 10 个字符)
    SseEmitter emitter = new SseEmitter(30 * 60 * 1000L);
    CompletableFuture.runAsync(() -> {
        Response<AiMessage> response = chatModel.generate(UserMessage.from(prompt));
        String fullText = response.content().text();
        for (int i = 0; i < fullText.length(); i += CHUNK_SIZE) {
            emitter.send(SseEmitter.event()
                .name("message")
                .data(fullText.substring(i, Math.min(i + CHUNK_SIZE, fullText.length()))));
        }
        emitter.send(SseEmitter.event().name("done").data(buildDoneEvent()));
        emitter.complete();
    }, asyncTaskExecutor);

    return emitter;
}

6.4 AiDocumentService:文档处理

// kb-ai/src/main/java/com/knowledge/base/ai/service/impl/AiDocumentServiceImpl.java
public String generateSummary(String content) {
    // 文档处理不提供用户模型选择,始终使用默认模型
    ChatLanguageModel model = modelProvider.getDefaultModel();
    // ... 构建摘要 Prompt、调用 LLM
}

文档处理的摘要、大纲、扩写等功能面向"生成内容"的稳定性要求高于"风格多样性",因此统一使用默认模型。


7. 前端模型选择与交互

7.1 模型选择 UI

AI 助手页面的工具栏中有模型选择下拉框和 RAG/KAG 开关:

// src/pages/AIAssistantPage.tsx
<div className="toolbar">
    {/* 模型选择 */}
    <Select
        size="small"
        value={selectedModel}
        onChange={setSelectedModel}
        options={availableModels.map(m => ({
            label: m.displayName,
            value: m.key,
        }))}
        style={{ width: 140 }}
    />

    {/* 知识库增强开关 */}
    <Tooltip title="开启后AI将从知识库中检索相关文档辅助回答">
        <Space size={4}>
            <Switch size="small" checked={ragEnabled} onChange={toggleRag} />
            <span>知识库增强</span>
        </Space>
    </Tooltip>
    {/* 图谱推理开关 */}
    <Tooltip title="开启后AI将利用知识图谱进行多跳推理">
        <Space size={4}>
            <Switch size="small" checked={kagEnabled} onChange={toggleKag} />
            <span>图谱推理</span>
        </Space>
    </Tooltip>
</div>

7.2 Zustand Store 状态管理

// src/stores/ai.store.ts
interface AIState {
    selectedModel: string;                  // 默认 'qwen'
    availableModels: AIModelOption[];       // 从后端获取
    ragEnabled: boolean;                    // 知识库增强
    kagEnabled: boolean;                    // 图谱推理

    fetchModels: () => Promise<void>;       // GET /ai/chat/models
    sendMessage: (content: string) => Promise<void>;
}

// 初始化时获取模型列表
const fetchModels = async () => {
    try {
        const models = await aiService.getModels();
        set({ availableModels: models });
    } catch {
        // 降级:使用前端常量中的模型列表
        const fallbackModels = Object.values(AI_CONFIG.MODELS).map(m => ({
            key: m.key,
            displayName: m.displayName,
            description: m.description,
            isDefault: m.key === AI_CONFIG.DEFAULT_MODEL,
        }));
        set({ availableModels: fallbackModels });
    }
};

// 发送消息时携带模型选择
const sendMessage = async (content: string) => {
    const { selectedModel, ragEnabled, kagEnabled } = get();
    const response = await aiService.askStream({
        model: selectedModel,
        content,
        enableRag: ragEnabled,
        enableKag: kagEnabled,
    });
};

7.3 前端常量降级

当后端 API 不可用时(如应用刚启动、网络异常),前端使用本地常量作为降级:

// src/constants/index.ts
export const AI_CONFIG = {
    MAX_TOKENS: 4000,
    TEMPERATURE: 0.3,
    DEFAULT_MODEL: 'qwen',
    MODELS: {
        qwen: {
            key: 'qwen',
            displayName: '通义千问',
            description: '阿里云大语言模型,支持多轮对话、文本生成等',
            color: '#2563eb',        // 蓝色标识
        },
        deepseek: {
            key: 'deepseek',
            displayName: 'DeepSeek',
            description: '深度求索大语言模型,擅长代码生成和深度推理',
            color: '#10b981',        // 绿色标识
        },
    },
} as const;

7.4 模型列表 API

// kb-ai/.../controller/AiChatController.java
@GetMapping("/chat/models")
@Operation(summary = "获取可用模型列表")
public Result<List<ModelVO>> getModels() {
    List<ModelVO> models = modelProvider.getAvailableModels();
    if (models.isEmpty()) {
        log.warn("没有可用的 AI 模型:所有 API Key 均未配置");
    }
    return Result.success(models);
}
// 后端返回格式
[
    {
        "key": "qwen",
        "displayName": "通义千问",
        "description": "阿里云大语言模型,支持多轮对话、文本生成等",
        "isDefault": true
    },
    {
        "key": "deepseek",
        "displayName": "DeepSeek",
        "description": "深度求索大语言模型,擅长代码生成和深度推理",
        "isDefault": false
    }
]

8. 流式响应:SSE 端到端实现

8.1 后端 SSE 发射器

// AiChatServiceImpl.chatStream()
public SseEmitter chatStream(ChatRequestDTO requestDTO, Long userId) {
    // 创建 30 分钟超时的 SseEmitter
    SseEmitter emitter = new SseEmitter(30 * 60 * 1000L);

    CompletableFuture.runAsync(() -> {
        try {
            // RAG / KAG / 标准 对话
            ChatResponseVO response = chat(requestDTO, userId);

            // 发送内容
            emitter.send(SseEmitter.event()
                .name("message").data(response.getContent()));

            // 发送元数据
            emitter.send(SseEmitter.event()
                .name("done")
                .data(objectMapper.writeValueAsString(response)));

            emitter.complete();

        } catch (Exception e) {
            emitter.completeWithError(e);
        }
    }, asyncTaskExecutor);

    return emitter;
}

8.2 前端 SSE 解析

// src/services/ai.service.ts
async askStream(
    data: ChatRequestDTO,
    callbacks: {
        onMessage: (chunk: string) => void,
        onDone: (result: ChatResponseVO) => void,
        onError: (msg: string) => void,
    }
): Promise<void> {
    const response = await fetch('/api/ai/chat/stream', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'Authorization': `Bearer ${getToken()}`,
        },
        body: JSON.stringify(data),
    });

    const reader = response.body!.getReader();
    const decoder = new TextDecoder();
    let eventType = '';
    let dataBuffer = '';

    while (true) {
        const { done, value } = await reader.read();
        if (done) break;

        const text = decoder.decode(value, { stream: true });
        const lines = text.split('\n');

        for (const line of lines) {
            if (line.startsWith('event:')) {
                eventType = line.substring(6).trim();
            } else if (line.startsWith('data:')) {
                dataBuffer = line.substring(5).trim();
                if (eventType === 'message') {
                    callbacks.onMessage(dataBuffer);
                } else if (eventType === 'done') {
                    callbacks.onDone(JSON.parse(dataBuffer));
                } else if (eventType === 'error') {
                    callbacks.onError(dataBuffer);
                }
            }
        }
    }
}

8.3 流式实现说明

当前系统的 SSE 实现使用 ChatLanguageModel.generate()(阻塞调用),而非 LangChain4j 的 StreamingChatLanguageModel。这意味着:

  • 后端:一次 generate() 调用获取完整响应,作为单个 message 事件发送
  • 写作服务:通过字符级分块(10 字符/块)模拟流式效果
  • WebSocket 替代:聊天历史中的多个对话通过 CompletableFuture 异步执行,SSE 按顺序返回
这是当前版本的设计选择,未来升级为 LangChain4j StreamingChatLanguageModel 后可以实现真正的 Token 级流式输出。

9. 新增一个模型:完整开发指南

假设我们要接入 OpenAI GPT-4o,以下是完整的改造步骤:

Step 1:backend — 添加配置

# kb-ai/src/main/resources/application.yml
openai:
  api-key: ${OPENAI_API_KEY:}
  base-url: ${OPENAI_BASE_URL:https://api.openai.com/v1}
  chat:
    options:
      model: ${OPENAI_MODEL:gpt-4o}
      temperature: 0.3
      max-tokens: 4096
# .env.example 追加
OPENAI_API_KEY=your-openai-api-key-here
OPENAI_MODEL=gpt-4o

Step 2:backend — ModelProvider 注册

在 ModelProvider.java 中添加:

// 1. 添加 @Value 配置字段
@Value("${openai.api-key:}")
private String openaiApiKey;

@Value("${openai.base-url:https://api.openai.com/v1}")
private String openaiBaseUrl;

@Value("${openai.chat.options.model:gpt-4o}")
private String openaiModel;

@Value("${openai.chat.options.temperature:0.3}")
private Double openaiTemperature;

@Value("${openai.chat.options.max-tokens:4096}")
private Integer openaiMaxTokens;

// 2. 在 init() 中注册
@PostConstruct
public void init() {
    checkAndRegister("qwen", "通义千问", "...", qwenApiKey);
    checkAndRegister("deepseek", "DeepSeek", "...", deepseekApiKey);
    checkAndRegister("openai", "GPT-4o",               // ← 新增
        "OpenAI GPT-4o,支持多模态、长上下文", openaiApiKey);
    // ...
}

// 3. 在 buildModel() 中添加分支
case "openai" -> {
    return OpenAiChatModel.builder()
        .apiKey(openaiApiKey)
        .baseUrl(openaiBaseUrl)
        .modelName(openaiModel)
        .temperature(openaiTemperature)
        .maxTokens(openaiMaxTokens)
        .build();
}

Step 3:frontend — 添加常量

// src/constants/index.ts — AI_CONFIG.MODELS 追加
openai: {
    key: 'openai',
    displayName: 'GPT-4o',
    description: 'OpenAI GPT-4o,支持多模态、长上下文理解',
    color: '#74aa9c',    // OpenAI 标志绿色
},

Step 4:frontend — 类型更新(如需要)

如果 AIModelOption 已有 key、displayName、description、isDefault 四个字段,则无需修改。

改造总结

图片.png

新增一个模型只需修改 4 处:

文件修改内容
application.yml新增模型配置段
ModelProvider.java字段 + 注册 + buildModel 分支
constants/index.ts新增模型常量
.env.example新增环境变量文档

无需修改任何业务代码(Service、Controller 等),因为它们完全通过 modelProvider.getModel(modelName) 获取模型实例。


10. 容错与降级

10.1 降级层级

图片.png

10.2 降级策略总结

层级故障点降级行为用户感知
1API Key 未配置模型不注册,不展示前端下拉框无该模型
2LLM API 超时/异常抛出异常,前端展示错误"AI 回答失败,请稍后重试"
3RAG 检索失败退化为纯 LLM 对话回答无引用标注

10.3 模型回退

当用户选择了某个模型但该模型不可用时:

// ModelProvider.getModel()
public ChatLanguageModel getModel(String modelName) {
    String key = resolveModelKey(modelName);
    if (!modelAvailable.containsKey(key)) {
        throw new IllegalStateException(
            "模型 " + key + " 的 API Key 未配置");
    }
    // ...
}

// AiChatServiceImpl — 用户请求的模型不可用时的兜底
private String resolveModel(ChatRequestDTO requestDTO) {
    if (requestDTO.getModel() != null) {
        // 检查该模型是否可用
        if (!modelProvider.isModelAvailable(requestDTO.getModel())) {
            log.warn("用户请求的模型 {} 不可用,回退到默认模型", requestDTO.getModel());
        } else {
            return requestDTO.getModel();
        }
    }
    return modelProvider.getDefaultModelName();
}

总结

  1. 供应商无关的抽象:所有模型通过 ChatLanguageModel 接口访问,业务代码不感知底层是通义千问还是 DeepSeek。新增 OpenAI 兼容模型只需配置和一处 switch 分支。
  2. 懒加载 + 缓存:instanceCache.computeIfAbsent() 确保模型实例只创建一次,应用启动时不阻塞在外部 API 调用上。
  3. API Key 驱动的注册机制:有 Key 就注册、无 Key 就跳过。可以用通义千问做对话 + DeepSeek 做代码生成,灵活组合。
  4. 前端本地常量降级:后端模型列表 API 不可用时,前端使用 constants/index.ts 中的硬编码模型列表作为兜底,确保用户始终能看到模型选择器。
  5. 多服务一致的模型解析模式:7 个服务类统一使用 modelProvider.getModel(modelName) 获取模型,代码风格高度一致。
  6. RAG/KAG 与模型切换解耦:模型选择和知识增强是两个独立维度。用户可以"通义千问 + RAG"、"DeepSeek + RAG + KAG"、"GPT-4o + 纯对话"任意组合。

适用场景

多模型接入与切换最适合以下场景:

  • 对话:用户根据偏好选择模型
  • 代码生成:使用 DeepSeek 等擅长代码的模型
  • 创意写作:使用高 temperature 的模型
  • 成本优化:简单问题用便宜模型,复杂推理用强模型
  • 多供应商灾备:一个供应商故障时快速切换到另一个
最后修改:2026 年 10 月 24 日
如果觉得我的文章对你有用,请随意赞赏