Cloudflare AI Search 教學：多文件 RAG、Similarity Cache 與 API 串接

586 瀏覽

2026-08-27 更新

想讓 AI 回答公司文件、產品手冊、FAQ 或網站內容，不一定要自己架設向量資料庫。Cloudflare AI Search 可以接收多份文件，自動完成解析、切塊與索引，再透過自然語言搜尋相關內容。這篇整理實務上最常遇到的三個問題：如何建立多文件 RAG、如何串接 Search API，以及如何用 Similarity Cache 減少重複查詢。

第一次測試時，先在同一個 AI Search instance 上傳 2～3 份內容清楚的小文件，再用 Playground 測試單一文件、跨文件與無答案問題。確認搜尋品質後，再調整篩選和快取。

Cloudflare AI Search 是什麼？

Cloudflare AI Search 是一套託管式 RAG（Retrieval-Augmented Generation，檢索增強生成）服務。它會先從指定資料來源找出與問題最相關的內容片段，再視需求交給模型產生答案。

內建儲存：直接上傳 PDF、Markdown、HTML、Word、試算表或圖片等檔案。
Website：連接網站，依 Sitemap 或頁面連結建立索引。
R2 Bucket：索引既有的 R2 文件，適合內容量較大的專案。

若還不熟悉 R2，可以先看 WordPress Offload 與 Cloudflare R2 儲存比較。第一次做 AI Search 不必先建立 R2，直接使用 instance 的內建儲存即可。

一個 RAG 可以放多份文件嗎？

可以，而且一般情況不需要為每份文件建立一個 RAG。比較合理的做法，是把同一個客戶或同一個知識領域的文件放進同一個 AI Search instance。每份文件會成為獨立 item，搜尋時可以一起排序，也能用 metadata filter 限定範圍。

規劃方式	適合情境
同一個 instance 放多份文件	同一客戶的產品手冊、FAQ、服務條款與內部 SOP
同一個 instance 搭配 metadata filter	只搜尋指定檔名、資料夾、產品、版本或已啟用文件
拆成不同 instance	不同客戶、權限邊界或資料必須完全隔離

Cloudflare 會提供 filename、folder、timestamp 等 metadata。若前端允許使用者勾選文件，就可以把選取的檔名放進 $in filter，一次搜尋多份指定文件；停用文件也能直接排除，不必刪除索引。

用 Dashboard 建立多文件知識庫

登入 Cloudflare Dashboard，進入 AI → AI Search。
選擇 Create Instance，設定容易辨識的英文名稱，例如 product-docs。
進入 instance 的 Items，上傳多份測試文件，或連接 Website、R2 Bucket。
等待索引完成，確認 Items 或 Jobs 沒有錯誤。
開啟 Playground，先用 Search 查看原始片段，再用 Chat 測試整理後的答案。

建議至少測三種問題：文件內有明確答案、需要跨兩份文件整理，以及文件內沒有答案。第三種問題可以確認系統會不會在資料不足時自行編造內容。

搜尋不準時先檢查這四點

文件品質：標題與章節要清楚；掃描 PDF 要先確認文字能被解析。
Chunking：片段太短會失去上下文，太長則容易混入無關資訊。
Hybrid Search：料號、專有名詞與錯誤碼很重要時，可結合向量搜尋與關鍵字 BM25。
Result Controls：調整 match threshold 與 maximum results，避免把太多低相關內容送進回答。

Search API 串接範例

建立 API Token 時，依使用需求給予 Account → AI Search:Run；若還要建立或管理 instance，再加入 AI Search:Edit。Token 應放在伺服器端，不要寫進前端 JavaScript 或提交到 Git。權限規劃可參考 Cloudflare API Token 最小權限教學。

read -s CLOUDFLARE_API_TOKEN export CLOUDFLARE_API_TOKEN export CLOUDFLARE_ACCOUNT_ID="你的 Account ID" export AI_SEARCH_INSTANCE="product-docs"  curl -i "https://api.cloudflare.com/client/v4/accounts/${CLOUDFLARE_ACCOUNT_ID}/ai-search/instances/${AI_SEARCH_INSTANCE}/search" \   --header "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}" \   --header "Content-Type: application/json" \   --data '{     "messages": [       {"role": "user", "content": "退貨期限是幾天？"}     ],     "ai_search_options": {       "cache": {         "enabled": true,         "cache_threshold": "close_enough"       },       "retrieval": {         "max_num_results": 5,         "filters": {           "filename": {             "$in": ["product-manual.pdf", "faq.pdf"]           }         }       }     }   }'

這個請求會同時搜尋兩份指定文件，並用 per-request override 開啟 Similarity Cache。若不需要限制文件，可以移除 filters。舊文章常見的 AutoRAG API 屬於舊版介面，新專案應以目前的 AI Search REST API 欄位為準。

Similarity Cache 是什麼？

Similarity Cache 會比對問題的相似程度。當新問題與先前查詢夠接近時，AI Search 可以直接回傳快取結果，不必重新建立一份相同用途的回應。它不是只比對完全相同的字串，因此「退貨可以在幾天內辦理？」與「退貨期限是幾天？」也可能命中同一份快取。

等級	API 值	建議用途
Exact	`super_strict_match`	內容敏感，只接受接近相同的問題
Strong	`close_enough`	一般客服與文件問答，建議先用這個預設值
Broad	`flexible_friend`	希望提高命中率，可接受較寬鬆的相似問題
Loose	`anything_goes`	重用範圍最大，需特別留意答非所問

快取 TTL 預設是 48 小時，instance 可設定的範圍從 10 分鐘到 6 天。若文件 chunk 被更新或刪除，相關快取也會清除，避免繼續使用舊內容。第一次查詢通常會看到 response header cf-aig-cache-status: MISS；再次送出相似問題，命中時會是 HIT。

Similarity Cache 能省下所有 LLM token 嗎？

要看程式架構。如果直接使用 AI Search 的生成回答流程，命中相似快取時可重用先前回應，減少重複生成。但如果程式只呼叫 /search 取得文件片段，再另外呼叫 OpenAI、Gemini 或 Anthropic 產生答案，Similarity Cache 主要省下的是 AI Search 檢索流程；後面的外部 LLM 仍然會被呼叫。

這種「AI Search 檢索＋外部 LLM 生成」架構，建議使用兩層快取：

Similarity Cache：重用語意相近問題的 AI Search 結果，加快 RAG 檢索。
回答快取：以客戶、模型、Prompt、對話與啟用文件集合建立快取鍵；完整命中時才略過外部 LLM，真正把該次生成 token 降為零。

回答快取如果只支援完全相同的請求，換一種問法仍可能無法命中。可先開啟 Similarity Cache，觀察常見問法與命中率，再評估是否要把完整答案快取擴充成語意快取。

不要開 AI Gateway 的一般 Cache

Cloudflare 官方特別提醒：連接 AI Search instance 的 AI Gateway 不應開啟一般 AI Gateway Cache。因為 AI Search 的 embedding、query rewriting、reranking 與生成請求都會經過該 Gateway，若 embedding 被一般快取錯誤重用，可能讓向量索引或查詢取得不正確的向量，搜尋準確度會在不容易察覺的情況下降。

需要快取 AI Search 結果時，使用 AI Search 自己的 Similarity Cache；AI Gateway 則保留 Analytics、Logs、Guardrails、模型 fallback 等用途。