一、為什麼不能讓 LLM 把關權限

直覺的做法：把權限規則寫進 prompt——「你不可以透露機密文件的內容」。這條路是死路，原因有三個層次：

1. LLM 是可以被說服的。 Prompt injection、角色扮演、「我是管理員」——模型的服從性本身就是攻擊面。把權限交給一個「會被聊天內容影響的元件」把關，等於把金庫鑰匙掛在會跟陌生人聊天的警衛身上。
2. 進了 prompt 就等於外洩。 就算模型忍住不直接複述，機密內容已經影響了它的回答——摘要、暗示、選字都可能洩漏。真正的邊界必須在內容進入 prompt 之前。
3. 連「存在」本身都是資訊。「我找到了相關文件但不能告訴你」——這句話已經洩漏了機密文件的存在與主題方向。

所以我的平台有四條鐵則，第一條就是：權限在檢索層強制執行。使用者無權看的切塊，根本不會出現在檢索結果，不會進 rerank，更不會進 prompt——對整條下游管線來說，那些文件不存在。

二、RBAC 模型：角色決定看得到什麼

權限模型參考 RuoYi 的 RBAC 設計：

1
2
3

使用者 ──* 角色 ──┬─* 功能權限（能用哪些功能）
    │              └─* 資料權限（看得到哪些文件）
  工號/部門

資料權限拆成四個維度，前三個管「範圍」、第四個管「密級」，彼此正交：

「正交」是關鍵設計：一份文件可以同時是「人資部 + 機密」，要看到它必須同時具備部門範圍權限與機密權限。預設的角色矩陣：

而且這張表不是寫死的——它存在資料庫裡，管理員可以在介面上編輯。這帶出一條隱形的設計紀律：程式碼裡永遠不出現 if role == "admin" 這種硬編碼判斷，一律查權限表。否則日後新增角色時，散落各處的角色判斷就是一顆顆地雷。

三、資料端：權限住在每一個切塊上

檢索層要能過濾，前提是每個切塊自帶權限標籤。文件切塊寫入 Qdrant 時，payload 除了原文和來源，還帶兩個權限欄位：

1
2
3
4
5
6
7

{
  "text": "切塊原文…",
  "source": "人事管理辦法.pdf",
  "chunk_index": 12,
  "scope": "HR",                      // "public" 或部門代號
  "confidentiality": "unclassified"   // unclassified | confidential
}

一個看似小事、實則重要的決定：scope 存部門代號（HR、IT），不存中文名稱。中文名稱只是 departments 表裡的顯示標籤——部門改名時只改標籤，幾十萬個切塊的 payload 一個都不用動。

那如果真的要改代號呢？這裡藏著一個多資料庫架構的經典陷阱：權限表在 SQLite、文件記錄在 MongoDB、但 scope 複製在每一個 Qdrant 切塊的 payload 裡。只改前兩者的話，檢索層還在用舊代號比對——結果是那個部門的員工突然什麼都查不到。所幸方向是安全的（fail-closed：資料消失而不是外洩），但功能就是壞了。所以系統提供了 rename_scope：用 Qdrant 的 set_payload 批次把所有 scope == 舊代號 的切塊改成新代號，並回傳受影響的切塊數供比對。冗餘欄位帶來檢索效率，也帶來同步義務——這是把權限放進檢索層的成本，值得，但要記帳。

四、查詢端:從 JWT 到 Qdrant Filter

完整的請求路徑是三段接力，每一段只做自己的事：

1
2
3
4
5
6
7
8

前端 ──JWT──▶ C# 閘道：驗證身分 → 查角色的 data_scopes → 展開成 perm_filter
                  │
                  ▼  {"scopes": ["public","own_dept"], "depts": ["HR"],
                      "max_confidentiality": "unclassified"}
              Python Agent：build_permission_filter() → Qdrant Filter
                  │
                  ▼
              Qdrant：filter 套在檢索的 prefetch 層，無權切塊不進候選

身分由閘道從 JWT 注入——這是鐵則第二條。使用者說自己是誰不算數，LLM 認為使用者是誰更不算數；權限條件是後端查表展開的，前端傳什麼都不採信。

Agent 端把權限條件翻譯成 Qdrant Filter 的核心邏輯（節錄實際程式碼）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

def build_permission_filter(perm_filter: dict | None) -> models.Filter | None:
    if perm_filter is None:
        return None          # 僅限內部評測；正式請求一律由閘道帶入

    scopes = perm_filter.get("scopes") or []
    depts = perm_filter.get("depts") or []

    allowed_scopes = []
    if "public" in scopes:
        allowed_scopes.append("public")

    conds = []
    if "cross_dept" in scopes:
        pass                 # 不限部門 → 不加 scope 條件
    else:
        if "own_dept" in scopes:
            allowed_scopes.extend(depts)
        if not allowed_scopes:
            # 沒有任何可見範圍 → 回傳「必然無結果」的 filter
            return models.Filter(must=[models.FieldCondition(
                key="scope", match=models.MatchValue(value="__none__"))])
        conds.append(models.FieldCondition(
            key="scope", match=models.MatchAny(any=allowed_scopes)))

    if perm_filter.get("max_confidentiality") != "confidential":
        conds.append(models.FieldCondition(
            key="confidentiality",
            match=models.MatchValue(value="unclassified")))

    return models.Filter(must=conds) if conds else None

最值得停下來看的是中間那段刻意的彆扭：當使用者沒有任何可見範圍時，函式不回傳 None，而是回傳一個匹配 scope == "__none__" 的 filter——一個保證撈不到任何東西的條件。因為在這個介面裡 None 的意思是「不過濾」；如果「無權限」被表示成 None，一個上游的疏忽就會讓無權限使用者看到全部文件。這就是 fail-closed 設計：預設值永遠朝安全的方向倒。

最後一哩：這個 filter 套在混合檢索的 prefetch 層（dense 與 sparse 兩路都套）。這意味著權限過濾發生在召回之前，而不是撈回來再刪——差別很實際：

• 召回名額不被無權文件浪費（top-20 全是你看得到的）
• rerank 不用處理註定被丟掉的候選
• 不存在「先看到再遮住」的時間窗

五、應用層的防繞過設計

檢索層是地基，但權限系統的完整性取決於每一條繞過路徑都被堵上。幾個實例：

上傳權與定範圍權是兩個權限。 docs.upload（能上傳）和 docs.scope（能決定文件給誰看）刻意拆開。部門主管有前者沒後者——他上傳的文件一律鎖定為自己部門，用戶端指定什麼 scope 都直接覆寫（並落一筆 SCOPE_OVERRIDDEN 稽核記錄）。同時，事後修改 scope 也被封死（回 403）——只擋上傳的話，「先上傳成部門文件、再編輯成 public」就繞過去了。但改機密等級仍被允許：把自己部門的文件標成機密只會更嚴，不構成風險。每條規則都對應一條被想像過的繞過路徑。

稽核角色能查軌跡、不能藉軌跡讀內容。 稽核能看所有人的問答紀錄（誰問了什麼、引用了哪些文件），但紀錄裡的引用只存檔名與切塊編號，不存全文——稽核權限不會變成讀機密文件的後門。

機密文件連生成階段都被隔離。 檢索結果裡如果含機密切塊，Router 會把生成路由到地端 LLM（文件內容不出內網）；地端模型不可用時直接拒絕服務，而非降級改用雲端——「不可用」的正確反應是失敗，不是妥協。

測試測的是繞過，不是正常流程。 權限測試專門驗證攻擊路徑：指定 public 上傳會不會被覆寫？先上傳再編輯會不會被擋？正常流程會過只證明功能存在，繞過測試才證明邊界存在。

小結：權限系統的三層縱深

1
2
3

資料層   每個切塊自帶 scope + confidentiality（同步義務：rename_scope）
檢索層   JWT → 權限表展開 → Qdrant filter 套在召回之前（fail-closed）
應用層   權限拆分、防繞過規則、稽核不越權、機密走地端

貫穿三層的是同一個思維：不信任下游。不信任 LLM 會守規矩、不信任前端傳來的參數、不信任「正常使用者不會那樣操作」。權限系統的品質不在正常路徑多順暢，而在每一條歪路是不是都走不通。

RAG 系列四篇到此完成一個段落：基礎邏輯、向量庫與 MongoDB、混合檢索、權限實作。後續主題（語意快取、結構化查詢、評測方法論）等專案推進再寫。

一、為什麼需要「混合」：兩種檢索的互補盲區

Dense（稠密向量）：懂語意、瞎於字面

Embedding 模型（我用 bge-m3）把整段文字壓成一個 1024 維向量，語意相近的文字在向量空間中距離相近。它的強項是同義與改寫：

查詢「員工請假要跑什麼流程」能命中寫著「休假申請辦法」的切塊——字面幾乎沒有重疊，語意卻是同一件事。

但它有個致命盲區：精確字串。「115年偵字第7615號」這種案號，對 dense 向量來說只是一串沒有語意結構的符號，壓進 1024 維後跟其他案號幾乎難以區分。查案號、料號、法條編號、產品型號——dense 檢索會給你「語意上都是案號」的一堆錯誤結果。

Sparse（稀疏向量）：認字精準、不懂改寫

bge-m3 的特別之處是同一次推理順便產出 sparse 向量——一張「token → 權重」的詞彙表，本質上是神經網路加權版的關鍵字索引（可以理解為學習出來的 BM25）。它的強項正好補上 dense 的盲區：「7615」就是「7615」，一字不差才有分。

但反過來，使用者查「休假」而文件寫「請假」，sparse 就完全接不上——它不懂同義詞。

兩者的失敗模式互斥——這就是混合檢索的理論基礎：不是「兩個都用比較保險」的迷信，而是盲區互補的必然。

二、RRF：為什麼融合名次，而不是分數

兩路檢索各自回傳一份帶分數的排名，怎麼合併？直覺是把分數加起來——這是錯的。dense 的分數是餘弦相似度（0~1 之間、分佈密集），sparse 的分數是詞彙權重內積（範圍完全不同）。兩種量綱不同的分數相加，等於拿體重加身高。

RRF（Reciprocal Rank Fusion）的解法：丟掉分數，只看名次。

1

RRF_score(文件d) = Σ 每一路檢索 1 / (k + rank_d)

rank_d 是文件在該路檢索的名次，k 是平滑常數（通常 60）。一個切塊如果在 dense 排第 2、sparse 排第 5，它的 RRF 分數就是 1/62 + 1/65。只在其中一路出現的，就只拿那一路的分。

這個設計的精妙之處：

• 免疫於量綱問題——名次永遠可比，不管各路的分數怎麼算
• 兩路都認可的結果自然上浮——雙料入榜的切塊分數幾乎翻倍
• k 壓制了「第一名獨大」——1/61 和 1/62 差距很小，避免任何一路的榜首直接輾壓全場，讓融合真的是「合議」而不是「一言堂」

三、Qdrant 實作：一次請求做完兩路檢索與融合

理論講完，看真實程式碼。Qdrant 的 query_points + prefetch 讓整個混合檢索在資料庫端一次完成，不用自己撈兩份結果回來手工融合：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

result = client.query_points(
    collection_name=settings.collection_name,
    prefetch=[
        models.Prefetch(               # 第一路：dense 語意檢索
            query=q["dense"],
            using="dense",
            limit=settings.dense_top_k,      # 各撈 20
        ),
        models.Prefetch(               # 第二路：sparse 關鍵字檢索
            query=models.SparseVector(
                indices=q["sparse_indices"],
                values=q["sparse_values"],
            ),
            using="sparse",
            limit=settings.sparse_top_k,
        ),
    ],
    query=models.FusionQuery(fusion=models.Fusion.RRF),   # 資料庫端 RRF 融合
    limit=limit,                       # 開 rerank 時廣撈 30 筆候選
    with_payload=True,
)

幾個實作細節：

• collection 建立時就要宣告雙向量欄位：vectors_config 放 dense（COSINE 距離）、sparse_vectors_config 放 sparse。一個切塊一個 point，同時攜帶兩種向量。
• 查詢端與索引端用同一顆 bge-m3——embed_query 同樣一次產出 dense + sparse，一次模型推理餵飽兩路檢索。
• 撈的數量由設定檔控制（dense_top_k / sparse_top_k 各 20），改參數不動程式碼，方便跑評測調參。

四、Reranker：雙塔的極限，交叉編碼來補

混合檢索解決了「兩種盲區」，但還有一個更深層的架構限制。

雙塔（Bi-encoder）為什麼天生粗糙

Dense 檢索是「雙塔」架構：問題和切塊各自獨立編碼成向量，事後只比距離。切塊在建索引時被壓縮成 1024 個數字——那時它根本不知道未來會被什麼問題查詢。一段 700 字的內容硬塞進固定維度，細節必然丟失；問題與切塊之間詞與詞的精細對應關係（誰修飾誰、否定詞在哪），距離計算完全看不見。

換來的是速度：所有切塊向量預先算好，查詢時只算一次問題向量，再做 ANN 近鄰搜尋——百萬級資料毫秒回應。

交叉編碼（Cross-encoder）：慢工出細活

Reranker（我用 bge-reranker-v2-m3）走完全不同的路：把**「問題＋切塊」串接成一段輸入**，整段送進模型，讓注意力機制直接看見兩者之間每個詞的互動，輸出一個相關性分數。

代價是每個候選都要跑一次完整的模型推理——不能預先計算（輸入包含查詢時才知道的問題），沒有索引可以加速。30 個候選就是 30 次推理。

兩段式：讓兩種架構各做擅長的事

1

百萬切塊 ──混合檢索（雙塔·快·粗）──▶ 30 個候選 ──Reranker（交叉編碼·慢·準）──▶ top-15 進 prompt

粗篩的職責是召回：寧可多撈，別漏掉正確答案——所以廣撈 30。精排的職責是排序：把真正相關的排上來、把「語意相似但答非所問」的踢下去。慢的模型只處理 30 筆，成本可控。

實作上有兩個值得記的細節：

• 用開關控制（rerank_enabled），方便 A/B 對照 rerank 到底有沒有幫助——回到第一篇說的：每個改動都要能被黃金問答集量測。
• 裝置選擇的實戰陷阱：bge-m3 embedding 在 Apple MPS 上會卡死（所以 embedding 預設避開 MPS），但同系列的 reranker 在 MPS 上不僅正常、還比 CPU 快約一倍（30 個候選 24 秒 → 12.3 秒，分數完全相同）。同一家的模型、同一台機器、完全相反的結論——加速後端的相容性只能實測，不能推論。

五、整條管線的最終形貌

1
2
3
4
5
6
7

問題
 └─ bge-m3 編碼（一次推理，dense + sparse 雙輸出）
     ├─ dense 檢索 top-20 ─┐
     └─ sparse 檢索 top-20 ─┤
                            ├─ RRF 融合（名次合議）→ 候選 30
                            └─ bge-reranker-v2-m3 交叉編碼精排 → top-15
                                └─ 進 prompt，強制標來源生成

每一層都在補上一層的不足：sparse 補 dense 的字面盲區，RRF 公平合議兩路結果，reranker 補雙塔架構的精度極限。**沒有一個環節是銀彈，疊起來才是。**第一篇提過的實測結果——檢索命中率 100%——就是這條管線加上表格感知切塊共同達成的。

下一篇處理企業場景最硬的需求：權限怎麼在檢索層強制執行——讓沒權限的文件連被檢索到的機會都沒有。

一、核心差異：兩種完全不同的「查詢」

先把最本質的差異放在最前面。

MongoDB 回答的問題是：「找出符合條件的資料。」

1
2

// 找出「業務部」所有「已完成」的任務
db.tasks.find({ department: "業務部", status: "done" })

這是精確匹配的世界：條件成立就回傳，不成立就不回傳，結果非黑即白。底層靠 B-tree 索引，本質上是排好序的目錄，查詢是「翻到那一頁」。

向量資料庫回答的問題是：「找出跟這個東西最『像』的資料。」

1
2

# 找出跟「員工請假要跑什麼流程」語意最接近的 20 個文件切塊
client.search(collection, query_vector=embed("員工請假要跑什麼流程"), limit=20)

這是相似度的世界：沒有「符合／不符合」，只有「多接近」。每筆資料是一個高維向量（我的專案用 1024 維），查詢是在這個空間裡找最近鄰。結果永遠是一個按距離排序的清單，第 1 名和第 20 名的差別只是遠近。

一句話總結：MongoDB 做的是「查找」（lookup），向量資料庫做的是「召回」（recall）。前者要的是準確命中，後者要的是語意涵蓋。

二、為什麼一般資料庫做不好向量搜尋？

「那我把向量存進 MongoDB 的欄位，查的時候自己算距離不就好了？」——可以，但會撞上兩堵牆。

第一堵牆：算距離不能用傳統索引。 B-tree 的前提是資料能排序（數字有大小、字串有字典序），但 1024 維向量之間只有「距離」沒有「順序」，B-tree 完全使不上力。不用索引的話就是暴力掃描：每次查詢跟全部向量算一次餘弦相似度——一萬筆還行，百萬筆每查一次都是災難。

第二堵牆：近似最近鄰（ANN）是門專門的學問。 向量資料庫的核心武器是 HNSW 這類 ANN 索引——用「多層跳躍圖」讓搜尋不用走訪全部節點就能找到近鄰，以極小的精度損失換取數量級的速度提升。這套索引的建構、維護、調參（精度與速度的權衡）是向量資料庫的看家本領。

此外還有 RAG 實戰很依賴的周邊能力，以我用的 Qdrant 為例：

• 一個 collection 同時放 dense + sparse 兩種向量——上一篇講的混合檢索，原生支援
• payload 過濾與向量搜尋同時做——「在『非機密』的切塊裡找最相似的」一次完成，這是我的權限系統的地基（下面細講）
• 量化壓縮、分片、向量專用的記憶體管理

公平地說：傳統資料庫陣營正在追。MongoDB Atlas 有 Vector Search、PostgreSQL 有 pgvector，小規模場景已經夠用，「順手用現有的資料庫加向量欄位」是完全合理的起點。但截至目前，混合檢索、過濾效率、向量規模化這些硬仗，專用向量資料庫仍是更穩的選擇——尤其自架（不用雲服務）的時候，MongoDB 社群版並沒有向量搜尋能力。

三、真實架構：我的專案裡兩者怎麼分工

講理論不如看實戰。我的文件問答平台資料層長這樣：

注意分工的邏輯：

Qdrant 是「可重建的索引」，MongoDB 是「事實的來源」。 向量庫裡的東西全部是從原始文件推導出來的——我的 ingest.py 甚至設計成每次重跑就清空重建整個 collection，方便「改切塊參數 → 重算 → 評測」的調校迴圈。敢這樣做正是因為向量庫裡沒有任何不可再生的資料。反過來，MongoDB 裡的對話歷史、稽核紀錄是事實本身，掉了就是掉了。這個「來源 vs 索引」的區分，是多資料庫架構最重要的心智模型。

各自發揮所長，而不是互相替代。 使用者問問題 → Qdrant 負責從幾萬個切塊裡召回最相關的 30 個；答案生成後 → 對話寫進 MongoDB；管理員要查「上週誰上傳了什麼文件」→ 純 MongoDB 條件查詢，向量庫完全不參與。硬要單邊包辦的話：MongoDB 做語意檢索做不動（自架版根本沒有），Qdrant 存對話歷史則是拿檢索引擎當業務資料庫用——payload 是給過濾用的，不是給你 CRUD 的。

權限在檢索層強制執行。 這是兩者合作最精彩的地方：每個切塊寫入 Qdrant 時都帶著 confidentiality（機密等級）payload；使用者查詢時，後端把他的權限範圍組成 Qdrant filter，向量搜尋只在他有權看的切塊中進行。沒權限的文件不是「檢索到了再過濾掉」，而是從一開始就不在搜尋範圍裡——不會漏答案位置、不會浪費召回名額、更不會在錯誤訊息裡洩漏機密文件的存在。這種「相似度搜尋 + 結構化過濾」一次完成的能力，正是向量資料庫相對於「自己算距離」的決定性優勢。

四、對照表：一次看懂

五、判斷準則：你需要哪一個？

• 只需要條件查詢、統計、業務資料 → MongoDB（或任何你熟的資料庫），跟向量無關。
• 要做語意搜尋，資料量小（幾萬筆內）、已在用 MongoDB Atlas 或 PostgreSQL → 先用 Atlas Vector Search / pgvector，別為了技術潮流多養一個服務。
• RAG 是核心功能，需要混合檢索、metadata 過濾、自架部署，或資料量會成長 → 專用向量資料庫。我選 Qdrant 的理由：docker compose 一行起服務、原生 dense+sparse 雙向量、filter 表達力強（權限系統直接建在上面）。
• 做正經的系統 → 大概率跟我一樣兩個都要：向量庫當檢索引擎，一般資料庫當事實來源。這不是架構的妥協，而是各就各位。

小結

「向量資料庫 vs MongoDB」其實是個假對立——它們一個管「像不像」、一個管「是不是」，在 RAG 系統裡是上下游的合作關係。真正要做的決定是：你的語意檢索需求，重到值得為它養一個專用引擎嗎？ 我的答案是值得——混合檢索與檢索層權限過濾這兩件事，就足以讓 Qdrant 在架構裡站穩位置。

系列下一篇的主題還在構思，可能是混合檢索與 Rerank 的深入拆解，或是檢索層權限設計的完整實作。敬請期待。

一、RAG 在解決什麼問題？

LLM 很聰明，但有三個先天限制：

1. 知識有截止日——模型訓練完成後發生的事它不知道。
2. 不知道你的私有資料——公司的規章、合約、會議記錄，模型從沒看過。
3. 會一本正經地胡說——被問到不知道的事，它傾向生成「看起來合理」的答案，而不是承認不知道。

RAG（Retrieval-Augmented Generation，檢索增強生成）的解法直觀得近乎樸素：回答之前，先把相關資料找出來塞給模型看。模型不再憑記憶作答，而是「開書考」——而且書是你指定的。

1
2

傳統 LLM：  問題 ──────────────────▶ 模型憑訓練記憶回答
RAG：      問題 ──▶ 檢索相關文件片段 ──▶ 模型根據片段回答（並標明出處）

這帶來三個直接的好處：答案有依據（可以強制標來源，錯了能追溯）、資料可以隨時更新（加文件就好，不用重訓模型）、私有資料不用送去訓練（我的專案裡 embedding 完全在本機跑，文件內容不出機器）。

二、完整管線：兩條路徑

RAG 系統有兩條獨立的資料流——建索引（把文件變成可檢索的形式，離線做）和查詢（把問題變成答案，即時做）：

1
2
3
4
5
6
7
8
9
10
11
12
13

【建索引 · Ingestion】
文件（PDF/Word/Excel/PPT/掃描檔）
  → 載入（含 OCR 判斷）
  → 切塊（chunking）
  → 向量化（embedding：dense + sparse）
  → 寫入向量資料庫（附 metadata）

【查詢 · Query】
問題 →（多輪對話時先改寫）
  → 向量化（與建索引同一顆模型！）
  → 混合檢索（dense 20 + sparse 20 → RRF 融合 → 廣撈 30）
  → Rerank 重排 → 取 top-15
  → 丟給 LLM 生成（強制標來源）

以下逐段拆解，每一段都附上我實際的做法與理由。

三、載入：文件世界比你想的髒

教學文章的 RAG 都從乾淨的純文字開始，現實裡你面對的是：有文字層的 PDF、沒有文字層的掃描 PDF、Word 裡的表格、Excel 的多工作表、PPT 的文字框。每種都要有對應的處理：

一個實用的小設計：怎麼判斷 PDF 是不是掃描檔？ 我的做法是「平均每頁字元數 < 20 就當掃描檔走 OCR」。閾值很土，但有效——有文字層的 PDF 每頁隨便都幾百字，掃描檔抽出來幾乎是空的。

四、切塊：RAG 品質的第一個決勝點

文件不能整份塞給模型（塞不下，也不精準），要切成小塊。切塊策略直接決定檢索品質，這是我整個專案裡投資報酬率最高的一個環節。

起手式：固定長度滑動視窗。 每塊 700 字、相鄰塊重疊 120 字，以字元數計（對中文最直覺），切點盡量落在自然斷點（換行 > 句末標點 > 逗號），避免硬切在詞中間。

為什麼從最笨的方法開始？先笨後巧——第一階段要驗證的是「檢索＋切塊能不能回答問題」這個大方向，固定切塊最穩、最好除錯；結構感知切塊是優化題，過早引入只會多一個出錯變數。

進化：表格列感知切塊。 固定切塊遇到表格會出災難——表格被橫向硬切，切塊開頭是上一筆資料的尾巴，「不能安全駕駛」被切成「不能安全駕/駛」，表頭和內容分家，切塊語意完全破碎。解法是先把版面文字還原成「一筆一列」的紀錄，再以固定筆數（我用 12 筆）完整列組成一個切塊，每塊都冠上表頭與文件日期，讓每個切塊能被獨立讀懂：

1
2
3
4

臺灣桃園地方檢察署公告（民國115年03月10日）偵查案件一覽
股別 | 年度 | 字別 | 案號 | 案由 | 移送機關 | 被告姓名 | 偵結要旨
律 | 115年偵字第7615號 | 家庭暴力防治 | 楊梅分局 | 黃○育 | 起訴
…（共 12 筆完整案件）

偵測不到已知表格樣式時自動退回固定長度切塊，一般文件不受影響。實測效果：答案正確率 50% → 72%（+22 個百分點）、檢索命中率 93% → 100%。 一個切塊策略的改進，比換模型、調 prompt 都有效——這是我想強調的重點：RAG 的瓶頸常常在資料工程，不在模型。

五、Embedding：把語意變成座標

Embedding 模型把文字轉成高維向量，讓「語意相近」變成「距離相近」——這是整個檢索的數學基礎。我用 bge-m3（本機執行，文件不出機器），它一次產生兩種向量：

• dense（稠密向量）：1024 維的語意向量。「請假規定」和「休假辦法」字面不同但語意近，dense 向量抓得到。
• sparse（稀疏向量）：詞彙級的權重表。專有名詞、案號、代碼這種「一字不差才算命中」的查詢，sparse 才可靠——dense 對「115年偵字第7615號」這種字串是很遲鈍的。

⚠️ 單向門：embedding 模型一旦定案就很難換

查詢時的向量必須跟建索引時用同一顆模型產生，否則兩邊的向量空間對不上，檢索結果全錯。這意味著換 embedding 模型 = 整個向量庫重算。所以選型時要想清楚，而且開發與正式環境用同一顆模型——品質一致、零重算。這是 RAG 架構裡少數「決定了就回不太了頭」的選擇。

六、檢索：混合搜尋 + 重排

單靠 dense 或單靠 sparse 都有盲區，所以用混合檢索：

1. dense 搜 20 筆 + sparse 搜 20 筆
2. 用 RRF（Reciprocal Rank Fusion）融合兩份排名——不比較兩邊的分數（量綱不同沒法比），只看名次
3. 廣撈 30 筆候選
4. 交給 reranker（bge-reranker-v2-m3）精排——它把「問題＋候選切塊」成對送進模型打分，比純向量距離準得多，但慢，所以只用在最後一哩
5. 取 top-15 進生成

這個「粗篩廣撈 → 精排收斂」的兩段式，是檢索系統的經典架構：粗篩要快、召回要廣（寧可多撈）；精排要準（把真正相關的排上來）。

七、生成：把模型鎖在證據裡

檢索到的切塊連同問題一起組成 prompt 送給 LLM（我用 Claude），關鍵的設計有兩個：

• 強制標來源：要求模型每個論點都標註出處（[1]、[2] 對應到具體文件與切塊）。這不只為了可信度——它實質上改變了模型的行為，讓它傾向「只說找得到依據的話」。
• 多輪改寫：對話中的追問常常是「那第二種呢？」這種缺乏上下文的句子，直接拿去檢索必死。所以檢索前先用 LLM 把問題改寫成獨立完整的查詢（query rewrite），這一步用 LangGraph 把「改寫 → 檢索 → 生成」串成明確的流程圖。

八、沒有評測，一切都是感覺

最後、也是最容易被跳過的一環：黃金問答集。準備一組「問題 + 標準答案 + 答案所在文件」的測試集，每次改動（換切塊策略、調檢索參數、改 prompt）都跑一遍，量兩個數字：

• 檢索命中率：正確答案所在的切塊，有沒有進到 top-k？
• 答案正確率：模型的回答對不對？

沒有這個，你只能憑感覺判斷「好像有變好」；有了它，前面提到的「表格切塊 +22pt」才有辦法被驗證。RAG 是資料工程，資料工程要量測。

小結：一張圖記住 RAG

1
2
3
4
5

     品質好壞的責任分佈（個人體感）
切塊策略 ████████████ 40%
檢索設計 ████████░░░░ 30%（混合檢索、rerank）
Embedding 選型 ████░░░░ 15%
Prompt／生成 ███░░░░░░ 15%

下一篇會深入資料層的一個常見疑問：向量資料庫和 MongoDB 到底差在哪？為什麼我的專案兩個都用？

前置需求

• macOS（防睡眠用 caffeinate；Windows 也能跑，自動走 Win32 分支）
• Python 3.10+
• 已安裝、登入完成的 claude CLI
• LINE Messaging API channel（下面申請）
• cloudflared（brew install cloudflared）

LINE 是 webhook 模式——LINE 的伺服器要能主動連到你的電腦，所以需要一個公開 HTTPS 網址。Cloudflare Tunnel 用一條 outbound 連線解決這件事：不開防火牆 port、不需要固定 IP。

一、申請 LINE channel

1. 到 LINE Developers Console 建立 Provider（沒有的話）
2. 建立 Messaging API channel
3. 記下兩樣東西：Channel secret（Basic settings 分頁）和 Channel access token（Messaging API 分頁，按 Issue）

二、設定並啟動 bot

1
2
3

git clone https://github.com/murmur-wu/claude_linebot.git ~/claude/lineBot
cd ~/claude/lineBot
cp .env.example .env

.env 至少填：

1
2
3
4
5

LINE_CHANNEL_SECRET=...
LINE_CHANNEL_ACCESS_TOKEN=...
ALLOWED_USER_IDS=          # 先留空，等下用 bot 的回覆拿自己的 id
PROJECTS=blog:/Users/you/projects/blog;work:/Users/you/projects/work
DEFAULT_PROJECT=blog

啟動（首次會自動建 .venv、裝套件）：

1

./start.sh

專案路徑建議放 ~/claude/ 這類一般目錄。放在 ~/Desktop、~/Documents、~/Downloads 的話，之後服務化會撞上 macOS 的保護目錄限制（見最後一節）。

三、Cloudflare Tunnel

先用 quick tunnel 打通流程

1

./tunnel.sh          # 會印出 https://xxxx.trycloudflare.com

quick tunnel 不用註冊、不用網域，適合驗證整條流程。缺點是網址每次重啟都會變，變了就要回 Console 更新 Webhook URL——所以打通後建議直接升級 named tunnel。

設定 Webhook URL

LINE Developers Console → 你的 channel → Messaging API 分頁：

1. Webhook URL 填 https://xxxx.trycloudflare.com/callback
2. Use webhook 打開
3. Auto-reply messages 關掉（不然官方罐頭回覆會跟 bot 打架）
4. 按 Verify → 應該回 Success

拿白名單 id

用手機加 bot 好友、傳任意訊息，bot 會直接回你的 userId（一串 U 開頭 33 字）。填進 .env 的 ALLOWED_USER_IDS，./restart.sh 重啟。這是 fail-closed 設計：名單空著時 bot 拒絕所有人，不存在「忘了設定所以全開」的狀態。

升級 named tunnel（固定網址）

前提：你有一個網域託管在 Cloudflare（免費方案即可）。

1
2

cloudflared tunnel login          # 瀏覽器授權，選你的 zone
cloudflared tunnel create linebot

建立 ~/.cloudflared/config.yml：

1
2
3
4
5
6
7

tunnel: linebot
credentials-file: /Users/<你>/.cloudflared/<tunnel-uuid>.json

ingress:
  - hostname: linebot.example.com
    service: http://127.0.0.1:8000
  - service: http_status:404

把 DNS 指到 tunnel、再啟動：

1
2

cloudflared tunnel route dns --overwrite-dns linebot linebot.example.com
./tunnel.sh          # 偵測到 config.yml 就自動跑 named tunnel

回 Console 把 Webhook URL 改成 https://linebot.example.com/callback，Verify 一次。從此網址固定，重啟也不用再碰 Console。

安全上的細節：bot 的 HOST 預設綁 127.0.0.1，只有 tunnel 進得來，不對區網開放；webhook 已內建 X-Line-Signature HMAC 驗簽，驗不過直接 400。

四、日常操作

1
2

./restart.sh              # 改完 .env 重啟（自動判斷 launchd / nohup 模式）
tail -f state/bot.log     # 看 log

重啟不會斷對話——session_id 存在 state/sessions.json。改 .env 不用重啟 tunnel（除非改了 PORT）。

五、開機自動啟動（LaunchAgent）

1

./services/install-service.sh     # 註冊 bot 與 tunnel 兩個 LaunchAgent

用的是使用者層的 LaunchAgent 而不是系統層的 LaunchDaemon——原因跟 Windows 版不能用 LocalSystem 一樣：claude CLI 的認證在 ~/.claude/，以 root 跑找不到。代價是「登入後」才啟動；要真正開機即跑，到系統設定開自動登入。

macOS 保護目錄的坑

如果專案放在 ~/Desktop、~/Documents、~/Downloads（TCC 保護目錄），launchd 會遇到一連串限制：不能 chdir 進去、不能直接 exec 裡面的執行檔、不能開啟由 Terminal 建立的既有 log 檔——而且失敗時只給 exit code 78 (EX_CONFIG)，零錯誤輸出，極難排查。

最陰險的是第三項：你先用 ./start.sh 手動跑過，state/bot.log 的存取權歸屬 Terminal；改成服務後 launchd 開不了那個檔案，服務永遠起不來。

install-service.sh 已經把能繞的都繞了（不設 WorkingDirectory、透過 /bin/sh -c 'exec …' 啟動、自動把舊 log 改名），但「launchd 啟動的程序讀取保護目錄檔案」這關必須手動授權：系統設定 → 隱私權與安全性 → 完全磁碟取用權 → 加入 <專案>/.venv/bin/python。

不想開這麼大的權限？把專案移出保護目錄（例如 ~/claude/lineBot）就完全不需要任何授權——這也是本文開頭建議 clone 到 ~/claude/ 的原因。

常見坑速查

系列回顧

• 第一篇：動機——為什麼是 LINE，三大平台難題
• 第二篇：架構——webhook 管線、回覆經濟學、兩段式附件
• 本篇：部署——LINE channel、Cloudflare Tunnel、LaunchAgent

到這裡，家裡的 Mac 就成了一台隨身可指揮的開發機：LINE 傳個訊息，Claude Code 改 code、跑指令、commit，結果回到手機上。

檔案結構

1
2
3
4
5
6
7
8
9

lineBot/
├── bot.py              ← aiohttp webhook server + 指令 + 訊息流程
├── line_client.py      ← LINE API 包裝：reply/push 路由、分段、打字動畫
├── claude_runner.py    ← async wrapper 包 `claude --print`（與 remotetools 幾乎相同）
├── attachment_store.py ← 圖片/檔案落地 + 待處理清單
├── session_store.py    ← session_id 持久化
├── usage_tracker.py    ← RPM + 每日上限 + 成本累計
├── keep_awake.py       ← macOS caffeinate / Windows SetThreadExecutionState
└── state/              ← sessions.json / usage.json / bot.log / uploads/

一則訊息的十道關卡

1
2
3
4

webhook POST ─▶ ① 驗 X-Line-Signature ─▶ ② webhookEventId 去重 ─▶ ③ 立刻回 200
            ─▶ ④ 解析 source 取兩種 key ─▶ ⑤ 白名單 ─▶ ⑥ lock（佔用即拒絕）
            ─▶ ⑦ 用量原子預留 ─▶ ⑧ spawn claude subprocess
            ─▶ ⑨ 每 55 秒續 loading animation ─▶ ⑩ 存 session、依 reply/push 規則送出

幾個關卡值得展開：

① 驗簽：對 request body 算 HMAC-SHA256（key 是 channel secret）、base64 後與 X-Line-Signature header 比對，不過直接 400。這是 webhook 模式的必要防線——你的 endpoint 在公網上，任何人都打得到。順帶一提，這也讓離線測試變得容易：自己簽一個假 webhook POST 到 127.0.0.1:8000/callback，不需要真的 LINE 就能走完整條管線。

③ 立刻回 200：LINE 要求 webhook 快速回應，逾時會重送（所以才需要②的去重）。實際處理丟進背景 asyncio task，webhook handler 永遠秒回。

⑥ lock 佔用即拒絕：這是跟 remotetools 的一個刻意分歧。Telegram/Discord 版的 per-對話鎖是排隊——前一個請求跑完，下一個接著跑。LINE 版改成直接拒絕：排隊期間 reply token 早就過期了，等排到的時候只能用付費 push 回覆，等於白花額度。與其默默扣錢，不如立刻告訴你「上一個還在跑」。

三組 key，各管各的

跟 Discord 版同一套拆法：

session_key 的規則：1:1 用 userId、群組用 groupId、聊天室用 roomId。所以你私聊問到一半的東西，不會污染群組裡的對話。

群組還有一個順序陷阱：訊息要先判斷「是不是對 bot 說的」（有沒有 claude 前綴），再做白名單檢查。順序反過來的話，群組成員正常聊天會被 bot 回「未授權」洗版——這是真實發生過才寫進文件的教訓。

回覆經濟學：ReplyContext

LINE 的計費模型：reply 免費但 token 一次性、約一分鐘失效；push 扣官方帳號的免費月額度。Claude 跑任務動輒數分鐘，所以「怎麼送回覆」需要一套決策邏輯，集中在 line_client.py 的 ReplyContext：

• 50 秒內（REPLY_TOKEN_BUDGET_SECONDS）跑完 → 用 reply，免費
• 超過 → 用 push，扣一則額度，log 會誠實印出 used a PUSH message
• reply 失敗（token 被判定失效）→ 自動 fallback 到 push，代價跟直接 push 一樣，所以 budget 可以放心用滿
• 執行中的「還在跑」提示用 loading animation——獨立 API，不算訊息、不扣額度（但只有 1:1 有效，群組裡 Claude 跑的時候畫面完全沒動靜）
• 回覆太長只送前 5 則（MAX_MESSAGE_CHUNKS），其餘存在記憶體等 /more——/more 是新訊息、帶新 reply token，免費

整套邏輯的優先序就一句話：能免費就免費。專案的 CLAUDE.md 特別警告未來的維護者（包括 AI）：不要為了程式簡潔一律改用 push。

兩段式附件：平台限制逼出來的好設計

LINE 的圖片訊息沒有 caption——圖片和說明文字是兩則獨立的 webhook 事件。收到圖就立刻跑 Claude 沒有意義（還不知道你要問什麼），所以：

1
2

你：[一張截圖]            ← bot 安靜收下，存進 state/uploads/，排進 pending
你：這個錯誤是什麼意思？   ← 文字 prompt 帶著圖的絕對路徑一起送進 Claude

可以連傳五張再一次提問，全部一起送。這裡藏著一個併發細節：每個 webhook 事件各自一個 task，五張圖是併發下載的；如果你手速快、圖剛送出就送問題，文字可能比下載先完成——所以 prompt 在取用附件前會等在途下載歸零（上限 8 秒）。拿掉這個等待，bug 只會在慢網路下出現，最難查的那種。

追問計時器與 reply token 的精算

收到圖時 bot 刻意不回「已收到」。原因還是 token 經濟學：reply token 一次性,拿去 ack 就沒了，之後想追問只能走付費 push。做法是把 token 留在一個計時器裡：

1
2
3

傳圖 ──30s──▶ 追問「請問你想問什麼？」──30s──▶ 靜默丟棄 pending
        │                    │
        └── 中途傳文字就取消計時器，圖照樣一起送 ──┘

追問本身就兼任 ack，而且用的是留下來的免費 token。追問後仍無下文就靜默丟棄（不發通知——那時 token 已用掉，通知會是一則付費 push）。磁碟上的檔案另由背景任務清理（預設保留 3 天，每 6 小時掃一次）。

一個真實的 bug：64KB 的 readline 上限

claude_runner.py 本來跟 remotetools 逐字元相同，但圖片支援逼出了一個分叉：Claude 讀圖時，stream-json 會把整張圖的 base64 塞進同一行 JSON，遠超 asyncio readline 預設的 64KB 上限——LimitOverrunError 拋出、整個請求靜默崩潰，使用者只看到「沒反應」。修法是 create_subprocess_exec 加上 limit=64MB，並把該例外收成明確的錯誤訊息。remotetools 沒有圖片支援所以永遠碰不到這個 bug——同一份程式碼，新的使用情境挖出了潛伏的地雷。

其他移植差異速覽

下一篇實戰：從 LINE Developers Console 到 Cloudflare Tunnel，把整套系統部署起來。

這是系列文的第一篇，先講這個專案是什麼、能做什麼；之後兩篇分別深入底層邏輯和部署教學。

它解決什麼問題

Claude Code 是跑在終端機裡的 AI coding agent，能讀寫檔案、跑指令、操作 git。但它只活在你的電腦上——人不在電腦前就用不了。

remotetools 把這個能力延伸到手機上：跑一個常駐的 Telegram 或 Discord bot，把你傳的訊息丟進本機的 claude CLI，再把回應切片傳回手機。

1
2
3
4
5
6

你 (📱)  ──訊息──▶  Telegram / Discord  ──polling──▶  bot.py  ──subprocess──▶  claude --print
                                                         ▲                          │
                                                         └──── stdout JSON ─────────┘
                                                         │
                                                         ▼
                                                   家裡的 repo（自動 edit / git / build）

重點特性：

• 對話有記憶：每段對話對應一個持續存活的 Claude session，用 --resume 接續脈絡，不是每句話都從零開始。
• 多專案切換：.env 裡定義多個 project（就是 working directory），用指令隨時切換 bot 要操作哪個 repo。
• 即時進度：Claude 跑任務的過程中，bot 會每兩秒更新一則訊息，顯示它正在呼叫哪些工具（讀檔、跑指令…），不是傻等到跑完。
• 配額保護：內建每分鐘與每日訊息上限，防止失控迴圈半小時燒光 Claude Max 的五小時配額。

支援平台

兩個平台是各自獨立的 Python app，各有自己的 .venv 和 .env，可以只跑一個或同時跑。有趣的設計決策是：兩邊有四個 byte-identical 的共用模組，但刻意不抽成共用 package——這個取捨在下一篇會細講。

指令一覽

不帶前綴的純訊息就是直接送給 Claude 的 prompt。

安全模型：一句話總結

這個 bot 等於把「在你電腦上執行任意動作的能力」開放到網路上，所以安全設計是 fail-closed 的：

1. 白名單是唯一的信任邊界——ALLOWED_CHAT_IDS / ALLOWED_USER_IDS 留空時 bot 拒絕所有人，永遠不要為了方便測試關掉它。
2. 權限模式只有兩種能用——bot 沒有 stdin，Claude 問「可以執行嗎？」沒人能回答，所以互動式權限模式會直接卡死。推薦 bypassPermissions（全放行，信任完全押在白名單上）。
3. 用量上限不是防別人，是防自己——自動化呼叫比人手快得多，預設每日 100 則、每分鐘 6 則。

系列文章

• 本篇：專案是什麼、能做什麼
• 第二篇：底層邏輯——訊息生命週期、session 管理、streaming、並發防護
• 第三篇：部署教學——從零架起來，含 Windows 服務化