Đặ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://stg-knowledgebase-internal-svc.mydatalakes.com/api/v1/thirdparty
Môi trường Production: https://knowledgebase-svc.mydatalakes.com/api/v1/thirdparty

Headers Bắt Buộc

Header Name	Kiểu	Bắt Buộc	Mô Tả
`Content-Type`	`string`	Có	Luôn là `application/json; charset=utf-8`
`x-api-key`	`string`	Có	Khóa API cấp riêng cho từng ứng dụng hoặc đối tá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:

Trường Dữ Liệu	Kiểu	Bắt Buộc	Ý Nghĩa Kỹ Thuật
`connectionSettings.connectionId`	`string`	Yes	Định danh kết nối lưu trữ backend (ví dụ: `"postgres_vng"`, `"qdrant_cluster_1"`).
`connectionSettings.targetCollection`	`string`	Yes	Tên Collection đích cần nạp dữ liệu (ví dụ: `enterprise_branches`, `product_pricing`).
`payload`	`array`	Yes	Danh sách các đối tượng tri thức cần nạp vào hệ thống.
`payload[].document`	`string`	Yes	Nội dung văn bản định dạng Markdown. Đây là nguồn dữ liệu chính để tính toán vector embedding và cung cấp ngữ cảnh cho Agent.
`payload[].metadata`	`object`	Yes	Tập thuộc tính khóa-giá trị (Key-Value) phục vụ lọc chính xác (Pre-filtering / Post-filtering) khi truy hồi.
`payload[].eType`	`string`	Yes	Phân loại thực thể (Entity Type) để phân luồng xử lý và gán nhãn tri thức (ví dụ: `location`, `pricing_lookup`, `sop`).

3. 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:

Batch Ingestion Interface

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).

Ingestion Form & Raw Editor

4. 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:

4.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

4.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 |

4.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.

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

5.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).

5.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 code hoặc id duy nhất trong metadata.
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.

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

Mã HTTP	Tên Lỗi	Nguyên Nhân	Cách Khắc Phục
`200 OK`	Thành công	Dữ liệu đã được tiếp nhận và đưa vào hàng đợi vector hóa.	Bản ghi sẽ sẵn sàng tìm kiếm sau 1 - 3 giây.
`400 Bad Request`	Sai cấu trúc	Thiếu `connectionSettings` hoặc các item trong `payload` thiếu trường `document`.	Kiểm tra lại payload theo mẫu JSON chuẩn ở trên.
`401 Unauthorized`	Sai API Key	Thiếu header `x-api-key` hoặc khóa không hợp lệ.	Cung cấp đúng API Key do Pango AI Team cấp phát.
`404 Not Found`	Sai Collection	Collection được chỉ định trong `targetCollection` chưa được khởi tạo.	Kiểm tra tên Collection trên giao diện Admin hoặc tạo mới.
`429 Too Many Requests`	Vượt hạn mức	Gửi request vượt tần suất cho phép.	Triển khai cơ chế lũy tiến thời gian chờ (Exponential Backoff).
`500 Server Error`	Lỗi máy chủ	Lỗi nội bộ trong quá trình phân tách hoặc vector DB gián đoạn.	Liên hệ bộ phận kỹ thuật Pango AI để kiểm tra nhật ký log.

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

On this page