Kết nối Cơ sở Kiến thức Bên ngoài

Tích hợp nguồn knowledge bên ngoài với ứng dụng ClickAI thông qua kết nối API để tận dụng hệ thống RAG tùy chỉnh hoặc dịch vụ knowledge bên thứ ba.

Mục lục

· [Tổng quan](#tổng-quan)

· [Bước 1: Xây dựng Retrieval API](#bước-1-xây-dựng-retrieval-api)

· [Bước 2: Đăng ký External Knowledge API](#bước-2-đăng-ký-external-knowledge-api)

· [Bước 3: Tạo External Knowledge Base](#bước-3-tạo-external-knowledge-base)

· [Xử lý lỗi](#xử-lý-lỗi)

Tổng quan

Ngoài việc tạo Knowledge Base trực tiếp trên ClickAI, bạn có thể kết nối với nguồn knowledge bên ngoài — ví dụ:

· Hệ thống RAG tự xây dựng

· AWS Bedrock Knowledge Base

· Vector databases: Pinecone, Weaviate, Qdrant, Milvus

· Dịch vụ knowledge bên thứ ba

Quy trình kết nối gồm 3 bước:

1. Xây dựng API service mà ClickAI có thể query

2. Đăng ký API endpoint trong ClickAI

3. Kết nối knowledge source cụ thể qua API đã đăng ký

Bước 1: Xây dựng Retrieval API

Bạn cần xây dựng một API service tuân thủ đặc tả External Knowledge API của ClickAI.

Endpoint format:

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

Request body:

{ "knowledge_id": "your-knowledge-id", "query": "Câu hỏi người dùng", "retrieval_setting": { "top_k": 3, "score_threshold": 0.5 } }

Response format:

{ "records": [ { "content": "Nội dung chunk được truy xuất.", "score": 0.98, "title": "document.txt", "metadata": { "path": "s3://bucket/document.txt", "description": "Mô tả tài liệu" } } ] }

⚠️ IMPORTANT: Trường `metadata` trong mỗi record phải là object (`{}`), không được là `null`. Giá trị `null` gây lỗi trong retrieval pipeline. Các trường `content` và `score` bắt buộc phải có trong mỗi record.

Bước 2: Đăng ký External Knowledge API

4. Vào Knowledge, nhấn External Knowledge API ở góc trên phải

5. Nhấn Add an External Knowledge API

6. Điền các trường:

Trường	Mô tả
Name	Tên để phân biệt API connection này với các connection khác
API Endpoint	URL cơ sở của external knowledge service. ClickAI tự động thêm /retrieval khi gửi request
API Key	Credential xác thực cho service. ClickAI gửi nó như Bearer token trong Authorization header

Ví dụ:

· API Endpoint: https://your-service.com

· ClickAI sẽ gửi request đến: https://your-service.com/retrieval

Bước 3: Tạo External Knowledge Base

7. Vào Knowledge và nhấn Connect to an External Knowledge Base

8. Điền các trường:

· External Knowledge Name và Knowledge Description (tùy chọn)

· External Knowledge API: Chọn API connection đã đăng ký

· External Knowledge ID: Định danh của knowledge source cụ thể trong hệ thống bên ngoài, được gửi đến API dưới dạng trường knowledge_id

🚨 WARNING: External Knowledge API và External Knowledge ID **không thể thay đổi** sau khi tạo. Để sử dụng API hoặc knowledge source khác, hãy tạo external knowledge base mới.

9. Cấu hình Retrieval Settings:

Setting	Mô tả
Top K	Số chunks tối đa truy xuất mỗi query. Giá trị cao hơn trả về nhiều kết quả hơn nhưng có thể bao gồm nội dung ít liên quan
Score Threshold	Điểm similarity tối thiểu cho chunks trả về. Bật để lọc bỏ kết quả ít liên quan. Giá trị cao hơn = strict hơn. Khi tắt, tất cả kết quả đến giới hạn Top K đều được trả về

Xử lý lỗi

Connection Refused hoặc Timeout (Self-Hosted)

Nếu bạn đang self-host ClickAI, kiểm tra cấu hình allowed_domains trong file docker/ssrf_proxy/squid.conf.template:

acl allowed_domains dstdomain .marketplace.dify.ai .your-kb-service.com

Thêm domain của external knowledge service vào danh sách allowed.

API Response Format Issues

Kiểm tra response format tuân thủ đặc tả:

· Trường metadata trong mỗi record phải là object ({}), không được là null

· Các trường content và score bắt buộc trong mỗi record

Ví dụ Error Response:

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

📖 Trước: [Knowledge Pipeline](./05-knowledge-pipeline.md) · Tiếp: [External Knowledge API Spec](./07-external-knowledge-api.md)