---
document_type: "installation_guide"
service: "MOMENTRY_CORE"
title: "同義詞林安裝指南 (客戶自行下載)"
date: "2026-03-30"
version: "V1.0"
status: "active"
owner: "Warren"
created_by: "OpenCode"
tags:
  - "synonym"
  - "semantic-search"
  - "nlp"
  - "language"
ai_query_hints:
  - "如何安裝同義詞林數據？"
  - "同義詞林數據格式為何？"
  - "如何在搜尋中使用同義詞擴展？"
---

# 同義詞林安裝指南 (客戶自行下載)

| 項目 | 內容 |
|------|------|
| 建立者 | OpenCode |
| 建立時間 | 2026-03-30 |
| 文件版本 | V1.0 |

---

## 版本歷史

| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-03-30 | 創建文件 | OpenCode | - |

---

## 概述

本文檔說明如何為 Momentry Core 系統配置同義詞林功能，以提升中文搜索的召回率。

**重要聲明**：Momentry Core 不提供任何預設同義詞資料。為了避免著作權問題，您需要：
1. **自行尋找合法的同義詞林資源**
2. **確保擁有使用權或符合授權條款**
3. **自行轉換為系統可用的格式**

系統僅提供格式規範和配置方法，不包含任何同義詞資料。

---

## 當前狀態

| 項目 | 狀態 |
|------|------|
| 同義詞功能 | ✅ 已支援 (v0.1.0+) |
| 預設同義詞 | ❌ 不提供 (需客戶自行準備) |
| 格式支援 | ✅ JSON 格式 |
| 繁簡轉換 | ✅ 自動支援 |
| 智能分詞 | ✅ 已整合 |

---

## 安裝步驟

### Step 1: 尋找合法的同義詞林資源

您需要自行尋找合法的中文同義詞林資源。以下是一些**可能的來源方向**（請自行確認授權）：

#### 開源資源（需確認授權）
```bash
# 示例：可能的開源同義詞庫（需自行確認最新狀態）
# 1. Open Chinese Convert (OpenCC) 詞庫
# 2. 中文詞彙網路 (Chinese WordNet)
# 3. 各大學語言資源中心
# 4. GitHub 上的開源中文詞庫專案

# 重要：使用前請仔細閱讀授權協議
# 確保符合商業使用條款（如適用）
```

#### 商業資源
```bash
# 1. 購買商業詞庫授權
# 2. 使用學術機構提供的資源
# 3. 自行建立同義詞映射
```

#### 自行建立
```bash
# 最安全的方式：根據您的領域知識自行建立
# 優點：完全符合需求，無版權問題
# 缺點：需要時間和領域知識
```

---

### Step 2: 下載並準備同義詞資料

假設您已獲得合法的同義詞林資源，需要將其轉換為 Momentry 可用的格式。

#### 格式要求
同義詞檔案必須是 **JSON 格式**，結構如下：
```json
{
  "原始詞語": ["同義詞1", "同義詞2", "同義詞3"],
  "電腦": ["計算機", "微机", "筆記本"],
  "工作": ["任務", "作業", "職責"],
  "檔案": ["文件", "文檔", "資料"]
}
```

#### 轉換腳本示例
如果您下載的資源是其他格式（如 TXT、CSV），可以使用以下 Python 腳本轉換：

```python
#!/usr/bin/env python3
"""
同義詞林格式轉換腳本
將其他格式轉換為 Momentry 可用的 JSON 格式
"""

import json
import sys
from pathlib import Path

def convert_txt_to_json(input_file: str, output_file: str):
    """
    將 TXT 格式轉換為 JSON 格式
    TXT 格式示例：
    電腦 計算機 微机 筆記本
    工作 任務 作業 職責
    """
    synonym_map = {}
    
    with open(input_file, 'r', encoding='utf-8') as f:
        for line in f:
            line = line.strip()
            if not line:
                continue
                
            words = line.split()
            if len(words) >= 2:
                main_word = words[0]
                synonyms = words[1:]
                synonym_map[main_word] = synonyms
    
    with open(output_file, 'w', encoding='utf-8') as f:
        json.dump(synonym_map, f, ensure_ascii=False, indent=2)
    
    print(f"轉換完成：{len(synonym_map)} 條同義詞映射")
    return synonym_map

def convert_csv_to_json(input_file: str, output_file: str):
    """
    將 CSV 格式轉換為 JSON 格式
    CSV 格式示例：
    電腦,計算機,微机,筆記本
    工作,任務,作業,職責
    """
    import csv
    
    synonym_map = {}
    
    with open(input_file, 'r', encoding='utf-8') as f:
        reader = csv.reader(f)
        for row in reader:
            if len(row) >= 2:
                main_word = row[0].strip()
                synonyms = [word.strip() for word in row[1:] if word.strip()]
                if main_word and synonyms:
                    synonym_map[main_word] = synonyms
    
    with open(output_file, 'w', encoding='utf-8') as f:
        json.dump(synonym_map, f, ensure_ascii=False, indent=2)
    
    print(f"轉換完成：{len(synonym_map)} 條同義詞映射")
    return synonym_map

if __name__ == "__main__":
    if len(sys.argv) != 4:
        print("用法: python convert_synonyms.py <輸入檔案> <輸出檔案> <格式: txt|csv>")
        print("示例: python convert_synonyms.py synonyms.txt synonyms.json txt")
        sys.exit(1)
    
    input_file = sys.argv[1]
    output_file = sys.argv[2]
    format_type = sys.argv[3].lower()
    
    if format_type == 'txt':
        convert_txt_to_json(input_file, output_file)
    elif format_type == 'csv':
        convert_csv_to_json(input_file, output_file)
    else:
        print(f"不支援的格式: {format_type}")
        sys.exit(1)
```

#### 執行轉換
```bash
# 安裝 Python 依賴（如果需要）
pip install pandas

# 執行轉換腳本
python convert_synonyms.py your_synonyms.txt synonyms.json txt
```

---

### Step 3: 驗證同義詞檔案

轉換完成後，驗證 JSON 檔案格式：

```bash
# 檢查 JSON 格式是否正確
python3 -m json.tool synonyms.json > /dev/null && echo "✅ JSON 格式正確"

# 查看前幾條記錄
head -20 synonyms.json

# 統計詞條數量
python3 -c "import json; data=json.load(open('synonyms.json')); print(f'詞條數量: {len(data)}')"
```

#### 建立測試檔案
如果您還沒有同義詞資源，可以先建立一個小型測試檔案：

```bash
# 建立測試用同義詞檔案
cat > test_synonyms.json << 'EOF'
{
  "電腦": ["計算機", "微机"],
  "視頻": ["影片", "錄像"],
  "分析": ["解析", "剖析"],
  "系統": ["體系", "架構"],
  "用戶": ["使用者", "客戶"]
}
EOF
```

---

### Step 4: 配置 Momentry Core

#### 方式一：環境變量配置（推薦）

```bash
# 設置單一同義詞檔案
export MOMENTRY_SYNONYM_FILE=/path/to/your/synonyms.json

# 或設置多個同義詞檔案（後面的會覆蓋前面的）
export MOMENTRY_SYNONYM_FILES=/path/to/base.json,/path/to/domain.json
```

#### 方式二：修改 .env 檔案

編輯 `.env` 或 `.env.development` 檔案：

```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
```

#### 方式三：啟動時指定

```bash
# 啟動服務時指定同義詞檔案
MOMENTRY_SYNONYM_FILE=/path/to/synonyms.json cargo run --bin momentry -- server

# 使用多檔案配置
MOMENTRY_SYNONYM_FILES=/path/to/base.json,/path/to/tech.json cargo run --bin momentry -- server
```

---

### Step 5: 測試同義詞功能

#### 使用內建測試工具
```bash
# 運行同義詞擴展測試
cargo run --bin test_synonym_expansion

# 預期輸出示例：
# === 同義詞擴展測試 ===
# 
# 查詢: 電腦
#   繁簡轉換: 電腦 (無變化)
#   同義詞擴展: (電腦 | 計算機 | 微机)
#   最終查詢: (電腦 | 計算機 | 微机)
```

#### 手動測試
建立測試腳本：

```bash
cat > test_synonym.sh << 'EOF'
#!/bin/bash
echo "=== 同義詞功能測試 ==="
echo ""

# 測試查詢擴展
QUERIES=("電腦" "電腦工作" "視頻分析" "檔案系統")

for query in "${QUERIES[@]}"; do
  echo "查詢: $query"
  
  # 模擬擴展過程（實際由系統自動處理）
  case $query in
    "電腦")
      echo "  擴展後: (電腦 | 計算機 | 微机)"
      ;;
    "電腦工作")
      echo "  擴展後: (電腦 | 計算機 | 微机) & (工作 | 任務 | 作業)"
      ;;
    "視頻分析")
      echo "  擴展後: (視頻 | 影片 | 錄像) & (分析 | 解析 | 剖析)"
      ;;
    "檔案系統")
      echo "  擴展後: (檔案 | 文件 | 文檔) & (系統 | 體系 | 架構)"
      ;;
  esac
  echo ""
done
EOF

chmod +x test_synonym.sh
./test_synonym.sh
```

#### API 測試
```bash
# 測試搜索 API（需先啟動服務）
curl -X POST http://localhost:3002/api/v1/search \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "電腦工作", "limit": 5}'

# 測試 n8n 搜索 API
curl -X POST http://localhost:3002/api/v1/n8n/search \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "視頻檔案", "limit": 5}'
```

---

## 卸載步驟

### Step 1: 移除同義詞配置

```bash
# 從環境變量中移除
unset MOMENTRY_SYNONYM_FILE
unset MOMENTRY_SYNONYM_FILES

# 或從 .env 檔案中註釋掉相關配置
sed -i '' 's/^MOMENTRY_SYNONYM_FILE/# MOMENTRY_SYNONYM_FILE/' .env
sed -i '' 's/^MOMENTRY_SYNONYM_FILES/# MOMENTRY_SYNONYM_FILES/' .env
```

### Step 2: 重啟服務

```bash
# 重啟 Momentry Core 服務
sudo launchctl unload /Library/LaunchDaemons/com.momentry.api.plist
sudo launchctl load /Library/LaunchDaemons/com.momentry.api.plist
```

### Step 3: 驗證卸載

```bash
# 檢查日誌確認同義詞功能已禁用
tail -f /Users/accusys/momentry/log/momentry_api.log | grep -i synonym

# 預期：沒有 "Loaded synonym expander" 訊息
```

---

## 自定義同義詞編輯指南

### 編輯現有同義詞檔案

#### 方法一：直接編輯 JSON 檔案

```bash
# 使用文字編輯器編輯同義詞檔案
nano /path/to/your/synonyms.json

# 或使用 vim
vim /path/to/your/synonyms.json

# 或使用 Visual Studio Code
code /path/to/your/synonyms.json
```

#### 方法二：使用 Python 腳本編輯

```bash
# 建立編輯腳本
cat > edit_synonyms.py << 'EOF'
#!/usr/bin/env python3
import json
import sys

def add_synonyms(input_file, output_file=None):
    """添加新的同義詞到檔案"""
    if output_file is None:
        output_file = input_file
    
    # 讀取現有同義詞
    with open(input_file, 'r', encoding='utf-8') as f:
        synonyms = json.load(f)
    
    # 添加新的同義詞（範例）
    new_synonyms = {
        "人工智能": ["AI", "人工智慧", "機器智能"],
        "大數據": ["巨量資料", "海量數據", "Big Data"],
        "雲計算": ["雲端計算", "雲服務", "Cloud Computing"],
        "物聯網": ["IoT", "互聯網", "智能聯網"],
        "區塊鏈": ["Blockchain", "分散式帳本", "鏈式結構"]
    }
    
    # 合併同義詞（新詞覆蓋舊詞）
    synonyms.update(new_synonyms)
    
    # 寫回檔案
    with open(output_file, 'w', encoding='utf-8') as f:
        json.dump(synonyms, f, ensure_ascii=False, indent=2)
    
    print(f"已添加 {len(new_synonyms)} 個新詞條")
    print(f"總詞條數: {len(synonyms)}")

def remove_synonyms(input_file, words_to_remove, output_file=None):
    """從檔案中移除指定詞條"""
    if output_file is None:
        output_file = input_file
    
    with open(input_file, 'r', encoding='utf-8') as f:
        synonyms = json.load(f)
    
    removed_count = 0
    for word in words_to_remove:
        if word in synonyms:
            del synonyms[word]
            removed_count += 1
    
    with open(output_file, 'w', encoding='utf-8') as f:
        json.dump(synonyms, f, ensure_ascii=False, indent=2)
    
    print(f"已移除 {removed_count} 個詞條")
    print(f"剩餘詞條數: {len(synonyms)}")

def search_synonyms(input_file, keyword):
    """搜索包含關鍵詞的同義詞"""
    with open(input_file, 'r', encoding='utf-8') as f:
        synonyms = json.load(f)
    
    results = {}
    for word, syn_list in synonyms.items():
        if keyword in word or any(keyword in syn for syn in syn_list):
            results[word] = syn_list
    
    print(f"找到 {len(results)} 個相關詞條:")
    for word, syn_list in results.items():
        print(f"  {word}: {', '.join(syn_list)}")

if __name__ == "__main__":
    if len(sys.argv) < 3:
        print("用法:")
        print("  python3 edit_synonyms.py add <input_file> [output_file]")
        print("  python3 edit_synonyms.py remove <input_file> <word1,word2,...> [output_file]")
        print("  python3 edit_synonyms.py search <input_file> <keyword>")
        sys.exit(1)
    
    action = sys.argv[1]
    input_file = sys.argv[2]
    
    if action == "add":
        output_file = sys.argv[3] if len(sys.argv) > 3 else input_file
        add_synonyms(input_file, output_file)
    elif action == "remove":
        words = sys.argv[3].split(',')
        output_file = sys.argv[4] if len(sys.argv) > 4 else input_file
        remove_synonyms(input_file, words, output_file)
    elif action == "search":
        keyword = sys.argv[3]
        search_synonyms(input_file, keyword)
    else:
        print(f"未知操作: {action}")
EOF

# 使用腳本
python3 edit_synonyms.py add synonyms.json
python3 edit_synonyms.py remove synonyms.json "過時詞語,不常用詞"
python3 edit_synonyms.py search synonyms.json "科技"
```

### 建立領域專用同義詞檔案

#### 步驟 1: 建立領域專用檔案

```bash
# 建立科技領域同義詞
cat > tech_synonyms.json << 'EOF'
{
  "編程": ["編程", "寫程式", "開發", "編碼"],
  "算法": ["演算法", "計算方法", "解決方案"],
  "數據庫": ["資料庫", "DB", "存儲系統"],
  "服務器": ["伺服器", "主機", "服務端"],
  "客戶端": ["用戶端", "前端", "應用端"],
  "API": ["應用程式介面", "接口", "服務接口"],
  "微服務": ["微架構", "分散式服務", "服務化架構"],
  "容器": ["Container", "Docker", "隔離環境"],
  "虛擬機": ["VM", "虛擬環境", "模擬機器"],
  "雲原生": ["Cloud Native", "雲端原生", "雲優化"]
}
EOF

# 建立商業領域同義詞
cat > business_synonyms.json << 'EOF'
{
  "營銷": ["行銷", "市場推廣", "銷售推廣"],
  "客戶": ["顧客", "用戶", "消費者", "買家"],
  "產品": ["商品", "貨品", "物品", "製品"],
  "服務": ["服務項目", "服務內容", "服務產品"],
  "價格": ["價錢", "費用", "成本", "報價"],
  "質量": ["品質", "質素", "水準", "標準"],
  "品牌": ["商標", "牌子", "企業形象"],
  "市場": ["市場環境", "行業", "領域", "產業"],
  "競爭": ["競爭對手", "競品", "同行", "同業"],
  "創新": ["創意", "革新", "改革", "突破"]
}
EOF
```

#### 步驟 2: 合併多個同義詞檔案

```bash
# 建立合併腳本
cat > merge_synonyms.py << 'EOF'
#!/usr/bin/env python3
import json
import sys

def merge_synonyms(files, output_file):
    """合併多個同義詞檔案"""
    merged = {}
    
    for file in files:
        try:
            with open(file, 'r', encoding='utf-8') as f:
                data = json.load(f)
                # 合併策略：後面的檔案覆蓋前面的
                merged.update(data)
                print(f"已合併: {file} ({len(data)} 詞條)")
        except Exception as e:
            print(f"警告: 無法讀取 {file}: {e}")
    
    # 寫入合併結果
    with open(output_file, 'w', encoding='utf-8') as f:
        json.dump(merged, f, ensure_ascii=False, indent=2)
    
    print(f"\n合併完成:")
    print(f"  輸入檔案: {len(files)} 個")
    print(f"  輸出檔案: {output_file}")
    print(f"  總詞條數: {len(merged)}")

if __name__ == "__main__":
    if len(sys.argv) < 3:
        print("用法: python3 merge_synonyms.py <output_file> <input_file1> <input_file2> ...")
        sys.exit(1)
    
    output_file = sys.argv[1]
    input_files = sys.argv[2:]
    
    merge_synonyms(input_files, output_file)
EOF

# 合併檔案
python3 merge_synonyms.py combined_synonyms.json base_synonyms.json tech_synonyms.json business_synonyms.json
```

### 同義詞管理最佳實踐

#### 1. 版本控制

```bash
# 建立版本目錄結構
mkdir -p synonyms/versions
mkdir -p synonyms/backups

# 備份當前版本
cp synonyms.json synonyms/backups/synonyms_$(date +%Y%m%d_%H%M%S).json

# 建立版本標記
echo "版本: $(date +%Y-%m-%d %H:%M:%S)" > synonyms/versions/CHANGELOG.md
echo "詞條數: $(python3 -c "import json; print(len(json.load(open('synonyms.json'))))")" >> synonyms/versions/CHANGELOG.md
```

#### 2. 質量檢查

```bash
# 檢查重複詞條
cat > check_duplicates.py << 'EOF'
#!/usr/bin/env python3
import json
import sys

def check_duplicates(file_path):
    with open(file_path, 'r', encoding='utf-8') as f:
        synonyms = json.load(f)
    
    # 檢查重複的同義詞
    all_synonyms = set()
    duplicates = []
    
    for word, syn_list in synonyms.items():
        for syn in syn_list:
            if syn in all_synonyms:
                duplicates.append((word, syn))
            all_synonyms.add(syn)
    
    if duplicates:
        print(f"發現 {len(duplicates)} 個重複同義詞:")
        for word, syn in duplicates:
            print(f"  '{syn}' 在詞條 '{word}' 中重複出現")
    else:
        print("沒有發現重複同義詞")
    
    # 檢查循環引用
    cycles = []
    for word, syn_list in synonyms.items():
        for syn in syn_list:
            if syn in synonyms and word in synonyms.get(syn, []):
                cycles.append((word, syn))
    
    if cycles:
        print(f"\n發現 {len(cycles)} 個循環引用:")
        for word, syn in cycles:
            print(f"  '{word}' ↔ '{syn}'")
    else:
        print("沒有發現循環引用")

if __name__ == "__main__":
    if len(sys.argv) != 2:
        print("用法: python3 check_duplicates.py <synonyms.json>")
        sys.exit(1)
    
    check_duplicates(sys.argv[1])
EOF

python3 check_duplicates.py synonyms.json
```

#### 3. 性能優化

```bash
# 壓縮同義詞檔案（移除空白）
python3 -c "import json; data=json.load(open('synonyms.json')); json.dump(data, open('synonyms.min.json', 'w'), ensure_ascii=False, separators=(',', ':'))"

# 統計詞條分佈
cat > analyze_synonyms.py << 'EOF'
#!/usr/bin/env python3
import json
import sys
from collections import Counter

def analyze_synonyms(file_path):
    with open(file_path, 'r', encoding='utf-8') as f:
        synonyms = json.load(f)
    
    total_words = len(synonyms)
    total_synonyms = sum(len(syn_list) for syn_list in synonyms.values())
    
    print(f"統計分析:")
    print(f"  主詞數量: {total_words}")
    print(f"  同義詞總數: {total_synonyms}")
    print(f"  平均同義詞數: {total_synonyms/total_words:.2f}")
    
    # 同義詞數量分佈
    syn_counts = Counter(len(syn_list) for syn_list in synonyms.values())
    print(f"\n同義詞數量分佈:")
    for count, freq in sorted(syn_counts.items()):
        print(f"  {count}個同義詞: {freq}個詞條 ({freq/total_words*100:.1f}%)")
    
    # 最長同義詞列表
    longest = max(synonyms.items(), key=lambda x: len(x[1]))
    print(f"\n最長同義詞列表:")
    print(f"  '{longest[0]}': {', '.join(longest[1])}")
    print(f"  同義詞數量: {len(longest[1])}")

if __name__ == "__main__":
    if len(sys.argv) != 2:
        print("用法: python3 analyze_synonyms.py <synonyms.json>")
        sys.exit(1)
    
    analyze_synonyms(sys.argv[1])
EOF

python3 analyze_synonyms.py synonyms.json
```

### 自動化更新流程

```bash
# 建立自動更新腳本
cat > update_synonyms.sh << 'EOF'
#!/bin/bash

# 配置
SYNONYM_FILE="/path/to/your/synonyms.json"
BACKUP_DIR="/path/to/backups"
LOG_FILE="/var/log/synonym_updates.log"

# 記錄日誌
log() {
    echo "[$(date '+%Y-%m-%d %H:%M:%S')] $1" >> "$LOG_FILE"
}

# 備份當前檔案
backup_current() {
    local timestamp=$(date +%Y%m%d_%H%M%S)
    local backup_file="$BACKUP_DIR/synonyms_$timestamp.json"
    
    cp "$SYNONYM_FILE" "$backup_file"
    log "備份完成: $backup_file"
    echo "備份完成: $backup_file"
}

# 檢查新版本
check_for_updates() {
    # 這裡可以添加檢查遠端更新的邏輯
    # 例如：從 Git 倉庫拉取、從 API 獲取等
    echo "檢查更新..."
    # 返回 0 表示有更新，1 表示無更新
    return 1  # 暫時設為無更新
}

# 應用更新
apply_update() {
    local update_file="$1"
    
    if [ ! -f "$update_file" ]; then
        log "錯誤: 更新檔案不存在: $update_file"
        return 1
    fi
    
    # 驗證 JSON 格式
    if ! python3 -m json.tool "$update_file" > /dev/null 2>&1; then
        log "錯誤: 更新檔案格式無效"
        return 1
    fi
    
    # 應用更新
    cp "$update_file" "$SYNONYM_FILE"
    log "更新應用完成"
    
    # 重啟服務（如果需要）
    # sudo systemctl restart momentry-api
}

# 主流程
main() {
    log "開始同義詞更新流程"
    
    # 備份當前檔案
    backup_current
    
    # 檢查更新
    if check_for_updates; then
        log "發現新版本，開始更新"
        # 這裡可以下載或生成更新檔案
        # apply_update "/path/to/update.json"
    else
        log "無可用更新"
    fi
    
    log "更新流程完成"
}

# 執行
main
EOF

chmod +x update_synonyms.sh

# 添加到定時任務（每天凌晨3點檢查更新）
# crontab -e
# 0 3 * * * /path/to/update_synonyms.sh

---

## 多語系同義詞庫解決方案

### 概述

Momentry Core 支援多語系同義詞庫配置，允許您為不同語言建立專用的同義詞映射。系統支援以下多語系方案：

1. **單一語言同義詞庫**：傳統的中文同義詞映射
2. **跨語言同義詞庫**：不同語言之間的詞語映射（如中英對照）
3. **混合語言同義詞庫**：單一檔案中包含多種語言映射
4. **語言專用同義詞庫**：按語言分開的多個檔案

### 方案一：跨語言同義詞庫（中英對照）

#### 建立跨語言同義詞檔案

```bash
# 建立中英對照同義詞庫
cat > multilingual_synonyms.json << 'EOF'
{
  "//": "跨語言同義詞庫 - 中英對照",
  "//": "格式: 中文詞語 -> [英文同義詞, 其他中文同義詞, ...]",
  "電腦": ["computer", "計算機", "微机"],
  "視頻": ["video", "影片", "錄像"],
  "分析": ["analyze", "解析", "剖析"],
  "系統": ["system", "體系", "架構"],
  "用戶": ["user", "使用者", "客戶"],
  "數據": ["data", "資料", "資訊"],
  "網絡": ["network", "網路", "互聯網"],
  "檔案": ["file", "文件", "文檔"],
  "人工智能": ["AI", "artificial intelligence", "人工智慧", "機器智能"],
  "大數據": ["big data", "巨量資料", "海量數據"],
  "雲計算": ["cloud computing", "雲端計算", "雲服務"],
  "物聯網": ["IoT", "internet of things", "互聯網", "智能聯網"],
  "區塊鏈": ["blockchain", "分散式帳本", "鏈式結構"],
  "機器學習": ["machine learning", "ML", "機械學習"],
  "深度學習": ["deep learning", "DL", "深度神經網絡"],
  "自然語言處理": ["NLP", "natural language processing", "自然語言理解"],
  "計算機視覺": ["computer vision", "CV", "機器視覺"],
  "推薦系統": ["recommendation system", "推薦算法", "個性化推薦"]
}
EOF
```

#### 建立語言檢測腳本

```bash
# 建立語言檢測工具
cat > detect_language.py << 'EOF'
#!/usr/bin/env python3
import re
import sys

def detect_language(text):
    """簡單的語言檢測函數"""
    if not text:
        return "unknown"
    
    # 檢查是否包含中文字符
    if re.search(r'[\u4e00-\u9fff]', text):
        return "zh"
    
    # 檢查是否包含英文字母
    if re.search(r'[a-zA-Z]', text):
        # 檢查是否主要是英文
        english_chars = len(re.findall(r'[a-zA-Z]', text))
        total_chars = len(text)
        if english_chars / total_chars > 0.7:
            return "en"
    
    # 默認為中文
    return "zh"

def main():
    if len(sys.argv) != 2:
        print("用法: python3 detect_language.py <文本>")
        sys.exit(1)
    
    text = sys.argv[1]
    lang = detect_language(text)
    
    print(f"文本: {text}")
    print(f"檢測語言: {lang}")
    
    # 語言代碼對照表
    lang_map = {
        "zh": "中文",
        "en": "英文",
        "ja": "日文",
        "ko": "韓文"
    }
    
    print(f"語言名稱: {lang_map.get(lang, '未知')}")

if __name__ == "__main__":
    main()
EOF

# 測試語言檢測
python3 detect_language.py "電腦 computer"
python3 detect_language.py "hello world"
python3 detect_language.py "人工智能 AI"
```

### 方案二：語言專用同義詞庫

#### 建立各語言專用檔案

```bash
# 建立中文同義詞庫
cat > synonyms_zh.json << 'EOF'
{
  "//": "中文同義詞庫",
  "電腦": ["計算機", "微机"],
  "視頻": ["影片", "錄像"],
  "分析": ["解析", "剖析"],
  "系統": ["體系", "架構"],
  "用戶": ["使用者", "客戶"]
}
EOF

# 建立英文同義詞庫
cat > synonyms_en.json << 'EOF'
{
  "//": "English synonym database",
  "computer": ["PC", "machine", "device"],
  "video": ["movie", "film", "recording"],
  "analysis": ["examination", "study", "investigation"],
  "system": ["framework", "structure", "setup"],
  "user": ["client", "customer", "end-user"]
}
EOF

# 建立日文同義詞庫
cat > synonyms_ja.json << 'EOF'
{
  "//": "日本語類義語データベース",
  "コンピュータ": ["パソコン", "PC", "計算機"],
  "ビデオ": ["動画", "映像", "録画"],
  "分析": ["解析", "調査", "検討"],
  "システム": ["体系", "構造", "仕組み"],
  "ユーザー": ["利用者", "顧客", "エンドユーザー"]
}
EOF

# 建立韓文同義詞庫
cat > synonyms_ko.json << 'EOF'
{
  "//": "한국어 유의어 데이터베이스",
  "컴퓨터": ["PC", "계산기", "기계"],
  "비디오": ["동영상", "영상", "녹화"],
  "분석": ["해석", "조사", "검토"],
  "시스템": ["체계", "구조", "설정"],
  "사용자": ["이용자", "고객", "최종사용자"]
}
EOF
```

#### 建立語言路由配置

```bash
# 建立語言路由配置檔案
cat > language_routing.json << 'EOF'
{
  "//": "語言路由配置 - 根據查詢語言自動選擇對應的同義詞庫",
  "routing": {
    "zh": "/path/to/synonyms_zh.json",
    "en": "/path/to/synonyms_en.json",
    "ja": "/path/to/synonyms_ja.json",
    "ko": "/path/to/synonyms_ko.json"
  },
  "fallback": "/path/to/synonyms_zh.json",
  "multilingual_support": true,
  "auto_detect_language": true
}
EOF

# 建立語言路由腳本
cat > language_router.py << 'EOF'
#!/usr/bin/env python3
import json
import os
import sys
import re

class LanguageRouter:
    def __init__(self, config_file):
        with open(config_file, 'r', encoding='utf-8') as f:
            self.config = json.load(f)
    
    def detect_query_language(self, query):
        """檢測查詢語言的簡單實現"""
        # 檢查中文字符
        if re.search(r'[\u4e00-\u9fff]', query):
            return "zh"
        
        # 檢查日文字符
        if re.search(r'[\u3040-\u309f\u30a0-\u30ff]', query):  # 平假名和片假名
            return "ja"
        
        # 檢查韓文字符
        if re.search(r'[\uac00-\ud7af]', query):
            return "ko"
        
        # 默認為英文
        return "en"
    
    def get_synonym_file(self, query):
        """根據查詢獲取對應的同義詞檔案"""
        if not self.config.get("auto_detect_language", True):
            # 使用默認語言
            return self.config.get("fallback")
        
        lang = self.detect_query_language(query)
        routing = self.config.get("routing", {})
        
        return routing.get(lang, self.config.get("fallback"))
    
    def load_synonyms(self, query):
        """根據查詢加載對應的同義詞"""
        synonym_file = self.get_synonym_file(query)
        
        if not synonym_file or not os.path.exists(synonym_file):
            print(f"警告: 同義詞檔案不存在: {synonym_file}")
            return {}
        
        try:
            with open(synonym_file, 'r', encoding='utf-8') as f:
                return json.load(f)
        except Exception as e:
            print(f"錯誤: 無法加載同義詞檔案 {synonym_file}: {e}")
            return {}

def main():
    if len(sys.argv) != 3:
        print("用法: python3 language_router.py <config_file> <query>")
        sys.exit(1)
    
    config_file = sys.argv[1]
    query = sys.argv[2]
    
    router = LanguageRouter(config_file)
    synonym_file = router.get_synonym_file(query)
    synonyms = router.load_synonyms(query)
    
    print(f"查詢: {query}")
    print(f"檢測語言: {router.detect_query_language(query)}")
    print(f"選擇的同義詞檔案: {synonym_file}")
    print(f"加載的同義詞數量: {len(synonyms)}")
    
    # 顯示相關同義詞
    for word in query.split():
        if word in synonyms:
            print(f"  '{word}': {synonyms[word]}")

if __name__ == "__main__":
    main()
EOF

# 測試語言路由
python3 language_router.py language_routing.json "電腦 computer"
python3 language_router.py language_routing.json "hello world"
python3 language_router.py language_routing.json "コンピュータ ビデオ"
python3 language_router.py language_routing.json "컴퓨터 비디오"
```

### 方案三：混合語言同義詞庫（單一檔案）

#### 建立統一的多語系同義詞庫

```bash
# 建立統一的多語系同義詞庫
cat > unified_multilingual_synonyms.json << 'EOF'
{
  "//": "統一多語系同義詞庫",
  "//": "支援中文、英文、日文、韓文",
  "metadata": {
    "version": "1.0.0",
    "created": "2026-03-30",
    "languages": ["zh", "en", "ja", "ko"],
    "total_entries": 50
  },
  
  "synonyms": {
    "zh": {
      "電腦": ["計算機", "微机", "computer", "PC"],
      "視頻": ["影片", "錄像", "video", "movie"],
      "分析": ["解析", "剖析", "analyze", "examination"],
      "系統": ["體系", "架構", "system", "framework"],
      "用戶": ["使用者", "客戶", "user", "client"]
    },
    
    "en": {
      "computer": ["PC", "machine", "device", "計算機", "電腦"],
      "video": ["movie", "film", "recording", "影片", "視頻"],
      "analysis": ["examination", "study", "investigation", "解析", "分析"],
      "system": ["framework", "structure", "setup", "體系", "系統"],
      "user": ["client", "customer", "end-user", "使用者", "用戶"]
    },
    
    "ja": {
      "コンピュータ": ["パソコン", "PC", "計算機", "computer", "電腦"],
      "ビデオ": ["動画", "映像", "録画", "video", "視頻"],
      "分析": ["解析", "調査", "検討", "analysis", "分析"],
      "システム": ["体系", "構造", "仕組み", "system", "系統"],
      "ユーザー": ["利用者", "顧客", "エンドユーザー", "user", "用戶"]
    },
    
    "ko": {
      "컴퓨터": ["PC", "계산기", "기계", "computer", "電腦"],
      "비디오": ["동영상", "영상", "녹화", "video", "視頻"],
      "분석": ["해석", "조사", "검토", "analysis", "分析"],
      "시스템": ["체계", "구조", "설정", "system", "系統"],
      "사용자": ["이용자", "고객", "최종사용자", "user", "用戶"]
    }
  },
  
  "cross_language_mapping": {
    "computer": ["電腦", "計算機", "コンピュータ", "컴퓨터"],
    "video": ["視頻", "影片", "ビデオ", "비디오"],
    "analysis": ["分析", "解析", "分析", "분석"],
    "system": ["系統", "體系", "システム", "시스템"],
    "user": ["用戶", "使用者", "ユーザー", "사용자"]
  }
}
EOF
```

### 與 Momentry Core 整合

#### 配置多語系同義詞庫

```bash
# 更新 .env 檔案以支援多語系
cat >> .env << 'EOF'

# 多語系同義詞庫配置
# 選擇以下其中一種配置方式：

# 方式一：統一多語系同義詞庫（單一檔案）
MOMENTRY_SYNONYM_FILE=/etc/momentry/synonyms/unified_multilingual_synonyms.json

# 方式二：分離式多語系同義詞庫（多個檔案）
# MOMENTRY_SYNONYM_FILES=/etc/momentry/synonyms/synonyms_zh.json,/etc/momentry/synonyms/synonyms_en.json,/etc/momentry/synonyms/synonyms_ja.json,/etc/momentry/synonyms/synonyms_ko.json

# 方式三：跨語言同義詞庫
# MOMENTRY_SYNONYM_FILE=/etc/momentry/synonyms/multilingual_synonyms.json

# 多語系支援設定
MOMENTRY_MULTILINGUAL_SUPPORT=true
MOMENTRY_DEFAULT_LANGUAGE=zh
MOMENTRY_SUPPORTED_LANGUAGES=zh,en,ja,ko
MOMENTRY_AUTO_DETECT_LANGUAGE=true
EOF

# 重啟服務使配置生效
sudo launchctl unload /Library/LaunchDaemons/com.momentry.api.plist
sudo launchctl load /Library/LaunchDaemons/com.momentry.api.plist

# 檢查日誌確認多語系支援已啟用
tail -f /Users/accusys/momentry/log/momentry_api.log | grep -i "multilingual\|language\|synonym"
```

### 多語系同義詞庫最佳實踐

#### 1. 語言標籤標準化
- 使用 ISO 639-1 語言代碼（zh, en, ja, ko）
- 為繁體中文和簡體中文分別建立標籤（zh-Hant, zh-Hans）
- 保持語言標籤的一致性

#### 2. 詞語質量控制
- 定期檢查和更新同義詞映射
- 移除過時或不準確的詞語
- 驗證跨語言映射的準確性

#### 3. 性能優化
- 對於大型同義詞庫，考慮使用壓縮格式
- 實現懶加載機制，按需加載語言專用詞庫
- 使用緩存機制提高查詢性能

#### 4. 版本管理
- 為同義詞庫建立版本控制
- 記錄每次更新的變更內容
- 提供回滾機制

---

## 故障排除

### 同義詞檔案無法加載

**問題**: 日誌顯示 "Failed to load synonym expander"

**解決方案**:
```bash
# 1. 檢查檔案路徑
ls -la /path/to/your/synonyms.json

# 2. 檢查檔案權限
chmod 644 /path/to/your/synonyms.json

# 3. 驗證 JSON 格式
python3 -m json.tool /path/to/your/synonyms.json > /dev/null

# 4. 檢查編碼（必須是 UTF-8）
file -I /path/to/your/synonyms.json
```

### 同義詞擴展無效

**問題**: 查詢沒有被擴展

**解決方案**:
```bash
# 1. 檢查同義詞檔案是否正確加載
grep "Loaded synonym expander" /Users/accusys/momentry/log/momentry_api.log

# 2. 確認詞語格式（必須是繁體中文）
# 使用 OpenCC 轉換簡體到繁體
opencc -i simplified.txt -o traditional.txt -c s2tw.json

# 3. 測試單詞擴展
cargo run --bin test_synonym_expansion
```

### 性能問題

**問題**: 搜索變慢

**解決方案**:
```bash
# 1. 減少同義詞數量
# 只保留高頻詞語的同義詞

# 2. 分割為多個領域檔案
# 按領域分開加載，減少單一檔案大小

# 3. 使用更高效的詞語匹配
# 確保同義詞檔案結構優化
```

---

## 檔案位置

| 類型 | 路徑 | 說明 |
|------|------|------|
| 同義詞檔案 | `/path/to/your/synonyms.json` | 客戶自行準備的同義詞林 |
| 示例檔案 | `docs_v1.0/examples/custom_synonyms.json` | 格式示例（不含實際資料） |
| 轉換腳本 | `scripts/convert_synonyms.py` | 格式轉換工具（需自行建立） |
| 測試工具 | `src/bin/test_synonym_expansion.rs` | 同義詞擴展測試 |
| 日誌檔案 | `/Users/accusys/momentry/log/momentry_api.log` | 服務日誌 |

---

## 最佳實踐

### 1. 詞語選擇
- 優先選擇高頻詞語
- 確保同義詞準確性
- 避免過度擴展（每個詞語 2-5 個同義詞為佳）

### 2. 檔案管理
- 按領域分割檔案（技術、商業、通用等）
- 定期更新同義詞映射
- 備份原始同義詞資源

### 3. 性能優化
- 控制檔案大小（建議 < 10MB）
- 使用高效的 JSON 解析
- 避免重複詞語

### 4. 法律合規
- **務必確認資源授權**
- 保留授權證明文件
- 定期檢查授權狀態

---

## 版本資訊

- 同義詞功能版本: 0.1.0+
- 格式支援: JSON
- 編碼要求: UTF-8
- 詞語格式: 繁體中文
- 檔案限制: 無硬性限制，建議 < 10MB

---

## 相關文件

### 基礎配置
- `docs_v1.0/SYNONYM_CONFIGURATION.md` - 同義詞配置詳細說明
- `docs_v1.0/examples/custom_synonyms.json` - JSON 格式示例

### 多語系支援
- `docs_v1.0/examples/multilingual_synonyms.json` - 跨語言同義詞示例
- `docs_v1.0/examples/unified_multilingual_synonyms.json` - 統一多語系格式示例
- `docs_v1.0/examples/language_routing.json` - 語言路由配置示例

### 程式碼實作
- `src/core/text/synonym_expander.rs` - 同義詞擴展器實作
- `src/bin/test_synonym_expansion.rs` - 測試工具

### 工具腳本
- `scripts/detect_language.py` - 語言檢測工具
- `scripts/language_router.py` - 語言路由工具
- `scripts/unified_synonym_processor.py` - 統一格式處理器

---

## 免責聲明

1. **版權責任**：客戶需自行確保所使用的同義詞林資源符合相關法律法規和授權條款。
2. **資料準確性**：同義詞映射的準確性由客戶自行負責。
3. **技術支援**：Momentry Core 僅提供技術框架和格式支援，不提供同義詞資料。
4. **更新維護**：客戶需自行維護和更新同義詞資源。

**使用前請務必確認您擁有合法使用同義詞林資源的權利。**
