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

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

&#x20;

Ví dụ:

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

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

&#x20;

## 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:

<table data-header-hidden><thead><tr><th valign="top"></th><th valign="top"></th></tr></thead><tbody><tr><td valign="top">Setting</td><td valign="top">Mô tả</td></tr><tr><td valign="top">Top K</td><td valign="top">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</td></tr><tr><td valign="top">Score Threshold</td><td valign="top">Đ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ề</td></tr></tbody></table>

&#x20;

&#x20;

## 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:

{\
&#x20; "error\_code": 1002,\
&#x20; "error\_msg": "Authorization failed. Please check your API key."\
}

&#x20;

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