Tham chiếu API: AI Assistant

Tài liệu này chi tiết về các điểm cuối API RESTful cho module AI Assistant, hỗ trợ các quy trình công việc RAG.

---

1. Xác thực

Tất cả các yêu cầu PHẢI bao gồm một Platform JWT trong tiêu đề Authorization.

Authorization: Bearer <JWT>

JWT được cấp bởi Shell và chứa danh tính, tổ chức và vai trò của người dùng.

---

2. API Trò chuyện Hội thoại

POST /sessions

Tạo một phiên trò chuyện mới.

Phản hồi (201 Created):

{
  "data": {
    "id": "uuid",
    "title": "Cuộc hội thoại mới"
  }
}

GET /sessions

Liệt kê các phiên trò chuyện của người dùng hiện tại.

POST /sessions/:id/messages

Gửi một tin nhắn và nhận phản hồi dạng luồng (SSE).

Thân yêu cầu (Body):

{
  "content": "Chính sách làm việc từ xa của công ty chúng ta là gì?"
}

Phản hồi (200 OK — SSE):

• event: message (các token thay đổi)
• event: sources (danh sách trích dẫn)
• event: error (nếu thất bại)

GET /sessions/:id/messages

Truy xuất lịch sử tin nhắn của một phiên làm việc.

---

3. API Cơ sở Tri thức

GET /sources

Liệt kê tất cả các nguồn đã đánh chỉ mục cho tổ chức hiện tại.

POST /sources

Thêm một nguồn mới vào cơ sở tri thức (kích hoạt đánh chỉ mục).

Thân yêu cầu (Body):

{
  "type": "url",
  "url": "https://handbook.example.com"
}

Hoặc cho các tệp Drive:

{
  "type": "drive",
  "fileId": "uuid"
}

POST /sources/:id/sync

Kích hoạt thủ công việc đánh chỉ mục lại cho một nguồn hiện có.

DELETE /sources/:id

Xóa một nguồn và tất cả các vector chunk của nó khỏi cơ sở tri thức.

---

4. API Phản hồi & Phân tích

POST /messages/:id/feedback

Đánh giá một phản hồi của AI.

Thân yêu cầu (Body):

{
  "isHelpful": true,
  "comment": "Câu trả lời rất chính xác!"
}

GET /analytics/summary

Lấy số liệu thống kê sử dụng toàn tổ chức (truy vấn, phiên hoạt động, sức khỏe cơ sở tri thức). Yêu cầu vai trò ADMIN.

---

5. Mã Lỗi Tiêu chuẩn

Mã Trạng thái	Mô tả
400 Bad Request	Truy vấn hoặc URL nguồn không hợp lệ.
401 Unauthorized	Thiếu hoặc JWT không hợp lệ.
403 Forbidden	Không đủ quyền hạn để quản lý cơ sở tri thức.
404 Not Found	Phiên làm việc hoặc nguồn không tồn tại.
429 Too Many Requests	Vượt quá giới hạn tốc độ (ví dụ: hạn mức sử dụng token).
500 Server Error	Lỗi LLM hoặc Vector DB.