ai-search 历史记录

• 1. API 说明
  • 1.1 获取所有聊天记录
  • 1.2 获取特定聊天记录详情
• 2. 代码实现
  • 2.1 ApiChatsController
  • 2.2 ChatsService
  • 2.3 ChatMessgeService
  • 2.4 SourcesController
• 总结

本文档旨在为您的 AI+搜索 系统的历史记录功能提供详细的 API 说明和代码实现示例。通过这些 API 接口，用户可以查看所有聊天记录以及指定聊天记录的详细内容，包括聊天基本信息和消息内容。除此之外，还提供了一个辅助接口，用于方便查看向大模型发送推理数据的过程。

---

1. API 说明

本节详细描述了用于管理和访问聊天历史记录的 API 接口，包括请求方法、URL、参数、响应格式及示例。

1.1 获取所有聊天记录

描述

获取所有用户的聊天记录列表，每条记录包含聊天的基本信息，如聊天 ID、标题、创建时间、焦点模式以及相关文件（当前为空）。

请求

• 方法： GET
• URL： http://192.168.3.9:3001/api/chats

请求参数

无。

响应

状态码： 200 OK
内容类型： application/json

响应体示例

{
  "chats": [
    {
      "id": "5a31859e83d0e45b6c5ba063091ff9403ed9eb3b",
      "title": "when is the first day of Kapiolani cummunity college",
      "createdAt": "Sat Dec 07 2024 09:35:59 GMT+0000 (Coordinated Universal Time)",
      "focusMode": "webSearch",
      "files": []
    },
    {
      "id": "041cd5f3fdef4fda1a0fa2a45564e3c22ce2fd9a",
      "title": "when is first day of kapiaoni community college",
      "createdAt": "Sat Dec 07 2024 09:21:12 GMT+0000 (Coordinated Universal Time)",
      "focusMode": "webSearch",
      "files": []
    }
  ]
}

字段说明

• chats: 聊天记录数组，每条记录包含：
  • id: 聊天的唯一标识符。
  • title: 聊天标题，通常为用户的初始问题。
  • createdAt: 聊天创建时间，格式为 UTC 时间字符串。
  • focusMode: 聊天的焦点模式，例如 webSearch。
  • files: 相关文件数组，当前为空。

---

1.2 获取特定聊天记录详情

描述

获取指定聊天记录的详细信息，包括聊天基本信息和相关的消息内容。

请求

• 方法： GET
• URL： http://192.168.3.9:3001/api/chats/{chat_id}
  • {chat_id}: 要获取详情的聊天记录的唯一标识符。

请求参数

无。

响应

状态码： 200 OK
内容类型： application/json

响应体示例

{
  "chat": {
    "id": "5a31859e83d0e45b6c5ba063091ff9403ed9eb3b",
    "title": "when is the first day of Kapiolani cummunity college",
    "createdAt": "Sat Dec 07 2024 09:35:59 GMT+0000 (Coordinated Universal Time)",
    "focusMode": "webSearch",
    "files": []
  },
  "messages": [
    {
      "id": 3,
      "content": "when is the first day of Kapiolani cummunity college",
      "chatId": "5a31859e83d0e45b6c5ba063091ff9403ed9eb3b",
      "messageId": "5b61edf4bc179e",
      "role": "user",
      "metadata": "{\"createdAt\":\"2024-12-07T09:35:59.119Z\"}"
    },
    {
      "id": 4,
      "content": "The first day of Kapiʻolani Community College for the current academic year is September 2[9]. This date marks the beginning of the instructional period at the college. It's important to note that a late registration fee of $30.00 is charged for new registrations on or after the first day of instruction[11]. Additionally, tuition payment is typically due by 4:00 pm on the day of registration to ensure enrollment in classes[11].",
      "chatId": "5a31859e83d0e45b6c5ba063091ff9403ed9eb3b",
      "messageId": "32fcbbf251337c",
      "role": "assistant",
      "metadata": "{\"createdAt\":\"2024-12-07T09:36:04.371Z\",\"sources\":[{\"pageContent\":\"Last day to register, add, or change full-semester class sections. Last day to withdraw from full-semester classes with 100% tuition refund* online at www.star.hawaii.edu *Note: Full refund of student/program fees are given for complete withdrawal from all classes in the UH System before instruction begins or within the 100% refund period.\",\"metadata\":{\"title\":\"Academic Calendar | Kapi'olani Community College\",\"url\":\"https://www.kapiolani.hawaii.edu/classes/academic-calendar/\"}}, {\"pageContent\":\"First Time Students; Transfer Students; International (F-1 Visa) ... Online PDF Version of the Kapi‘olani Community College General Catalog ... Classes . Other Useful Dates. 2024 Holidays. Jan 15 – Dr. Martin Luther King, Jr. Day Feb 19 – Presidents' Day Mar 18-22 – Spring Recess Mar 26 – Prince Kūhiō Day Mar 29 – Good Friday\",\"metadata\":{\"title\":\"Classes | Kapi'olani Community College\",\"url\":\"https://www.kapiolani.hawaii.edu/classes/\"}}]}"
    }
  ]
}

字段说明

• chat: 聊天基本信息，包括：
  • id: 聊天的唯一标识符。
  • title: 聊天标题，通常为用户的初始问题。
  • createdAt: 聊天创建时间，格式为 UTC 时间字符串。
  • focusMode: 聊天的焦点模式，例如 webSearch。
  • files: 相关文件数组，当前为空。
• messages: 聊天消息数组，每条消息包含：
  • id: 消息的唯一标识符（数据库中的自增 ID）。
  • content: 消息内容。
  • chatId: 关联的聊天记录 ID。
  • messageId: 消息的唯一标识符（例如 UUID）。
  • role: 消息角色，可能的值包括 user 和 assistant。
  • metadata: 额外的元数据信息，存储为 JSON 字符串，包含创建时间和来源信息等。

---

2. 代码实现

下面展示了与聊天历史记录相关的代码实现，包括控制器、服务类以及数据模型的部分代码。

2.1 ApiChatsController

该控制器负责处理对 /api/chats 及 /api/chats/{id} 的请求。

• index 方法返回所有聊天记录列表。
• get 方法返回指定聊天记录的详细信息，包括聊天基本信息和相关消息。

package nexus.io.perplexica.controller;

import java.util.ArrayList;
import java.util.List;
import java.util.Map;

import com.alibaba.fastjson2.JSONArray;
import com.alibaba.fastjson2.JSONObject;
import com.jfinal.kit.Kv;
import nexus.io.annotation.Get;
import nexus.io.annotation.RequestPath;
import nexus.io.jfinal.aop.Aop;
import nexus.io.perplexica.model.MaxSearchChatMessage;
import nexus.io.perplexica.services.ChatMessgeService;
import nexus.io.perplexica.services.ChatsService;
import nexus.io.perplexica.vo.WebPageSource;
import nexus.io.tio.utils.json.FastJson2Utils;

@RequestPath("/api/chats")
public class ApiChatsController {
  private ChatsService chatsService = Aop.get(ChatsService.class);
  private ChatMessgeService chatMessgeService = Aop.get(ChatMessgeService.class);

  @Get
  public Kv index(Long userId) {
    Kv kv = Kv.by("chats", chatsService.listChats(userId));
    return kv;
  }

  @Get("/{id}")
  public Kv get(Long id) {
    Kv kv = Kv.by("chat", chatsService.getById(id));
    List<MaxSearchChatMessage> listMessage = chatMessgeService.listMessage(id);
    List<Map<String, Object>> newMessages = new ArrayList<>();
    for (MaxSearchChatMessage perplexicaChatMessage : listMessage) {
      Map<String, Object> map = perplexicaChatMessage.toMap();
      String sourcesStr = perplexicaChatMessage.getSources();
      if (sourcesStr != null) {
        JSONArray jsonArray = FastJson2Utils.parseArray(sourcesStr);
        List<WebPageSource> sources = new ArrayList<>();
        for (int i = 0; i < jsonArray.size(); i++) {
          JSONObject jsonObject = jsonArray.getJSONObject(i);
          String title = jsonObject.getString("title");
          String url = jsonObject.getString("url");
          String content = jsonObject.getString("content");
          WebPageSource webPageSource = new WebPageSource(title, url, content);
          sources.add(webPageSource);
        }
        map.put("sources", sources);
      }
      newMessages.add(map);
    }
    kv.set("messages", newMessages);
    return kv;
  }
}

说明：

• index 方法调用 ChatsService.listChats(userId) 获取当前用户的所有聊天记录，并将其封装到 Kv 对象中返回。
• get 方法根据传入的聊天 ID 获取聊天基本信息和所有消息记录，同时对每条消息中保存的 sources（存储为 JSON 字符串）进行解析，将其转换为 WebPageSource 对象列表，并将解析后的数据一起返回。

---

2.2 ChatsService

该服务类用于查询聊天记录的基本信息。

• listChats 方法返回指定用户的聊天记录列表，按创建时间降序排列。
• getById 方法返回指定聊天记录的详细信息（基本信息部分）。

package nexus.io.perplexica.services;

import java.util.List;

import nexus.io.perplexica.model.MaxSearchChatSession;

public class ChatsService {

  public List<MaxSearchChatSession> listChats(Long userId) {
    String sql = "select id,title,focus_mode,created_at,files from max_search_chat_session where user_id=? order by created_at desc";
    List<MaxSearchChatSession> chats = MaxSearchChatSession.dao.find(sql, userId);
    return chats;
  }

  public MaxSearchChatSession getById(Long id) {
    String sql = "select id,title,focus_mode,created_at,files from max_search_chat_session where id=?";
    return MaxSearchChatSession.dao.findFirst(sql, id);
  }
}

说明：

• listChats 方法使用 SQL 查询获取指定用户的所有聊天记录。
• getById 方法根据聊天 ID 查询对应的聊天记录基本信息。

---

2.3 ChatMessgeService

该服务类提供与聊天消息相关的操作。

• listMessage 方法返回指定聊天会话中的所有消息（包括角色、内容、创建时间和 sources）。
• getHistoryById 方法将消息列表转换为通用的 ChatMessage 对象列表，方便其他模块获取历史记录。

package nexus.io.perplexica.services;

import java.util.ArrayList;
import java.util.List;

import nexus.io.openai.chat.ChatMessage;
import nexus.io.perplexica.model.MaxSearchChatMessage;

public class ChatMessgeService {

  public List<MaxSearchChatMessage> listMessage(Long sessionId) {
    return MaxSearchChatMessage.dao.find("select id,role,content,created_at,sources from $table_name where chat_id=?", sessionId);
  }

  public List<ChatMessage> getHistoryById(Long sessionId) {
    List<ChatMessage> retval = new ArrayList<>();
    List<MaxSearchChatMessage> messages = MaxSearchChatMessage.dao.find("select role,content from $table_name where chat_id=?", sessionId);
    for (MaxSearchChatMessage perplexicaChatMessage : messages) {
      ChatMessage chatMessage = new ChatMessage(perplexicaChatMessage.getRole(), perplexicaChatMessage.getContent());
      retval.add(chatMessage);
    }
    return retval;
  }
}

说明：

• listMessage 方法返回完整的消息数据，用于获取聊天详情时展示。
• getHistoryById 方法只返回消息的角色和内容，方便生成对话历史上下文。

---

2.4 SourcesController

该控制器用于辅助查看推理过程中的向大模型发送的推理数据，即显示保存到数据库中的 sources 数据，便于调试和核对搜索结果内容。

package nexus.io.perplexica.controller;

import java.util.List;

import com.alibaba.fastjson2.JSON;
import nexus.io.annotation.Get;
import nexus.io.annotation.RequestPath;
import nexus.io.db.activerecord.Db;
import nexus.io.model.web.WebPageContent;

@RequestPath("/sources")
public class SourcesController {

  @Get("/{id}")
  public String source(Long id) {
    String sql = "select sources from max_search_chat_message where id=?";
    String queryStr = Db.queryStr(sql, id);
    List<WebPageContent> webPages = JSON.parseArray(queryStr, WebPageContent.class);
    StringBuffer markdown = new StringBuffer();
    for (int i = 0; i < webPages.size(); i++) {
      WebPageContent webPageContent = webPages.get(i);
      markdown.append("source " + (i + 1) + " title: " + webPageContent.getTitle() + "\r\n");
      markdown.append("link " + (i + 1) + " link: " + webPageContent.getUrl() + "\r\n");
      markdown.append("source " + (i + 1) + " content " + webPageContent.getContent() + "\r\n\r\n");
    }
    return markdown.toString();
  }
}

说明：

• 该接口通过指定消息 ID 查询存储在数据库中的 sources 数据（JSON 格式），并将其解析为 WebPageContent 对象列表，最终生成 Markdown 格式的文本返回，方便调试和验证推理数据。

---

总结

本文档详细介绍了 ai-search 历史记录功能的 API 接口及其代码实现，主要内容包括：

• API 说明
  • 获取所有聊天记录：通过 GET /api/chats 获取用户所有的聊天记录列表。
  • 获取特定聊天记录详情：通过 GET /api/chats/{chat_id} 获取指定聊天记录的详细信息，包括聊天基本信息和所有消息。
• 代码实现
  • ApiChatsController：控制器层，处理历史记录查询请求，并对查询结果进行格式化返回。
  • ChatsService：服务层，提供查询聊天记录基本信息的方法。
  • ChatMessgeService：服务层，提供查询消息记录和转换历史记录的方法。
  • SourcesController：辅助接口，用于查看推理过程中发送给大模型的详细数据（sources）。