⚠️ Pre-1.0 — API 可能在 minor 版本間變更。

繁體中文

為什麼選 wenji？

大多數 RAG 框架預設「LLM-default」：建索引用 LLM 抽 entity、LLM 做 community summary、LLM 重排序。成本隨語料線性成長，LLM 不可用時整個系統停擺。

wenji 走相反路線 — LLM-essential, not LLM-default：建索引零 LLM 呼叫；LLM 只允許在查詢時用，必須 cache，必須有確定性 fallback。結果：LLM 成本 = unique queries × cache miss rate，與語料大小無關。

典型使用場景

• 📚 中文知識語料搜尋 — 講道、課堂筆記、法律條文、古典詩詞、技術文章，中英混合支援
• 🖥️ 本地部署，零外部服務 — 一個 Python 行程 + 一個 SQLite 檔，不租 vector DB
• 🏷️ Tag + 分類軸瀏覽 — Web UI sidebar 篩選，/tags tag 索引頁，?tag=X 精確過濾
• 📊 Eval 對齊 — JSONL eval runner + 80 題回歸基準，檢索改動必過 before/after 對比

3 大特色

三行快速上手

示範語料 examples/articles/ 只隨 source checkout 提供；有自己的 markdown 目錄可直接 ingest。

pip install wenji
git clone https://github.com/notoriouslab/wenji   # 只為了拿示範語料
wenji ingest dir wenji/examples/articles/ --db wenji.db
wenji serve --db wenji.db --port 8000

打開瀏覽器 http://127.0.0.1:8000，得到完整 Web UI（搜尋 + tag 瀏覽 + 文章閱讀器）。

大語料運維：中斷的批次匯入直接重跑同一個 wenji ingest dir 命令即可續跑（未變更的文章走 content-hash 快路徑、不重算 embedding；rebuild 永遠從 wipe 開始，不用它續跑）；語料含少數壞 frontmatter 檔時加 --skip-bad（結尾列清單、exit 1）。

支援 Python 3.10–3.12（3.13 尚未支援）。第一次跑 wenji ingest 或 wenji search 會自動下載 ONNX BGE-M3 INT8 embed model（~600 MB）至 user cache。macOS arm64 / Linux x86_64 內建 libsimple binary；其他平台用 wenji download-model 手動抓。

常見使用路徑

場景 1：CLI 快速搜尋

wenji search "勞動契約" --db wenji.db --top-k 5

輸出前 5 筆，含 BM25 / 向量分數、chunk-level 摘要、chunk 索引（可 deep link 至 /article/<id>#c<n>）。

場景 2：Web UI + tag 瀏覽

wenji serve --db wenji.db --port 8000

⚠️ Production 部署 checklist（wenji serve 預設沒有認證、沒有速率限制）：

• 設 WENJI_API_KEY=<random-32-bytes> 開啟 API key auth；同時關掉 /docs /openapi.json 自動文件（沒設 API key 時這兩個端點公開）
• 設 WENJI_CORS_ORIGINS=https://your-frontend.example.com（預設 empty 拒所有 cross-origin）
• 綁 127.0.0.1 走反代（nginx / Caddy）+ 反代層做 rate limit（/api/ask 一次呼叫等於一次 LLM 計費）
• Docker / systemd：用 EnvironmentFile=/etc/wenji.env 載入 WENJI_*（不要 inline Environment= 或 docker -e，會被 systemctl show / ps 看到）
• axes.yaml 為選配；缺檔不影響 ingest/search，只是 sidebar 不會有分軸

場景 3：Domain corpus（corpus-christian 範例）

wenji serve --db wenji.db \
  --entity-source example:corpus-christian \
  --intent-source example:corpus-christian

啟動 entity scoring + intent classification 層，Searcher pipeline 升級為：RRF merge with intent boost → entity scoring/filter。省略 flags 時退化為純 RRF + chunk signals（仍優於 v0.3.5 線性 hybrid）。

場景 4：Eval 回歸基準

前置：先在另一 terminal 跑 wenji serve --db wenji.db（eval runner 透過 /api/search 打 80q 基準）；snapshot tests/benchmark_80_v2_snapshot.json 已內建 repo 內。

Smoke 建議：改動 retrieval pipeline 後，先用 snapshot 前 10 題跑 mini-baseline（手動 jq '.categories[].questions |= .[:3]' snapshot.json > smoke.json 之類）確認沒大幅退步，再跑全 80q。

wenji eval run-benchmark --db wenji.db --out r0.json

輸出標準 JSON 格式（per-question gold_path_match、pass@3、MRR@5）。用 wenji eval sanity-eyeball --baseline-output <path> 做人工雙閘門驗收。改動 retrieval pipeline 前後各跑一次，pass 數與 miss 清單不得劣化。

核心概念

搜尋架構

Searcher.search() 執行 8 步 pipeline：

entity detect → intent detect → alias expand
  → BM25 + vector → chunk BM25 → RRF merge (intent boost)
  → entity scoring + filter → snippet hydration

省略 --entity-source / --intent-source 時，entity/intent 步驟 skip，降級為 RRF + chunk signals。

核心模組

分類引擎

# axes.yaml — 摘錄自 examples/axes.yaml
axes:
  - id: sermon
    name: 講道
    short: 講道
    order: 1
    description: 講道 / 信仰主題長文
    rules:
      - source_type: sermon
        primary: true

每條 rule 支援 source_type / tag / title_regex（regex search）/ subtype 多欄位 AND 組合，及 hierarchical parent: <id>。Axes 是 derived data，隨時 wenji classify / wenji rebuild 重建，不動原始 markdown。

Observability

wenji stats   --db wenji.db            # articles / chunks / indices 快照
wenji segment "因信稱義"               # query pipeline trace（tokens、fts_form、dict hits）

等效 HTTP 端點：GET /api/stats、GET /api/segment?q=。

進階設定

LLM 設定（/api/ask 問答用）

任何 OpenAI-compatible endpoint（Groq、OpenRouter、Together、Gemini、vLLM、llama.cpp …）。強烈建議用 .env + direnv 載入，避免 API key 寫進 shell rc 或被 process listing 看到：

# .env （請複製 .env.example 為 .env 後填入；不要 commit）
WENJI_LLM_BASE_URL=https://api.groq.com/openai/v1
WENJI_LLM_API_KEY=<your-key>
WENJI_LLM_MODEL=llama-3.3-70b-versatile
WENJI_LLM_TIMEOUT=10.0                # 選配，預設 10s

⚠️ 確認 .gitignore 含 .env 與 .env.*（已內建）。不要 export WENJI_LLM_API_KEY=... 寫進 ~/.zshrc／~/.bashrc，也不要傳 -e WENJI_LLM_API_KEY=... 給 docker（會被 ps 看到）。

LLM 失敗 fallback：/api/ask 在 LLM 失敗時 answer=null 但 citations 仍正常填值；檢索本身零 LLM 依賴。

Entity / Intent Sources

多來源，last-write-wins on key collision：

wenji serve --db wenji.db \
  --entity-source example:corpus-christian \
  --entity-source /path/to/my_entities.json \
  --intent-source example:corpus-christian

或 env var（comma-separated）：

export WENJI_ENTITY_SOURCES=example:corpus-christian,/path/to/my_entities.json
export WENJI_INTENT_SOURCES=example:corpus-christian

Network URLs（http://、https://）被 source loader 拒絕；只接受 example:<name> 和本機路徑。注意：本機路徑目前沒有沙箱（Path traversal 防護待 v0.4），請只指向你信任的目錄。多來源 last-write-wins：右邊覆蓋左邊（--entity-source A --entity-source B → B 的 keys 優先）。

Web 部署：站點 URL / SEO / CORS（v0.3.7+）

對外發行時，由 env vars 控制 SEO meta 與 CORS（全部 unset 時預設不暴露任何品牌 / 不允許任何 cross-origin，最安全 zero-config）：

# .env
WENJI_SITE_URL=https://wenji.example.com           # 啟用 canonical / og:* / JSON-LD
WENJI_SITE_NAME=My Wenji                          # 可選，最長 256 字
WENJI_OG_IMAGE_URL=https://wenji.example.com/og.png  # 可選；⚠️ 此 host 會收到所有訪客 IP / UA
WENJI_CORS_ORIGINS=https://my-frontend.example.com,https://api.example.com

URL host 啟動時做白名單驗證：拒 userinfo（https://a@b.com）、私網 IP、IDN homograph、控制字元、非預設 port、percent-encoded host —— fail-fast 啟動失敗。CORS 拒 * / null / wildcard subdomain / 非 https。

Local dev SPA：跑 localhost:5173 連 /api/* 會被預設 CORS 擋下；開發時設 WENJI_CORS_ORIGINS=http://localhost:5173 WENJI_ALLOW_HTTP_CORS=1。

部署前用 wenji doctor --db wenji.db 驗 db 一致性（cross-table sanity + sample FTS MATCH）；exit 1 代表 db 不一致、wenji serve 啟動會拒絕 bind port。非中文 corpus 加 --sample-keywords k1,k2,k3 override。

升級指南

wenji 用 markdown 為 SSOT，舊 db 升級沒有 migration script —— 直接重建：

rm wenji.db && wenji ingest dir <markdown-dir> --db wenji.db

支援平台：

中國大陸 / 受限網路：Hugging Face 模型下載可設 HF_ENDPOINT=https://hf-mirror.com。

進階參考

CLI 子命令

選型建議

何時用 entity/intent？

整合與生態

notoriouslab 相關專案

擴展點：entity/intent 詞典多來源組合（from_sources，last-write-wins）。詳見 docs/extending.md。

貢獻

pip install -e ".[dev]"
ruff check src/wenji tests/wenji   # linter
pytest                              # unit（634 tests）
pytest -m integration              # 真實 ONNX（需下載 ~600 MB）

詳見 CONTRIBUTING.md。

授權

MIT © 2026 notoriouslab

English

At a glance

Why wenji?

Most RAG frameworks are built around an "LLM-default" assumption: extract entities with an LLM during ingest, build community summaries with an LLM, re-rank with an LLM. The cost grows with the corpus, and the system stops working when the LLM is unavailable.

wenji is built on the opposite premise — LLM-essential, not LLM-default:

1. The indexing pipeline performs zero LLM calls.
2. LLM use is restricted to query time, must be cached, and must have a deterministic structured fallback.
3. Entity dictionaries, classification axes, and chunking strategies are user-supplied, not LLM-derived.

The result: LLM cost scales with unique queries × cache miss rate, not with corpus size.

Quickstart (4 commands)

The demo corpus in examples/articles/ ships only with the source checkout; point ingest at your own markdown directory otherwise.

pip install wenji
git clone https://github.com/notoriouslab/wenji   # demo corpus only
wenji ingest dir wenji/examples/articles/ --db wenji.db
wenji serve --db wenji.db --port 8000

Bulk-ingest operations: resume an interrupted run by re-running the same wenji ingest dir command (unchanged articles take the content-hash fast path, no re-embedding; rebuild always starts from a wipe — don't use it to resume). Add --skip-bad to skip files with broken frontmatter (listed at the end, exit 1).

Then open http://127.0.0.1:8000 — full Web UI with search, tag browsing, and article viewer.

To search from the command line:

wenji search "勞動契約" --db wenji.db --top-k 5

Common paths

Search pipeline

Searcher.search() runs an 8-step pipeline:

entity detect → intent detect → alias expand
  → BM25 + vector → chunk BM25 → RRF merge (intent boost)
  → entity scoring + filter → snippet hydration

Without --entity-source / --intent-source, the entity/intent steps are skipped and the pipeline degrades to RRF + chunk signals (still an improvement over v0.3.5 linear hybrid).

Core modules

LLM setup (optional, for /api/ask)

Any OpenAI-compatible endpoint (Groq, OpenRouter, Together, Gemini, vLLM, llama.cpp…):

export WENJI_LLM_BASE_URL=https://api.groq.com/openai/v1
export WENJI_LLM_API_KEY=<your-key>
export WENJI_LLM_MODEL=llama-3.3-70b-versatile

Retrieval itself never calls an LLM; on LLM failure /api/ask returns answer=null with citations intact.

Configuration

# axes.yaml — excerpt from examples/axes.yaml
axes:
  - id: sermon
    name: 講道
    short: 講道
    order: 1
    description: 講道 / 信仰主題長文
    rules:
      - source_type: sermon
        primary: true

Each rule supports source_type / tag / title_regex (regex search) / subtype fields combined with AND, plus hierarchical parent: <id>. Axes are derived data — wenji rebuild always regenerates them deterministically.

Ecosystem

Extension point: compose entity/intent dictionaries from multiple sources (from_sources, last-write-wins). See docs/extending.md.

Star History

Development

pip install -e ".[dev]"
ruff check src/wenji tests/wenji
pytest                    # unit
pytest -m integration     # ~600 MB model download, real ONNX

See CONTRIBUTING.md for the full PR flow.

License

MIT © 2026 notoriouslab