wikiparse

從中文維基百科 dump（.xml.bz2）串流解析條目，抽取人物出生日期（DOB）與出生地（birth_place）。

目標

• 只處理主命名空間（ns=0）且非 redirect 的頁面。
• 先以規則抽取 DOB 與出生地，失敗時才呼叫地端 LLM 兜底。
• 結果可持久化、可中斷續跑（resume）。
• 優先追求穩定與可恢復性，而非極速。

建議輸入資料

Wiki dump 放在專案下的 data/ 目錄。建議使用下列檔案（multistream + index）：

• zhwiki-*-pages-articles-multistream.xml.bz2
• zhwiki-*-pages-articles-multistream-index.txt.bz2

處理流程

1. 串流解壓與 XML 逐頁解析。
2. 過濾 ns=0 且非 redirect。
3. 人物判斷（分類/infobox 等規則），非人物直接丟棄不輸出。
4. 規則抽取（infobox、首段括號）。
5. 必要時 LLM 兜底（只給短片段，禁止猜測）。
6. 驗證後立即寫入儲存層，確保可 resume。

輸出欄位（建議）

• wiki：例如 zhwiki
• pageid
• rev_id
• title
• dob：YYYY-MM-DD | YYYY-MM | YYYY | null
• precision：day | month | year | null
• source：rule_infobox | rule_lead | llm | none
• evidence：原文片段（可為 null）
• birth_place：出生地名稱（可為 null）
• birth_place_source：rule_infobox | rule_lead | llm | none
• birth_place_evidence：出生地證據片段（可為 null）
• status：success | failed
• notes：補充資訊（例如 dob_not_found、錯誤摘要）
• attempts_rule
• attempts_llm
• updated_at

環境變數（LLM）

• VLLM_BASE_URL（例如 http://127.0.0.1:8000/v1）
• VLLM_API_KEY（可空）
• VLLM_MODEL（例如 openai/gpt-oss-20b）
• 可選：HTTP_TIMEOUT_SECONDS、LLM_TIMEOUT_SECONDS

可使用 python-dotenv 透過 .env 管理上述變數（建議）。

• 執行時優先讀取系統環境變數，其次才讀 .env。
• .env 不要提交到版本控制（可提交 .env.example）。

執行環境

• Python 依賴建議使用 uv 管理。
• 專案目錄通常透過 SMB 掛載到本機做瀏覽與編輯。
• 批次實際執行在遠端機器上（透過 SSH 觸發）。

開發狀態

目前已提供最小可跑實作：

• main.py：主流程（串流解析、輸出、checkpoint/resume）
• extractors.py：人物判斷與規則抽取
• llm_client.py：LLM fallback

執行方式

先安裝依賴（遠端機器）：

uv sync

小批次 smoke run（不呼叫 LLM）：

uv run python main.py --max-pages 200 --disable-llm --output output/smoke.jsonl --state-file output/smoke_state.json

一般執行（允許 LLM fallback）：

uv run python main.py --wiki-id zhwiki --output output/zhwiki_dob_birthplace.jsonl --state-file output/zhwiki_state.json

Update 模式（增量補齊）：

uv run python main.py \
  --mode update \
  --wiki-id zhwiki \
  --input data/zhwiki-2026-05-01-pages-articles-multistream.xml.bz2 \
  --base-output output/zhwiki_dob_birthplace.jsonl \
  --output output/zhwiki_update_delta.jsonl \
  --state-file output/zhwiki_update_state.json

合併 base + delta（產生新 full 檔）：

uv run python merge_outputs.py \
  --base output/zhwiki_dob_birthplace.jsonl \
  --delta output/zhwiki_update_delta.jsonl \
  --output output/zhwiki_dob_birthplace_merged.jsonl

可用參數：

• --input：指定 .xml.bz2，預設取 data/ 第一個檔案
• --mode：full | update
• --base-output：update 模式下的舊輸出 JSONL（必填）
• --wiki-id：語系/維基識別（如 zhwiki，建議必填）
• --max-pages：最多寫出幾筆人物結果
• --disable-llm：只跑規則抽取
• --llm-retries：LLM 失敗重試次數
• --llm-workers：LLM fallback 並行 worker 數（預設 1；若 vLLM 可同時 2 session，建議設 2）
• --output：輸出 JSONL
• --state-file：checkpoint/摘要狀態檔