package com.custom.webui.service; import java.util.List; /** * LLM 调用抽象。 * *

当前有两个实现: *

* 通过 {@code webui.llm.provider} 切换。抽出接口的收益是: * 未来接入 OpenAI 兼容协议(DeepSeek、通义等)时只需新增实现,业务层零改动。 */ public interface LlmService { /** * 以流式方式生成回复。 * *

本方法是阻塞式的:它会一直读到模型输出结束。 * 调用方(MessageServiceImpl)负责把它放到 SSE 专用线程池里执行。 * * @param messages 完整上下文(含 system / 历史对话 / 本轮用户输入),按时间正序 * @param options 采样参数与模型名 * @param consumer 每收到一个增量片段就回调一次 * @throws com.custom.webui.exception.BusinessException LLM 不可用或返回错误时抛出 */ void streamChat(List messages, LlmOptions options, TokenConsumer consumer); /** * 非流式调用,用于会话标题生成这类短任务。 * * @return 模型输出的完整文本;失败时返回 null,由调用方决定降级策略 */ String complete(List messages, LlmOptions options); /** 返回当前生效的默认模型名,用于前端展示和落库 */ String defaultModel(); // ==================== 内部值对象 ==================== /** * 一条发给 LLM 的消息。 * * @param role system / user / assistant * @param content 文本内容 */ record LlmMessage(String role, String content) { } /** * 本次调用的生成参数。 * * @param modelName 模型名,null 时用默认模型 * @param temperature 采样温度 * @param topP 核采样 * @param numCtx 上下文窗口 */ record LlmOptions(String modelName, Double temperature, Double topP, Integer numCtx) { } /** * 增量输出回调。 * *

约定:{@code thinking} 为 true 表示这是 reasoning 模型的思考过程而非正式回答, * 前端可折叠展示。普通模型该值恒为 false。 */ @FunctionalInterface interface TokenConsumer { void accept(String token, boolean thinking); } }