Đặc tả API Kiến thức Bên ngoài

Đặc tả API mà external knowledge service của bạn cần implement để tích hợp với ClickAI.

Mục lục

· [Authentication](#authentication)

· [Request](#request)

· [Response](#response)

· [Error Handling](#error-handling)

Authentication

ClickAI xác thực với external knowledge service bằng Bearer token trong Authorization header:

Authorization: Bearer {API_KEY}

API Key là credential bạn cung cấp khi đăng ký External Knowledge API trong ClickAI.

Request

Endpoint

POST {your-endpoint}/retrieval Content-Type: application/json Authorization: Bearer {API_KEY}

ClickAI tự động thêm /retrieval vào API Endpoint đã đăng ký. Ví dụ nếu bạn cấu hình endpoint là https://your-service.com, ClickAI sẽ gửi request đến https://your-service.com/retrieval.

Body

Trường	Kiểu	Bắt buộc	Mô tả
knowledge_id	string	✅	ID của knowledge source trong hệ thống bên ngoài
query	string	✅	Câu hỏi tìm kiếm từ người dùng
retrieval_setting	object	✅	Cấu hình retrieval (xem chi tiết bên dưới)
metadata_condition	object	❌	Điều kiện lọc metadata (xem chi tiết bên dưới)

retrieval_setting

Trường	Kiểu	Mô tả
top_k	integer	Số chunks tối đa trả về
score_threshold	float	Điểm similarity tối thiểu (0.0 - 1.0). Mặc định 0.0 (không lọc)

metadata_condition

Trường	Kiểu	Mô tả
logical_operator	string	Toán tử logic: and hoặc or. Mặc định and
conditions	array	Danh sách điều kiện lọc

Mỗi condition gồm:

Trường	Kiểu	Mô tả
name	string	Tên trường metadata
comparison_operator	string	Toán tử so sánh
value	any	Giá trị so sánh (không bắt buộc cho empty, not empty)

Supported Comparison Operators:

Loại dữ liệu	Operators
String	contains, not contains, start with, end with, is, is not, in, not in, empty, not empty
Number	=, ≠, >, <, ≥, ≤, empty, not empty
Date	before, after, is, empty, not empty

Example Request

{ "knowledge_id": "your-knowledge-id", "query": "ClickAI là gì?", "retrieval_setting": { "top_k": 3, "score_threshold": 0.5 } }

Example Request với Metadata Filtering:

{ "knowledge_id": "your-knowledge-id", "query": "Chính sách bảo hành", "retrieval_setting": { "top_k": 5, "score_threshold": 0.4 }, "metadata_condition": { "logical_operator": "and", "conditions": [ { "name": "category", "comparison_operator": "is", "value": "policy" }, { "name": "language", "comparison_operator": "is", "value": "vi" } ] } }

Response

Response phải chứa trường records dạng array. Nếu không có kết quả, trả về array rỗng:

{"records": []}

records

Mỗi record trong array records gồm:

Trường	Kiểu	Bắt buộc	Mô tả
content	string	✅	Nội dung text của chunk
score	float	✅	Điểm relevance/similarity (0.0 - 1.0)
title	string	❌	Tiêu đề tài liệu nguồn
metadata	object	✅	Metadata bổ sung. Phải là object {}, KHÔNG được là null

Example Response

{ "records": [ { "content": "ClickAI là nền tảng AI toàn diện cho doanh nghiệp.", "score": 0.98, "title": "gioi-thieu.txt", "metadata": { "path": "s3://clickai/gioi-thieu.txt", "description": "Tài liệu giới thiệu ClickAI" } }, { "content": "ClickAI cho phép xây dựng ứng dụng AI không cần code.", "score": 0.85, "title": "features.txt", "metadata": {} } ] }

Error Handling

Khi xảy ra lỗi, API nên trả về object chứa error_code và error_msg:

Trường	Kiểu	Mô tả
error_code	integer	Mã lỗi
error_msg	string	Thông điệp lỗi chi tiết

Các mã lỗi phổ biến:

Mã lỗi	Mô tả
1001	Invalid request format
1002	Authorization failed
2001	Knowledge not found
2002	Retrieval service unavailable

Example Error Response

{ "error_code": 1002, "error_msg": "Authorization failed. Please check your API key." }

📖 Trước: [Kết nối External Knowledge](./06-external-knowledge.md) · Tiếp: [Quản lý Documents & Chunks](./08-manage-documents-chunks.md)