Typesense怎麼用 輕量級搜尋引擎教程

Typesense是一個開源的輕量級搜尋引擎，部署簡單、搜尋速度快，適合做網站搜尋和電商商品檢索。它透過集合（Collection）組織資料，文件寫入後即可查詢，還支援拼寫容錯、篩選和排序。下面用 Docker 和 HTTP API 演示從啟動服務到完成一次商品搜尋的流程，適合先在本機搭建體驗，再按業務需要部署到伺服器。

第一步：安裝Typesense

先確認電腦已安裝 Docker，然後在終端建立資料目錄，避免容器重啟後索引檔案丟失：mkdir -p typesense-data。接著啟動容器並對映預設 API 埠 8108：docker run -p 8108:8108 -v “$(pwd)/typesense-data:/data” typesense/typesense:30.2 –data-dir /data –api-key=change-this-key。初學時可在本機測試，正式環境請換成足夠複雜的金鑰，並妥善儲存。

容器啟動後，另開一個終端檢查服務是否就緒：curl http://localhost:8108/health。如果返回表示健康的狀態資訊，就可以繼續操作；若連線失敗，先檢視容器日誌，確認埠對映和啟動引數無誤。示例裡的 change-this-key 是演示值，後續每次請求都要把它換成啟動服務時設定的 API 金鑰。

第二步：建立集合和寫入資料

在 Typesense 裡，一組欄位相似的文件放在一個集合中。先建立名為 products 的集合，並定義商品名稱、類別、價格和庫存欄位。執行下面請求時，把金鑰替換為自己的值；price 用數值型別，便於之後篩選和排序，庫存也使用數值，欄位型別應與寫入的資料保持一致。

建立集合可以用 curl 傳送 JSON：curl -X POST http://localhost:8108/collections -H ‘Content-Type: application/json’ -H ‘X-TYPESENSE-API-KEY: change-this-key’ -d ‘{“name”:”products”,”fields”:[{“name”:”name”,”type”:”string”},{“name”:”category”,”type”:”string”,”facet”:true},{“name”:”price”,”type”:”float”},{“name”:”in_stock”,”type”:”bool”}]}’。這裡 category 開啟 facet，後續可按類別彙總或篩選；建集合成功後，服務會返回集合定義。

接下來新增一條商品文件。每條記錄都需要唯一的 id，下面用 p001；其他欄位名稱和資料型別必須與集合定義一致。把請求發到 documents 端點即可寫入，成功時會返回已建立的文件資訊。實際匯入大量商品時，可使用批次匯入介面，並檢查每行的處理結果，避免個別格式錯誤被忽略。

curl -X POST http://localhost:8108/collections/products/documents -H ‘Content-Type: application/json’ -H ‘X-TYPESENSE-API-KEY: change-this-key’ -d ‘{“id”:”p001″,”name”:”輕便通勤雙肩包”,”category”:”揹包”,”price”:299.0,”in_stock”:true}’。再用類似方式寫入其他商品，就完成了最小資料集。商品圖片地址等只用於結果展示、不參與搜尋或篩選的內容，可以作為額外欄位儲存，避免不必要地建立索引。

配置欄位和搜尋引數

設計欄位時，先區分哪些內容要全文搜尋、哪些用於過濾或展示。名稱、品牌、描述通常適合字串搜尋；價格適合數值欄位，類別適合開啟 facet。集合欄位一旦設計不合適，調整可能需要更新 schema 或重新整理索引，因此建議先拿少量真實資料驗證，並讓所有文件使用一致的資料格式。

• 搜尋欄位：在 query_by 中寫入可檢索欄位，例如 name；多個欄位用逗號分隔。
• 篩選欄位：用 filter_by 限定條件，例如 category:=揹包 或 price:100..500。
• 結果數量：用 per_page 控制每頁返回條數，按頁面設計調整。
• 訪問金鑰：服務端管理金鑰不要放進公開網頁，前端應使用權限受限的搜尋金鑰。

第三步：執行搜尋查詢

集合和文件準備好後，向 products 搜尋端點傳送 GET 請求。q 是使用者輸入的關鍵詞，query_by 指定搜尋欄位；如果想只看在售且價格在 100 到 500 之間的揹包，可加篩選引數。查詢引數需要進行 URL 編碼，避免空格、中文或特殊符號造成請求錯誤。試試搜尋“通勤包”，觀察返回的匹配文件。

curl -G ‘http://localhost:8108/collections/products/documents/search’ –data-urlencode ‘q=通勤包’ –data-urlencode ‘query_by=name’ –data-urlencode ‘filter_by=category:=揹包 && price:100..500 && in_stock:true’ –data-urlencode ‘per_page=10’ -H ‘X-TYPESENSE-API-KEY: change-this-key’。響應中的 hits 包含匹配商品及相關資訊。前端可讀取這些結果渲染列表，並在輸入變化時發起查詢；可加短暫防抖，減少連續請求。

上線前建議根據真實查詢除錯 query_by、排序和篩選條件，並限制搜尋金鑰的權限。若團隊不想自行維護搜尋伺服器，也可以瞭解火山引擎等國內服務選項；潤滅整理的相關入口是volcengine.cgref.cn。無論選自建還是託管方案，都先用樣例資料驗證響應速度、欄位能力和運維成本，再決定部署方式。