> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/build/knowledge-base/scrape-website.md).

# 如何使用爬蟲（爬取資料）功能

輸入網址、設定爬取範圍，選擇單次執行或定期排程，MaiAgent 就會自動爬取網頁並匯入知識庫，還能在匯入紀錄中追蹤每一次匯入結果。

## 功能用途與價值 <a href="#feature-purpose-and-value" id="feature-purpose-and-value"></a>

身為企業人員，可能經常會接到長官指示，需要參考或彙整某些公開網站上的法規資料，或讓 Agent 掌握官網上最新的產品與 FAQ 內容。

若具備技術背景，或有工程人員協助，或許可以透過撰寫爬蟲程式自動擷取資料；但對於非技術人員而言，通常只能手動一頁頁整理，不僅耗時費力，還容易遺漏關鍵資訊。

此時，您可以善用 MaiAgent 的爬蟲功能，透過 No-Code（免寫程式）方式：

* **一次爬取整個網站範圍**：設定爬取深度、頁數上限與網址規則，決定要爬哪些頁面
* **單次執行或定期排程**：可以立即爬一次，也可以每日、每週、每月自動重新爬取
* **自動匯入知識庫**：爬完直接匯入指定知識庫，並可選擇網址重複時要略過、覆蓋或允許重複
* **追蹤匯入結果**：每次匯入成功幾頁、失敗幾頁，都可以在匯入紀錄中查看

## 使用情境 <a href="#use-case" id="use-case"></a>

某公司的客服主管希望 AI 客服回答問題時，內容能和官網 FAQ 保持一致。她先在知識庫中建立一個專門收納官網 FAQ 的知識庫，接著進入「爬蟲」建立爬取請求：填入官網 FAQ 的網址，把最大爬取深度與頁數設小，先確認只會爬到 FAQ 相關頁面；執行方式選「排程執行」、頻率設為每週一早上 9 點，自動匯入目標選剛建立的知識庫，網址已存在時的處理方式選「略過」。建立後，排程分頁就會出現這筆每週同步的任務。之後每次爬取完成，她在爬取請求詳情的「匯入紀錄」就能看到這次自動匯入到哪個知識庫、成功與失敗各幾頁；官網 FAQ 改版時，也不需要再請工程師幫忙整理資料。

## 如何進行爬蟲？ <a href="#how-to-scrape" id="how-to-scrape"></a>

{% hint style="info" %}
若左側選單看不到「爬蟲」，代表您的帳號沒有爬蟲的存取權限，請聯絡組織管理員確認權限設定。
{% endhint %}

### 1. 進入爬蟲頁面 <a href="#open-crawler" id="open-crawler"></a>

從左側選單點選 <mark style="color:blue;">AI 功能</mark> → <mark style="color:blue;">爬蟲</mark>。頁面分為兩個分頁：

* <mark style="color:blue;">頁面爬取請求</mark>：列出每一次爬取（包含單次執行，以及排程每次自動執行產生的爬取），可依名稱或網址搜尋，並以類型（單次／排程）與爬取狀態（完成／進行中／失敗）篩選
* <mark style="color:blue;">排程</mark>：列出所有定期爬取的排程設定

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-e4539a8db7b766461e78291d443ecd5bdab3035f%2Fcrawl-list-requests.png?alt=media" alt="爬蟲頁面的頁面爬取請求分頁，列出一筆單次爬取，爬取狀態為完成，操作欄有詳情、匯入與檢視"><figcaption><p>頁面爬取請求分頁：每筆請求顯示類型、爬取狀態與建立時間</p></figcaption></figure>

### 2. 輸入任務名稱與網址 <a href="#step-url" id="step-url"></a>

點選右上方的 <mark style="color:blue;">建立頁面爬取請求</mark>，建立流程分為「網址」、「爬取設定」、「執行方式」三個步驟。

第一步請填寫：

* <mark style="color:blue;">任務名稱</mark>：方便辨識這個爬取任務，例如「每日商品頁面爬取」
* <mark style="color:blue;">URL</mark>：要開始爬取的網址

填好後點 <mark style="color:blue;">下一步</mark>。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-90d847c058b16aa2555db9acbfb4deb8cb91d7df%2Fcrawl-create-url.png?alt=media" alt="建立頁面爬取請求視窗的第一步，填寫任務名稱與 URL"><figcaption><p>第一步：填寫任務名稱與起始網址</p></figcaption></figure>

### 3. 設定爬取深度與範圍 <a href="#step-crawl-settings" id="step-crawl-settings"></a>

第二步「爬取設定」決定要爬多少頁面。<mark style="color:blue;">基本設定</mark>有兩個欄位：

| 欄位                                      | 說明                                          |
| --------------------------------------- | ------------------------------------------- |
| <mark style="color:blue;">最大爬取深度</mark> | 從起始網址往下追連結的層數，可選 1–10，預設 2                  |
| <mark style="color:blue;">最大爬取頁數</mark> | 這次最多爬取的頁數，可選 10、50、100、500、1000、5000，預設 100 |

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-b8322b7180855f80945e61f82f8859bbf5c5a8bb%2Fcrawl-create-basic-settings.png?alt=media" alt="爬取設定步驟的基本設定，最大爬取深度設為 1、最大爬取頁數設為 10"><figcaption><p>基本設定：以最大爬取深度與最大爬取頁數控制爬取範圍</p></figcaption></figure>

需要更精確地控制範圍時，展開 <mark style="color:blue;">進階設定</mark>：

| 設定                                          | 說明                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <mark style="color:blue;">使用提示語生成規則</mark>  | 用自然語言描述要收哪些網址（例如「只爬取商品頁面，並忽略已封存的文章」），按 <mark style="color:blue;">生成規則</mark> 後 AI 會把它轉成下方的網址比對與排除規則，生成後仍可逐條修改。要先在第一步填入網址才能生成；提示語無法對應到網址規則時會提示「目前只支援依網址篩選」，請改寫提示語或手動新增規則。沒按生成規則就繼續時會先跳出確認，見下方「[提示語還沒生成規則時的確認](#prompt-not-generated-confirm)」                                                                                                                                                                                                                             |
| <mark style="color:blue;">網址比對規則</mark>     | 只爬取符合規則的網址，例如 `/products/*`；未新增規則時會爬取範圍內的所有頁面                                                                                                                                                                                                                                                                                                                                                                                                                            |
| <mark style="color:blue;">網址排除規則</mark>     | 符合規則的網址不爬取，例如 `/admin/*` 或 `\.pdf$`                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| <mark style="color:blue;">邊界設定</mark>       | 是否 <mark style="color:blue;">允許爬取至同層或上層路徑</mark>、<mark style="color:blue;">包含子網域</mark>、<mark style="color:blue;">允許外部連結</mark>，預設皆關閉                                                                                                                                                                                                                                                                                                                                    |
| <mark style="color:blue;">Sitemap 策略</mark> | <mark style="color:blue;">優先使用 sitemap（預設）</mark>、<mark style="color:blue;">忽略 sitemap</mark> 或 <mark style="color:blue;">僅使用 sitemap</mark>                                                                                                                                                                                                                                                                                                                             |
| <mark style="color:blue;">內容擷取設定</mark>     | <mark style="color:blue;">僅擷取主要內容</mark>、<mark style="color:blue;">忽略網址參數</mark>（預設皆開啟），以及 <mark style="color:blue;">JS 渲染等待時間</mark>（0、500、1000、2000 ms）                                                                                                                                                                                                                                                                                                                |
| <mark style="color:blue;">爬取語系／地區</mark>    | 以指定語言與地區讀取網站。多語網站會依此回傳對應語言版本，例如選 <mark style="color:blue;">繁體中文（台灣）</mark> 可避免被轉到英文版；可選 <mark style="color:blue;">繁體中文（台灣）</mark>、<mark style="color:blue;">简体中文（中国）</mark>、<mark style="color:blue;">English (US)</mark>、<mark style="color:blue;">日本語（日本）</mark>。<mark style="color:blue;">預設（不指定）</mark> 不向網站宣告語言，由爬取服務決定（目前等同英文）。位於 <mark style="color:blue;">內容擷取設定</mark> 下方，預覽與排程的每次執行都沿用同一個語系，說明見[多語網站：指定爬取語系／地區](/build/knowledge-base/crawler.md#crawl-locale) |

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-ea33308d14838c70084cba9240919e27688ce38c%2Fcrawl-create-advanced-settings.png?alt=media" alt="爬取設定步驟展開的進階設定，包含使用提示語生成規則、網址比對規則、網址排除規則、邊界設定、Sitemap 策略、內容擷取設定，以及內容擷取設定下方的爬取語系／地區（預設（不指定））"><figcaption><p>進階設定：以網址規則、邊界與 Sitemap 策略進一步限定爬取範圍，並可指定爬取語系／地區</p></figcaption></figure>

{% hint style="warning" %}
開啟 <mark style="color:blue;">允許外部連結</mark> 後會爬取站外網址，可能大幅增加爬取頁數與費用。建議先用較小的深度與頁數測試，確認範圍正確後再放大。
{% endhint %}

{% hint style="info" %}
提示語只會轉成網址的比對／排除規則，無法依頁面標題或內文篩選；以按鈕或表單翻頁（網址不變）的列表，爬蟲只收得到第一頁。
{% endhint %}

#### 提示語還沒生成規則時的確認 <a href="#prompt-not-generated-confirm" id="prompt-not-generated-confirm"></a>

填了 <mark style="color:blue;">使用提示語生成規則</mark>，但還沒按 <mark style="color:blue;">生成規則</mark>（或生成後又改過提示語）就按 <mark style="color:blue;">下一步</mark> 或 <mark style="color:blue;">預覽</mark> 時，系統會先跳出「提示語尚未轉換成規則」確認視窗，提醒直接繼續會爬取範圍內的所有頁面：

* <mark style="color:blue;">生成規則</mark>：依提示語生成網址規則。從 <mark style="color:blue;">預覽</mark> 跳出時，會先回到「爬取設定」步驟生成，讓您看到產生的規則，確認後再預覽
* <mark style="color:blue;">仍要繼續</mark>：不生成規則，照目前的設定繼續
* 按右上角關閉或 Esc：留在目前步驟，不做任何動作

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-7f8055a4cfe839de6bbcdb293681827d151388cf%2Fcrawl-create-prompt-confirm.png?alt=media" alt="提示語尚未轉換成規則確認視窗，說明直接繼續會爬取範圍內的所有頁面，下方有仍要繼續與生成規則兩個按鈕"><figcaption><p>提示語還沒生成規則就按下一步時跳出的確認視窗</p></figcaption></figure>

{% hint style="info" %}
只有提示語本身的變動會觸發確認；生成後手動新增或刪除 <mark style="color:blue;">網址比對規則</mark>、<mark style="color:blue;">網址排除規則</mark> 不算改提示語，不會再跳出確認。在 <mark style="color:blue;">下一步</mark> 選了 <mark style="color:blue;">仍要繼續</mark> 後，到「執行方式」再按 <mark style="color:blue;">預覽</mark> 仍會再問一次。
{% endhint %}

例如，某公司的知識管理專員要把官網 `/docs/` 底下的說明文件爬進知識庫。她在提示語寫「只收 /docs/ 底下的頁面，排除 PDF」後直接按 <mark style="color:blue;">下一步</mark>，系統跳出確認視窗；她選 <mark style="color:blue;">生成規則</mark>，規則區隨即出現 `/docs/.*` 比對規則與 `.*\.pdf$` 排除規則，再按 <mark style="color:blue;">下一步</mark> 就不會重複詢問，避免一不小心把整個網站都爬進知識庫。

#### 爬取範圍怎麼決定 <a href="#crawl-scope-rules" id="crawl-scope-rules"></a>

爬蟲從起始網址出發，沿著頁面上的連結往外找，一個網址要同時通過下列條件才會被爬取：

| 條件         | 規則                                                                                                                                                                                                                                                                 |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 站內範圍       | 預設只爬同一個主機名稱、且路徑在起始網址底下的頁面（起始網址是 `https://example.com/docs/` 時，`/docs/a` 會爬、`/blog/` 不會）。<mark style="color:blue;">允許爬取至同層或上層路徑</mark> 放寬為整個網域；<mark style="color:blue;">包含子網域</mark> 再加入 `help.example.com` 這類子網域；<mark style="color:blue;">允許外部連結</mark> 才會爬到其他網站 |
| 網址規則       | <mark style="color:blue;">網址排除規則</mark> 優先於 <mark style="color:blue;">網址比對規則</mark>；設了比對規則後，不符合任何一條的網址都不爬。規則是正規表示式，預設只比對網址的路徑部分（不含主機名稱與參數）                                                                                                                         |
| 深度         | <mark style="color:blue;">最大爬取深度</mark> 是「發現順序」的層數：起始網址與 sitemap 裡列出的網址算第 0 層，從它們連出去的頁面是第 1 層，再連出去的是第 2 層，依此類推。只要超過設定的層數就不再往下找                                                                                                                                     |
| 頁數         | <mark style="color:blue;">最大爬取頁數</mark> 是這次爬取的總頁數上限，達到就停止，和深度無關                                                                                                                                                                                                    |
| Sitemap    | 預設 <mark style="color:blue;">優先使用 sitemap</mark>：網站有 sitemap 時，裡面列出的網址會直接納入（視為第 0 層），即使起始頁面沒有連到它們；<mark style="color:blue;">忽略 sitemap</mark> 只沿連結找；<mark style="color:blue;">僅使用 sitemap</mark> 只爬 sitemap 列出的網址                                                  |
| 網址參數       | <mark style="color:blue;">忽略網址參數</mark> 開啟時，`?page=2` 這類只差參數的網址視為同一頁，只爬一次；頁面內容靠參數切換的網站請關閉                                                                                                                                                                          |
| robots.txt | 一律遵守目標網站的 robots.txt，被禁止的路徑不會爬取，也無法用設定繞過                                                                                                                                                                                                                           |

同一個網址在一次爬取中只會處理一次，不會因為多個頁面都連到它而重複爬取。

**只想抓起始頁這一頁**時：Sitemap 策略選 <mark style="color:blue;">忽略 sitemap</mark>、最大爬取深度設 1，並在 <mark style="color:blue;">網址比對規則</mark> 加入只符合該頁路徑的規則（例如 `^/about/?$`），再用 <mark style="color:blue;">預覽</mark> 確認「將爬取」只有這一頁。

設定完成後點 <mark style="color:blue;">下一步</mark>。

### 4. 選擇執行方式與匯入知識庫 <a href="#step-execution" id="step-execution"></a>

第三步「執行方式」決定何時爬取，以及爬完之後要匯入哪裡。

**執行方式**

* <mark style="color:blue;">單次執行</mark>：建立後立即執行一次爬取
* <mark style="color:blue;">排程執行</mark>：依設定的排程週期執行爬取（設定方式見下一節「[設定定期排程](#schedule)」）

**知識庫設定**

* <mark style="color:blue;">匯入至既有知識庫</mark>：在 <mark style="color:blue;">自動匯入目標（選填）</mark> 選擇一個或多個知識庫，爬取完成後會自動匯入；留空則只爬取頁面、不自動匯入，之後可再[手動匯入](#manual-import)
* <mark style="color:blue;">自動建立新知識庫</mark>：每次執行都會以任務名稱自動建立一個新的知識庫，並將爬取內容匯入其中

選擇了匯入目標後，會出現 <mark style="color:blue;">網址已存在時的處理方式</mark>，用來處理同一個網址已經匯入過該知識庫的情況：

| 選項                                      | 說明               |
| --------------------------------------- | ---------------- |
| <mark style="color:blue;">略過</mark>（預設） | 已匯入到此知識庫的網址將被略過  |
| <mark style="color:blue;">覆蓋</mark>     | 現有檔案會被新爬取的內容取代   |
| <mark style="color:blue;">允許重複</mark>   | 即使網址已存在，仍會建立新的檔案 |

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-b849114622ef4fe018592ac55f4824c782ab52d5%2Fcrawl-create-execution-oneshot.png?alt=media" alt="執行方式步驟選擇單次執行、匯入至既有知識庫，並顯示網址已存在時的處理方式，預設為略過"><figcaption><p>執行方式：選擇單次執行，並指定自動匯入的知識庫與重複網址的處理方式</p></figcaption></figure>

{% hint style="info" %}
定期同步同一個網站時，建議使用 <mark style="color:blue;">略過</mark> 或 <mark style="color:blue;">覆蓋</mark>，避免知識庫中累積重複的檔案，導致 Agent 引用到舊內容。
{% endhint %}

### 5. 預覽並建立 <a href="#preview-and-create" id="preview-and-create"></a>

建立前可以先點 <mark style="color:blue;">預覽</mark>，確認實際會爬取哪些頁面。預覽會探索網站網址並計費，系統會先跳出確認視窗，按 <mark style="color:blue;">確定</mark> 後才會執行。

預覽結果會顯示發現的網址數、將爬取與被排除的網址數、預估頁數與預估時間，並列出將爬取的頁面。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-98ade6f0b412295b27e59ddb54058d43ec4ade6b%2Fcrawl-preview.png?alt=media" alt="預覽視窗顯示目標網址、發現 URL、將爬取與排除的數量、預估頁數與預估時間，以及將爬取的頁面清單"><figcaption><p>預覽：建立前先確認將爬取的頁面數量與清單</p></figcaption></figure>

{% hint style="info" %}
預覽是預估結果，實際爬取會因深度限制、JavaScript 動態頁面與 robots.txt 而略有差異。
{% endhint %}

確認無誤後點 <mark style="color:blue;">建立</mark>。單次執行的請求會出現在「頁面爬取請求」分頁，並開始爬取。

若這個網址先前已經爬取過，系統會跳出 <mark style="color:blue;">此網址已被爬取過</mark> 的確認視窗，列出先前爬取的時間、頁面數與已匯入的知識庫。確定仍要重新爬取時點 <mark style="color:blue;">再次爬取</mark>，不需要則點 <mark style="color:blue;">取消</mark>。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-1701750793d8cd036def10ccfdc6c13d6294e3a0%2Fcrawl-previously-crawled.png?alt=media" alt="此網址已被爬取過的確認視窗，列出先前的爬取時間、子頁面數與已匯入的知識庫"><figcaption><p>重複爬取提醒：可先確認先前的爬取結果，再決定是否重新爬取</p></figcaption></figure>

## 設定定期排程 <a href="#schedule" id="schedule"></a>

網站內容會持續更新時，可在第三步選擇 <mark style="color:blue;">排程執行</mark>，讓系統定期重新爬取並自動匯入知識庫。

| 欄位                                                                          | 說明                                                                                                                                              |
| --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:blue;">頻率</mark>                                         | <mark style="color:blue;">單次</mark>、<mark style="color:blue;">每日</mark>、<mark style="color:blue;">每週</mark>、<mark style="color:blue;">每月</mark> |
| <mark style="color:blue;">時區</mark>                                         | 排程時間所依據的時區                                                                                                                                      |
| <mark style="color:blue;">開始日期</mark>／<mark style="color:blue;">結束日期</mark> | 排程生效期間；結束日期為選填，頻率為「單次」時只需開始日期                                                                                                                   |
| <mark style="color:blue;">執行時間</mark>                                       | 每次執行的時間                                                                                                                                         |
| <mark style="color:blue;">週幾執行</mark>                                       | 頻率為「每週」時，勾選要執行的星期（可複選）                                                                                                                          |
| <mark style="color:blue;">每月幾號</mark>                                       | 頻率為「每月」時，填寫 1–31                                                                                                                                |

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-2d4abe505f3c1a4ac079e7c5eabefd3ebea96cdb%2Fcrawl-create-execution-schedule.png?alt=media" alt="排程執行設定，頻率選每週、時區 Asia/Taipei、執行時間 09:00、週幾執行勾選週一，並匯入至既有知識庫"><figcaption><p>排程執行：設定每週一早上 9 點自動爬取並匯入知識庫</p></figcaption></figure>

建立後，排程會列在 <mark style="color:blue;">排程</mark> 分頁，顯示排程設定與狀態（<mark style="color:blue;">啟用中</mark>／<mark style="color:blue;">已暫停</mark>）。操作欄的圖示依序可以：

* **編輯**：開啟「編輯排程」修改任務名稱、爬取設定、排程時間與知識庫設定（起始網址建立後無法修改）
* **執行紀錄**：查看這個排程每一次執行的時間與爬取狀態，並可進入該次爬取的詳情
* **暫停／啟用**：暫時停止排程，或重新啟用
* **刪除**：刪除排程

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-a004c12c146f1a0a9fae14b5ee685e937d16b530%2Fcrawl-schedule-list.png?alt=media" alt="排程分頁列出一筆每週一 9:00 執行的排程，狀態為啟用中，操作欄有編輯、執行紀錄、暫停與刪除圖示"><figcaption><p>排程分頁：查看排程設定，並可編輯、查看執行紀錄、暫停或刪除</p></figcaption></figure>

{% hint style="warning" %}
每次排程執行都會實際爬取網頁並消耗 Credits。暫時不需要同步時，建議先暫停排程。
{% endhint %}

## 查看爬取結果與匯入紀錄 <a href="#results-and-import-history" id="results-and-import-history"></a>

在「頁面爬取請求」分頁點選該筆請求的 <mark style="color:blue;">詳情</mark>，進入 <mark style="color:blue;">爬取請求詳情</mark> 頁面：

* <mark style="color:blue;">爬取進度</mark>：已處理頁面與總頁面數
* <mark style="color:blue;">爬取任務設定</mark>：展開後可回顧建立時的網址、爬取設定與執行方式；切到「爬取設定」可看到這次使用的 <mark style="color:blue;">爬取語系／地區</mark>（未設定時顯示「預設（不指定）」）
* <mark style="color:blue;">已爬取頁面</mark>：列出每個爬到的頁面標題、URL、爬取狀態與完成時間

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-0d2fa9e3af7c9c17622c9a76458e1535b3a2f8f8%2Fcrawl-detail.png?alt=media" alt="爬取請求詳情頁，顯示爬取進度、爬取任務設定與已爬取頁面列表"><figcaption><p>爬取請求詳情：查看爬取進度與已爬取的頁面</p></figcaption></figure>

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-5c79ddd8513569f8e090b2f8f926a1d2a7dedb09%2Fcrawl-detail-locale.png?alt=media" alt="爬取任務設定的內容擷取設定區，爬取語系／地區唯讀顯示繁體中文（台灣），下方已爬取頁面列出一筆完成的中文標題頁面"><figcaption><p>爬取任務設定：唯讀顯示這次使用的爬取語系／地區</p></figcaption></figure>

切換到 <mark style="color:blue;">匯入紀錄</mark> 分頁，可以看到每一次匯入的時間、匯入的知識庫、<mark style="color:blue;">匯入方式</mark>（依建立時的設定自動匯入者顯示「自動」），以及成功與失敗的頁數。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-e7cd87be7b457d330db2ca3192ca780cf6fb4cab%2Fcrawl-import-history.png?alt=media" alt="匯入紀錄分頁顯示一筆匯入，知識庫為示範知識庫，匯入方式為自動，成功 1、失敗 0"><figcaption><p>匯入紀錄：每次匯入的知識庫、匯入方式與成功／失敗頁數</p></figcaption></figure>

點操作欄的圖示可開啟 <mark style="color:blue;">匯入頁面列表</mark>，逐頁查看匯入狀態，以及對應的知識庫檔案。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-776aee0d55309e3f78688782e1f8b4c84cbd41f7%2Fcrawl-import-run-pages.png?alt=media" alt="匯入頁面列表視窗，列出頁面標題、URL、匯入狀態成功與對應的知識庫檔案"><figcaption><p>匯入頁面列表：確認每個頁面匯入後對應的知識庫檔案</p></figcaption></figure>

此外，在「頁面爬取請求」列表中，已完成的請求可點 <mark style="color:blue;">檢視</mark> 開啟 <mark style="color:blue;">失敗匯入紀錄</mark>，選擇知識庫後查看匯入失敗的頁面與失敗原因。

匯入後的內容會以 .md 檔呈現在知識庫的文件列表中（檔名取自頁面標題），和一般文件一樣可以設定標籤與元資料。這些檔案的 <mark style="color:blue;">來源</mark> 欄會顯示 <mark style="color:blue;">爬蟲</mark> 標籤，點選即可回到對應的爬取請求詳情。系統也會把來源網址寫進文件的 `url` 元資料，Agent 引用這份文件時，使用者點引用會直接開啟原始網頁；內容保留方式見[知識庫總覽的常見問題](/build/knowledge-base/km.md#faq-format-preservation)。

## 手動匯入爬取頁面 <a href="#manual-import" id="manual-import"></a>

建立時沒有設定自動匯入，或想把頁面匯入其他知識庫時，可以手動匯入：

1. 在爬取請求詳情頁點 <mark style="color:blue;">匯入知識庫</mark>（或在列表中點該筆請求的 <mark style="color:blue;">匯入</mark>）
2. 選擇要匯入的 <mark style="color:blue;">知識庫</mark>，並選擇 <mark style="color:blue;">網址已存在時的處理方式</mark>
3. 勾選要匯入的頁面，點 <mark style="color:blue;">匯入</mark>

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-b84abfbe106ef4aab81f035bee907c9c9c77b2e2%2Fcrawl-manual-import.png?alt=media" alt="頁面列表視窗，選擇知識庫與網址已存在時的處理方式，並勾選要匯入的頁面"><figcaption><p>手動匯入：選擇知識庫、重複網址處理方式與要匯入的頁面</p></figcaption></figure>

若選擇 <mark style="color:blue;">略過</mark> 且部分網址已經匯入過，系統會提示建立了幾個匯入任務、略過了幾個重複網址。

{% hint style="warning" %}
手動匯入時會重新爬取最新頁面資料，會產生一次爬取費用。
{% endhint %}

## 爬取或匯入失敗時怎麼查 <a href="#troubleshooting" id="troubleshooting"></a>

先分清楚是哪一段失敗，再對照原因：

| 現象                           | 常見原因                                                   | 怎麼處理                                                                                                                                                                          |
| ---------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 建立請求時就被擋下                    | 起始網址超過 200 個字元，或不是完整的網址（需含 `http://` 或 `https://`）     | 改用較短的上層網址作為起點，再用爬取深度與比對規則涵蓋目標頁面                                                                                                                                               |
| 爬取狀態為失敗，原因是「爬取已結束，但沒有取得任何頁面」 | 目標網站的 robots.txt 不允許爬取（原因會列出被阻擋的網址）；網站阻擋自動化存取；起始網址無法載入 | 確認網址在未登入的瀏覽器中打得開。網站不允許爬取時，請改用上傳檔案的方式提供內容                                                                                                                                      |
| 爬到的頁面比預期少                    | 頁面超出爬取網域範圍、被排除規則排除、超過最大爬取深度或頁數；內容由 JavaScript 動態載入     | 建立前先用預覽確認「將爬取」與「被排除」的網址，再調整深度、頁數與比對規則                                                                                                                                         |
| 頁面需要登入才能看                    | 爬蟲只能讀取公開頁面                                             | 把內容匯出成檔案後上傳到知識庫                                                                                                                                                               |
| 網站只放行白名單 IP，想把爬蟲的來源 IP 加進去   | 爬取由雲端爬取服務執行，來源 IP 不固定，MaiAgent 無法提供可加入白名單的 IP          | 請網站管理者把要提供的內容匯出成檔案，上傳到知識庫                                                                                                                                                     |
| 爬取成功，但匯入知識庫失敗                | 個別頁面在匯入時處理失敗                                           | 在「頁面爬取請求」列表點 <mark style="color:blue;">檢視</mark> 開啟 <mark style="color:blue;">失敗匯入紀錄</mark>，選擇知識庫後查看每一頁的 <mark style="color:blue;">失敗原因</mark>，再用 [手動匯入](#manual-import) 重新匯入 |

失敗原因看不出問題，或同一個網址反覆失敗時，請記下爬取請求的名稱與時間，洽 MaiAgent 窗口。

## 爬蟲使用注意事項 <a href="#scraping-considerations" id="scraping-considerations"></a>

* 請確保您有權限爬取目標網站內容
* 爬取、預覽與手動匯入都會消耗 Credits，建議先用較小的最大爬取深度與頁數測試，確認範圍後再擴大
* 爬取完成後可透過[搜尋測試功能](/build/knowledge-base/test-search-result.md)驗證資料品質
* 網站內容經常更新時，建議使用[定期排程](#schedule)保持資訊時效性，並搭配 <mark style="color:blue;">略過</mark> 或 <mark style="color:blue;">覆蓋</mark> 避免重複檔案


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/build/knowledge-base/scrape-website.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.