Chat服务架构

┌──────────────────────────────────────────────────────┐
│           LcChatController (REST API)              │
└────────────────┬─────────────────────────────────┘
                 │
                 ▼
┌──────────────────────────────────────────────────────┐
│               ChatService                          │
│              业务逻辑层                             │
│  - 参数验证                                        │
│  - 业务处理                                        │
│  - 消息保存                                        │
└────────────────┬─────────────────────────────────┘
                 │
                 ▼
┌──────────────────────────────────────────────────────┐
│              LcChatService                         │
│              核心服务层                             │
│  - 上下文构建                                      │
│  - 模型获取                                        │
│  - AI Service组装                                  │
│  - 流式调用                                        │
└────────────────┬─────────────────────────────────┘
                 │
                 ▼
┌──────────────────────────────────────────────────────┐
│           LangChain4j Agent                        │
│              AI推理引擎                             │
└──────────────────────────────────────────────────────┘

// 流式聊天
@PostMapping("/chat/chat")
public void chat(@RequestBody LcChatReq req, HttpServletResponse response) throws IOException

// 独立流式聊天
@PostMapping("/chat/standalone")
public void standalone(@RequestBody LcChatReq req, HttpServletResponse response) throws IOException

// 聊天（流式）
TokenStream chat(ChatReq req)

// 聊天（异步处理）
void asyncChat(ChatReq req, StreamEventPublisher publisher)

// 聊天建议获取
String getChatSuggestion(ChatSuggestionReq req)

// 简单文本对话
String simpleChatForText(SimpleChatContext context)

// 流式聊天（支持知识库、RAG）
TokenStream streamingChat(LcChatReq req)

// 独立流式聊天（不关联知识库）
TokenStream standaloneStreamingChat(LcChatReq req)

// 简单文本对话
String simpleChatForText(SimpleChatContext context)

// 获取ChatModel
ChatModel getChatModel(BaseChatContext context)

// 获取StreamingChatModel
StreamingChatModel getStreamingChatModel(BaseChatContext context)

@Override
public TokenStream streamingChat(LcChatReq req) {
    // 1. 生成chatId
    String chatId = StrUtil.isNotBlank(req.getChatId()) 
        ? req.getChatId() 
        : LcIdUtil.getUUID();
    
    // 2. 构建ChatContext
    var chatContext = contextBuilder.build(req);
    chatContext.setChatId(chatId);
    chatContext.setAppId(req.getAppId());
    chatContext.setConversationId(req.getConversationId());
    
    // 3. 设置ThreadLocal上下文
    ChatContextHolder.set(chatContext);
    
    // 4. 获取StreamingChatModel（带listener）
    StreamingChatModel streamingModel = 
        modelFactory.getStreamingModel(chatContext, chatId);
    
    // 5. 构建Agent
    var agent = aiServiceBuilder.build(streamingModel, req, conversationId);
    
    // 6. 构建消息
    var message = buildChatMessages(req);
    
    // 7. 调用Agent
    var tokenStream = agent.stream(conversationId, message);
    
    return tokenStream;
}

┌─────────────┐
│   Client    │
└──────┬──────┘
       │ HTTP / REST API
       │ LcChatReq
       ▼
┌─────────────────────┐
│ LcChatController   │
│  (接收请求)         │
└──────┬──────────────┘
       │
       │ 转发请求
       ▼
┌─────────────────────┐
│   ChatService      │
│  (业务逻辑)        │
│  - 参数验证        │
│  - 权限检查        │
│  - 敏感词过滤      │
└──────┬──────────────┘
       │
       │ LcChatReq
       ▼
┌─────────────────────┐
│  LcChatService     │
│  (核心服务)        │
└──────┬──────────────┘
       │
       ├────────────────────────────────┐
       │                              │
       ▼                              ▼
┌──────────────┐           ┌───────────────┐
│ContextBuilder│           │ModelFactory   │
│(构建上下文)  │           │(获取模型)      │
└──────┬───────┘           └──────┬────────┘
       │                           │
       └───────────┬───────────────┘
                   ▼
         ┌──────────────────┐
         │AiServiceBuilder  │
         │(组装AI Service) │
         └────────┬────────┘
                  │
                  ▼
         ┌──────────────────┐
         │ LangChain4j     │
         │   Agent         │
         └────────┬────────┘
                  │
                  ▼
         ┌──────────────────┐
         │ TokenStream     │
         │ (流式响应)      │
         └────────┬────────┘
                  │
                  │ onPartialThinking
                  │ onComplete
                  │ onError
                  ▼
         ┌──────────────────┐
         │ Client          │
         │ (接收响应)       │
         └─────────────────┘

@Component
public class ChatContextBuilder {
    
    public BaseChatContext build(LcChatReq req) {
        var context = SimpleChatContext.of(req.getModelConfig());
        context.setModelId(req.getModelId());
        context.setUserId(req.getUserId());
        context.setFormat(req.getFormat());
        return context;
    }
}

// 获取StreamingChatModel（带chatId绑定listener）
public StreamingChatModel getStreamingModel(
    BaseChatContext context, 
    String chatId
)

// 获取ChatModel（带chatId绑定listener）
public ChatModel getChatModel(
    BaseChatContext context, 
    String chatId
)

public LangChatAgent build(
    StreamingChatModel model, 
    LcChatReq req, 
    String conversationId
)

tokenStream
    .onPartialThinking(thinking -> {
        // 接收思维过程
        log.debug("Thinking: {}", thinking);
    })
    .onPartialResponse(response -> {
        // 接收部分响应
        log.debug("Response: {}", response);
    })
    .onComplete(answer -> {
        // 接收完整回答
        log.info("Complete: {}", answer);
    })
    .onError(error -> {
        // 错误处理
        log.error("Error", error);
    });

public String buildChatMessages(LcChatReq req) {
    var message = "";
    
    // 1. 优先单独的message字段
    if (StrUtil.isNotBlank(req.getMessage())) {
        message = req.getMessage();
    }
    
    // 2. 处理messages列表
    if (StrUtil.isNotBlank(req.getMessage()) 
        && CollUtil.isNotEmpty(req.getMessages())) {
        LcChatMessage userMessage = 
            ChatMessageConverter.getLatestUserMessage(req.getMessages());
        message = userMessage != null ? userMessage.getContent() : "";
    }
    
    // 3. 验证消息是否为空
    if (StrUtil.isBlank(message)) {
        throw new IllegalArgumentException("消息为空");
    }
    
    return message;
}

return MessageWindowChatMemory.builder()
    .id(conversationId)
    .chatMemoryStore(new LcChatMemory(redisTemplate))
    .maxMessages(maxMessages)
    .build();

Exception
  ↓
LcChatService catch
  ↓
记录日志
  ↓
ChatListener.onError
  ↓
Client接收错误
  ↓
清理ThreadLocal

private Cache<String, ChatModel> chatModelCache;
private Cache<String, StreamingChatModel> streamingChatModelCache;

langchat:
  memory:
    max-message: 20  # 历史消息数量
    ttl: 86400      # 过期时间（秒）

langchat:
  model:
    timeout: 5  # 超时时间（分钟）

@Component
public class CustomChatListener extends ChatListener {
    
    @Override
    public void onRequest(ChatModelRequestContext context) {
        // 自定义处理
    }
}

public class CustomChatMemoryStore implements ChatMemoryStore {
    // 自定义实现
}

public TokenStream customChatMode(LcChatReq req) {
    // 自定义逻辑
}