一条 AI 消息是怎么产生的：追踪完整模型调用链

上一篇我们从整体上认识了 yudao-module-ai，知道了模型、聊天、知识库、Tool、MCP、Workflow 等能力分别处在什么位置，也看过了 ai_model、ai_chat_conversation、ai_chat_message 等核心表。

接下来，我们来看用户发送一条消息到 AI 消息响应到前端这个过程内部到底发生了什么？

AI 聊天页面
frontend/src/views/ai/chat/index/index.vue
        ↓
ChatMessageApi.sendChatMessageStream(...)
frontend/src/api/ai/chat/message/index.ts
        ↓
POST /admin-api/ai/chat/message/send-stream
        ↓
AiChatMessageController
        ↓
AiChatMessageServiceImpl
        │
        ├── 查 Conversation
        ├── 查历史消息
        ├── 找 Model
        ├── 创建 ChatModel
        ├── RAG / 联网搜索
        ├── 保存 User Message
        ├── 创建 Assistant Message
        ├── 构造 Prompt
        │
        ▼
StreamingChatModel.stream(prompt)
        ↓
Spring AI
        ↓
真实模型平台
        ↓
Flux<ChatResponse>
        ↓
SSE
        ↓
Vue 页面逐段接收
        ↓
完整 Assistant 内容落库

---

从浏览器里的 send-stream 开始

前端最终发出了什么请求

我们先从前端开始分析，

聊天主页面位于：

frontend/src/views/ai/chat/index/index.vue

用户输入内容以后，最终会进入：

const doSendMessage = async (content: string) => {
  if (content.length < 1) {
    message.error('发送失败，原因：内容为空！')
    return
  }

  if (activeConversationId.value == null) {
    message.error('还没创建对话，不能发送!')
    return
  }

  await doSendMessageStream({
    conversationId: activeConversationId.value,
    content,
    attachmentUrls: [...uploadFiles.value]
  } as ChatMessageVO)
}

真正负责发送流式请求的是：

doSendMessageStream(...)

在正式请求后端之前，前端还会先向当前消息列表插入两条临时消息：

activeMessageList.value.push({
  id: -1,
  type: 'user',
  content: userMessage.content
})

activeMessageList.value.push({
  id: -2,
  type: 'assistant',
  content: '思考中...'
})

也就是说，当我们点击“发送”以后，页面不需要等待服务器返回第一段数据，首先就可以立即展示：

我的问题

思考中...

等真正的流式响应回来以后，这两条临时数据才会被后端返回的真实 Message 替换。

继续往下看。

真正的 HTTP 请求封装位于：

frontend/src/api/ai/chat/message/index.ts

核心代码是：

sendChatMessageStream: async (
  conversationId,
  content,
  ctrl,
  enableContext,
  enableWebSearch,
  onMessage,
  onError,
  onClose,
  attachmentUrls
) => {
  const token = getAccessToken()

  return fetchEventSource(
    `${config.base_url}/ai/chat/message/send-stream`,
    {
      method: 'post',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${token}`
      },
      body: JSON.stringify({
        conversationId,
        content,
        useContext: enableContext,
        useSearch: enableWebSearch,
        attachmentUrls: attachmentUrls || []
      }),
      onmessage: onMessage,
      onerror: onError,
      onclose: onClose,
      signal: ctrl.signal
    }
  )
}

所以发送一条消息时，真正提交给后端的内容是：

{
  "conversationId": 1,
  "content": "你好",
  "useContext": true,
  "useSearch": false,
  "attachmentUrls": []
}

对应后端的 Request VO 也完全一致：

backend/yudao-module-ai/src/main/java/
cn/iocoder/yudao/module/ai/controller/admin/chat/vo/message/
AiChatMessageSendReqVO.java

public class AiChatMessageSendReqVO {

    private Long conversationId;

    private String content;

    private Boolean useContext;

    private Boolean useSearch;

    private List<String> attachmentUrls;

}

因此到这里只是一次普通的HTTP 请求，请求参数包括：

聊天对话 ID
+
用户输入
+
上下文开关
+
联网搜索开关
+
附件

---

为什么这里使用 SSE

和我们常见的普通后台接口不同，聊天页面没有等待模型把整段答案生成完成以后，再一次性显示。

而是：

模型生成一点
    ↓
后端返回一点
    ↓
浏览器显示一点

所以前端没有继续使用普通 Axios 请求，而是使用：

fetchEventSource(...)

源码中直接写了注释：

// 为什么不用 axios 呢？因为它不支持 SSE 调用

SSE，也就是 Server-Sent Events，可以让服务器在一个持续建立的 HTTP 连接上不断向浏览器发送事件。

SSE 的底层原理具体可以参考我们后续原理栏目的内容。

上一节我们在浏览器 Network 中看到的：

/admin-api/ai/chat/message/send-stream

就是这条流式请求。

---

请求进入后端

找到 AiChatMessageController

根据请求路径：

/ai/chat/message/send-stream

可以直接找到：

backend/yudao-module-ai/src/main/java/
cn/iocoder/yudao/module/ai/controller/admin/chat/
AiChatMessageController.java

流式接口则是：

@PostMapping(
    value = "/send-stream",
    produces = MediaType.TEXT_EVENT_STREAM_VALUE
)
public Flux<CommonResult<AiChatMessageSendRespVO>>
        sendChatMessageStream(
            @Valid @RequestBody AiChatMessageSendReqVO sendReqVO) {

    return chatMessageService.sendChatMessageStream(
        sendReqVO,
        getLoginUserId()
    );
}

注意这两个地方。

第一个是：

produces = MediaType.TEXT_EVENT_STREAM_VALUE

它告诉 Spring：

这个接口返回的不是普通 JSON，而是 SSE 流。

第二个是返回类型：

Flux<CommonResult<AiChatMessageSendRespVO>>

Flux 不是一个结果，而是一串会持续产生的数据。

所以：

前端 fetchEventSource

和：

后端 Flux + TEXT_EVENT_STREAM

正好形成了流式通信的两端。

---

send-stream 把请求交给了谁

Controller 本身几乎没有业务逻辑。

它只是取出当前登录用户：

getLoginUserId()

然后调用：

chatMessageService.sendChatMessageStream(
    sendReqVO,
    getLoginUserId()
);

所以继续往下看，真正重要的文件是：

backend/yudao-module-ai/src/main/java/
cn/iocoder/yudao/module/ai/service/chat/
AiChatMessageServiceImpl.java

这也是整个聊天调用链里最核心的一个类。

---

进入聊天核心逻辑

校验 Conversation

进入：

sendChatMessageStream(...)

第一件事情还不是找模型，而是先找当前聊天对话：

AiChatConversationDO conversation =
        chatConversationService
            .validateChatConversationExists(
                sendReqVO.getConversationId()
            );

if (ObjUtil.notEqual(conversation.getUserId(), userId)) {
    throw exception(CHAT_CONVERSATION_NOT_EXISTS);
}

为什么一定要先找 Conversation？

因为我们上一篇已经看到，一次对话本身保存了：

modelId
model

systemMessage
temperature
maxTokens
maxContexts

所以前端发送消息的时候，并没有每次都重新传：

{
  "model": "deepseek-chat",
  "temperature": 0.7,
  "maxTokens": 2048
}

前端只传：

conversationId

后端再根据 Conversation 找到这次聊天真正应该使用的模型和配置。

因此：

Conversation

就是一组连续聊天的运行上下文。

---

找到这次使用的 Model

接着代码会读取：

AiModelDO model =
        modalService.validateModel(
            conversation.getModelId()
        );

找到具体模型记录。

因此链路现在已经变成：

conversationId
      ↓
ai_chat_conversation
      ↓
modelId
      ↓
ai_model

---

读取历史消息

紧接着还有：

List<AiChatMessageDO> historyMessages =
        chatMessageMapper
            .selectListByConversationId(
                conversation.getId()
            );

这里拿到的是当前 Conversation 之前已经存在的消息。

但是查出来所有历史消息，不代表所有历史消息都会发给模型。

真正选择多少历史消息，是后面的 filterContextMessages(...)决定的。

当前实现会根据：sendReqVO.useContext 和conversation.maxContexts

如果没有开启上下文：

if (conversation.getMaxContexts() == null
        || ObjUtil.notEqual(
            sendReqVO.getUseContext(),
            Boolean.TRUE)) {

    return Collections.emptyList();
}

就完全不带历史消息。

如果开启，则会从最近的消息开始，按照：

User + Assistant

为一组向前取。

核心判断类似：

if (contextMessages.size()
        >= conversation.getMaxContexts() * 2) {
    break;
}

所以：

maxContexts = 10

表示最多取最近 10 组问答，而不是无限把整张消息表都塞进 Prompt。

---

模型实例是怎么创建出来的

从 modelId 找到模型配置

刚才只是拿到了：

AiModelDO model

但数据库里的一条记录显然还不能直接调用大模型。

真正创建模型客户端的代码在：

backend/yudao-module-ai/src/main/java/
cn/iocoder/yudao/module/ai/service/model/
AiModelServiceImpl.java

Chat 调用时执行：

StreamingChatModel chatModel =
        modalService.getChatModel(model.getId());

对应的实现是：

@Override
public ChatModel getChatModel(Long id) {
    AiModelDO model = validateModel(id);

    AiApiKeyDO apiKey =
            apiKeyService.validateApiKey(
                model.getKeyId()
            );

    AiPlatformEnum platform =
            AiPlatformEnum.validatePlatform(
                apiKey.getPlatform()
            );

    return modelFactory.getOrCreateChatModel(
            platform,
            apiKey.getApiKey(),
            apiKey.getUrl()
    );
}

这里终于把上一篇讲过的两张表连起来了：

ai_model
   │
   │ keyId
   ▼
ai_api_key

系统从 Model 中找到：

keyId

然后再从 API Key 中获取：

platform
apiKey
url

---

从 keyId 找到 API Key

这也解释了为什么前面配置模型时，要先创建 API Key，再创建 Model。

真正调用模型需要两类信息：

AiApiKeyDO
→ 我怎么访问模型平台

AiModelDO
→ 我要使用哪个具体模型以及什么参数

---

AiModelService 怎么拿到 ChatModel

继续看：

backend/yudao-module-ai/src/main/java/
cn/iocoder/yudao/module/ai/framework/ai/core/model/
AiModelFactoryImpl.java

核心方法：

public ChatModel getOrCreateChatModel(
        AiPlatformEnum platform,
        String rawApiKey,
        String rawUrl) {

    switch (platform) {
        case TONG_YI:
            return buildTongYiChatModel(apiKey);

        case DEEP_SEEK:
            return buildDeepSeekChatModel(apiKey);

        case OPENAI:
            return buildOpenAiChatModel(apiKey, url);

        case ANTHROPIC:
            return buildAnthropicChatModel(apiKey, url);

        case OLLAMA:
            return buildOllamaChatModel(url);

        // ...
    }
}

实际代码支持的平台远不止我这里简写的几个。

当前平台枚举位于：

backend/yudao-module-ai/src/main/java/
cn/iocoder/yudao/module/ai/enums/model/
AiPlatformEnum.java

里面可以看到：

TONG_YI("TongYi", "通义千问"),
DEEP_SEEK("DeepSeek", "DeepSeek"),
DOU_BAO("DouBao", "豆包"),
SILICON_FLOW("SiliconFlow", "硅基流动"),

OPENAI("OpenAI", "OpenAI"),
ANTHROPIC("Anthropic", "Anthropic"),
GEMINI("Gemini", "Gemini"),
OLLAMA("Ollama", "Ollama"),
// ...

---

不同模型平台怎么被统一起来

这一步其实是 Spring AI 在当前项目中非常重要的价值。

上层聊天代码并没有写成：

if (DeepSeek) {
    调 DeepSeek SDK
} else if (OpenAI) {
    调 OpenAI SDK
} else if (Anthropic) {
    调 Anthropic SDK
}

而是最终统一拿到：

ChatModel

或者流式场景中的：

StreamingChatModel

所以 Chat Service 后面可以完全不关心：

DeepSeek
OpenAI
通义
Anthropic
Ollama

具体是哪一家。

它只需要：

chatModel.stream(prompt);

当前 AI 模块固定使用的 Spring AI 版本为：

<spring-ai.version>1.1.8</spring-ai.version>

同时使用 Spring AI Alibaba 1.1.2.2。

这就是项目把不同模型 Provider 统一到一条 Chat 调用链上的基础。

---

Prompt 是怎么组装出来的

现在已经有了：

Conversation
Model
ChatModel
历史消息
用户本次输入

下一步就是真正构造发给大模型的 Prompt。

仍然在：

backend/yudao-module-ai/src/main/java/
cn/iocoder/yudao/module/ai/service/chat/
AiChatMessageServiceImpl.java

方法是：

buildPrompt(...)

---

System Message

第一部分是 Conversation 自己保存的角色设定：

if (StrUtil.isNotBlank(
        conversation.getSystemMessage())) {

    chatMessages.add(
        new SystemMessage(
            conversation.getSystemMessage()
        )
    );
}

所以如果聊天设置中写了：

你是一名 Java 架构师……

最终就是作为：

SystemMessage

进入 Prompt。

---

历史上下文

然后加入刚才筛选出来的历史消息：

List<AiChatMessageDO> contextMessages =
        filterContextMessages(
            messages,
            conversation,
            sendReqVO
        );

contextMessages.forEach(message -> {
    chatMessages.add(
        AiUtils.buildMessage(
            message.getType(),
            message.getContent()
        )
    );
});

AiUtils.buildMessage() 再把数据库里的：

user
assistant
system

转换为 Spring AI 的：

UserMessage
AssistantMessage
SystemMessage

实现位于：

backend/yudao-module-ai/src/main/java/
cn/iocoder/yudao/module/ai/util/
AiUtils.java

public static Message buildMessage(
        String type,
        String content) {

    if (MessageType.USER.getValue().equals(type)) {
        return new UserMessage(content);
    }

    if (MessageType.ASSISTANT.getValue().equals(type)) {
        return new AssistantMessage(content);
    }

    if (MessageType.SYSTEM.getValue().equals(type)) {
        return new SystemMessage(content);
    }

    // ...
}

---

当前用户消息

历史消息之后，才加入用户本轮真正输入的内容：

chatMessages.add(
    new UserMessage(
        sendReqVO.getContent()
    )
);

到这里，一个最普通的聊天 Prompt 已经大概是：

System
你是一名 Java 架构师

User
之前的问题

Assistant
之前的回答

User
这一次的新问题

但是当前项目还会继续往里加其他内容。

---

知识库召回

在构建 Prompt 之前，Service 已经调用：

List<AiKnowledgeSegmentSearchRespBO>
        knowledgeSegments =
        recallKnowledgeSegment(
            sendReqVO.getContent(),
            conversation
        );

不过并不是每一次聊天都会执行 RAG。

recallKnowledgeSegment() 首先检查当前 Conversation 有没有角色：

if (conversation == null
        || conversation.getRoleId() == null) {

    return Collections.emptyList();
}

然后继续检查角色是否配置：

knowledgeIds

没有知识库，同样直接返回空。

真正有知识库以后，才会遍历知识库并调用：

knowledgeSegmentService.searchKnowledgeSegment(...)

进行召回。

召回结果在构造 Prompt 时会被包装成类似：

<Reference>
知识片段内容
</Reference>

再作为额外的：

UserMessage

加入 Prompt。

实际逻辑：

if (CollUtil.isNotEmpty(knowledgeSegments)) {

    String reference = knowledgeSegments.stream()
        .map(segment ->
            "<Reference>"
            + segment.getContent()
            + "</Reference>")
        .collect(Collectors.joining("\n\n"));

    chatMessages.add(
        new UserMessage(
            String.format(
                KNOWLEDGE_USER_MESSAGE_TEMPLATE,
                reference
            )
        )
    );
}

因此当前 RAG 本质上也是：

先检索
    ↓
拿到知识片段
    ↓
拼进 Prompt
    ↓
让模型基于这些内容回答

---

联网搜索与附件

如果前端开启：

联网搜索

并且当前系统已经配置 AiWebSearchClient，Service 会调用：

webSearchClient.search(...)

然后把搜索结果包装为：

<WebSearch>
...
</WebSearch>

继续作为 UserMessage 塞进 Prompt。

附件也是类似处理。

如果：

sendReqVO.getAttachmentUrls()

不为空，会调用：

buildAttachmentUserMessage(...)

文本文件会读取内容，图片会下载并转成 Base64，最后包装成：

<Attachment name="...">
...
</Attachment>

再作为新的 UserMessage。

所以当前 Prompt 已经可能非常复杂：

System Message
        ↓
历史消息
        ↓
当前用户消息
        ↓
RAG Reference
        ↓
Web Search
        ↓
Attachment

---

Tool 和 MCP

Prompt 的消息部分构建完以后，还没有结束。

代码继续调用：

List<ToolCallback> toolCallbacks =
        getToolCallbackListByRoleId(
            conversation.getRoleId()
        );

如果当前 Chat Role 配置了：

toolIds

系统会根据数据库中的 Tool 名称：

toolCallbackResolver.resolve(toolName)

找到真正的 ToolCallback。

如果角色配置了：

mcpClientNames

还会从已经连接的：

McpSyncClient

中取得 MCP Tools，并转换成：

ToolCallback[]

当前关键代码类似：

ToolCallback[] mcpToolCallBacks =
        new SyncMcpToolCallbackProvider(mcpClient)
            .getToolCallbacks();

CollUtil.addAll(
    toolCallbacks,
    mcpToolCallBacks
);

所以到了 Spring AI 这一层以后普通 Java Tool 和 MCP Tool 都统一成了ToolCallback，然后再一起交给模型。

---

真正调用模型发生在哪里

StreamingChatModel.stream

所有准备工作完成后，会生成：

ChatOptions chatOptions =
        AiUtils.buildChatOptions(
            platform,
            model.getModel(),
            conversation.getTemperature(),
            conversation.getMaxTokens(),
            toolCallbacks,
            toolContext
        );

return new Prompt(
    chatMessages,
    chatOptions
);

这里就把前面一直没有传给模型工厂的：

model.getModel()

带进来了。

真正作为模型标识进入 ChatOptions。

不同平台会创建不同 Options。

文件：

backend/yudao-module-ai/src/main/java/
cn/iocoder/yudao/module/ai/util/
AiUtils.java

例如 DeepSeek：

return DeepSeekChatOptions.builder()
        .model(model)
        .temperature(temperature)
        .maxTokens(maxTokens)
        .toolCallbacks(toolCallbacks)
        .toolContext(toolContext)
        .build();

OpenAI：

return OpenAiChatOptions.builder()
        .model(model)
        .temperature(temperature)
        .maxTokens(maxTokens)
        .toolCallbacks(toolCallbacks)
        .toolContext(toolContext)
        .build();

最终真正发起模型调用的代码只有这一行：

Flux<ChatResponse> streamResponse =
        chatModel.stream(prompt);

文件仍然是：

backend/yudao-module-ai/src/main/java/
cn/iocoder/yudao/module/ai/service/chat/
AiChatMessageServiceImpl.java

前面那么长的准备工作，最终都汇聚到这里：

ChatModel
+
Prompt
        ↓
chatModel.stream(prompt)

这一行就是当前 Chat 场景真正跨出系统、调用大模型的核心位置。

这个位置后面会非常重要。

---

Spring AI 返回了什么

stream() 返回的不是 String。

而是：

Flux<ChatResponse>

每一个流式片段都是：

ChatResponse

拿到一个 Chunk 后，先调用：

String newContent =
        AiUtils.getChatResponseContent(chunk);

String newReasoningContent =
        AiUtils.getChatResponseReasoningContent(chunk);

AiUtils 的正文提取非常直接：

public static String getChatResponseContent(
        ChatResponse response) {

    if (response == null
            || response.getResult() == null
            || response.getResult().getOutput() == null) {
        return null;
    }

    return response
            .getResult()
            .getOutput()
            .getText();
}

推理模型的 reasoningContent 则针对 DeepSeek 和部分其他模型做了兼容。

---

模型结果怎么回到前端

Flux 怎么变成 SSE

模型返回Flux<ChatResponse>以后，当前 Service 对每一个 Chunk 执行：

return streamResponse.map(chunk -> {

    String newContent =
            AiUtils.getChatResponseContent(chunk);

    String newReasoningContent =
            AiUtils.getChatResponseReasoningContent(chunk);

    if (StrUtil.isNotEmpty(newContent)) {
        contentBuffer.append(newContent);
    }

    if (StrUtil.isNotEmpty(newReasoningContent)) {
        reasoningContentBuffer
            .append(newReasoningContent);
    }

    return success(
        new AiChatMessageSendRespVO()
            .setSend(...)
            .setReceive(
                ...
                .setContent(
                    StrUtil.nullToDefault(
                        newContent, ""
                    )
                )
                .setReasoningContent(
                    StrUtil.nullToDefault(
                        newReasoningContent, ""
                    )
                )
            )
    );
});

所以每一个模型 Chunk 都被重新包装成：

CommonResult
    ↓
AiChatMessageSendRespVO

然后 Controller 原样把：

Flux<CommonResult<...>>

作为 SSE 返回。

整个路径就是：

Flux<ChatResponse>
        ↓
map()
        ↓
Flux<CommonResult<...>>
        ↓
Controller
        ↓
SSE

---

前端怎么逐段接收内容

再回到：

frontend/src/views/ai/chat/index/index.vue

fetchEventSource 每收到一个 SSE Event，就进入：

async (res) => {
  const { code, data, msg } =
    JSON.parse(res.data)

  // ...

  if (data.receive.reasoningContent) {
    // 拼接推理内容
  }

  if (data.receive.content !== '') {
    receiveMessageFullText.value =
      receiveMessageFullText.value
      + data.receive.content
  }

  await scrollToBottom()
}

注意这里后端每次发送的：

data.receive.content

只是当前这一段。

前端自己维护：

receiveMessageFullText

不断累加：

第一段：“Cost”
第二段：“Flow”
第三段：“ 是”
第四段：“一个”
...

最后才形成完整回答。

---

为什么页面能看到打字机效果

页面中真正展示文字时，又做了一层：

textRoll()

它不会直接一次把：

receiveMessageFullText

全部塞到页面。

而是根据当前：

已经收到多少字符
已经显示多少字符

计算展示速度，然后逐字更新最后一条 Assistant Message。

因此页面表现实际上是两层流式：

第一层
模型 → SSE → 浏览器
真实网络流式

第二层
receiveMessageFullText
        ↓
textRoll()
        ↓
逐字显示
前端视觉流式

所以页面看起来像 ChatGPT 一样逐字出现，并不代表后端真的每次只返回一个汉字。

---

一次聊天是怎么落库的

先保存用户消息

当前系统并不是：

先调模型
    ↓
成功以后
    ↓
再保存 User 和 Assistant

而是在调用模型之前就开始写数据库。

仍然位于：

backend/yudao-module-ai/src/main/java/
cn/iocoder/yudao/module/ai/service/chat/
AiChatMessageServiceImpl.java

首先：

AiChatMessageDO userMessage =
        createChatMessage(
            conversation.getId(),
            null,
            model,
            userId,
            conversation.getRoleId(),
            MessageType.USER,
            sendReqVO.getContent(),
            sendReqVO.getUseContext(),
            null,
            sendReqVO.getAttachmentUrls(),
            null
        );

createChatMessage() 最终会：

chatMessageMapper.insert(message);

所以用户消息在真正请求大模型之前就已经存在于：

ai_chat_message

里。

---

再创建 Assistant 消息

随后系统立即创建：

AiChatMessageDO assistantMessage =
        createChatMessage(
            conversation.getId(),
            userMessage.getId(),
            model,
            userId,
            conversation.getRoleId(),
            MessageType.ASSISTANT,
            "",
            sendReqVO.getUseContext(),
            knowledgeSegments,
            null,
            webSearchResponse
        );

注意这里 Assistant 的初始：

content = ""

并且：

replyId = userMessage.getId()

因此数据库关系已经建立：

User Message
id = 100

Assistant Message
id = 101
replyId = 100
content = ""

然后才：

chatModel.stream(prompt);

---

流式结束后更新完整内容

流式过程中，后端维护：

StringBuffer contentBuffer =
        new StringBuffer();

StringBuffer reasoningContentBuffer =
        new StringBuffer();

每来一个 Chunk：

contentBuffer.append(newContent);

等 Flux 正常结束：

.doOnComplete(() -> {

    TenantUtils.executeIgnore(() ->
        chatMessageMapper.updateById(
            new AiChatMessageDO()
                .setId(assistantMessage.getId())
                .setContent(
                    contentBuffer.toString()
                )
                .setReasoningContent(
                    reasoningContentBuffer.toString()
                )
        )
    );

})

最终：

ai_chat_message

中的 Assistant Message 才从：

content = ""

变成：

content = "完整模型回答……"

---

调用失败和主动取消怎么处理

这里当前还要考虑了两个情况：

模型调用出错

和：

用户点击“停止”

分别对应：

.doOnError(...)

和：

.doOnCancel(...)

两者处理思路基本一致。

如果模型已经返回了一部分内容：

if (StrUtil.isNotEmpty(contentBuffer)) {

    chatMessageMapper.updateById(
        new AiChatMessageDO()
            .setId(assistantMessage.getId())
            .setContent(contentBuffer.toString())
    );
}

就把已经收到的部分保存下来。

如果一个字都没有返回：

else {
    chatMessageMapper.deleteById(
        assistantMessage.getId()
    );
}

就把刚才提前创建的空 Assistant Message 删除。

因此当前的异常行为大概是：

用户消息
→ 已保存

Assistant
→ 有部分返回：保存部分内容
→ 完全没返回：删除空记录

这一点对以后做 Usage 和计费尤其重要。

因为将来还必须回答：

调用失败、调用取消、只生成一半时，到底算不算一次用量？

但现在先不解决，我们后续再来处理。

---

这条链里已经有什么，还缺什么

现在我们已经完整走完了一次 Chat 调用。

index.vue
    ↓
ChatMessageApi
    ↓
AiChatMessageController
    ↓
AiChatMessageServiceImpl
    │
    ├─ Conversation
    ├─ History
    ├─ Model
    ├─ Knowledge
    ├─ Web Search
    ├─ Tool / MCP
    │
    ↓
buildPrompt()
    ↓
AiModelServiceImpl
    ↓
AiModelFactoryImpl
    ↓
StreamingChatModel.stream()
    ↓
Spring AI
    ↓
模型 Provider
    ↓
Flux<ChatResponse>
    ↓
SSE
    ↓
Vue

而当前数据库已经记录：

userId
conversationId

modelId
model

用户输入
模型输出
reasoningContent

知识库 Segment
联网搜索
附件

createTime

从“这是谁发出的哪一次聊天”角度看，上下文其实已经很丰富。

但现在就会发现了一个非常关键的断层。

Spring AI：

ChatResponse
    ↓
getMetadata()
    ↓
getUsage()

可以提供统一的：

Prompt Tokens
Completion Tokens
Total Tokens

抽象。

而当前 RuoYi Vue Pro 在处理每一个：

ChatResponse chunk

时，只读取了：

AiUtils.getChatResponseContent(chunk);

AiUtils.getChatResponseReasoningContent(chunk);

整个当前 Chat Service 并没有继续读取：

chunk.getMetadata().getUsage()

也没有把：

promptTokens
completionTokens
totalTokens

保存进：

ai_chat_message

这和上一篇我们从数据库看到的现象完全对应起来了。

模型响应中
可能已经有 Usage
        ↓
当前业务代码只取 Content
        ↓
Usage 没有进入业务数据
        ↓
数据库自然也没有 Token 用量

这个位置已经非常适合接入 CostFlow。

---

为什么现在还不能直接计费

看到这里可能很容易得出一个结论：

那就在这里 getUsage()
然后乘模型单价不就行了？

但还不能这么快。

因为还有很多问题没有解决。

例如流式响应：

Flux<ChatResponse>

会返回很多个 Chunk。

那么：

Usage 出现在哪个 Chunk？

如果多个 Chunk 都有：

它是增量还是累计？

不同 Provider：

Usage 行为是否完全一致？

如果发生：

模型调用失败
用户取消流式请求
Tool Calling
MCP Tool Calling
一次业务请求触发多次模型调用

又应该怎么处理？

另外 CostFlow 最终显然不能只绑死在：

AiChatMessageServiceImpl

这一行代码上。

因为前面已经知道：

Chat
Write
Image
MindMap
Workflow

未来都可能产生 AI 成本。

所以我们现在已经确定了一个非常重要的认知：

Chat 场景中真正的模型调用边界已经找到了，而且 Spring AI 响应中已经存在 Usage 抽象。

至于 CostFlow 应该怎样采集它，我们下一章再讨论。

---

交给 Coding Agent

这篇文章其实最适合让本地 Agent 直接沿真实源码重新走一次，而且这一次最好让 Agent 输出文件路径 + 方法名 + 调用关系，而不是泛泛解释 Spring AI。

请基于当前 CostFlow 本地代码，带我完整追踪一次已经真实跑通的 AI Chat 流式调用。

不要修改任何代码，也不要实现 CostFlow。

必须以当前本地固定版本源码为准。

1. 从前端发送按钮开始

从：

frontend/src/views/ai/chat/index/index.vue

找到用户发送消息的真实方法。

继续追到：

frontend/src/api/ai/chat/message/index.ts

告诉我：

• 最终请求地址；
• HTTP 方法；
• 请求体；
• 为什么使用 fetchEventSource；
• conversationId、useContext、useSearch、attachmentUrls 分别来自哪里。

画出前端调用链，并列出真实方法名。

2. 追到后端 Controller

找到：

AiChatMessageController

以及 /ai/chat/message/send-stream 对应的方法。

告诉我：

• Controller 的完整相对路径；
• 方法名；
• Request VO；
• 返回类型；
• 为什么返回 Flux；
• 请求最终交给哪个 Service 方法。

不要解释 Spring MVC 基础知识。

3. 进入 Chat Service

重点阅读：

AiChatMessageServiceImpl.sendChatMessageStream

按真实执行顺序告诉我：

• Conversation 在哪里查询；
• 用户权限怎么校验；
• 历史消息在哪里读取；
• Model 怎么找到；
• ChatModel 怎么拿到；
• 知识库什么时候召回；
• 联网搜索什么时候执行；
• User Message 什么时候落库；
• Assistant Message 什么时候创建；
• 真正调用模型发生在哪一行。

请输出一条按真实执行顺序排列的调用链。

4. 追 Model 创建过程

继续追：

• AiModelServiceImpl
• AiModelFactoryImpl
• AiPlatformEnum
• AiUtils

重点回答：

1. modelId 怎么找到 ai_model；
2. keyId 怎么找到 API Key；
3. Provider 是根据哪里的 platform 决定的；
4. ChatModel 客户端什么时候创建；
5. 真正的模型标识什么时候传入；
6. temperature、maxTokens 等参数在哪里进入 ChatOptions；
7. 不同模型平台最终怎么统一到 Spring AI 接口。

必须列真实相对文件路径和真实方法名。

5. 拆解 buildPrompt

完整检查：

AiChatMessageServiceImpl.buildPrompt

按照最终加入 Prompt 的顺序告诉我：

• System Message
• 历史消息
• 当前 User Message
• Knowledge
• Web Search
• Attachment
• Tool
• MCP

分别从哪里来。

同时检查：

filterContextMessages

告诉我上下文到底按照什么规则截取。

不要根据经验猜，必须以当前代码为准。

6. 追真正的模型调用

找到真实的：

chatModel.stream(prompt)

继续检查当前项目使用的 Spring AI 版本。

然后查看该版本 Spring AI 中：

• ChatResponse
• ChatResponseMetadata
• Usage

确认是否真实存在：

• getPromptTokens()
• getCompletionTokens()
• getTotalTokens()
• getNativeUsage()

并告诉我当前 RuoYi Vue Pro 是否真正读取了这些 Usage。

不要修改代码。

7. 追 SSE 返回和数据库写入

继续检查：

• 每个 ChatResponse Chunk 怎么返回给前端；
• 前端怎么累加流式内容；
• 前端打字效果怎么实现；
• User Message 在什么时候插入；
• Assistant Message 在什么时候插入；
• 完整 Assistant 内容什么时候更新；
• 正常完成、异常、主动取消分别怎么处理。

同时告诉我对应的真实文件和方法。

8. 最后输出完整调用图

最终给我一张从：

index.vue

一直到：

StreamingChatModel.stream

再回到：

ai_chat_message

的完整调用图。

另外单独标出：

ChatResponse -> Metadata -> Usage

这一条目前原项目存在、但业务代码没有消费的数据路径。

本轮只理解调用链和确认事实。

不要新增 Usage 表，不要增加 Token 字段，不要设计 Pricing，也不要实现 Billing。

---

下一步

现在我们已经不是“猜” CostFlow 应该接在哪里了。

我们真正找到了一次聊天的模型调用边界：

Flux<ChatResponse> streamResponse =
        chatModel.stream(prompt);

也确认了 Spring AI 1.1.8 的：

ChatResponse
    ↓
ChatResponseMetadata
    ↓
Usage

本身已经提供 Token Usage 抽象。

而现有业务代码目前主要消费的是：

content
reasoningContent

并没有把 Usage 继续变成业务数据。

下一篇就可以正式回答一个问题：

CostFlow 的第一条 Usage，到底应该在哪里、以什么方式采集？

下一篇：

现有 AI 调用缺了什么：找到 CostFlow 的第一个计费入口