Semantic Query Skill

Semantic Query 是 graphify 的三大查詢指令之一：graphify query。不同於傳統 graph database（要寫 Cypher），你只要打中文 / 英文的問題，graphify 就會：

1. 挑關鍵字（filter stop-words，涵蓋英德法等歐語）¹
2. 每個關鍵字找 BFS seed（最高 degree 的命中節點）
3. 擴張子圖（依 relevance ranking）
4. 回傳 ranked subgraph + 每條邊的 relation 與信心標籤

何時使用

✅ 適合的情境：

• 開放式問題「認證怎麼做的？」
• 找一個概念但不知道相關函式名稱
• 助理要先給你看子圖再回答

❌ 不適合的情境：

• 已知兩個節點要看連結 → 用 graphify path
• 已知單一節點要看脈絡 → 用 graphify explain
• 想算 exact match 數量 → 用 jq 直接查 graph.json

查詢機制

Stop-word 過濾

中文 / 英文 / 德文 / 主要拉丁語系的 stop-words 會被過濾。例如：

"Wie funktioniert die Authentifizierung?"

→ 關鍵字：Authentifizierung（不是 Wie、der）

BFS seeds

graphify 對每個關鍵字找圖譜中的名稱 / alias / community label 命中點，挑出最高 degree 的種子，從這些種子 BFS 擴張。

Ranking

回傳節點依 relevance rank（hop distance + 文字命中分數），seed first 永遠置頂不會被截斷。

Budget 控制

--budget N 限制輸出 token：對 god node 跑 query 時建議加 budget，避免塞爆 context。

範例對話

使用者：這個專案的 auth 在哪？

助理：我先 query 圖譜。
> graphify query "auth 在哪？"

Showing 6 of 6 nodes (ranked by relevance)

Node: login
  Source: auth.py:1
  Community: 2 (Auth)
  Degree: 4

Node: verify_password
  Source: auth.py:6
  ...

Edges (5):
  login -[calls]-> verify_password  [EXTRACTED]
  login -[calls]-> create_session   [EXTRACTED]
  create_session -[imports]-> Session [INFERRED]

→ 認證流程：
   `auth.py` 的 `login()` → `verify_password()` → `create_session()`
   `session.py` 的 `Session` 類別負責產生 token。

效能特性

v0.9.17 起 scoring 改為「每查詢 1 次 pass」²，比舊版（per-token）快 1.3-1.4 倍。對於 T-token 查詢，舊版要 T+1 次完整 scoring，新版只要 1 次。

對 small corpus（< 100 nodes），查詢通常 < 1 秒。

不一樣：「Semantic Query」≠ Vector Search

graphify 不是 vector index：沒有 embeddings、沒有 vector store。

graphify 對「理解架構」遠優於 vector RAG；對「找近似字串」則 vector RAG 更合適。

MCP 工具對應

把圖譜開成 MCP server (python -m graphify.serve) 後，host 端可呼叫：

• query_graph("<問題>") — 等同 CLI graphify query
• get_neighbors(node_id, token_budget=2000) — 列出鄰居

內部連結

• graphify query 指令詳解
• Knowledge Extraction Skill
• Source Tracking Skill

下一步

1. Source Tracking Skill：節點與邊的來源追溯
2. graphify path-explain 指令詳解
3. graphify build 指令詳解