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.mdnew file mode 100644index 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 methoddiff --git a/docs/en/concepts/methods.md b/docs/en/concepts/methods.mdindex 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.mdindex 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 templatesdiff --git a/docs/zh/concepts/choosing-a-method.md b/docs/zh/concepts/choosing-a-method.mdnew file mode 100644index 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.mdindex 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.mdindex 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.ymlindex 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