stark 完整教學

Repository: https://github.com/snap-stanford/stark Stars: 334 | Language: Python | License: MIT 論文: STaRK: Benchmarking LLM Retrieval on Textual and Relational Knowledge Bases（NeurIPS 2024 Datasets & Benchmarks Track） 官網: https://stark.stanford.edu/ ｜ PyPI: stark-qa ｜ Leaderboard: HuggingFace Space

1. 專案概覽 (Project Overview)

1.1 專案背景、研究團隊與動機

STaRK（Semi-structured Retrieval Benchmark，STaRK; 半結構化檢索基準）是由 Stanford SNAP（Stanford Network Analysis Project; 史丹佛網路分析計畫）實驗室（Jure Leskovec 團隊）與 Amazon 合作發表的大規模檢索評測基準（benchmark; 基準測試），於 2024 年 NeurIPS Datasets & Benchmarks Track 發表。

作者群橫跨學界與業界：Shirley Wu、Shiyu Zhao、Michihiro Yasunaga、Kexin Huang、Kaidi Cao、Qian Huang（Stanford），以及 Vassilis N. Ioannidis、Karthik Subbian（Amazon），James Zou、Jure Leskovec（Stanford）。這個組合本身就透露了專案動機：Amazon 電商搜尋、學術論文檢索、生醫知識庫查詢這三個真實場景都同時面臨「使用者問題既包含自然語言語意，又隱含結構化關聯條件」的難題。

舉例來說，一個真實使用者可能會問：

「幫我找近三年內、由史丹佛某位教授指導、跟蛋白質摺疊有關、且被引用超過 50 次的論文」

這句話裡同時混雜了：

• 文字語意條件（textual condition; 文字條件）：跟蛋白質摺疊有關
• 關聯／結構化條件（relational condition; 關聯條件）：由某位教授指導、發表時間、引用數

傳統的 RAG（Retrieval-Augmented Generation; 檢索增強生成）系統多半只針對「文字相似度」做向量檢索，難以同時處理圖結構中的多跳關聯（multi-hop relation; 多跳關聯）與數值篩選條件。STaRK 正是為了量化評估 LLM（Large Language Model; 大型語言模型）驅動的檢索系統，在這種「文字 + 關聯」混合查詢上到底表現如何而生。

1.2 解決什麼問題、為什麼重要

STaRK 想解決的核心問題是：現有的檢索評測基準（如傳統 IR benchmark、單純向量檢索評測）都低估了真實世界查詢的複雜度。真實查詢通常同時涉及：

1. 自然語言描述的語意需求
2. 結構化知識庫（knowledge base; 知識庫）中的關聯路徑
3. 屬性篩選（如日期、價格、評分等數值/類別條件）

STaRK 提出的解法是建構三個半結構化知識庫（Semi-structured Knowledge Base, SKB; 半結構化知識庫）：

每個知識庫都是「文字內容（節點文件）+ 圖結構（節點與邊的關聯）」的混合體，並搭配大量自然、實用、貼近真實使用情境的查詢（query），其中一部分還經過人工撰寫（human-generated queries）以確保問題的自然度與難度。

這個問題之所以重要，是因為它直接對應到工業界正在部署的場景：企業內部知識庫問答、電商智能客服、學術文獻助理、藥物研發知識查詢——這些系統的核心痛點，正是「LLM 能不能理解結構化關聯，而不只是做語意相似度匹配」。

1.3 在 snap-stanford 生態系中的定位

snap-stanford 組織（GitHub org）長期深耕圖神經網路（Graph Neural Network, GNN; 圖神經網路）、知識圖譜（Knowledge Graph, KG; 知識圖譜）與生醫 AI 領域，代表作包括 PyG（PyTorch Geometric）、OGB（Open Graph Benchmark）、PrimeKG、TxGNN 等。STaRK 可以視為這個生態系中「檢索評測層」的關鍵拼圖——它銜接了：

• 圖資料層（PrimeKG 等知識圖譜）
• LLM 應用層（RAG、Agent 檢索）

STaRK 把 SNAP 實驗室長年累積的圖資料工程能力，轉化為一套可以量測「LLM + 檢索」系統效能的標準化評測協議，填補了 GNN 研究與 LLM 應用研究之間的橋樑。

1.4 相關論文引用

 1@inproceedings{wu24stark,
 2    title        = {STaRK: Benchmarking LLM Retrieval on Textual and Relational Knowledge Bases},
 3    author       = {
 4        Shirley Wu and Shiyu Zhao and
 5        Michihiro Yasunaga and Kexin Huang and
 6        Kaidi Cao and Qian Huang and
 7        Vassilis N. Ioannidis and Karthik Subbian and
 8        James Zou and Jure Leskovec
 9    },
10    booktitle    = {NeurIPS Datasets and Benchmarks Track},
11    year         = {2024}
12}

論文全文：https://arxiv.org/abs/2404.13207

2. 核心架構 (Core Architecture)

2.1 系統架構圖

STaRK 的整體架構可以分成四層：資料層 → 知識庫抽象層 → 檢索模型層 → 評測層。

flowchart TB
    subgraph L1["資料層 (Data Layer)"]
        A1["Amazon 產品資料"]
        A2["MAG 學術圖譜"]
        A3["PrimeKG 生醫知識圖譜"]
    end

    subgraph L2["知識庫抽象層 (SKB Layer)"]
        B["SKB 基底類別
(node_info + edge_index)"]
        B1["AmazonSKB"]
        B2["MAGSKB"]
        B3["PrimeSKB"]
    end

    subgraph L3["檢索模型層 (Retrieval Models)"]
        C1["BM25
(稀疏關鍵字檢索)"]
        C2["VSS
(向量相似度檢索)"]
        C3["MultiVSS
(分塊向量檢索)"]
        C4["Colbertv2
(晚期互動檢索)"]
        C5["LLMReranker
(LLM 重排序)"]
        C6["HybridRetriever
(RRF 融合)"]
    end

    subgraph L4["評測層 (Evaluation Layer)"]
        D1["Evaluator
(Hit@k / MRR / Recall)"]
        D2["eval.py
(CLI 評測入口)"]
    end

    A1 --> B1 --> B
    A2 --> B2 --> B
    A3 --> B3 --> B

    B --> C1
    B --> C2
    B --> C3
    B --> C4
    B --> C5
    C1 & C2 --> C6

    C1 --> D1
    C2 --> D1
    C3 --> D1
    C4 --> D1
    C5 --> D1
    C6 --> D1
    D1 --> D2

2.2 關鍵模組、類別與資料流說明

從 repo 目錄結構可以清楚看到模組分工（節錄自 stark_qa/）：

 1stark_qa/
 2├── skb/                    # 知識庫（Semi-structured Knowledge Base）
 3│   ├── knowledge_base.py   # SKB 基底類別
 4│   ├── amazon.py           # AmazonSKB
 5│   ├── mag.py              # MAGSKB
 6│   └── prime.py            # PrimeSKB
 7├── models/                 # 檢索模型
 8│   ├── base.py             # ModelForSTaRKQA 基底類別
 9│   ├── bm25.py              # BM25 稀疏檢索
10│   ├── vss.py               # VSS 向量相似度檢索
11│   ├── multi_vss.py         # MultiVSS 分塊檢索
12│   ├── colbertv2.py         # ColBERTv2 晚期互動檢索
13│   ├── llm_reranker.py      # LLM 重排序
14│   └── hybrid.py            # HybridRetriever（社群貢獻的融合檢索）
15├── retrieval/
16│   └── dataset.py           # QA 資料集載入與 split 管理
17├── tools/
18│   ├── graph.py              # k-hop 子圖抽取
19│   ├── llm_lib/               # 多家 LLM API 封裝（Claude/GPT/HuggingFace）
20│   └── ...
21├── load_qa.py                # QA 資料集載入入口
22├── load_skb.py                # SKB 知識庫載入入口
23├── load_model.py              # 檢索模型工廠函式
24└── evaluator.py                # 評測指標計算

資料流（一次完整評測的路徑）：

1. load_skb(dataset_name) 讀入知識庫（節點資訊 node_info + 圖結構 edge_index），必要時自動從 HuggingFace 下載已處理好的資料。
2. load_qa(dataset_name) 讀入該資料集對應的查詢資料集（QA pairs），並提供官方 train/val/test 切分（split）。
3. load_model(args, skb) 依照 --model 參數實例化對應的檢索模型（VSS / BM25 / HybridRetriever 等）。
4. 檢索模型的 forward(query, query_id) 輸出一個 候選節點 id -> 分數 的字典。
5. Evaluator 依照分數排序計算 Hit@k、MRR（Mean Reciprocal Rank; 平均倒數排名）、Recall@k 等指標。
6. 結果寫入 output/eval/{dataset}/{model}/eval_metrics_{split}.json。

2.3 設計哲學與技術選擇分析

STaRK 的設計哲學可以歸納為三個關鍵字：解耦（decoupling）、可擴充（extensibility）、可重現（reproducibility）。

1. 知識庫與檢索模型解耦：SKB 基底類別統一定義了 node_info（節點文字資訊）與 edge_index（PyG 格式的邊索引），任何新的檢索模型只需依賴這個抽象介面，不需要知道底層是 Amazon 產品圖還是生醫知識圖譜。這是典型的**依賴反轉（Dependency Inversion）**設計，讓新增資料集或新增模型都不需要動到對方的程式碼。

2. 模型可插拔（pluggable model）：所有檢索模型都繼承 ModelForSTaRKQA 基底類別，只需實作 forward() 回傳分數字典。這讓社群貢獻新模型的門檻很低——例如社群後續貢獻的 HybridRetriever 就只新增了 1 個檔案、修改了約 20 行既有程式碼即完成整合（詳見 docs/HYBRID_RETRIEVER.md）。

3. 資料下載與處理分離：load_skb(download_processed=True) 預設直接從 HuggingFace 下載已處理好的資料（省去長達一小時的原始資料前處理），但同時保留 download_processed=False 選項，讓研究者可以查驗、重現前處理流程——這是兼顧易用性與透明度／可重現性的取捨。

4. embedding 快取與解耦：查詢與文件的 embedding（向量嵌入）預先計算並存成 .pt 檔（candidate_emb_dict.pt），評測時直接載入而非重新呼叫 API——這大幅降低了跑評測的成本與變異性，也讓不同研究者用同一份 embedding 比較不同的排序演算法時具備公平的比較基礎。

3. 安裝與設定 (Installation & Setup)

3.1 環境需求

• Python: >=3.8, <3.12（注意：不支援 3.12+，這點在做環境規劃時要留意）
• GPU：非必要但強烈建議。向量相似度計算（VSS）與 embedding 生成在 GPU 上速度差距明顯；--device cuda 為預設值
• 磁碟空間：STaRK-Amazon / STaRK-MAG 前處理需下載較大原始資料（若不用 download_processed=True 可能需要數 GB 空間 + 約 1 小時處理時間）；STaRK-Prime（PrimeKG）約 5 分鐘可下載處理完成

3.2 完整安裝步驟

方式一：pip 安裝（推薦，符合本機工具鏈 uv 慣例可用 uv pip）

1# 建議在隔離環境中安裝，遵循 uv 優先原則
2uv venv stark-env --python 3.11
3source stark-env/bin/activate
4uv pip install stark-qa

方式二：從原始碼安裝

1git clone https://github.com/snap-stanford/stark.git
2cd stark
3
4conda create -n stark python=3.11
5conda activate stark
6pip install -r requirements.txt

若要跑評測（evaluation），額外安裝檢索模型相依套件：

1pip install llm2vec gritlm bm25

3.3 資料集下載與準備

STaRK 的資料集透過 HuggingFace Datasets 自動管理快取，最簡單的方式是直接在 Python 中呼叫：

 1from stark_qa import load_qa, load_skb
 2
 3dataset_name = 'amazon'  # 可選: 'amazon', 'mag', 'prime'
 4
 5# 載入檢索任務的 QA 資料（自動下載至 data/{dataset}/stark_qa）
 6qa_dataset = load_qa(dataset_name)
 7idx_split = qa_dataset.get_idx_split()  # 取得官方 train/val/test 切分
 8
 9# 載入半結構化知識庫（自動從 HuggingFace 下載已處理資料）
10skb = load_skb(dataset_name, download_processed=True, root=None)

• root=None 時資料預設存放在 HuggingFace cache（~/.cache/huggingface/）
• 若要跑評測，還需下載或生成 embedding：

1# 下載官方提供、由 text-embedding-ada-002 產生的查詢與文件 embedding
2python emb_download.py --dataset amazon --emb_dir emb/
3
4# 或自行生成 embedding（需對應 API key）
5python emb_generate.py --dataset amazon --mode query --emb_dir emb/ --emb_model text-embedding-ada-002

emb_generate.py 支援的 emb_model 包含 text-embedding-ada-002、text-embedding-3-large、voyage-large-2-instruct、GritLM/GritLM-7B、McGill-NLP/LLM2Vec-Meta-Llama-3-8B-Instruct-mntp 等多種嵌入模型。

3.4 資料集層級預設參數：config/default_args.json

STaRK 用一份簡單的 JSON 設定檔管理各資料集特有的預設參數，避免在 CLI 呼叫時每次都要手動指定：

 1{
 2    "mag": {
 3        "chunk_size": 256,
 4        "multi_vss_topk": 50
 5    },
 6    "prime": {
 7        "chunk_size": 256,
 8        "multi_vss_topk": 50
 9    },
10    "amazon": {
11        "chunk_size": 256,
12        "multi_vss_topk": 50
13    }
14}

eval.py 執行時會先讀入 CLI 參數，再用 merge_args() 把這份資料集層級的預設值（如 MultiVSS 分塊大小 chunk_size、每個查詢要聚合的分塊數 multi_vss_topk）合併進去——CLI 參數優先權高於設定檔預設值，這是一個很值得參考的「合理預設值 + 可覆寫」設計模式：三個資料集目前用的都是相同預設（chunk_size=256, multi_vss_topk=50），但架構上已經預留了未來針對不同資料集特性做差異化調校的彈性。

3.5 測試實務：tests/test_hybrid.py

STaRK 對社群貢獻的 HybridRetriever 附上了單元測試，展示了對核心演算法邏輯（而非只測試 I/O）做測試的實務做法，這與本機專案 Python 測試規範（pytest + 覆蓋率）的精神一致：

 1class TestRRFLogic:
 2    """驗證 Reciprocal Rank Fusion 的核心計算邏輯"""
 3
 4    def test_rrf_formula(self):
 5        """驗證 RRF 分數公式：排名越前面分數越高"""
 6        k = 60
 7        rrf_rank1 = 1.0 / (k + 1)
 8        rrf_rank10 = 1.0 / (k + 10)
 9        rrf_rank100 = 1.0 / (k + 100)
10
11        assert rrf_rank1 > rrf_rank10 > rrf_rank100
12        assert abs(rrf_rank1 - 1/61) < 1e-6
13
14
15class TestFusionMethods:
16    """驗證融合方法的邊界行為"""
17
18    def test_weighted_fusion_alpha_bounds(self):
19        """驗證 alpha 在邊界值時能正確退化為單一檢索器"""
20        bm25_score, vss_score = 1.0, 0.0
21
22        # alpha = 0 -> 完全退化為純 BM25
23        assert (1 - 0.0) * bm25_score + 0.0 * vss_score == 1.0
24
25        # alpha = 1 -> 完全退化為純 VSS
26        assert (1 - 1.0) * bm25_score + 1.0 * vss_score == 0.0

這個測試設計的亮點在於：針對演算法的數學性質做斷言，而不是只測「跑起來沒有 crash」——例如驗證 alpha=0 時融合結果必須完全等同純 BM25、alpha=1 時必須完全等同純 VSS，這種「邊界值退化為已知簡單情況」的測試策略，是驗證融合類演算法正確性的常見且有效手法，值得在 AIKT 內部任何涉及加權融合、多路徑聚合的邏輯（例如未來若要對 paper-search 的多資料庫結果做加權合併）中複用。

3.6 常見問題排解

4. 核心概念詳解 (Key Concepts)

4.1 SKB：半結構化知識庫

想像一個傳統的搜尋引擎索引，只認得「文字」；而一個純粹的圖資料庫，只認得「節點與邊的連線」。SKB（Semi-structured Knowledge Base）是把這兩者黏在一起的資料結構——每個節點（node）既有文字內容（例如一篇論文的摘要、一個產品的描述），也有明確的關聯（例如「這篇論文引用了那篇論文」、「這個產品屬於哪個類別」）。

用類比來說，SKB 就像一本帶有超連結的百科全書：你讀到「蛋白質摺疊」這個詞條時，不只看得到文字說明，還能沿著超連結跳到「相關基因」「相關疾病」「相關論文」等節點——而這些連結的類型（type）本身也是有意義的結構化資訊。

flowchart LR
    subgraph sg1["SKB 節點示例（PrimeKG）"]
        N1["蛋白質 X
(文字：功能描述)"]
        N2["疾病 Y
(文字：症狀描述)"]
        N3["藥物 Z
(文字：作用機制)"]
    end
    N1 -->|"associated_with
(關聯邊)"| N2
    N3 -->|"treats
(治療邊)"| N2
    N1 -->|"targeted_by
(靶向邊)"| N3

4.2 查詢類型：文字 + 關聯的混合查詢

STaRK 的查詢刻意設計成同時包含語意條件與關聯條件，例如：

• 純語意查詢：「有沒有推薦的輕量健行鞋？」
• 混合查詢：「我要找跟某款登山鞋同一品牌、評價 4 星以上、適合雨天穿的鞋款」

後者要求檢索系統不只是做文字相似度匹配，還要**沿著圖結構做多跳推理（multi-hop reasoning; 多跳推理）**並套用屬性篩選——這正是傳統向量檢索最弱的地方。

4.3 檢索模型光譜：從稀疏到 LLM 驅動

STaRK 內建的檢索模型可以放在一個「計算成本 vs. 語意理解力」的光譜上理解：

flowchart LR
    A["BM25
稀疏關鍵字比對
(最快/最省)"] --> B["VSS
向量相似度
(語意理解)"]
    B --> C["MultiVSS
分塊向量檢索
(處理長文件)"]
    C --> D["ColBERTv2
晚期互動檢索
(細粒度比對)"]
    D --> E["HybridRetriever
RRF 融合
(稀疏+密集)"]
    E --> F["LLMReranker
LLM 重排序
(最貴/最準)"]

• BM25：經典的 TF-IDF 系列稀疏檢索算法，靠關鍵字詞頻與逆文件頻率打分，優點是快、可解釋，缺點是完全不懂語意（例如「摺疊」跟「构象」語意相近但字面不同，BM25 抓不到）。
• VSS（Vector Similarity Search; 向量相似度檢索）：把查詢與文件都投影到同一個 embedding 空間，用內積或餘弦相似度打分，能捕捉語意相近但字面不同的匹配，但對精確關鍵字（如型號、專有名詞）可能反而不夠敏感。
• MultiVSS：文件過長時先切塊（chunk）分別做 embedding，再聚合分數（aggregate='max' 等策略），解決長文件被單一 embedding 稀釋語意的問題。
• LLMReranker：先用便宜的方法（如 VSS）撈出候選集，再讓 LLM 針對每個候選做細緻的相關性判斷並重新排序——準確率最高但成本也最高。
• HybridRetriever（社群貢獻）：見 4.4 節詳解。

4.4 RRF 融合：HybridRetriever 的核心概念

HybridRetriever 是社群針對 STaRK 的一個實際貢獻案例（見 docs/HYBRID_RETRIEVER.md），它用 Reciprocal Rank Fusion（RRF; 倒數排名融合） 演算法，把 BM25（稀疏）與 VSS（密集）的檢索結果融合成一個分數：

$$ \text{RRF_score}(d) = \alpha \times \frac{1}{k + \text{rank}{VSS}(d)} + (1-\alpha) \times \frac{1}{k + \text{rank}{BM25}(d)} $$

用直觀的方式理解：每個檢索器各自對文件排名，排名越前面貢獻的分數越高，但分數增長是「倒數」關係而非線性——這樣即使兩個檢索器的原始分數尺度完全不同（BM25 分數可能是 050，VSS 分數是 01），也不需要做尺度校正，直接用排名位置本身做融合。這正是業界（Elasticsearch、Pinecone、Weaviate）採用 RRF 而非直接加權平均分數的原因——排名比原始分數更穩健。

其中 α（alpha）控制語意檢索與關鍵字檢索的權重比例，k（RRF 常數，預設 60）則是平滑因子，避免排名第 1 名與第 2 名的分數差距過度放大。

4.5 評測指標：Hit@k、MRR、Recall@k 三兄弟

STaRK 的 Evaluator 採用資訊檢索領域的標準指標組合，理解這三個指標的差異對解讀評測結果至關重要：

用類比理解：如果把檢索結果想像成一份排好名次的候選名單，Hit@k 像是問「及格名單裡有沒有他」，MRR 像是「他排第幾名，名次越前面越加分」，而 Recall@k 則是「這次考試有 5 位及格者，及格名單裡抓到了幾位」。三者合併使用，才能同時掌握「有沒有找到」「排得夠不夠前面」「找得夠不夠齊全」這三個不同面向。

4.6 為什麼「人工生成查詢」（human-generated queries）很重要

STaRK 除了用模板 + LLM 自動生成大量查詢外，額外提供三個小規模但經人工撰寫與校對的查詢資料集（human_generated_eval split）。這個設計背後的洞察是：自動生成的查詢容易帶有系統性偏差（例如句型單一、用詞重複、難度分佈不均），如果評測完全依賴自動生成的查詢，很容易讓某些檢索方法「恰好」利用了生成模板的規律性而拿到虛高的分數，卻無法反映真實使用者的提問習慣。人工查詢集雖然規模小，但提供了一個更貼近真實分佈的「試金石」，用來交叉驗證自動生成查詢集上的評測結論是否可靠。

5. 使用方式與程式碼範例 (Usage & Code Examples)

5.1 基礎用法：載入資料並探索知識庫

 1from stark_qa import load_qa, load_skb
 2
 3# 1. 載入 STaRK-Amazon 的 QA 資料集
 4qa_dataset = load_qa('amazon')
 5idx_split = qa_dataset.get_idx_split()
 6print(f"Train: {len(idx_split['train'])}, "
 7      f"Val: {len(idx_split['val'])}, "
 8      f"Test: {len(idx_split['test'])}")
 9
10# 2. 載入知識庫（自動下載已處理版本）
11skb = load_skb('amazon', download_processed=True)
12print(f"知識庫節點總數: {len(skb)}")
13
14# 3. 隨機看一個查詢範例
15query, query_id, answer_ids, meta_info = qa_dataset[0]
16print(f"查詢內容: {query}")
17print(f"正確答案節點 id: {answer_ids}")
18
19# 4. 查看知識庫中一個節點的文件內容
20doc_text = skb.get_doc_info(answer_ids[0], add_rel=True)
21print(f"對應節點文件:\n{doc_text}")

5.2 進階用法：跑一次完整的 VSS 評測

首先下載官方提供的預算 embedding，再執行評測腳本：

 1# Step 1: 下載官方 embedding（避免自己重新呼叫 API）
 2python emb_download.py --dataset amazon --emb_dir emb/
 3
 4# Step 2: 用 VSS 模型評測（純向量相似度檢索）
 5python eval.py \
 6    --dataset amazon \
 7    --model VSS \
 8    --emb_dir emb/ \
 9    --output_dir output/ \
10    --emb_model text-embedding-ada-002 \
11    --split test \
12    --save_pred

評測完成後，結果會寫入：

• output/eval/amazon/VSS/text-embedding-ada-002/eval_results_test.csv（每筆查詢的詳細預測）
• output/eval/amazon/VSS/text-embedding-ada-002/eval_metrics_test.json（彙總指標，如 Hit@1、Hit@5、MRR、Recall@20）

5.3 用 LLM 重排序（LLMReranker）並整合 Claude API

 1# 設定 API key（依 CLAUDE.md 安全規範，應放在 .env 或環境變數，不可硬編碼）
 2export ANTHROPIC_API_KEY=$YOUR_ANTHROPIC_API_KEY
 3
 4python eval.py \
 5    --dataset amazon \
 6    --model LLMReranker \
 7    --emb_dir emb/ \
 8    --output_dir output/ \
 9    --emb_model text-embedding-ada-002 \
10    --split human_generated_eval \
11    --llm_model claude-3-5-sonnet-20241022 \
12    --save_pred

值得注意的是 stark_qa/tools/llm_lib/completion/claude.py 專門封裝了 Claude API 呼叫邏輯，說明 STaRK 從一開始就把 Anthropic 模型系列納入官方支援的重排序 LLM 選項，這對已經在使用 Claude 生態的團隊（如企業內部知識庫問答場景）相當友善。

5.4 範例三：使用 HybridRetriever 融合稀疏與密集檢索

1# 基本用法：預設 alpha=0.5（語意/關鍵字各半）
2python eval.py --dataset amazon --model HybridRetriever \
3    --emb_dir emb/ --split test
4
5# 調整為更偏重語意檢索
6python eval.py --dataset amazon --model HybridRetriever \
7    --emb_dir emb/ --hybrid_alpha 0.7 --split test \
8    --hybrid_fusion rrf --hybrid_rrf_k 60 --hybrid_bm25_topk 100

若想在 Python 中直接呼叫，不透過 CLI：

 1from stark_qa import load_qa, load_skb
 2from stark_qa.models.hybrid import HybridRetriever
 3
 4skb = load_skb('amazon', download_processed=True)
 5qa_dataset = load_qa('amazon')
 6
 7model = HybridRetriever(
 8    skb=skb,
 9    query_emb_dir='emb/amazon/text-embedding-ada-002/query',
10    candidates_emb_dir='emb/amazon/text-embedding-ada-002/doc',
11    emb_model='text-embedding-ada-002',
12    alpha=0.6,
13    rrf_k=60,
14    fusion_method='rrf',
15    bm25_top_k=100,
16    device='cuda'
17)
18
19query, query_id, answer_ids, meta_info = qa_dataset[0]
20pred_dict = model.forward(query, query_id)
21top5 = sorted(pred_dict.items(), key=lambda x: -x[1])[:5]
22print(f"Top-5 預測節點: {top5}")

6. 進階應用場景 (Advanced Use Cases)

6.1 真實世界應用案例

1. 企業內部知識庫問答：把公司內部的產品文件、工單記錄、組織架構圖建成一個 SKB，用 HybridRetriever 或 LLMReranker 回答「哪個團隊負責跟 X 客戶對接、且最近有處理過退貨問題」這類混合查詢。
2. 學術文獻探索工具：仿照 STaRK-MAG 的架構，把內部文獻庫（含引用關係、作者關係）建成 SKB，供研究者做「找出跟某篇論文主題相近、且被同一群作者引用」的查詢。
3. 藥物研發知識查詢：STaRK-Prime 直接基於 PrimeKG，可作為藥物-疾病-基因關聯查詢的評測基礎，適合藥物研發流程中的知識檢索模組驗證（與本機 AIKT L19 tu-plan-generator 的 ChEMBL/藥物開發場景高度相關，見第 7 節分析）。

6.2 與其他 snap-stanford 工具的整合

STaRK 的 SKB 資料結構直接使用 PyTorch Geometric（PyG）的 edge_index 格式，因此可以無縫接上 SNAP 生態系其他工具：

• PrimeKG：STaRK-Prime 本身就是 PrimeKG 的下游應用，可直接沿用 PrimeKG 的節點/邊 schema
• PyG GNN 模型：由於 SKB 的圖結構是標準 PyG 格式，理論上可以訓練 GNN 做節點分類或連結預測，再把 GNN 的表徵（representation）作為額外特徵餵給 VSS 或 HybridRetriever，形成「GNN 增強檢索」的混合方案

6.3 效能調校與最佳實踐

• embedding 快取先行：務必先用 emb_download.py 或 emb_generate.py 產生並持久化 embedding，避免每次評測都重新呼叫付費 API——這對控制 token/API 成本至關重要
• 先用便宜模型篩選再用 LLM 精修：LLMReranker 的 --llm_topk 參數控制只對 top-k 候選做 LLM 重排序，建議先用 VSS/BM25/HybridRetriever 縮小候選集到 10~20 筆，再交給 LLM，可大幅降低成本
• RRF 參數調校：hybrid_alpha 建議先用 test-0.1（10% 抽樣測試集）快速掃過 0.3/0.5/0.7 幾個值找出最佳平衡點，再用完整 test split 做正式評測，避免每次調參都跑全量資料
• batch_size 依 GPU 記憶體調整：--batch_size 預設 256，大型候選集或大 embedding 維度時應調低，避免 CUDA OOM

7. 與 AIKT 的關聯分析 (AIKT Integration Analysis)

7.1 此專案可作為 AIKT 的資料來源或分析工具嗎？

可以，且有兩個明確的切入角度：

1. 作為「檢索評測方法論」的參考資料來源：STaRK 的論文與程式碼本身就是很好的 ai-gh-save（L2）收錄對象——它提供了一套嚴謹的、可量化的檢索系統評測框架，對 AIKT 自身未來若要評估 paper-qa-lite（L10，本地文獻 RAG 問答）或 graphify（L4，知識圖譜索引）的檢索品質時，STaRK 的評測指標設計（Hit@k / MRR / Recall@k）與混合查詢構造方法可直接借鏡。

2. 作為知識庫抽象設計的範例：STaRK 的 SKB 基底類別（node_info + edge_index 解耦設計）示範了「文字內容 + 圖結構」統一建模的做法，這正好對應 AIKT graphify（L4，知識圖譜建索引）與 gitnexus（L6，程式碼符號圖）想解決的問題——如何把非結構化文字與結構化關聯統一放進同一個可查詢的資料結構。

7.2 AIKT 的哪些 Layer 可以包裝或編排此專案

flowchart TB
    subgraph AIKT["AIKT 相關 Layer"]
        L2["L2 ai-gh-save
收錄 STaRK repo+論文"]
        L4["L4 graphify
知識圖譜設計參考"]
        L9["L9 paper-search
檢索 STaRK 後續引用論文"]
        L10["L10 paper-qa-lite
評測方法論借鏡"]
        L19["L19 tu-plan-generator
PrimeKG 生醫檢索場景"]
        L12["L12 gh-tutorial-qd
本教學文件產出"]
    end

    subgraph STARK["STaRK 專案"]
        S1["SKB 抽象設計"]
        S2["檢索模型光譜
BM25→VSS→LLMReranker"]
        S3["Evaluator 指標
Hit@k/MRR/Recall"]
        S4["STaRK-Prime
(PrimeKG 生醫)"]
    end

    L2 --> STARK
    STARK --> S1
    STARK --> S2
    STARK --> S3
    STARK --> S4

    S1 -.參考.-> L4
    S2 -.參考.-> L10
    S3 -.參考.-> L10
    S4 -.場景關聯.-> L19
    L2 --> L12

• L2 ai-gh-save：直接收錄此 repo 與論文摘要進 inbox/，作為未來檢索評測相關工作的知識底座
• L4 graphify：STaRK 的 SKB 抽象（文字 + 圖結構統一建模）可作為 graphify 索引架構設計的參考範例，尤其是「節點文件生成」（get_doc_info，可含關聯資訊 add_rel=True）的做法
• L9/L10 paper-search / paper-qa-lite：STaRK 的評測指標（Hit@k、MRR、Recall@k）與混合查詢構造思路，可用來設計 AIKT 內部檢索工具的品質評測協議——例如評估 paper-qa-lite 在「文字語意 + metadata 篩選（作者/年份/期刊）」混合查詢下的表現
• L19 tu-plan-generator：STaRK-Prime 基於 PrimeKG，與 L19 藥物開發計畫生成（整合 ChEMBL/SMILES）處理的生醫知識領域高度重疊，若未來需要驗證藥物-疾病關聯查詢的檢索能力，STaRK-Prime 的資料與評測腳本可直接複用
• L12 gh-tutorial-qd：本教學文件本身即是此 Layer 的產出範例

7.3 潛在整合場景與價值

1. 檢索品質健檢框架：把 STaRK 的 Evaluator（Hit@k/MRR/Recall）抽取出來，包裝成 AIKT 內部工具，定期對 graphify 產出的知識圖譜查詢品質做量化評測，取代目前僅靠人工判斷的檢索效果驗證方式
2. 混合查詢語料庫借鏡：STaRK 的「文字 + 關聯」混合查詢構造方法，可用來設計 AIKT 內部測試集，驗證 paper-qa-lite 面對「找出某作者 2023 年後跟 CRISPR 相關且引用數 >20 的論文」這類混合條件查詢時的實際表現
3. HybridRetriever 融合思路的移植：AIKT 目前的知識檢索多半依賴單一策略（向量檢索或關鍵字），STaRK 社群貢獻的 RRF 融合方法論可作為未來優化 paper-qa-lite 檢索精準度的技術參考——不需要真的整合 STaRK 程式碼，而是借鏡其演算法設計

價值定位：STaRK 對 AIKT 而言，主要價值不在於「直接串接執行」（兩者的資料型態與應用場景不同），而在於作為檢索評測方法論與知識庫抽象設計的高品質參考範例——尤其對 L4/L9/L10 這幾個處理「文字知識 + 結構化關聯」的 Layer 有直接的設計借鏡價值。

7.4 具體落地建議：一個最小可行整合範例

若要把 STaRK 的評測方法論實際落地到 AIKT，一個低成本、高價值的起手式是：建一份 AIKT 內部的「混合查詢驗收集」，不需要引入 STaRK 的程式碼依賴，只需借鏡其查詢構造原則：

 1# 概念示意：借鏡 STaRK 查詢構造原則，建立 AIKT 內部檢索驗收集
 2# 不依賴 stark_qa 套件，純粹沿用其評測方法論
 3
 4test_queries = [
 5    {
 6        "query": "找出 2024 年後、跟 CRISPR 基因編輯有關、且被 gh-tutorial-qd 收錄過的論文",
 7        "expected_doc_ids": ["inbox/20240815-crispr-review.md"],
 8        "query_type": "hybrid",  # 語意 + 時間篩選 + 來源關聯
 9    },
10    {
11        "query_type": "relational",  # 純粹圖結構關聯查詢
12    },
13]
14
15def evaluate_hit_at_k(retriever_fn, test_queries, k=5):
16    """仿照 STaRK Evaluator 的 Hit@k 計算方式"""
17    hits = 0
18    for item in test_queries:
19        results = retriever_fn(item["query"], top_k=k)
20        if any(doc_id in results for doc_id in item["expected_doc_ids"]):
21            hits += 1
22    return hits / len(test_queries)

這種輕量級驗收框架可以定期跑在 paper-qa-lite 或 graphify 的查詢介面上，量化追蹤檢索品質是否隨資料量增長而退化。

8. 優缺點與生態系定位 (Strengths, Limitations & Ecosystem Position)

8.1 核心優勢與創新點

1. 真實貼近實務的混合查詢設計：不同於傳統 IR benchmark 只測純文字相似度，STaRK 刻意構造同時涉及語意與關聯的查詢，更貼近企業級知識庫問答的真實挑戰
2. 三領域覆蓋、涵蓋人工標註查詢：Amazon（電商）、MAG（學術）、Prime（生醫）三個領域各具代表性，且部分查詢經人工撰寫確保自然度，避免模板化查詢帶來的評測失真
3. 模型光譜完整：從最輕量的 BM25 到最重量級的 LLMReranker 一應俱全，且 HybridRetriever 這類社群貢獻證明了架構的可擴充性——新增模型只需少量程式碼改動
4. 官方 leaderboard + pip 套件化：stark-qa 已是可直接 pip install 的正式套件，並有 HuggingFace 官方 leaderboard 持續徵集新方法提交，形成活躍的社群評測生態
5. 成本可控的評測設計：embedding 預先計算並持久化，避免評測過程重複呼叫昂貴 API，這對學術界資源有限的研究團隊尤其友善

8.2 目前限制與改進空間

1. 依賴外部 embedding API：預設的 text-embedding-ada-002 等模型多為商業 API（OpenAI/Voyage），對於希望完全離線或自建模型評測的場景需額外整合開源 embedding 模型
2. Python 版本上限（<3.12）：對於已升級到最新 Python 版本的環境，需額外建立獨立虛擬環境，增加環境管理複雜度
3. STaRK-Amazon/MAG 原始資料前處理成本高：若不使用 download_processed=True，前處理耗時約 1 小時，對快速迭代實驗不夠友善（雖然已提供預處理版本作為緩解）
4. LLMReranker 成本與延遲：LLM 驅動的重排序雖準確率最高，但成本與延遲遠高於 VSS/BM25，實務部署時需要額外的候選集縮減策略（如本文 6.3 節建議）
5. 缺乏動態知識庫更新機制：目前 SKB 設計偏向靜態快照，對於需要頻繁更新的生產環境知識庫（如即時商品庫存、每日更新的論文資料庫），缺乏增量更新的官方支援方案

8.3 與同領域工具的比較

8.4 適用場景建議

• 適合：需要評估「LLM + 檢索」系統在混合語意/關聯查詢下表現的研究團隊；正在設計企業知識庫問答系統、想找標準化評測方法論的工程團隊；生醫知識圖譜檢索（PrimeKG 相關）研究
• 較不適合：純粹需要向量資料庫效能評測（如 QPS、延遲）的場景（STaRK 關注的是檢索準確度而非系統吞吐量）；完全離線、無法呼叫任何外部 embedding API 的封閉環境（除非自行替換為開源 embedding 模型）

8.5 生態系定位總結圖

flowchart TB
    subgraph upstream["上游：資料與圖譜生態"]
        U1["PrimeKG
生醫知識圖譜"]
        U2["Microsoft Academic Graph"]
        U3["Amazon 產品資料"]
    end

    subgraph stark_core["STaRK 核心定位"]
        S["STaRK Benchmark
檢索評測層"]
    end

    subgraph downstream["下游：應用與後續研究"]
        D1["企業 RAG 系統評測"]
        D2["HuggingFace Leaderboard
社群方法競賽"]
        D3["社群貢獻模型
(HybridRetriever 等)"]
    end

    subgraph adjacent["同層相鄰工具"]
        A1["BEIR
(純文字 IR benchmark)"]
        A2["RAGAS
(生成品質評測)"]
    end

    U1 --> S
    U2 --> S
    U3 --> S
    S --> D1
    S --> D2
    S --> D3
    S <-.互補而非競爭.-> A1
    S <-.互補而非競爭.-> A2

STaRK 在整個 LLM 檢索評測生態系中扮演的角色，是填補「結構化關聯查詢」評測空白的專門化基準——它不試圖取代 BEIR（純文字檢索評測的標準）或 RAGAS（生成品質評測的標準），而是與兩者互補，共同構成一套完整的「檢索 + 生成」評測光譜的一環。

9. 學習路徑建議 (Suggested Learning Path)

若你是第一次接觸 STaRK，建議依照以下順序上手，避免一開始就掉進評測腳本的參數細節裡：

flowchart LR
    A["1. 讀論文摘要
理解混合查詢動機"] --> B["2. pip install stark-qa
跑 load_qa/load_skb"]
    B --> C["3. 手動看 5-10 筆
查詢與對應節點文件"]
    C --> D["4. 跑一次 VSS 評測
(用官方 embedding)"]
    D --> E["5. 對照 eval_metrics.json
理解 Hit@k/MRR 數字意義"]
    E --> F["6. 嘗試 HybridRetriever
比較與純 VSS 的差異"]
    F --> G["7. (進階) 實作自己的
SKB 子類別接自有資料"]

第一階段（理解問題）：先花 20-30 分鐘讀論文摘要與 README 的「What is STaRK」段落，建立「為什麼混合查詢比純文字查詢難」的直覺，不要急著跑程式碼。

第二階段（跑起來）：用最小資料集（建議先選 prime，因為前處理只需約 5 分鐘）跑通 load_qa + load_skb，親眼看幾筆查詢與對應的知識庫節點內容，建立對資料型態的具體印象。

第三階段（評測與比較）：依序跑 BM25 → VSS → HybridRetriever 三種模型的評測，比較 eval_metrics_test.json 裡的 Hit@1/Hit@5/MRR 數字差異，親自體會「為什麼混合檢索通常優於單一策略」這件事，而不是只讀論文裡的表格。

第四階段（進階整合）：若目的是應用到自己的資料（如 AIKT 內部知識庫），此時再深入研讀 SKB 基底類別與 AmazonSKB/PrimeSKB 的實作細節，規劃如何把自己的資料轉換成相容格式。

附錄 A：常見問答 (FAQ)

Q1: STaRK 跟一般的 RAG 評測工具（如 RAGAS）有什麼不同？

RAGAS 一類工具主要評測「生成答案的品質」（如 faithfulness、answer relevance），關注的是 LLM 生成階段的表現；STaRK 則專注在檢索階段本身——也就是「有沒有找到對的文件/節點」，並且刻意引入結構化關聯條件來增加檢索難度。兩者可以視為互補：先用 STaRK 式的方法驗證檢索模組準不準，再用 RAGAS 式的方法驗證生成模組答得好不好。

Q2: 我可以用自己的資料集套用 STaRK 的評測框架嗎？

可以，但需要自行實作繼承 SKB 基底類別的知識庫類別（如 AmazonSKB、PrimeSKB 的寫法），把自己的資料轉換成 node_info（節點文件字典）+ edge_index（PyG 格式邊索引）的格式，並提供對應的 QA 查詢資料集（含官方 split）。這也是 6.1 節提到的「企業內部知識庫問答」整合路徑的具體技術路徑。

Q3: 為什麼不直接用向量資料庫（如 Pinecone）內建的評測工具？

商業向量資料庫的評測工具通常聚焦在系統效能（QPS、延遲、記憶體用量），而非檢索準確度在混合查詢下的表現。STaRK 填補的正是「準確度評測」這塊——它不關心你用什麼向量資料庫做底層儲存，只關心最終排序出來的候選集品質。

Q4: download_processed=True 跟 False 差在哪？我該選哪個？

True 直接下載官方已經處理好的知識庫資料（快，適合絕大多數想直接跑評測或做應用開發的場景）；False 會從原始資料重新跑一次前處理流程（慢，但完全透明、可審查每一步轉換邏輯，適合想研究資料前處理細節或需要客製化前處理邏輯的場景）。除非有特殊研究需求，建議一律選 True。

Q5: HybridRetriever 的 alpha 應該設多少？

沒有放諸四海皆準的答案，取決於你的查詢集裡「精確關鍵字匹配」與「語意相似度匹配」何者更重要。建議做法（見 6.3 節）：先用 test-0.1 子集掃過 0.3/0.5/0.7 幾個值，用驗收指標（Hit@k/MRR）挑出最佳值，再用完整測試集驗證。若你的查詢常含專有名詞、型號、精確數值，alpha 應偏低（更倚重 BM25）；若查詢偏向開放式自然語言描述，alpha 應偏高（更倚重 VSS）。

Q6: LLMReranker 支援哪些 LLM？

從 stark_qa/tools/llm_lib/completion/ 目錄可見，官方原生封裝了 Claude（claude.py）、GPT（gpt.py）與 HuggingFace 開源模型（huggingface.py）三條路徑，可透過 --llm_model 參數指定具體模型名稱（如 claude-3-5-sonnet-20241022、gpt-4-1106-preview），並依模型系列設定對應的 API key 環境變數。

附錄 B：關鍵術語對照表

附錄 C：快速指令參考

 1# 安裝
 2uv pip install stark-qa
 3
 4# 載入資料集（Python）
 5python -c "from stark_qa import load_qa, load_skb; \
 6    qa = load_qa('prime'); skb = load_skb('prime', download_processed=True)"
 7
 8# 下載官方 embedding
 9python emb_download.py --dataset prime --emb_dir emb/
10
11# 跑 VSS 評測
12python eval.py --dataset prime --model VSS --emb_dir emb/ \
13    --emb_model text-embedding-ada-002 --split test --save_pred
14
15# 跑 HybridRetriever 評測
16python eval.py --dataset prime --model HybridRetriever --emb_dir emb/ \
17    --hybrid_alpha 0.5 --hybrid_fusion rrf --split test --save_pred
18
19# 跑 LLMReranker 評測（需 API key）
20export ANTHROPIC_API_KEY=$YOUR_KEY
21python eval.py --dataset prime --model LLMReranker --emb_dir emb/ \
22    --llm_model claude-3-5-sonnet-20241022 --split human_generated_eval --save_pred

本教學文件依據 GitHub repo snap-stanford/stark（HEAD, 2026-07-13 擷取）之 README、程式碼結構與 docs/HYBRID_RETRIEVER.md 撰寫，供 AIKT 知識庫收錄與後續檢索評測方法論參考使用。