> For the complete documentation index, see [llms.txt](https://developer.eagle.cool/web-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.eagle.cool/web-api/zh-tw/api/ai-search.md). # AI Search {% hint style="info" %} **需要** [**AI Search**](https://eagle.cool/support/article/ai-search) **插件。** AI 搜尋功能需要安裝並執行 Eagle AI 搜尋插件。在進行搜尋前，請使用狀態端點確認服務是否可用。 {% endhint %} ## 端點概覽 | 方法 | 端點 | 說明 | | ---- | ------------------------------------- | ---------------- | | GET | `/api/v2/aiSearch/isInstalled` | 檢查 AI 搜尋是否已安裝 | | GET | `/api/v2/aiSearch/isReady` | 檢查 AI 搜尋是否已就緒 | | GET | `/api/v2/aiSearch/isStarting` | 檢查 AI 搜尋是否正在啟動中 | | GET | `/api/v2/aiSearch/isSyncing` | 檢查 AI 搜尋是否正在同步資料 | | GET | `/api/v2/aiSearch/getSyncStatus` | 取得詳細的同步狀態 | | GET | `/api/v2/aiSearch/checkServiceHealth` | 檢查服務健康狀態 | | POST | `/api/v2/aiSearch/searchByText` | 以文字描述搜尋 | | POST | `/api/v2/aiSearch/searchByBase64` | 以圖片搜尋（Base64） | | POST | `/api/v2/aiSearch/searchByItemId` | 以項目 ID 尋找相似項目 | *** ## 狀態端點 ### GET /api/v2/aiSearch/isInstalled 檢查 AI 搜尋插件是否已安裝。 ```javascript await fetch("http://localhost:41595/api/v2/aiSearch/isInstalled").then(r => r.json()); ``` **回應：** ```json { "status": "success", "data": true } ``` *** ### GET /api/v2/aiSearch/isReady 檢查 AI 搜尋是否已完全初始化並準備好接受搜尋查詢。 ```javascript await fetch("http://localhost:41595/api/v2/aiSearch/isReady").then(r => r.json()); ``` **回應：** ```json { "status": "success", "data": true } ``` *** ### GET /api/v2/aiSearch/isStarting 檢查 AI 搜尋服務是否正在啟動中。 ```javascript await fetch("http://localhost:41595/api/v2/aiSearch/isStarting").then(r => r.json()); ``` **回應：** ```json { "status": "success", "data": false } ``` *** ### GET /api/v2/aiSearch/isSyncing 檢查 AI 搜尋是否正在同步（索引）資源庫資料。 ```javascript await fetch("http://localhost:41595/api/v2/aiSearch/isSyncing").then(r => r.json()); ``` **回應：** ```json { "status": "success", "data": false } ``` *** ### GET /api/v2/aiSearch/getSyncStatus 取得詳細的同步狀態，包含進度資訊。 ```javascript await fetch("http://localhost:41595/api/v2/aiSearch/getSyncStatus").then(r => r.json()); ``` **回應：** ```json { "status": "success", "data": { "isSyncing": false, "syncedCount": 12500, "totalCount": 12500, "progress": 1.0 } } ``` *** ### GET /api/v2/aiSearch/checkServiceHealth 對 AI 搜尋服務執行健康檢查。 ```javascript await fetch("http://localhost:41595/api/v2/aiSearch/checkServiceHealth").then(r => r.json()); ``` **回應：** ```json { "status": "success", "data": { "healthy": true } } ``` *** ## 搜尋端點 ### POST /api/v2/aiSearch/searchByText 使用自然語言文字描述搜尋項目。AI 模型會找到視覺上或語義上匹配的項目。 #### 請求主體 * `query` string（必填）— 要搜尋的文字描述 * `options` Object（可選） * `limit` integer — 最大結果數量（預設值依 AI 搜尋設定而定） #### 回應 ```json { "status": "success", "data": { "results": [ { "item": { "id": "M3QSGJNQTC2DG", "name": "sunset-beach", "ext": "jpg", "width": 1920, "height": 1080, "tags": ["nature", "sunset"], "star": 4 }, "score": 0.892 }, { "item": { "id": "K7XPWQBN9TC3F", "name": "golden-hour", "ext": "png", "width": 2560, "height": 1440, "tags": ["photography"], "star": 3 }, "score": 0.756 } ] } } ``` #### 範例 ```javascript // 以文字描述搜尋 await fetch("http://localhost:41595/api/v2/aiSearch/searchByText", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ query: "an orange cat sitting on a windowsill" }) }).then(r => r.json()); // 搜尋並限制結果數量 await fetch("http://localhost:41595/api/v2/aiSearch/searchByText", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ query: "minimalist logo design", options: { limit: 20 } }) }).then(r => r.json()); ``` *** ### POST /api/v2/aiSearch/searchByBase64 提供 Base64 編碼的圖片來尋找視覺上相似的項目。 #### 請求主體 * `base64` string（必填）— Base64 編碼的圖片資料 * `options` Object（可選） * `limit` integer — 最大結果數量 #### 回應 與 `searchByText` 格式相同 — 回傳按相似度排序的 `{ item, score }` 結果陣列。 #### 範例 ```javascript await fetch("http://localhost:41595/api/v2/aiSearch/searchByBase64", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ base64: "/9j/4AAQSkZJRg...", options: { limit: 10 } }) }).then(r => r.json()); ``` *** ### POST /api/v2/aiSearch/searchByItemId 尋找與資源庫中現有項目視覺上相似的項目。 #### 請求主體 * `itemId` string（必填）— 要尋找相似項目的項目 ID * `options` Object（可選） * `limit` integer — 最大結果數量 #### 回應 與 `searchByText` 格式相同 — 回傳按相似度排序的 `{ item, score }` 結果陣列。 #### 範例 ```javascript await fetch("http://localhost:41595/api/v2/aiSearch/searchByItemId", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ itemId: "M3QSGJNQTC2DG", options: { limit: 10 } }) }).then(r => r.json()); ``` *** ## 建議的工作流程 1. **檢查可用性** — 在搜尋前先呼叫 `isInstalled` 和 `isReady` 2. **啟動中請等待** — 如果 `isStarting` 回傳 `true`，持續輪詢直到 `isReady` 變為 `true` 3. **檢查同步狀態** — 使用 `getSyncStatus` 確認索引是否為最新 4. **搜尋** — 使用 `searchByText` 進行描述性搜尋、`searchByBase64` 進行以圖搜圖、或 `searchByItemId` 尋找相似項目 ```javascript // 步驟 1：確認 AI 搜尋已就緒 const { data: isReady } = await fetch("http://localhost:41595/api/v2/aiSearch/isReady") .then(r => r.json()); if (isReady) { // 步驟 2：執行搜尋 const results = await fetch("http://localhost:41595/api/v2/aiSearch/searchByText", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ query: "sunset landscape", options: { limit: 10 } }) }).then(r => r.json()); console.log(results.data.results); } ```