# 同義詞配置指南

## 概述

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

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

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

## 配置方法

### 1. 創建同義詞 JSON 檔案

同義詞檔案為標準 JSON 格式，鍵值對結構：
```json
{
  "原始詞語": ["同義詞1", "同義詞2", "同義詞3"],
  "電腦": ["計算機", "微机", "筆記本"],
  "工作": ["任務", "作業", "職責"],
  "檔案": ["文件", "文檔", "資料"]
}
```

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

### 2. 環境變量配置

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

#### 方式一：單一檔案（推薦）
```bash
export MOMENTRY_SYNONYM_FILE=/path/to/your/synonyms.json
```

#### 方式二：多個檔案（後面的檔案會覆蓋前面的）
```bash
export MOMENTRY_SYNONYM_FILES=/path/to/base.json,/path/to/domain.json
```

### 3. 開發環境設置

在 `.env.development` 或 `.env` 檔案中添加：
```bash
# 同義詞配置文件（可選）
# 取消註釋並設置為您的同義詞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`)
```json
{
  "電腦": ["計算機", "微机"],
  "視頻": ["影片", "錄像"],
  "分析": ["解析", "剖析"],
  "系統": ["體系", "架構"],
  "用戶": ["使用者", "客戶"],
  "數據": ["資料", "資訊"],
  "網絡": ["網路", "互聯網"],
  "檔案": ["文件", "文檔"],
  "團體": ["組織", "團隊"],
  "工作": ["任務", "作業"]
}
```

### 查詢擴展示例

| 原始查詢 | 擴展後查詢 | 說明 |
|---------|-----------|------|
| `電腦` | `(電腦 | 計算機 | 微机 | 筆記本)` | 單一詞語擴展 |
| `電腦 工作` | `(電腦 | 計算機 | 微机) & (工作 | 任務 | 作業)` | 多詞語擴展 |
| `視頻分析` | `(視頻 | 影片 | 錄像) & (分析 | 解析 | 剖析)` | 連續詞語擴展 |
| `檔案系統` | `(檔案 | 文件 | 文檔) & (系統 | 體系 | 架構)` | 複合詞擴展 |

### API 使用

**BM25 搜索端點**：
```bash
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 搜索端點**：
```bash
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
```

### 測試擴展功能
使用內建測試工具：
```bash
cargo run --bin test_synonym_expansion
```

### 手動測試
創建測試程式檢查擴展結果：
```rust
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`