package com.custom.webui.service;
import java.util.List;
/**
* LLM 调用抽象。
*
*
当前有两个实现:
*
* - {@link com.custom.webui.service.impl.OllamaLlmService} —— 对接本地 Ollama,生产使用
* - {@link com.custom.webui.service.impl.MockLlmService} —— 本地模拟流式输出
*
* 通过 {@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);
}
}