> For the complete documentation index, see [llms.txt](https://docs.clickai.vn/clickai-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clickai.vn/clickai-docs/co-so-du-lieu/ket-noi-co-so-kien-thuc-ben-ngoai.md). # Kết nối Cơ sở Kiến thức Bên ngoài ## 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ườngMô tả
NameTên để phân biệt API connection này với các connection khác
API EndpointURL cơ sở của external knowledge service. ClickAI tự động thêm /retrieval khi gửi request
API KeyCredential xác thực cho service. ClickAI gửi nó như Bearer token trong Authorization header
Ví dụ: · API Endpoint: · ClickAI sẽ gửi request đến: ## 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:
SettingMô tả
Top KSố 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)* --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.clickai.vn/clickai-docs/co-so-du-lieu/ket-noi-co-so-kien-thuc-ben-ngoai.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.