# 使用知識庫—建立與互動
## 概述
MaiAgent 提供開發者透過 API 管理知識庫檔案的能力。開發者可以在工作區內對知識庫進行以下操作:
* 上傳新檔案到知識庫
* 查詢知識庫中的所有檔案
* 更新現有檔案的資訊
* 刪除單一或批次檔案
{% hint style="info" %}
**📘 重要提醒**
使用 API 時，所有操作都需要有效的 API Key 進行身份驗證。請確保您的 API Key 具備相應的權限。
{% endhint %}
***
## 知識庫操作
### 建立知識庫
在開始使用知識庫前，必須先建立至少**一個**知識庫。建立知識庫時，您必須指定知識庫使用的 Embedding Model、Reranker Model、知識庫名稱及可使用此知識庫的 AI 助理等資訊。
您可以將以上的設定資訊，透過腳本化的方式指定，以下為建立資料庫的請求範例：
{% code overflow="wrap" %}
```json
{
"embeddingModel": "550e8400-e29b-41d4-a716-446655440000", // Embedding Model ID
"rerankerModel": "550e8400-e29b-41d4-a716-446655440000", // Reranker Model ID
"name": "內部訓練手冊",
"description": "此知識庫供內部訓練使用，包含使用者手冊、產品手冊及錯誤處理手冊，僅供新人教育使用",
"numberOfRetrievedChunks": 12, // 指定檢索片段數量
"enableRerank": true,
"chatbots": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
]
}
```
{% endcode %}
送出並獲得 HTTPS 回應後即代表建立成功，可以針對此知識庫進行操作。
### 使用 ID 操作單一知識庫
在開始對所單一知識庫進行檔案管理之前,您需要先取得知識庫的唯一識別碼(`id`)。
{% hint style="warning" %}
如何取得知識庫 id？
1. 取得剛建立的知識庫 `id`
針對剛使用腳本建立的知識庫，在建立完成後 HTTPS 會回傳包含 id 在內的 reponse，response 中的 `id`就代表該知識庫的 `id`值。
2. 取得其他已建立的知識庫 `id`
您可以透過取得所有知識庫的 `reponse` 內容獲取您需要的對應知識庫 `id`，請參考 API 文件：[知識庫(新版)](https://docs.maiagent.ai/api/api-reference/zhi-shi-ku-xin-ban#lie-chu-suo-you-zhi-shi-ku)
{% endhint %}
### 查詢知識庫檔案
`查詢檔案` 端點可用於列出知識庫中的所有檔案。您可以使用查詢參數來篩選特定類型、狀態的檔案,或搜尋特定關鍵字。將您要查詢的知識庫 `id` 加入端點內`{knowledgeBasePK}`的位置，就能夠針對特定知識庫進行查詢。
#### 端點
```
GET /api/knowledge-bases/{knowledgeBasePk}/files/
```
#### 檔案狀態值(key 值為 Status)
您可以根據端點回應，查看每個檔案的處理情況，分別為以下幾種，若顯示為`done` 即表示檔案已處理完成可供 LLM 回答檢索使用：
* `initial` - 初始化
* `processing` - 處理中
* `done` - 完成
* `deleting` - 刪除中
* `deleted` - 已刪除
* `failed` - 失敗
此端點可透過設定 `fileType`指定查詢檔案類型，如：`pdf`、`docx`、`txt`、`xlsx` 等
#### 範例:查詢所有 PDF 檔案
{% tabs %}
{% tab title="Shell/Bash" %}
{% code overflow="wrap" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/?fileType=example&knowledgeBase=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&status=deleted" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endcode %}
{% endtab %}
{% endtabs %}
***
## 檔案操作
### 上傳檔案到知識庫
#### 端點
```
POST /api/knowledge-bases/{knowledgeBasePk}/files/
```
您可以使用此端點直接將檔案上傳到知識庫。您可以在上傳時透過參數指定該文件的資訊，如：
* `rawUserDefineMetadata`：文件元資料
* `labels`：文件分類標籤
#### 範例：上傳單個文件—產品手冊
**請求結構範例**
您可以指定要上傳的檔案內容與知識庫。
{% code overflow="wrap" %}
```json
{
"files": [
{
"filename": "產品手冊.pdf",
"file": "https://my-product-bucket.s3.ap-northeast-1.amazonaws.com/products/laptop-dell-xps-15.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIOSFODNN7EXAMPLE%2F20251030%2Fap-northeast-1%2Fs3%2Faws4_request&X-Amz-Date=20251030T143000Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
"knowledgeBase": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "內部訓練知識庫"
},
"parser": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"labels": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "新人訓練"
}
],
},
]
}
```
{% endcode %}
回應將包含新建立的檔案物件,包括系統自動生成的檔案 ID。
您也可以上傳多個檔案至不同的知識庫
#### 範例：上傳多個文件至不同知識庫
{% code overflow="wrap" %}
```json
{
"files": [
{
"filename": "新人教育手冊.pdf",
"file": "https://my-product-bucket.s3.ap-northeast-1.amazonaws.com/products/laptop-dell-xps-15.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIOSFODNN7EXAMPLE%2F20251030%2Fap-northeast-1%2Fs3%2Faws4_request&X-Amz-Date=20251030T143000Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567891",
"knowledgeBase": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "內部訓練知識庫"
},
},
{
"filename": "D256 產品說明文件.pdf",
"file": "https://my-product-bucket.s3.ap-northeast-1.amazonaws.com/products/laptop-dell-xps-15.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIOSFODNN7EXAMPLE%2F20251030%2Fap-northeast-1%2Fs3%2Faws4_request&X-Amz-Date=20251030T143000Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=abcdef1234567890abcdef1234567890abcdef123456",
"knowledgeBase": {
"id": "3fa85f64-5717-4562-b3fc-2c963f655o2l1",
"name": "對外客服資料庫"
},
}
]
}
```
{% endcode %}
{% hint style="danger" %}
請注意：單一檔案限制不能超過 100MB，否則將無法正確處理，HTTP 將回傳錯誤訊息
{% endhint %}
### 更新現有檔案資訊
您可以使用 `更新檔案資訊` 端點來修改已上傳檔案的資訊,例如檔案名稱、標籤或自訂元資料。若檔案有更新，您無須重複上傳，可直接透過腳本進行資訊變動。
#### 端點
```
PUT /api/knowledge-bases/{knowledgeBasePk}/files/{id}/
```
**請求範例**
{% code overflow="wrap" %}
```json
{
"filename": "產品手冊修訂版.pdf",
"file": "https://ecommerce-products.s3.us-west-2.amazonaws.com/images/electronics/smartphones/iphone-15-pro-max-256gb-natural-titanium.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAI44QH8DHBEXAMPLE%2F20251030%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20251030T120000Z&X-Amz-Expires=7200&X-Amz-SignedHeaders=host&X-Amz-Security-Token=FwoGZXIvYXdzEBYaDH...truncated...&X-Amz-Signature=8c9d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d",
"knowledgeBase": {
"id": "550e8400-e29b-41d4-a716-446655440000"
},
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
}
],
"rawUserDefineMetadata": {
"editDate": "2025/10/30",
"lastEditBy": "Wang",
"version": "online"
}
}
```
{% endcode %}
### 刪除檔案
#### 刪除單一檔案
**端點**
```
DELETE /api/knowledge-bases/{knowledgeBasePk}/files/{id}
```
使用此端點可以從知識庫中移除單一檔案，移除時需在端點`{id}`位置指定要刪除的文件`id`。
**範例**
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% endtabs %}
成功刪除後，API 將回傳 `204` 狀態碼。此文件將無法再讓 LLM 作為回覆參考。
#### 批次刪除檔案
若要一次刪除多個檔案，可以使用 `批次刪除檔案` 端點，提升管理效率。
**端點**
```
POST /api/knowledge-bases/{knowledgeBasePk}/files/batch-delete/
```
請求範例值
```json
{
"ids": [
"550e8400-e29b-41d4-a716-446655440000",
"550e8400-e29b-41d4-a716-446655449198",
"kdlkjf029-e2b-41d4-adk06-dklwie091874"
]
}
```
您可以傳入多個文件 `id`，讓系統協助您一次刪除多個文件。
{% hint style="warning" %}
此端點僅能批次刪除單一知識庫內的文件，無法跨知識庫進行批次刪除。
{% endhint %}
***
## 使用案例
知識庫檔案管理 API 有許多實際應用場景,例如:
### 1. 自動化文件更新
當您的產品文件在 Git 儲存庫中更新時，可以透過 CI/CD 流程自動將最新版本上傳到知識庫。確保 AI 助理始終能存取最新的產品資訊。
#### **範例流程**
{% stepper %}
{% step %}
**偵測到文件更新的 commit**
{% endstep %}
{% step %}
**查詢是否已存在該檔案**
使用 MaiAgent API 查詢知識庫內是否有可匹配之檔案。
{% endstep %}
{% step %}
**更新/上傳檔案**
若存在則使用部分更新資訊端點更新；如果不存在則使用上傳檔案端點上傳新檔案。
{% endstep %}
{% endstepper %}
### 2. 內容管理系統整合
如果您使用 MaiAgent 作為內容管理系統 (CMS)，可以建立一個管理介面,讓內容編輯者能夠
* 上傳新的內容檔案
* 使用標籤組織內容
* 搜尋和篩選特定類型的內容
* 批次刪除過期內容
***
## 總結
MaiAgent 的公開 REST API 可以讓您更有效率管理知識庫檔案，包括：
* 建立知識庫
* 查詢和篩選檔案
* 上傳新檔案
* 更新檔案資訊
* 刪除單一或批次檔案
## 下一步
* 查看完整的 [API 參考文件](https://docs.maiagent.ai/api)開始使用 MaiAgent API 服務
* 探索 [MaiAgent WebChat SDK ](https://docs.maiagent.ai/tech/api-integration/web-chat-sdk)以簡化 API 整合
---
# Agent Instructions: 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:
```
GET https://docs.maiagent.ai/tech/api-integration/shi-yong-zhi-shi-ku-jian-li-yu-hu-dong.md?ask=
```
The question should be specific, self-contained, and written in natural language.
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.