Skip to content

Hypergraph is more powerful. Transform unstructured text into structured knowledge with LLMs. Graphs, hypergraphs, and spatio-temporal extractions — with one command.

docs: choosing a method — baseline vs structured

Frankie-Xu6e52ad644378
diff --git a/docs/en/concepts/choosing-a-method.md b/docs/en/concepts/choosing-a-method.md
new file mode 100644
index 0000000..3847123
--- /dev/null
+++ b/docs/en/concepts/choosing-a-method.md
@@ -0,0 +1,65 @@
+# Choosing a method: baseline vs structured
+
+When do you pay for graph extraction, and when are raw chunks enough?
+
+This page is a decision aid, not an evaluation framework. It does not define recall metrics, QA pairs, or CI scores. For a same-corpus walkthrough of answers, latency, and token use, run the companion script on `examples/en/tesla.md` once it is in `examples/en/methods/` (`chunk_vs_graph_rag.py`). That script is a manual demo — CI will not run it.
+
+The catalog of algorithms lives in [Methods](methods.md). How to call them is in [Using Methods](../python/guides/using-methods.md).
+
+---
+
+## Two defaults
+
+| Need | Start with | Why |
+|------|------------|-----|
+| Lookup, quote the original wording, or locate a passage | `chunk_rag` | Ingest is embed-only. No LLM extraction cost. Retrieval returns the chunks themselves. |
+| Multi-hop or relationship-dense questions | `graph_rag` | Extraction builds nodes and edges so answers can follow links, not only lexical overlap. |
+
+`chunk_rag` shipped as the zero-extraction baseline. Use it first; pay for `graph_rag` (or another structured method) only when that extra ingest cost changes the answers you care about.
+
+---
+
+## When chunks are enough
+
+Prefer `chunk_rag` when:
+
+- The question is **lookup-style**: “What year…?”, “Quote the clause…”, “Where does the document say…?”
+- You need **the original wording**, not a synthesized graph fact.
+- The corpus is large and **ingest LLM cost** is the constraint.
+- You are deciding whether extraction is worth it at all — this is the baseline.
+
+Ingest path: chunk → embed → index. Query path: retrieve chunks → (optional) chat over those chunks.
+
+---
+
+## When graph extraction pays off
+
+Prefer `graph_rag` (or another graph/hypergraph method) when:
+
+- The question is **multi-hop**: “Who funded the company that acquired X?”
+- The question is **relationship-dense**: rivals, successors, ownership, causation.
+- You will **reuse the graph** (export, scoped graph search, visualization), not only ask once.
+
+You pay an LLM at ingest to extract structure. That cost is wasted if every question could have been answered by pointing at a chunk.
+
+---
+
+## Same corpus, same provenance
+
+`chunk_rag` and `graph_rag` share the provenance machinery: source ledger, `he tag`, scoped `he search` / `he talk`, and per-document rollback. A comparison on one corpus (`examples/en/tesla.md`) is apples-to-apples — the difference is extraction, not tagging or rollback.
+
+See [Source Attribution & Provenance](../python/guides/provenance.md).
+
+---
+
+## This is not an eval harness
+
+This page does not define hit-rate metrics, expected spans, or a benchmark set. Hash embeddings in CI would make recall numbers meaningless. A separate RFC would be needed before any harness — that work is out of scope here.
+
+---
+
+## See Also
+
+- [Methods](methods.md) — algorithm catalog and comparison table
+- [Using Methods](../python/guides/using-methods.md) — `Template.create("method/…")`
+- [Search and Chat](../python/guides/search-and-chat.md) — `search` / `chat` after you pick a method
diff --git a/docs/en/concepts/methods.md b/docs/en/concepts/methods.md
index b96580e..29dcbab 100644
--- a/docs/en/concepts/methods.md
+++ b/docs/en/concepts/methods.md
@@ -351,6 +351,7 @@ for name, info in methods.items():
## See Also
+- [Choosing a method: baseline vs structured](choosing-a-method.md)
- [Using Methods Guide](../python/guides/using-methods.md)
- [Templates](../templates/index.md)
- [Auto-Types](autotypes.md)
diff --git a/docs/en/python/guides/using-methods.md b/docs/en/python/guides/using-methods.md
index 24eec7a..7e48828 100644
--- a/docs/en/python/guides/using-methods.md
+++ b/docs/en/python/guides/using-methods.md
@@ -285,4 +285,5 @@ for name, info in methods.items():
**Reference:**
- [Methods Concept Doc](../../concepts/methods.md) — Detailed algorithm explanations
+- [Choosing a method: baseline vs structured](../../concepts/choosing-a-method.md) — When chunks suffice vs when graph extraction pays off
- [Template Library](../../templates/index.md) — Browse existing templates
diff --git a/docs/zh/concepts/choosing-a-method.md b/docs/zh/concepts/choosing-a-method.md
new file mode 100644
index 0000000..87ae5c0
--- /dev/null
+++ b/docs/zh/concepts/choosing-a-method.md
@@ -0,0 +1,65 @@
+# 选择方法:基线 vs 结构化抽取
+
+什么时候值得为图谱抽取多付钱,什么时候只用原文 chunks 就够?
+
+本页是决策说明,不是评测框架。它不定义召回指标、QA 对,也不给出 CI 分数。同一语料上的答案、延迟和 token 用量,等 `examples/en/methods/chunk_vs_graph_rag.py` 落地后,用 `examples/en/tesla.md` 跑那个脚本即可。那是手工演示,CI 不会跑它。
+
+算法目录见 [方法](methods.md)。调用方式见 [使用方法](../python/guides/using-methods.md)。
+
+---
+
+## 两个默认选项
+
+| 需求 | 先用 | 原因 |
+|------|------|------|
+| 查找、引用原文、定位段落 | `chunk_rag` | 摄入只做分块和嵌入,没有 LLM 抽取成本。检索直接返回原文 chunk。 |
+| 多跳或关系密集的问题 | `graph_rag` | 抽取会建节点和边,答案可以顺着关系走,而不只靠字面重叠。 |
+
+`chunk_rag` 就是零抽取基线。先用它;只有当额外的摄入成本能改变你关心的答案时,再为 `graph_rag`(或其他结构化方法)付钱。
+
+---
+
+## 什么时候 chunks 就够
+
+优先 `chunk_rag` 当:
+
+- 问题是 **lookup 式**:「哪一年……?」「引用那一条款……」「文档哪里写了……?」
+- 你需要 **原文措辞**,而不是合成后的图谱事实。
+- 语料很大,**摄入阶段的 LLM 成本** 是瓶颈。
+- 你还在判断抽取值不值 —— 这就是基线。
+
+摄入:分块 → 嵌入 → 建索引。查询:检索 chunks →(可选)基于这些 chunks 做 chat。
+
+---
+
+## 什么时候图谱抽取划算
+
+优先 `graph_rag`(或其他图谱 / 超图方法)当:
+
+- 问题是 **多跳**:「收购了 X 的那家公司,出资人是谁?」
+- 问题是 **关系密集**:对手、继任、股权、因果。
+- 你会 **复用这张图**(导出、范围检索、可视化),而不是只问一次。
+
+摄入时要用 LLM 抽结构。如果每个问题都能靠指到一段原文回答,这笔钱就浪费了。
+
+---
+
+## 同一语料、同一套 provenance
+
+`chunk_rag` 和 `graph_rag` 共用 provenance:来源台账、`he tag`、范围限定的 `he search` / `he talk`、按文档回滚。在同一份语料(`examples/en/tesla.md`)上对比是 apples-to-apples —— 差别在抽取,不在打标或回滚。
+
+见[来源标注与溯源](../python/guides/provenance.md)。
+
+---
+
+## 这不是评测框架
+
+本页不定义命中率、期望 span,也不提供基准集。CI 里的 hash embedding 会让 recall 数字没有意义。任何 harness 都应另开 RFC —— 这里不做。
+
+---
+
+## 另请参见
+
+- [方法](methods.md) — 算法目录与对照表
+- [使用方法](../python/guides/using-methods.md) — `Template.create("method/…")`
+- [搜索和聊天](../python/guides/search-and-chat.md) — 选定方法后的 `search` / `chat`
diff --git a/docs/zh/concepts/methods.md b/docs/zh/concepts/methods.md
index 84775c8..f46d806 100644
--- a/docs/zh/concepts/methods.md
+++ b/docs/zh/concepts/methods.md
@@ -325,6 +325,7 @@ for name, info in methods.items():
## 另请参见
+- [选择方法:基线 vs 结构化抽取](choosing-a-method.md)
- [使用方法指南](../python/guides/using-methods.md)
- [模板](../templates/index.md)
- [自动类型](autotypes.md)
diff --git a/docs/zh/python/guides/using-methods.md b/docs/zh/python/guides/using-methods.md
index 50e030d..0a91f93 100644
--- a/docs/zh/python/guides/using-methods.md
+++ b/docs/zh/python/guides/using-methods.md
@@ -285,4 +285,5 @@ for name, info in methods.items():
**参考:**
- [方法概念文档](../../concepts/methods.md) — 详细算法解释
+- [选择方法:基线 vs 结构化抽取](../../concepts/choosing-a-method.md) — 何时只用 chunks,何时值得做图谱抽取
- [模板库](../../templates/index.md) — 浏览现有模板
diff --git a/mkdocs.yml b/mkdocs.yml
index 2cc2aa7..88a6043 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -118,6 +118,7 @@ plugins:
- concepts/provider-system.md
- concepts/autotypes.md
- concepts/methods.md
+ - concepts/choosing-a-method.md
- concepts/templates-format.md
- Templates:
- templates/index.md
@@ -218,6 +219,7 @@ plugins:
- zh/concepts/provider-system.md
- zh/concepts/autotypes.md
- zh/concepts/methods.md
+ - zh/concepts/choosing-a-method.md
- zh/concepts/templates-format.md
- 模板库:
- zh/templates/index.md