feat: backup architecture docs, source code, and scripts
This commit is contained in:
Warren
187
docs_v1.0/IMPLEMENTATION/SYNONYM_CONFIGURATION.md
Normal file
187
docs_v1.0/IMPLEMENTATION/SYNONYM_CONFIGURATION.md
Normal file
@@ -0,0 +1,187 @@
|
||||
# 同義詞配置指南
|
||||
|
||||
## 概述
|
||||
|
||||
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`
|
||||
Reference in New Issue
Block a user