動態語義顯影與逆向語義遮罩系統：本地端實作技術白皮書

Local Implementation Whitepaper for Dynamic Semantic Revealing and Reverse Semantic Masking

版本：v0.1
日期：2026-07-26
文件性質：本地端 AI 工程實作交接文件
目標：建立可直接整合至現有時間線、文件庫或研究網站的逆向語義篩選功能

0. 文件用途

本文件不是公開概念論文的重述，而是交付本地端 AI、工程代理或開發者執行的實作規格。

本系統需要完成以下核心能力：

1. 以查詢語義動態顯影相關文件；
2. 同時支援精確與模糊搜尋；
3. 不因查詢詞不一致而直接歸零；
4. 清楚區分直接命中、詞彙命中、語義近似與結構關聯；
5. 不要求先替全部歷史文件人工補完元資料；
6. 可逐步導入，先以標題與摘要運作，再擴充全文與圖譜；
7. 優先支援本地模型與本地向量索引；
8. 保留原始時間線或文件排列脈絡。

1. MVP 範圍

1.1 MVP 必須完成

• 建立文件索引；
• 支援標題、日期、網址、摘要、標題層級；
• 支援精確詞組搜尋；
• 支援模糊詞彙搜尋；
• 支援本地向量語義搜尋；
• 合併多路檢索結果；
• 每筆結果提供命中理由；
• 支援「顯影模式」；
• 支援「只看結果」聚焦模式；
• 支援最低結果數；
• 支援查詢展開詞顯示；
• 支援 JSON 靜態索引；
• 無後端時仍可運作基本精確搜尋。

1.2 MVP 暫不要求

• 完整知識圖譜；
• 自動全文問答；
• 即時大型語言模型重排；
• 跨使用者個人化；
• 自動修改原始 Markdown；
• 雲端向量資料庫；
• 複雜權限管理；
• 多語言完整對齊。

2. 建議技術架構

建議拆為五層：

[原始文件層]
Markdown / HTML / JSON / Timeline records
        ↓
[抽取與衍生層]
title / date / headings / summary / keywords / aliases
        ↓
[索引層]
lexical index / vector index / relation index
        ↓
[查詢與融合層]
normalization / expansion / retrieval / reranking
        ↓
[顯影介面層]
highlight / dim / collapse / hide / focus

3. 建議檔案結構

semantic-revealing/
├─ README.md
├─ package.json
├─ pyproject.toml
├─ config/
│  ├─ search.config.json
│  ├─ field_weights.json
│  ├─ thresholds.json
│  └─ stopwords_zh_tw.txt
├─ data/
│  ├─ documents.raw.jsonl
│  ├─ documents.index.jsonl
│  ├─ aliases.json
│  ├─ concept_lexicon.json
│  ├─ relations.jsonl
│  └─ embeddings/
│     ├─ vectors.npy
│     └─ ids.json
├─ scripts/
│  ├─ extract_documents.py
│  ├─ build_summaries.py
│  ├─ build_lexical_index.py
│  ├─ build_embeddings.py
│  ├─ build_relations.py
│  ├─ validate_index.py
│  └─ export_static_bundle.py
├─ backend/
│  ├─ app.py
│  ├─ search_service.py
│  ├─ ranker.py
│  ├─ query_expander.py
│  └─ schemas.py
├─ frontend/
│  ├─ semantic-filter.js
│  ├─ semantic-filter.css
│  ├─ semantic-panel.html
│  └─ worker/
│     └─ lexical-search-worker.js
├─ tests/
│  ├─ queries.jsonl
│  ├─ test_normalization.py
│  ├─ test_retrieval.py
│  ├─ test_ranking.py
│  ├─ test_nonzero.py
│  └─ test_frontend_state.js
└─ dist/
   ├─ semantic-index.min.json
   ├─ semantic-filter.min.js
   └─ semantic-filter.min.css

4. 文件索引資料模型

4.1 最小文件紀錄

{
  "id": "doc-000001",
  "title": "文件標題",
  "url": "/paper/example/",
  "date": "2026-07-26",
  "language": "zh-TW",
  "summary": "短摘要",
  "headings": ["第一節", "第二節"],
  "body_text": "",
  "series": [],
  "keywords": [],
  "aliases": [],
  "related_ids": [],
  "metadata": {
    "title_source": "author_declared",
    "summary_source": "model_derived",
    "keywords_source": "model_derived",
    "confidence": 0.82,
    "schema_version": "0.1"
  }
}

4.2 搜尋用壓縮紀錄

前端靜態索引應避免載入完整正文：

{
  "i": "doc-000001",
  "t": "文件標題",
  "u": "/paper/example/",
  "d": "2026-07-26",
  "s": "短摘要",
  "h": ["第一節", "第二節"],
  "k": ["關鍵詞一", "關鍵詞二"],
  "r": ["doc-000005"]
}

4.3 正文策略

正文可採三種模式：

1. title_only：僅標題與日期；
2. summary_index：標題、摘要、章節；
3. fulltext_index：包含完整正文。

建議導入順序：

5. 元資料來源標記

所有自動生成內容必須標明來源：

{
  "value": ["語義搜尋", "知識庫"],
  "source": "model_derived",
  "confidence": 0.79,
  "generator": "local-model-name",
  "generated_at": "2026-07-26T19:00:00+08:00"
}

允許來源：

author_declared
editor_confirmed
model_derived
system_inferred
query_generated

不得把 model_derived 靜默轉成 author_declared。

6. 查詢正規化

6.1 必要處理

Unicode NFKC
全形轉半形
英文轉小寫
連續空白合併
前後空白移除
繁簡映射可選
異體字映射可選
標點切分
縮寫保留
數學符號保留
連字號與底線等價化

6.2 不能移除的內容

不得粗暴移除：

• 數字；
• 版本號；
• 數學符號；
• 希臘字母；
• 連字號；
• 專案縮寫；
• 模型名稱；
• 單字母變數。

例如：

X積分
GPT-5.6
RH-W-20
C++
Ω

都可能是有效查詢。

6.3 正規化函數介面

def normalize_query(query: str) -> dict:
    return {
        "original": query,
        "normalized": "...",
        "tokens": ["..."],
        "detected_language": "zh-TW",
        "variants": ["..."]
    }

7. 專屬詞典

7.1 詞典資料模型

{
  "concept_id": "concept-ai-agency",
  "canonical": "AI 主體性",
  "aliases": [
    {"term": "人工智慧主體性", "weight": 0.95},
    {"term": "AI 能動性", "weight": 0.82}
  ],
  "related": [
    {"term": "持續意圖", "weight": 0.72},
    {"term": "記憶連續性", "weight": 0.68}
  ],
  "broader": [],
  "narrower": [],
  "status": "editor_confirmed"
}

7.2 關係類型

alias
synonym
abbreviation
broader
narrower
related
historical_name
translation
spelling_variant

7.3 展開限制

每次查詢最多：

{
  "max_aliases": 8,
  "max_related_terms": 6,
  "max_graph_depth": 1,
  "min_expansion_confidence": 0.60
}

不得無限制遞迴擴展。

8. 多路候選召回

至少建立四路召回。

8.1 精確召回

來源：

• 完整標題；
• 標題詞組；
• 摘要詞組；
• 人工別名。

輸出：

{
  "document_id": "doc-1",
  "channel": "exact",
  "raw_score": 1.0,
  "reason": "title_phrase"
}

8.2 詞彙召回

可使用：

• BM25；
• trigram；
• token overlap；
• edit distance；
• prefix match；
• phrase proximity。

8.3 向量召回

建議本地嵌入模型，索引內容優先順序：

title
title + summary
title + headings + summary
chunked full text

MVP 建議採：

title + summary + headings

向量相似度：

8.4 關聯召回

關聯來源：

• 同系列；
• 相鄰版本；
• 明確連結；
• 共同關鍵詞；
• 同一來源頁；
• 時間上的連續研究節點。

MVP 可只做 related_ids 與 series。

9. 分數融合

9.1 初始權重

{
  "exact_title": 1.00,
  "exact_summary": 0.82,
  "alias_title": 0.88,
  "lexical": 0.60,
  "semantic": 0.55,
  "series_relation": 0.25,
  "direct_link_relation": 0.30,
  "anchor_bonus": 0.08
}

9.2 建議公式

其中 $F$ 為欄位權重。

加入錨定：

9.3 分數校正

不同召回器分數範圍不同，融合前先正規化：

或以排名融合代替原始分數融合。

9.4 去重

同一文件可被多路召回，應合併：

{
  "document_id": "doc-1",
  "channels": ["exact", "lexical", "semantic"],
  "reasons": [
    "title_phrase",
    "alias_match",
    "semantic_similarity"
  ],
  "score": 0.91
}

10. 分級規則

建議初始門檻：

{
  "tier_A": 0.82,
  "tier_B": 0.68,
  "tier_C": 0.54,
  "tier_D": 0.38,
  "minimum_display": 5,
  "absolute_floor": 0.28
}

注意：分級不能只看總分，也要看召回類型。

A 級

直接詞組命中
標題精確命中
人工別名命中

B 級

高詞彙相似
高可信度同義詞
標題部分命中

C 級

向量高相似
摘要概念近似
缺乏直接文字錨點

D 級

系列關聯
引用關聯
低分語義近似

11. 非歸零機制

11.1 演算法

def ensure_minimum_results(results, minimum=5, thresholds=None):
    thresholds = thresholds or [0.78, 0.70, 0.62, 0.54, 0.46, 0.38]

    for threshold in thresholds:
        selected = [r for r in results if r["score"] >= threshold]
        if len(selected) >= minimum:
            return {
                "results": selected,
                "threshold": threshold,
                "relaxed": threshold != thresholds[0]
            }

    fallback = sorted(results, key=lambda x: x["score"], reverse=True)[:minimum]
    return {
        "results": fallback,
        "threshold": None,
        "relaxed": True,
        "low_confidence": True
    }

11.2 顯示文案

直接結果不足：

直接命中較少，已加入詞彙與語義近似結果。

僅有低可信結果：

沒有找到高可信度直接結果。以下僅列出語義上最接近的文件。

完全沒有候選：

索引中沒有可用結果。請嘗試較短詞組、別名或移除限制條件。

非歸零保證不代表必須偽造結果；當索引真的沒有任何候選時，仍應誠實顯示空結果。

12. 查詢處理流程

def search(query: str, limit: int = 50):
    nq = normalize_query(query)
    expansions = expand_query(nq)

    exact = exact_retrieve(nq, expansions)
    lexical = lexical_retrieve(nq, expansions)
    semantic = semantic_retrieve(nq, expansions)
    graph = relation_retrieve(exact + lexical + semantic)

    candidates = merge_candidates(
        exact=exact,
        lexical=lexical,
        semantic=semantic,
        graph=graph
    )

    ranked = rerank(candidates, nq, expansions)
    tiered = assign_tiers(ranked)
    final = ensure_minimum_results(tiered)

    return {
        "query": nq,
        "expansions": expansions,
        "results": final["results"][:limit],
        "relaxed": final.get("relaxed", False),
        "low_confidence": final.get("low_confidence", False)
    }

13. API 規格

13.1 搜尋 API

POST /api/semantic-search
Content-Type: application/json

請求：

{
  "query": "使用者查詢",
  "mode": "reveal",
  "limit": 50,
  "minimum_results": 5,
  "include_related": true
}

回應：

{
  "query": {
    "original": "使用者查詢",
    "normalized": "使用者查詢"
  },
  "expansions": [
    {
      "term": "相關詞",
      "type": "alias",
      "weight": 0.88
    }
  ],
  "summary": {
    "exact_count": 3,
    "lexical_count": 8,
    "semantic_count": 12,
    "related_count": 5,
    "relaxed": true
  },
  "results": [
    {
      "id": "doc-0001",
      "title": "文件標題",
      "url": "/paper/example/",
      "date": "2026-07-26",
      "score": 0.91,
      "tier": "A",
      "visibility": 1.0,
      "reasons": [
        {
          "type": "exact_title",
          "label": "標題包含完整查詢詞"
        }
      ]
    }
  ]
}

13.2 索引健康檢查

GET /api/semantic-search/health

回應：

{
  "status": "ok",
  "documents": 1727,
  "lexical_index": true,
  "vector_index": true,
  "relation_index": true,
  "schema_version": "0.1"
}

14. 前端互動規格

14.1 搜尋框

需要：

• 300 毫秒 debounce；
• 支援 Enter 立即搜尋；
• 支援清除；
• 顯示查詢展開；
• 顯示結果層級統計；
• 保留原始查詢。

14.2 顯影狀態

每個文件節點設定：

<article
  data-doc-id="doc-0001"
  data-semantic-score="0.91"
  data-semantic-tier="A"
  data-semantic-visible="true">
</article>

14.3 CSS 建議

.semantic-tier-a {
  opacity: 1;
  filter: none;
}

.semantic-tier-b {
  opacity: 0.92;
}

.semantic-tier-c {
  opacity: 0.62;
}

.semantic-tier-d {
  opacity: 0.38;
}

.semantic-hidden {
  opacity: 0.12;
  pointer-events: none;
}

.semantic-focus .semantic-hidden {
  display: none;
}

正式實作時可依網站主題調整，但不得只靠顏色區分，必須同時使用文字、圖示或透明度。

14.4 兩種模式

顯影模式：
  非相關節點保留輪廓

聚焦模式：
  非相關節點 display: none

14.5 切換控制

<button data-mode="reveal">顯影</button>
<button data-mode="focus">只看結果</button>
<button data-action="reset">重設</button>

15. 命中理由 UI

每筆結果至少顯示一項：

A｜標題精確命中
B｜命中已確認別名
C｜摘要語義近似
D｜與直接結果屬於同系列

展開後可顯示：

{
  "matched_text": "命中的文字",
  "field": "title",
  "expansion_term": "別名",
  "semantic_score": 0.83,
  "relation": "same_series"
}

不得只顯示一個不透明的「AI 推薦」。

16. 靜態網站方案

若現有網站為靜態網站，可採雙層方案。

16.1 前端純文字模式

瀏覽器載入：

semantic-index.min.json

以 Web Worker 完成：

• 精確搜尋；
• token overlap；
• trigram；
• 欄位加權；
• 顯影控制。

優點：

• 無伺服器；
• 易部署；
• 離線可用；
• 不需 API。

限制：

• 向量索引較重；
• 手機記憶體有限；
• 大量全文不適合一次載入。

16.2 API 增強模式

前端先執行精確搜尋，再呼叫本地 API 取得語義結果：

前端精確結果
+
本地向量 API 結果
=
融合顯影

若 API 失效，系統退化為精確搜尋，不得整體失效。

17. 向量索引方案

17.1 小型資料庫

若文件數少於數萬，可選：

• NumPy 暴力 cosine；
• FAISS；
• hnswlib；
• SQLite + 向量擴充；
• 本地輕量向量庫。

17.2 向量內容

每篇文件先建立一個文件級向量：

title + "\n" + summary + "\n" + headings

若後續加入全文，再建立 chunk 向量：

{
  "chunk_id": "doc-1#chunk-3",
  "document_id": "doc-1",
  "text": "段落內容",
  "heading": "章節名稱",
  "position": 3
}

17.3 文件級聚合

若文件有多個 chunk 分數：

或：

MVP 使用最大值即可，正式版可採 Top-K 平均避免單段偶然誤配。

18. 摘要與關鍵詞生成

18.1 批次生成輸出

本地 AI 對每篇文件輸出：

{
  "document_id": "doc-1",
  "summary": "80 至 150 字摘要",
  "keywords": ["3 至 8 個"],
  "candidate_series": ["0 至 3 個"],
  "named_concepts": ["概念一"],
  "confidence": 0.81
}

18.2 生成限制

• 不得改寫原文立場；
• 不得將推測寫成確定事實；
• 不得生成不存在的系列；
• 關鍵詞應來自文本或可合理概括；
• 低信心時保留空值；
• 原始標題永遠優先於模型摘要。

18.3 增量更新

以文件 hash 判斷是否需要重建：

{
  "document_id": "doc-1",
  "content_hash": "sha256:...",
  "indexed_at": "2026-07-26T19:00:00+08:00"
}

若 hash 不變，不重新生成摘要與向量。

19. 關聯索引

19.1 MVP 關聯

same_series
previous_version
next_version
explicit_link
same_primary_keyword

19.2 關聯資料模型

{
  "source": "doc-1",
  "target": "doc-2",
  "type": "same_series",
  "weight": 0.72,
  "source_type": "system_inferred"
}

19.3 圖擴展限制

只允許一跳擴展：

否則結果容易被大型概念網絡污染。

20. 多樣性重排

避免單一系列占滿結果。

可使用簡化配額：

{
  "max_per_series_top_10": 4,
  "max_same_title_prefix_top_10": 3
}

或使用最大邊際相關性：

建議：

21. 測試集

建立 tests/queries.jsonl：

{"query":"完整專有詞","expected_tier_a":["doc-1"]}
{"query":"已知別名","expected_any":["doc-1","doc-2"]}
{"query":"自然語言描述","expected_top10":["doc-3"]}
{"query":"常見錯字","expected_suggestion":"正確詞"}
{"query":"不存在概念","expect_low_confidence":true}

至少準備：

• 20 個精確查詢；
• 20 個別名查詢；
• 20 個自然語言查詢；
• 10 個錯字查詢；
• 10 個零資料查詢；
• 10 個跨領域查詢。

22. 驗收標準

22.1 功能驗收

• 輸入查詢後 500 毫秒內出現前端精確結果；
• 語義 API 在可接受時間內補入結果；
• 精確命中永遠排在純語義近似之前；
• 每筆結果至少有一個命中理由；
• 查詢結果可切換顯影與聚焦；
• 清除查詢後完整恢復原時間線；
• API 失效時前端精確搜尋仍可用；
• 不會因低分結果而假裝是直接命中；
• 索引可增量更新；
• 同一文件不重複顯示。

22.2 品質驗收

• 精確查詢 Top-3 命中率高於 95%；
• 已知別名 Top-5 命中率高於 90%；
• 自然語言查詢 Top-10 可用率高於 80%；
• 每筆顯示結果解釋覆蓋率為 100%；
• 低可信查詢必須顯示放寬提示；
• 查詢清除後 DOM 狀態無殘留。

23. 效能要求

23.1 前端

建議：

索引壓縮後 < 5 MB：可直接載入
5–20 MB：延遲載入 + Web Worker
> 20 MB：改用分片或 API

23.2 後端

對數千篇文件，基本向量查詢不需大型服務。優先：

• 單機；
• 本地索引；
• 增量更新；
• 啟動時載入記憶體；
• 定期匯出靜態備份。

23.3 快取

快取 key：

normalized_query
index_version
search_config_version

若索引版本改變，全部舊快取失效。

24. 日誌與觀測

記錄：

{
  "query": "使用者查詢",
  "normalized_query": "使用者查詢",
  "result_count": 12,
  "exact_count": 3,
  "semantic_count": 6,
  "relaxed": true,
  "latency_ms": 84,
  "index_version": "0.1"
}

若涉及公開網站，應避免記錄可識別個人資訊。查詢日誌可選擇匿名化或完全關閉。

25. 安全要求

• 不執行查詢字串；
• 防止 XSS；
• 所有摘要與標題輸出需 escape；
• 不允許前端傳入任意檔案路徑；
• 限制查詢長度；
• 限制 API 頻率；
• 向量索引不得包含未授權文件；
• 權限過濾必須在候選召回前完成；
• 不把私人文件傳送至外部模型。

26. 導入階段

Phase 0：資料盤點

• 掃描所有文件；
• 建立穩定 ID；
• 對應 URL；
• 檢查日期與標題；
• 產出 documents.raw.jsonl。

Phase 1：純前端精確顯影

• 標題與摘要文字搜尋；
• 顯影與聚焦切換；
• 命中高亮；
• 無向量模型。

Phase 2：詞典與別名

• 建立概念詞典；
• 支援查詢展開；
• 顯示展開詞。

Phase 3：本地向量搜尋

• 建立文件級嵌入；
• API 回傳語義結果；
• 加入 C 級顯示。

Phase 4：關聯與系列

• 建立系列與版本關聯；
• 加入 D 級顯示；
• 加入多樣性重排。

Phase 5：全文與評估

• 建立 chunk；
• 建立測試集；
• 調整權重；
• 建立搜尋品質儀表板。

27. 本地端 AI 工作指令

本地端 AI 應依以下順序執行：

1. 讀取現有網站或文件庫結構；
2. 找出時間線節點的 DOM 結構；
3. 建立文件 ID 與 URL 對應；
4. 產出最小 documents.raw.jsonl；
5. 實作純前端標題搜尋；
6. 加入顯影與聚焦狀態；
7. 加入命中理由；
8. 建立詞典資料格式；
9. 建立本地向量索引；
10. 實作 API 與前端融合；
11. 建立測試集；
12. 生成部署文件與回滾方案。

每個階段必須保留可運行版本，不得等到全部完成後才第一次整合。

28. 回滾與相容性

28.1 回滾

搜尋功能應可由單一設定關閉：

{
  "semantic_search_enabled": false
}

關閉後，網站恢復原有時間線，不影響文件內容與 URL。

28.2 相容性

不得：

• 改變既有網址；
• 重新命名歷史文件；
• 依賴 JavaScript 才能讀取原文；
• 將原始時間線永久改寫為搜尋結果頁。

搜尋層必須是附加層。

29. 最小可交付成果

本地端 AI 最終至少交付：

1. 可運作的搜尋元件
2. semantic-index.min.json
3. semantic-filter.js
4. semantic-filter.css
5. 索引生成腳本
6. 查詢詞典格式
7. 測試集
8. README
9. 部署步驟
10. 回滾步驟
11. 已知限制
12. 一份搜尋品質報告

30. 最終原則

實作時必須遵守以下原則：

原則一：精確優先

原則二：近似必須被標示

不得把模糊結果偽裝成直接結果。

原則三：非歸零不等於偽造

系統可以放寬搜尋，但必須揭露放寬狀態。

原則四：不修改原文

索引、摘要、關鍵詞與關聯皆在外部層生成。

原則五：先有可用版本，再逐步增強

原則六：保留知識脈絡

搜尋不是把文件搬走，而是改變文件在當下查詢中的可見程度。

附錄 A：建議設定檔

{
  "schema_version": "0.1",
  "search": {
    "minimum_results": 5,
    "max_results": 100,
    "initial_threshold": 0.78,
    "threshold_step": 0.08,
    "absolute_floor": 0.28
  },
  "channels": {
    "exact": true,
    "lexical": true,
    "semantic": true,
    "relations": true
  },
  "weights": {
    "exact": 0.40,
    "lexical": 0.20,
    "semantic": 0.25,
    "relations": 0.10,
    "field": 0.05,
    "anchor_bonus": 0.08
  },
  "display": {
    "default_mode": "reveal",
    "tier_a_opacity": 1.0,
    "tier_b_opacity": 0.92,
    "tier_c_opacity": 0.62,
    "tier_d_opacity": 0.38,
    "hidden_opacity": 0.12
  }
}

附錄 B：完成定義

專案只有在以下條件同時成立時才算完成：

使用者輸入一個精確術語時，直接結果優先出現；
使用者輸入同義說法時，系統仍能找到主要文件；
使用者輸入自然語言描述時，系統能給出可解釋的近似結果；
查詢過窄時，介面不會突然無意義地全空白；
查詢完全無資料時，系統不偽造結果；
清除查詢時，原始時間線完整恢復；
所有自動衍生資料都標記來源與信心；
搜尋功能可獨立關閉且不破壞原網站。