Đặc Tả API Nạp Dữ Liệu (Ingestion API)

Ingestion API là giao thức RESTful chuẩn hóa dành cho các hệ thống phần mềm của đối tác (Backend Services, ERP, CRM, ETL Data Pipelines, CMS) để đẩy các dữ liệu tri thức mới nhất vào Knowledge Base Hub phục vụ cho hệ thống Chatbot AI.

1. Thông Tin Endpoint & Xác Thực

• Phương thức: POST
• Môi trường Sandbox / Staging: https://domain-knowledgebase-svc.com/api/v1/thirdparty
• Môi trường Production: sẽ được gửi qua email khi bắt đầu tích hợp.

Headers Bắt Buộc

2. Cấu Trúc JSON Request Body Chuẩn

Dữ liệu gửi lên API bao gồm 2 phần chính: Cấu hình kết nối kho lưu trữ (connectionSettings) và Danh sách các bản ghi tri thức (payload).

{
  "connectionSettings": {
    "connectionId": "postgres_vng",
    "targetCollection": "enterprise_knowledge_collection"
  },
  "payload": [
    {
      "document": "## Tiêu đề tài liệu hoặc mục tri thức\n- Thuộc tính 1: Giá trị\n- Thuộc tính 2: Giá trị...",
      "metadata": {
        "code": "DOC_001",
        "category": "Policy",
        "author": "Pango AI Admin",
        "_hash": "a1b2c3d4e5f6"
      },
      "eType": "generic_document"
    }
  ]
}

Chi Tiết Các Trường Dữ Liệu:

3. Cơ Chế Ingestion Pub/Sub

Ngoài luồng nạp trực tiếp, Knowledge Base Hub có cơ chế Ingestion Pub/Sub cho các nguồn dữ liệu lớn hoặc đồng bộ thường xuyên. API tiếp nhận và kiểm tra payload trước, sau đó đưa tác vụ vào hàng đợi để xử lý nền.

Luồng Xử Lý

1. Hệ thống đối tác gửi dữ liệu qua Ingestion API.
2. API xác thực và đưa payload hợp lệ vào hàng đợi Pub/Sub.
3. Worker xử lý lần lượt: chuẩn hóa, kiểm tra trùng lặp, chia đoạn, tạo vector và lập chỉ mục.
4. Dữ liệu sẵn sàng tìm kiếm sau khi xử lý hoàn tất; trạng thái có thể theo dõi trong Ingestion Logs.

Lợi Ích

• Phản hồi nhanh: Không cần chờ toàn bộ quá trình vector hóa hoàn tất trong một request.
• Ổn định khi tải cao: Hàng đợi điều tiết số lượng batch và giảm nguy cơ timeout.
• Dễ mở rộng và khôi phục: Worker có thể tăng theo lưu lượng; tác vụ lỗi được ghi nhận để kiểm tra hoặc chạy lại.

Đối tác vẫn sử dụng payload Ingestion API chuẩn. Cấu hình Pub/Sub chi tiết sẽ được Pango AI Team cung cấp khi kích hoạt luồng đồng bộ này.

4. Giao Diện Kiểm Tra & Nạp Payload

Quản trị viên và lập trình viên có thể kiểm tra trực tiếp cấu trúc JSON Payload hoặc nạp thủ công thông qua giao diện Batch Ingestion:

Giao diện hỗ trợ kiểm tra tính hợp lệ của cú pháp JSON (JSON Lint), kiểm tra định dạng Markdown và xem trước các trường Metadata trước khi kích hoạt tiến trình nhúng vector (Embedding).

5. Quy Chuẩn Định Dạng Văn Bản (document)

Để LLM có thể đọc hiểu và trích xuất dữ liệu với độ chính xác cao nhất, nội dung trường document cần được định dạng theo các quy tắc Markdown sau:

5.1. Thực Thể Định Danh (Entity / Profile)

Sử dụng danh sách gạch đầu dòng có tiêu đề cấp bậc (##, ###):

## Hồ Sơ Sản Phẩm: Gói Dịch Vụ Pango Enterprise (SKU_ENT_01)
- Phân khúc: Doanh nghiệp lớn (> 500 nhân sự)
- Tính năng: Hỗ trợ đa kênh (Zalo, Web, Messenger, App), SLA 99.99%
- Giá cước: Liên hệ đội ngũ tư vấn giải pháp
- Website chi tiết: https://pango.ai/enterprise

5.2. Dữ Liệu Bảng Biểu (Pricing Table / Specification)

Bắt buộc sử dụng cú pháp Markdown Table. Không viết bảng biểu dưới dạng văn bản tự do nối dòng:

## BẢNG GIÁ DỊCH VỤ NĂM 2026

| Mã Gói | Thời Hạn | Giá Gốc (VNĐ) | Giá Khuyến Mãi (VNĐ) | Hạn Mức Chat/Tháng |
|---|---|---|---|---|
| BASIC | 1 tháng | 2,000,000 | 1,600,000 | 10,000 |
| PRO | 6 tháng | 12,000,000 | 9,600,000 | 50,000 |
| VIP | 12 tháng | 24,000,000 | 16,800,000 | Không giới hạn |

5.3. Quy Trình & Kịch Bản Nghiệp Vụ (SOP / Script)

Trình bày rõ ràng theo từng bước kèm điều kiện rẽ nhánh:

## QUY TRÌNH XỬ LÝ KHIẾU NẠI DỊCH VỤ (SOP_CS_01)
- Bước 1: Tiếp nhận phản ánh từ khách hàng và ghi nhận mã đơn hàng.
- Bước 2: Kiểm tra lịch sử giao dịch trên hệ thống CRM trong vòng 5 phút.
  + Nếu lỗi do hệ thống: Thực hiện hoàn tiền ngay theo chính sách Điều 3.
  + Nếu lỗi do đối tác vận chuyển: Chuyển tiếp phiếu hỗ trợ cho đơn vị bưu chính.
- Bước 3: Cập nhật trạng thái phiếu hỗ trợ thành "Đang Xử Lý" trên CRM.

6. Best Practices Cho Kỹ Sư Tích Hợp

6.1. Kích Thước Batch Tối Ưu

• Mỗi request gửi đến API nên chứa từ 20 đến 50 items trong mảng payload.
• Tránh gửi từng item đơn lẻ (gây nghẽn mạng do HTTP handshake lặp lại) hoặc gửi vượt quá 100 items (dễ chạm giới hạn timeout của Gateway).

6.2. Cơ Chế Khóa Trùng Lặp & Upsert Dữ Liệu

Để tránh việc nạp trùng lặp một bản ghi nhiều lần khi chạy script ETL định kỳ:

• Đặt trường hash duy nhất nếu muốn cập nhật dữ liệu.
• Tính mã băm MD5 hoặc SHA-256 của nội dung tài liệu và gán vào khóa _hash trong metadata. Khi gặp hash giống nhau, hệ thống sẽ bỏ qua bước embedding giúp tiết kiệm chi phí và tài nguyên.

7. Bảng Mã Lỗi HTTP Thường Gặp