Tham chiếu API — AI Knowledge Base

Tổng quan Resources

Resource	Mô tả	Quyền truy cập
aiKnowledgeBases	Quản lý knowledge bases	Admin
aiDocuments	Quản lý tài liệu trong knowledge base	Admin
aiDocumentChunks	Chunks sau khi chia nhỏ tài liệu	Nội bộ
aiEmbeddings	Vector embeddings	Nội bộ

Knowledge Base

Tạo knowledge base

await agent.resource('aiKnowledgeBases').create({
  values: {
    name: 'Chính sách nhân sự',
    description: 'Tất cả quy định về nghỉ phép, lương thưởng, phúc lợi',
    embeddingModel: 'text-embedding-3-small',
  },
});

Lấy danh sách knowledge bases

const response = await agent.resource('aiKnowledgeBases').list({
  sort: ['-createdAt'],
});
// response.body.data = [{ id, name, description, embeddingModel, documentCount, ... }]

Cập nhật knowledge base

await agent.resource('aiKnowledgeBases').update({
  filterByTk: kbId,
  values: {
    name: 'Tên mới',
    description: 'Mô tả cập nhật',
  },
});

Xoá knowledge base

// Xoá knowledge base + tất cả tài liệu, chunks, embeddings liên quan
await agent.resource('aiKnowledgeBases').destroy({
  filterByTk: kbId,
});

Documents (Tài liệu)

Upload tài liệu

await agent.resource('aiDocuments').create({
  values: {
    knowledgeBaseId: kbId,
    file: fileBlob,          // File object hoặc Blob
    chunkSize: 1000,         // Tuỳ chọn: kích thước chunk
    chunkOverlap: 200,       // Tuỳ chọn: độ chồng lấp
  },
});

Lấy danh sách tài liệu

const docs = await agent.resource('aiDocuments').list({
  filter: { knowledgeBaseId: kbId },
  sort: ['-createdAt'],
});

Xoá tài liệu

// Xoá tài liệu + tất cả chunks và embeddings của tài liệu
await agent.resource('aiDocuments').destroy({
  filterByTk: docId,
});

Tìm kiếm (Search / Retrieval)

Tìm kiếm ngữ nghĩa

const results = await agent.resource('aiKnowledgeBases').search({
  filterByTk: kbId,
  values: {
    query: 'Chính sách nghỉ phép năm',
    topK: 5,   // Số kết quả tối đa trả về
  },
});
// results.body.data = [{ content, score, metadata: { documentId, fileName, ... } }]

Kết quả trả về được sắp xếp theo cosine similarity — score càng cao càng liên quan.

Database Collections

Collection	Mô tả	Các field chính
aiKnowledgeBases	Danh sách knowledge bases	name, description, embeddingModel
aiDocuments	Tài liệu đã upload	knowledgeBaseId, fileName, status, chunkCount
aiDocumentChunks	Chunks sau khi chia nhỏ	documentId, content, index
aiEmbeddings	Vector embeddings	chunkId, vector, metadata

Document Object

Trường	Kiểu	Mô tả
id	bigint	ID tài liệu
knowledgeBaseId	bigint	Knowledge base chứa tài liệu
fileName	string	Tên file gốc khi upload
fileType	string	Loại file (pdf, docx, txt, md, csv)
status	string	Trạng thái: processing, ready, failed
chunkCount	integer	Số chunks đã tạo
fileSize	bigint	Kích thước file (bytes)
createdAt	datetime	Thời gian upload
updatedAt	datetime	Thời gian cập nhật gần nhất

Giới hạn kỹ thuật

Tham số	Giá trị	Ghi chú
File tối đa	50MB	Chia file lớn thành nhiều phần
Định dạng hỗ trợ	PDF, DOCX, TXT, MD, CSV	Thêm format qua DocumentLoaders
Số tài liệu / KB	100 (mặc định)	Cấu hình được
Embedding API key	Bắt buộc	Dùng key của LLM provider tương ứng
TopK mặc định	5	Có thể tăng/giảm qua parameter