momentry_core/docs_v1.0/IMPLEMENTATION/SYNONYM_CONFIGURATION.md

同義詞配置指南

概述

Momentry Core 支持中文查詢的同義詞擴展功能，可將用戶查詢中的詞語自動擴展為其同義詞，提升搜索召回率。

重要：系統不提供預設同義詞資料集。為了避免版權問題，您需要提供自己的同義詞 JSON 檔案。系統提供擴展機制和示例檔案，但不會自動加載任何同義詞資料。

主要特性：

• 繁簡體中文轉換：自動將簡體中文查詢轉換為繁體中文（假設資料庫儲存繁體中文）
• 同義詞擴展：將查詢詞語擴展為多個同義詞，使用 OR 邏輯連接
• 智能分詞：對中文文本進行分詞處理，支援混合查詢
• 多檔案支持：可從多個 JSON 檔案加載同義詞映射

配置方法

1. 創建同義詞 JSON 檔案

同義詞檔案為標準 JSON 格式，鍵值對結構：

{
  "原始詞語": ["同義詞1", "同義詞2", "同義詞3"],
  "電腦": ["計算機", "微机", "筆記本"],
  "工作": ["任務", "作業", "職責"],
  "檔案": ["文件", "文檔", "資料"]
}

注意事項：

• 詞語需為繁體中文（系統會自動轉換簡體查詢）
• 同義詞列表可包含多個詞語
• 支援單一詞語或多字詞語

2. 環境變量配置

有兩種方式配置同義詞檔案：

方式一：單一檔案（推薦）

export MOMENTRY_SYNONYM_FILE=/path/to/your/synonyms.json

方式二：多個檔案（後面的檔案會覆蓋前面的）

export MOMENTRY_SYNONYM_FILES=/path/to/base.json,/path/to/domain.json

3. 開發環境設置

在 .env.development 或 .env 檔案中添加：

# 同義詞配置文件（可選）
# 取消註釋並設置為您的同義詞JSON檔案路徑以啟用同義詞擴展
MOMENTRY_SYNONYM_FILE=/Users/accusys/momentry_core_0.1/data/synonyms.json

# 多個同義詞檔案（逗號分隔），會覆蓋 MOMENTRY_SYNONYM_FILE
# MOMENTRY_SYNONYM_FILES=/path/to/first.json,/path/to/second.json

使用示例

示例同義詞檔案 (docs/examples/custom_synonyms.json)

{
  "電腦": ["計算機", "微机"],
  "視頻": ["影片", "錄像"],
  "分析": ["解析", "剖析"],
  "系統": ["體系", "架構"],
  "用戶": ["使用者", "客戶"],
  "數據": ["資料", "資訊"],
  "網絡": ["網路", "互聯網"],
  "檔案": ["文件", "文檔"],
  "團體": ["組織", "團隊"],
  "工作": ["任務", "作業"]
}

查詢擴展示例

原始查詢	擴展後查詢	說明
電腦	`(電腦	計算機
電腦 工作	`(電腦	計算機
視頻分析	`(視頻	影片
檔案系統	`(檔案	文件

API 使用

BM25 搜索端點：

curl -X POST http://localhost:3003/api/v1/search/bm25 \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "電腦工作", "limit": 10}'

n8n 搜索端點：

curl -X POST http://localhost:3003/api/v1/n8n/search/bm25 \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "視頻檔案", "limit": 5}'

技術細節

擴展邏輯

1. 繁簡轉換：使用 OpenCC 將簡體中文轉換為繁體
2. 同義詞查找：在加載的映射中查找匹配詞語
3. 查詢重構：將原始詞語替換為 (原始詞語 OR 同義詞1 OR 同義詞2 ...)
4. 分詞處理：對未匹配部分進行中文分詞
5. TSQUERY 生成：生成 PostgreSQL 全文搜索查詢語法

分詞處理

• 使用 Jieba 分詞器進行中文分詞
• 分詞結果用空格分隔，例如："電腦工作" → "電 腦 工作"
• 分詞後每個部分都會加上前綴搜索符號 (:*)

性能考慮

• 同義詞映射在應用啟動時加載並緩存
• 擴展操作在內存中進行，性能影響最小
• 支援大量同義詞映射（數千條）

除錯與測試

檢查同義詞加載

查看應用日誌中是否有以下訊息：

Loaded synonym expander from /path/to/synonyms.json

測試擴展功能

使用內建測試工具：

cargo run --bin test_synonym_expansion

手動測試

創建測試程式檢查擴展結果：

use momentry_core::core::text::global_synonym_expander;

let expander = global_synonym_expander();
println!("擴展 '電腦': {}", expander.expand_word("電腦"));
println!("擴展 '電腦 工作': {}", expander.expand_query("電腦 工作"));

注意事項

1. 詞語格式：確保同義詞檔案中的詞語為繁體中文
2. 檔案編碼：使用 UTF-8 編碼保存 JSON 檔案
3. 重啟需求：修改同義詞檔案後需要重啟應用才能生效
4. 版本兼容：同義詞功能需 Momentry Core 0.1.0 以上版本
5. 版權注意：請使用自創或已獲授權的同義詞資料，避免使用受版權保護的詞庫

進階配置

領域特定同義詞

為不同領域創建專用同義詞檔案：

• technical_terms.json - 技術術語
• business_terms.json - 商業術語
• industry_terms.json - 行業術語

通過 MOMENTRY_SYNONYM_FILES 加載多個檔案。

動態更新（計劃中）

未來版本將支援：

• 熱重載同義詞檔案
• API 端點管理同義詞
• 用戶自定義同義詞

---

附錄

示例同義詞檔案

• 基礎示例：docs/examples/custom_synonyms.json
• 舊示例（僅供參考）：data/synonyms.json
• 領域示例（僅供參考）：data/domain_synonyms.json

注意：這些檔案僅作為格式示例，系統不會自動加載。您需要設置 MOMENTRY_SYNONYM_FILE 環境變量指向您自己的同義詞檔案。

相關程式檔案

• 同義詞擴展器：src/core/text/synonym_expander.rs
• 繁簡轉換：src/core/text/synonym.rs
• 分詞器：src/core/text/tokenizer.rs
• PostgreSQL 整合：src/core/db/postgres_db.rs