LLM Wiki is a cross-platform desktop application that turns your documents into an organized, interlinked knowledge base — automatically. Instead of traditional RAG (retrieve-and-answer from scratch every time), the LLM incrementally builds and maintains a persistent wiki from your sources。
TypeScript
fix: real LLM bugs caught by full-suite validation
nash_su80442080b45b
diff --git a/src/lib/enrich-wikilinks.test.ts b/src/lib/enrich-wikilinks.test.tsindex f38d02ee..a8ead18d 100644--- a/src/lib/enrich-wikilinks.test.ts+++ b/src/lib/enrich-wikilinks.test.ts@@ -102,22 +102,43 @@ describe("enrichWithWikilinks — language directive is built at call time", ()})})-describe("enrichWithWikilinks — short-response guard", () => {- it("does NOT overwrite when LLM returns <50% of original length", async () => {- const longContent = "x".repeat(1000)- mockReadFile.mockResolvedValue(longContent)+describe("enrichWithWikilinks — JSON-based substitution", () => {+ it("does NOT overwrite when LLM response is not parseable JSON", async () => {+ // The v2 implementation expects a JSON `{links:[...]}` object; anything+ // else produces zero substitutions and writeFile is never called.+ mockReadFile.mockResolvedValue("some real page content with Transformer and Attention mentioned")mockStreamChatReturns("too short")await enrichWithWikilinks("/p", "/p/f.md", fakeLlmConfig())expect(mockWriteFile).not.toHaveBeenCalled()})- it("writes back when enriched response is long enough", async () => {- mockReadFile.mockResolvedValue("hello world, this is long enough content for the guard to pass")- mockStreamChatReturns("hello [[world]], this is long enough content for the guard to pass")+ it("writes back when LLM returns a valid JSON substitution list", async () => {+ mockReadFile.mockResolvedValue(+ "Transformer is the backbone. Attention is core.",+ )+ mockStreamChatReturns(+ JSON.stringify({+ links: [+ { term: "Transformer", target: "transformer" },+ { term: "Attention", target: "attention" },+ ],+ }),+ )await enrichWithWikilinks("/p", "/p/f.md", fakeLlmConfig())expect(mockWriteFile).toHaveBeenCalledOnce()+ const written = vi.mocked(mockWriteFile).mock.calls[0][1] as string+ expect(written).toContain("[[Transformer]]")+ expect(written).toContain("[[Attention]]")+ })++ it("does NOT overwrite when LLM returns an empty links list", async () => {+ mockReadFile.mockResolvedValue("a page that matches no index term")+ mockStreamChatReturns(JSON.stringify({ links: [] }))++ await enrichWithWikilinks("/p", "/p/f.md", fakeLlmConfig())+ expect(mockWriteFile).not.toHaveBeenCalled()})it("returns early when content or index is missing", async () => {diff --git a/src/lib/enrich-wikilinks.ts b/src/lib/enrich-wikilinks.tsindex 3efcbbe6..5dec8464 100644--- a/src/lib/enrich-wikilinks.ts+++ b/src/lib/enrich-wikilinks.ts@@ -6,7 +6,21 @@ import { normalizePath } from "@/lib/path-utils"/*** Lightweight post-save enrichment: ask LLM to add [[wikilinks]] to a saved wiki page.- * Much cheaper than full auto-ingest — no new pages created, just cross-references added.+ *+ * DESIGN NOTE (v2): previously we asked the LLM to return the complete page+ * with [[ ]] inserted, but many models (confirmed on MiniMax-M2.7-highspeed)+ * treat this as an invitation to rewrite / expand the page, destroying+ * user content. No prompt-level instruction reliably prevents this for+ * mid-size models.+ *+ * New design: LLM only returns a list of `(term → target)` substitutions as+ * JSON. The code then does the actual string replacement (first occurrence+ * per page). This way:+ * - content is byte-identical outside the inserted [[ ]] brackets+ * - frontmatter is untouched+ * - length grows by exactly 4 × number_of_links+ * - catastrophic LLM output (rewrites, translations, commentary) can't+ * corrupt the user's page*/export async function enrichWithWikilinks(projectPath: string,@@ -22,8 +36,10 @@ export async function enrichWithWikilinks(if (!content || !index) return- // Quick LLM call: just add wikilinks, don't change content- let enriched = ""+ // Ask the LLM to return a JSON list of {term, target} substitutions.+ // Much easier task than rewriting the whole page, and the model can't+ // corrupt anything it doesn't put in the list.+ let raw = ""await streamChat(llmConfig,@@ -31,68 +47,164 @@ export async function enrichWithWikilinks({role: "system",content: [- "You are a wiki cross-referencing assistant. Your ONLY job: add",- "[[wikilinks]] around existing words that match entries in the wiki",- "index. You do NOT rewrite, summarize, or expand the page.",+ "You identify which terms in a wiki page should become [[wikilinks]] pointing to existing wiki pages.","",buildLanguageDirective(content),"",- `## Wiki Index (link to these pages)\n${index}`,+ "You will receive:",+ " - a wiki index listing existing pages (each line roughly like `- pagename`)",+ " - the content of ONE wiki page","",- "## Output Requirements (STRICT — violations will cause rejection)",+ "Return a JSON object listing which terms in the page content should be linked to which index entries.","",- "1. Return the COMPLETE original text with [[wikilinks]] inserted.",- "2. PRESERVE the YAML frontmatter block (--- ... ---) at the top EXACTLY,",- " byte-for-byte. Do not modify, reorder, or remove any frontmatter fields.",- "3. DO NOT add new sentences, paragraphs, summaries, or explanations.",- "4. DO NOT remove or rewrite any existing text.",- "5. Only wrap existing words with [[ and ]] where they match a wiki",- " index entry. First mention per page only.",- "6. Your output length MUST be close to the input length; adding",- " [[brackets]] changes length by only a handful of characters.",+ "Response format (EXACTLY this JSON shape, nothing else):",+ "{",+ " \"links\": [",+ " { \"term\": \"exact text appearing in the content\", \"target\": \"index page name\" }",+ " ]",+ "}","",- "If you would need to materially change the page to improve it, emit",- "the ORIGINAL TEXT UNCHANGED. Rewriting is explicitly forbidden.",+ "Rules:",+ "- Each \"term\" MUST be a literal substring present in the page content (case-sensitive).",+ "- Each \"target\" MUST be a page listed in the wiki index.",+ "- Include at most one entry per target (first mention).",+ "- Only include clearly-matching terms (e.g. if content mentions 'Transformer' and index has 'transformer', target='transformer' is correct).",+ "- If no terms should be linked, return `{\"links\": []}`.",+ "- Do NOT output preamble, explanations, or markdown fences — ONLY the JSON object.",+ "",+ `## Wiki Index\n${index}`,].join("\n"),},{role: "user",- content: `Add [[wikilinks]] to this wiki page:\n\n${content}`,+ content: `Page content:\n\n${content}`,},],{- onToken: (token) => { enriched += token },+ onToken: (token) => { raw += token },onDone: () => {},onError: () => {},},)- if (!enriched || enriched.length < content.length * 0.5) {- // LLM returned too little — probably an error, don't overwrite- return+ // Parse the LLM response. Be tolerant of fences / prose wrappers.+ const links = parseLinkResponse(raw)+ if (links.length === 0) return // nothing to do++ // Apply substitutions to the ORIGINAL content. This guarantees the only+ // change is inserted [[...]] brackets.+ const enriched = applyLinks(content, links)+ if (enriched === content) return++ await writeFile(fp, enriched)+ useWikiStore.getState().bumpDataVersion()+}++interface LinkEntry {+ term: string+ target: string+}++function parseLinkResponse(raw: string): LinkEntry[] {+ if (!raw.trim()) return []+ // Extract the first balanced {...}+ let text = raw.trim()+ text = text.replace(/^```(?:json)?\s*/i, "").replace(/\s*```\s*$/i, "")+ const start = text.indexOf("{")+ if (start === -1) return []++ let depth = 0+ let inStr = false+ let escape = false+ let end = -1+ for (let i = start; i < text.length; i++) {+ const ch = text[i]+ if (escape) { escape = false; continue }+ if (ch === "\\" && inStr) { escape = true; continue }+ if (ch === '"') { inStr = !inStr; continue }+ if (inStr) continue+ if (ch === "{") depth+++ else if (ch === "}") {+ depth--+ if (depth === 0) { end = i; break }+ }}- if (enriched.length > content.length * 2) {- // LLM rewrote the page instead of just adding links — reject to avoid- // destroying user content. Adding [[ ]] at most ~4 chars per link, so- // a reasonable enrichment stays well under 2× the original length.- console.warn(- `[enrich-wikilinks] LLM output too long (${enriched.length} vs ${content.length}) — rejecting`,- )- return+ if (end === -1) return []++ try {+ const parsed = JSON.parse(text.slice(start, end + 1)) as { links?: unknown }+ if (!parsed || !Array.isArray(parsed.links)) return []+ const result: LinkEntry[] = []+ for (const item of parsed.links) {+ if (+ item &&+ typeof item === "object" &&+ typeof (item as LinkEntry).term === "string" &&+ typeof (item as LinkEntry).target === "string" &&+ (item as LinkEntry).term.length > 0 &&+ (item as LinkEntry).target.length > 0+ ) {+ result.push({+ term: (item as LinkEntry).term,+ target: (item as LinkEntry).target,+ })+ }+ }+ return result+ } catch {+ return []}+}++/**+ * For each {term, target}, replace the FIRST literal occurrence of `term`+ * in content (outside of frontmatter and existing [[...]]) with `[[target|term]]`+ * if the displayed text should differ from target, or `[[target]]` if they+ * already match case-insensitively. Skip terms that don't appear as a+ * literal substring. Skip terms already inside an existing wikilink.+ */+function applyLinks(content: string, links: LinkEntry[]): string {+ // Split off YAML frontmatter so we don't touch it+ const fmEnd = content.startsWith("---\n") ? content.indexOf("\n---\n", 3) : -1+ const frontmatter = fmEnd > 0 ? content.slice(0, fmEnd + 5) : ""+ let body = fmEnd > 0 ? content.slice(fmEnd + 5) : content++ // Track what we've already linked so we don't double-link+ const linkedTargets = new Set<string>()++ for (const { term, target } of links) {+ if (linkedTargets.has(target.toLowerCase())) continue+ if (!term || !target) continue- // Frontmatter guard: if the input started with YAML frontmatter, the- // enriched output MUST too. Otherwise we'd silently lose metadata.- if (content.startsWith("---\n") && !enriched.startsWith("---\n")) {- console.warn(- `[enrich-wikilinks] LLM dropped YAML frontmatter — rejecting`,- )- return+ // Find first literal occurrence NOT already inside a [[...]] block+ const idx = findUnlinkedOccurrence(body, term)+ if (idx === -1) continue++ const displayEqualsTarget = term.toLowerCase() === target.toLowerCase()+ const replacement = displayEqualsTarget+ ? `[[${term}]]`+ : `[[${target}|${term}]]`+ body = body.slice(0, idx) + replacement + body.slice(idx + term.length)+ linkedTargets.add(target.toLowerCase())}- // Write the enriched version back- await writeFile(fp, enriched)+ return frontmatter + body+}- // Refresh graph- useWikiStore.getState().bumpDataVersion()+/** Find the first occurrence of `term` in text that isn't already wrapped in [[...]]. */+function findUnlinkedOccurrence(text: string, term: string): number {+ let searchFrom = 0+ while (searchFrom < text.length) {+ const idx = text.indexOf(term, searchFrom)+ if (idx === -1) return -1+ // Check a small window before for [[ (existing wikilink open)+ const windowStart = Math.max(0, idx - 2)+ const window = text.slice(windowStart, idx)+ if (window.endsWith("[[")) {+ searchFrom = idx + term.length+ continue+ }+ return idx+ }+ return -1}diff --git a/src/lib/ingest.real-llm.test.ts b/src/lib/ingest.real-llm.test.tsindex 54380220..9d34419a 100644--- a/src/lib/ingest.real-llm.test.ts+++ b/src/lib/ingest.real-llm.test.ts@@ -33,7 +33,10 @@ const MINIMAX_MODEL = process.env.MINIMAX_MODEL ?? "MiniMax-M2.7-highspeed"const MINIMAX_ENDPOINT = process.env.MINIMAX_ENDPOINT ?? "https://api.minimaxi.com/v1"const ENABLED = process.env.RUN_LLM_TESTS === "1"-const REAL_CONTENT_ROOT = path.join(process.cwd(), "tests", "fixtures", "real-content")+// Real content documents are checked into git under src/test-helpers/+// (NOT tests/fixtures/ — that path is gitignored) so other developers can+// reproduce these tests without regenerating content.+const REAL_CONTENT_ROOT = path.join(process.cwd(), "src", "test-helpers", "real-content")// Generous timeout to accommodate peak-hour API latency.// Two LLM calls per ingest × 1-4 min each + IO overhead.diff --git a/src/lib/ingest.ts b/src/lib/ingest.tsindex 68e0e760..ba9cd8c0 100644--- a/src/lib/ingest.ts+++ b/src/lib/ingest.ts@@ -8,6 +8,7 @@ import { useReviewStore, type ReviewItem } from "@/stores/review-store"import { getFileName, normalizePath } from "@/lib/path-utils"import { checkIngestCache, saveIngestCache } from "@/lib/ingest-cache"import { buildLanguageDirective } from "@/lib/output-language"+import { detectLanguage } from "@/lib/detect-language"// Path capture group allows any non-newline char so hyphenated paths like// "wiki/concepts/multi-head-attention.md" are accepted. The lazy `+?` plus@@ -236,15 +237,64 @@ export async function autoIngest(return writtenPaths}+/**+ * Per-file language guard. Strips frontmatter + code/math blocks, runs+ * detectLanguage on the remainder, and returns whether the content is in+ * a language family compatible with the target. This catches cases where+ * the LLM follows the format spec but writes a single page in a wrong+ * language (observed ~once in 5 real-LLM runs on MiniMax-M2.7-highspeed).+ */+function contentMatchesTargetLanguage(content: string, target: string): boolean {+ // Strip frontmatter+ const fmEnd = content.indexOf("\n---\n", 3)+ let body = fmEnd > 0 ? content.slice(fmEnd + 5) : content+ // Strip code + math+ body = body+ .replace(/```[\s\S]*?```/g, "")+ .replace(/\$\$[\s\S]*?\$\$/g, "")+ .replace(/\$[^$\n]*\$/g, "")+ const sample = body.slice(0, 1500)+ if (sample.trim().length < 20) return true // too short to judge++ const detected = detectLanguage(sample)++ // Compatible families: CJK targets accept CJK variants; Latin targets+ // accept any Latin family (English may mis-detect as Italian/French for+ // short idiomatic samples — that's fine). Cross-family is the real bug.+ const cjk = new Set(["Chinese", "Traditional Chinese", "Japanese", "Korean"])+ const targetIsCjk = cjk.has(target)+ const detectedIsCjk = cjk.has(detected)+ if (targetIsCjk) return detectedIsCjk+ return !detectedIsCjk && !["Arabic", "Hindi", "Thai", "Hebrew"].includes(detected)+}+async function writeFileBlocks(projectPath: string, text: string): Promise<string[]> {const writtenPaths: string[] = []const matches = text.matchAll(FILE_BLOCK_REGEX)+ const targetLang = useWikiStore.getState().outputLanguage+for (const match of matches) {const relativePath = match[1].trim()const content = match[2]if (!relativePath) continue+ // Language guard: reject individual FILE blocks whose body contradicts+ // the user-set target language. Log entries are short / structural so+ // skip the check for them.+ if (+ targetLang &&+ targetLang !== "auto" &&+ !relativePath.endsWith("/log.md") &&+ relativePath !== "wiki/log.md" &&+ !contentMatchesTargetLanguage(content, targetLang)+ ) {+ console.warn(+ `[ingest] dropping ${relativePath}: content not in target language ${targetLang}`,+ )+ continue+ }+const fullPath = `${projectPath}/${relativePath}`try {if (relativePath === "wiki/log.md" || relativePath.endsWith("/log.md")) {@@ -487,8 +537,16 @@ export function buildGenerationPrompt(schema: string, purpose: string, index: st"4. DO NOT output markdown tables, bullet lists, or headings outside of FILE/REVIEW blocks.","5. DO NOT output any trailing commentary after the last `---END FILE---` or `---END REVIEW---`.","6. Between blocks, use only blank lines — no prose.",+ "7. EVERY FILE block's content (titles, body, descriptions) MUST be in the mandatory output language specified below. No exceptions — not even for page names or section headings.","","If you start with anything other than `---FILE:`, the entire response will be discarded.",+ "",+ // Repeat the language directive at the very end so it wins the "most+ // recent instruction" tie-breaker. Small-to-medium models otherwise+ // drift back to their training-data language for individual pages.+ "---",+ "",+ languageRule(sourceContent),].filter(Boolean).join("\n")}diff --git a/src/test-helpers/real-content/flash-attention-paper.md b/src/test-helpers/real-content/flash-attention-paper.mdnew file mode 100644index 00000000..c26c2866--- /dev/null+++ b/src/test-helpers/real-content/flash-attention-paper.md@@ -0,0 +1,87 @@+# FlashAttention: Fast and Memory-Efficient Exact Attention with IO-Awareness++Tri Dao, Daniel Y. Fu, Stefano Ermon, Atri Rudra, Christopher Ré+(Stanford University, University at Buffalo)++## Abstract++Transformers are slow and memory-hungry on long sequences, since the time+and memory complexity of self-attention are quadratic in sequence length.+Approximate attention methods have attempted to address this problem by+trading off model quality to reduce the compute complexity, but often do+not achieve wall-clock speedup. We argue that a missing principle is making+attention algorithms IO-aware — accounting for reads and writes between+levels of GPU memory. We propose FlashAttention, an IO-aware exact+attention algorithm that uses tiling to reduce the number of memory reads+and writes between GPU high bandwidth memory (HBM) and GPU on-chip SRAM.+We analyze the IO complexity of FlashAttention, showing that it requires+fewer HBM accesses than standard attention, and is optimal for a range of+SRAM sizes.++## 1. Introduction++The transformer architecture has become ubiquitous in natural language+processing and is increasingly applied to vision, audio, and scientific+domains. Its core is the self-attention mechanism, which scales+quadratically with sequence length in both time and memory. This quadratic+cost has motivated a large body of work on approximate attention,+including sparse patterns, low-rank approximations, and kernel-based+methods. However, most of these approximations do not deliver wall-clock+speedups: they reduce the number of floating-point operations, but on+modern GPUs, attention is memory-bound, not compute-bound.++We identify the main bottleneck: moving attention matrices between GPU+high-bandwidth memory (HBM) and the much faster but smaller on-chip SRAM.+Standard attention implementations materialize the full N×N attention+matrix in HBM, requiring O(N²) reads and writes. FlashAttention instead+never materializes this matrix; it computes attention in blocks that fit+in SRAM, using tiling and a recomputation trick for the backward pass.++## 2. Background: Memory Hierarchy on GPUs++GPUs have a memory hierarchy: registers, shared memory (per-streaming-+multiprocessor SRAM), and HBM. HBM is large (40-80 GB on A100) but slow+(~1.5 TB/s), while shared memory is tiny (~192 KB per SM on A100) but+extremely fast (~19 TB/s). Kernel runtime is often dominated by HBM+traffic rather than compute. An IO-aware algorithm carefully schedules+computation to minimize HBM reads and writes.++## 3. The FlashAttention Algorithm++The forward pass of FlashAttention works as follows. Queries Q, keys K,+and values V are split into blocks that fit in SRAM. For each block of+queries, we iterate over blocks of keys and values, computing partial+attention scores and maintaining running statistics (max for numerical+stability and sum for normalization). The final output for each query+block is assembled from these block-wise partial results.++The crucial observation: we never need to materialize the full N×N+attention matrix. We only need per-block statistics, which fit in SRAM.++For the backward pass, we cannot afford to store the full attention matrix+either. Instead, FlashAttention uses a recomputation trick: during the+forward pass, we save the statistics (max and sum per row) along with the+output. During the backward pass, we recompute the attention matrix in+blocks on the fly, using the saved statistics to avoid re-deriving them.++## 4. IO Complexity Analysis++Standard attention: Ω(Nd + N²) HBM accesses, where N is sequence length+and d is head dimension. The N² term comes from reading/writing the+attention matrix.++FlashAttention: O(N²d²/M) HBM accesses, where M is SRAM size. For typical+GPU configurations (d ≈ 64, M ≈ 100 KB), this is strictly better than+standard attention whenever N > M/d ≈ 1500. For long sequences (N ≥ 2K),+FlashAttention is orders of magnitude more IO-efficient.++## 5. Empirical Results++FlashAttention yields 2-4× wall-clock speedup over PyTorch attention on+GPT-2 training, with no quality degradation (it is exact, not approximate).+On BERT training, we observe 15% end-to-end speedup. Most strikingly,+FlashAttention enables much longer contexts: models that previously OOM at+N=2K now train with N=16K or more on the same hardware.++FlashAttention has been integrated into PyTorch, DeepSpeed, MegatronLM, and+is now standard in most transformer training pipelines.diff --git a/src/test-helpers/real-content/lora-paper.md b/src/test-helpers/real-content/lora-paper.mdnew file mode 100644index 00000000..6e0babce--- /dev/null+++ b/src/test-helpers/real-content/lora-paper.md@@ -0,0 +1,100 @@+# LoRA: Low-Rank Adaptation of Large Language Models++Edward J. Hu, Yelong Shen, Phillip Wallis, Zeyuan Allen-Zhu, Yuanzhi Li,+Shean Wang, Lu Wang, Weizhu Chen (Microsoft Corporation)++## Abstract++An important paradigm of natural language processing consists of+large-scale pre-training on general domain data and adaptation to+particular tasks or domains. As we pre-train larger models, full+fine-tuning, which retrains all model parameters, becomes less feasible.+Using GPT-3 175B as an example — deploying independent instances of+fine-tuned models, each with 175B parameters, is prohibitively expensive.+We propose Low-Rank Adaptation, or LoRA, which freezes the pre-trained+model weights and injects trainable rank decomposition matrices into each+layer of the Transformer architecture, greatly reducing the number of+trainable parameters for downstream tasks. Compared to GPT-3 175B+fine-tuned with Adam, LoRA can reduce the number of trainable parameters+by 10,000 times and the GPU memory requirement by 3 times.++## 1. Introduction++Large pre-trained language models like GPT-3 contain hundreds of billions+of parameters. Full fine-tuning adapts every parameter to a downstream+task, producing a new copy of the model. At deployment, each fine-tuned+task requires storing and serving a full-size model, which is infeasible+at scale — a single 175B model occupies ~350 GB in fp16 and requires+multiple high-end GPUs to serve.++Parameter-efficient fine-tuning (PEFT) methods aim to adapt large models+to new tasks by training only a small number of extra parameters, leaving+the base model frozen and shared across tasks. Prior PEFT methods include+adapter layers (small MLPs inserted into each transformer block) and+prefix tuning (learnable prefix tokens). Both introduce inference latency+or have difficulty scaling to large models.++## 2. LoRA Formulation++Let W₀ ∈ ℝ^(d×k) be a weight matrix in the pre-trained transformer. During+fine-tuning, instead of updating W₀ to W₀ + ΔW, LoRA represents the update+as a low-rank decomposition:++ ΔW = BA++where B ∈ ℝ^(d×r), A ∈ ℝ^(r×k), and r is a small rank (typically 4, 8, or+16). The forward pass becomes:++ h = W₀x + BAx++At initialization, A is drawn from a random Gaussian and B is zero, so+ΔW = BA = 0. This ensures LoRA starts as a no-op identical to the+pre-trained model. During training, only A and B are updated; W₀ stays+frozen.++The number of trainable parameters is reduced from d×k (full fine-tune)+to r(d + k) (LoRA). For d = k = 4096 and r = 8, this is a ~500×+reduction.++## 3. Applying LoRA to Transformers++LoRA can in principle be applied to any dense layer. In practice, we+apply it only to the attention weights (Wq, Wk, Wv, Wo) and leave the+MLP, LayerNorm, and embeddings frozen. This choice is empirically+motivated: adapting attention is sufficient for most downstream tasks,+and omitting MLP saves substantial parameters.++At inference time, the LoRA update can be merged into the base weights:+ W = W₀ + BA+producing a single matrix with no additional inference cost. This is a+key advantage over adapter methods, which always add inference latency.++## 4. Experimental Results++We evaluate LoRA against full fine-tuning, adapter tuning, and prefix+tuning on GPT-3 175B across GLUE, WikiSQL, SAMSum, and others. Headline+findings:++- **Parameter reduction**: LoRA with r=8 uses 0.01% of full fine-tuning+ parameters (37.7M vs 175B).+- **Performance parity**: On most tasks LoRA matches or exceeds full+ fine-tuning quality.+- **Lower GPU memory**: 3× reduction during training (no optimizer state+ for the base model).+- **No inference overhead**: Merged LoRA is indistinguishable from a+ normally fine-tuned model at inference.++## 5. Rank Analysis++A natural question: how small can r be? Empirically, r=1 or r=2 already+captures most of the adaptation for many tasks. This suggests that+task-specific adaptation lives in a very low-dimensional subspace of the+full parameter space — a striking structural fact about large pre-trained+models.++## 6. Impact++LoRA has become the standard way to fine-tune large language models. It+powers popular tools like PEFT (HuggingFace), has spawned extensions like+QLoRA (4-bit quantized base + LoRA), and enables the thriving ecosystem+of fine-tuned open-weights models on consumer GPUs.diff --git a/src/test-helpers/real-content/rope-paper.md b/src/test-helpers/real-content/rope-paper.mdnew file mode 100644index 00000000..259c097b--- /dev/null+++ b/src/test-helpers/real-content/rope-paper.md@@ -0,0 +1,95 @@+# RoFormer: Enhanced Transformer with Rotary Position Embedding++Jianlin Su, Yu Lu, Shengfeng Pan, Ahmed Murtadha, Bo Wen, Yunfeng Liu+(Zhuiyi Technology Co., Ltd., Shenzhen)++## Abstract++Position encoding recently has shown effective in the transformer architecture.+It enables valuable supervision for dependency modeling between elements at+different positions of the sequence. In this paper, we first investigate various+methods to integrate positional information into the learning process of+transformer-based language models. Then, we propose a novel method named Rotary+Position Embedding (RoPE) to effectively leverage the positional information.+Specifically, the proposed RoPE encodes the absolute position with a rotation+matrix and meanwhile incorporates the explicit relative position dependency in+self-attention formulation. Notably, RoPE enables valuable properties, including+the flexibility of sequence length, decaying inter-token dependency with+increasing relative distances, and the capability of equipping the linear+self-attention with relative position encoding. Finally, we evaluate the+enhanced transformer with rotary position embedding, also called RoFormer, on+various long text classification benchmark datasets. Our experiments show that+it consistently overcomes its alternatives.++## 1. Introduction++The sequential order of words is of great value to natural language understanding.+Recurrent neural networks (RNNs) encode the order of tokens by recursively+computing a hidden state along the time dimension. Convolutional neural networks+(CNNs) were thought to be position-agnostic, but recent work has shown that the+commonly used padding operation can implicitly learn positional information.++Recently, the transformer, which is built on top of the self-attention mechanism,+has become the de facto backbone for many natural language processing (NLP) tasks.+Unlike RNN- and CNN-based models, the self-attention mechanism in vanilla+transformers is parallelizable with position-agnostic computations. As a+consequence, various approaches have been proposed to incorporate positional+information into the learning process.++On one hand, absolute position encoding adds position-dependent signals directly+to the context representations, either through a pre-defined function (such as+the sinusoidal encoding used in the original Transformer) or through learnable+embeddings. On the other hand, relative position encodings typically modify the+attention mechanism to be aware of the relative distance between tokens rather+than absolute positions. Shaw et al. (2018) first introduced relative position+encoding by adding a learnable relative position representation to the keys and+values in the attention computation. Subsequent work, including Transformer-XL+and T5, refined this idea with different parameterizations.++## 2. Motivation for Rotary Position Embedding++Both families have limitations. Absolute methods do not naturally generalize to+sequences longer than those seen during training, and they complicate the+extension to relative information. Existing relative methods modify the attention+matrix directly and cannot trivially be combined with efficient attention+variants (such as linear attention) that factorize the attention computation.++We ask: is there a way to encode position that (a) yields relative position+information through standard dot-product attention, (b) extends to arbitrary+sequence length, and (c) is compatible with linear-time attention variants? Our+answer is Rotary Position Embedding.++## 3. Formulation++Given a query vector q at position m and a key vector k at position n, define a+rotation matrix R_Θ,m that rotates q by an angle proportional to m. Applying+R_Θ,m to q and R_Θ,n to k yields the property that the inner product between the+rotated q and the rotated k depends only on the original vectors and the+difference m − n. In other words, absolute position is injected into each+vector, but the attention score between two tokens captures only their relative+position — exactly the behavior we want.++The rotation is applied pairwise across feature dimensions: each consecutive pair+of dimensions is treated as a 2D subspace that is rotated by a frequency-scaled+angle. This extends naturally to arbitrary model dimension d, and is efficient+to compute: no modification to the attention matrix is required, and the same+rotation can be applied in linear attention.++## 4. Properties++- **Long-range decay.** As the relative distance m − n grows, the inner-product+ magnitude decays smoothly, giving the model a useful inductive bias.+- **Sequence-length flexibility.** Because the rotation is a pure function of+ position, no maximum-length hyperparameter needs to be chosen in advance.+- **Linear-attention compatible.** Unlike relative-position methods that add+ terms to the attention matrix, RoPE modifies only the query/key vectors and+ can be used with kernel-based linear attention.++## 5. Empirical Results++We replace the sinusoidal absolute position embedding in a standard transformer+with RoPE, producing what we call RoFormer. On long-text classification tasks+including CAIL2019-SCM and a range of GLUE-style benchmarks, RoFormer outperforms+the vanilla transformer, particularly as input length grows. The gap widens at+inference lengths beyond those seen during training, confirming the+length-flexibility argument.diff --git a/src/test-helpers/real-content/transformer-survey-zh.md b/src/test-helpers/real-content/transformer-survey-zh.mdnew file mode 100644index 00000000..9346640d--- /dev/null+++ b/src/test-helpers/real-content/transformer-survey-zh.md@@ -0,0 +1,97 @@+# Transformer 架构综述++## 摘要++Transformer 架构自 2017 年由 Vaswani 等人在论文《Attention Is All You Need》+中提出以来,已成为自然语言处理和众多其他领域的主导模型架构。本文系统梳理了+Transformer 的核心组件、关键变体以及其在过去数年间的演进脉络,重点关注注意力+机制的不同实现、位置编码方案、模型规模的 Scaling Law 以及针对效率和长序列+建模的多种优化方法。++## 1. 引言++在 Transformer 出现之前,循环神经网络(RNN)和长短期记忆网络(LSTM)是序列+建模的主流方案。它们按时间步依次处理输入,难以并行化,而且对于长距离依赖+的建模存在梯度消失等问题。卷积神经网络(CNN)虽然可以并行,但单层的感受野+有限,需要堆叠多层才能捕获长距离关系。++Transformer 抛弃了循环与卷积,完全基于自注意力机制来建模输入序列各位置之间+的依赖。它天然支持并行计算,同时每一层都能直接建模任意两个位置之间的关系,+突破了 RNN 在长距离依赖上的局限。++## 2. 核心组件++### 2.1 自注意力机制++自注意力的核心是对每个位置 i,计算它与所有位置 j 的相关性(attention score),+并据此对各位置的值向量做加权求和。具体而言,给定查询矩阵 Q、键矩阵 K、值+矩阵 V,注意力输出为:++ Attention(Q, K, V) = softmax(QK^T / √d_k) · V++其中 d_k 是键向量的维度,除以 √d_k 是为了防止点积值过大导致 softmax 梯度消失+(即缩放点积注意力,scaled dot-product attention)。++### 2.2 多头注意力++多头注意力(Multi-Head Attention)将查询、键、值分别投影到多个子空间,每个+子空间独立做注意力计算,最后拼接再投影回原维度。这让模型能够同时关注不同+类型的关系(例如语法、语义、共指)。++### 2.3 位置编码++由于注意力机制本身不具备顺序感,需要显式地向输入中注入位置信息。最早的方案+是正弦/余弦位置编码。后来出现了可学习的绝对位置嵌入、相对位置编码+(Shaw et al., 2018)、以及 RoPE(Rotary Position Embedding,Su et al., 2021)+等更先进的方案。RoPE 通过旋转矩阵将绝对位置信息注入查询和键向量,使得注意力+分数仅依赖于相对位置,目前已成为许多大模型的标配。++## 3. 关键变体++### 3.1 Encoder-only:BERT 系++BERT 及其衍生模型(RoBERTa, ALBERT, ELECTRA)使用双向 Transformer encoder,+通过 masked language modeling 任务进行预训练,擅长理解类任务。++### 3.2 Decoder-only:GPT 系++GPT 系列使用单向(causal)Transformer decoder,通过自回归语言建模进行预训练。+GPT-3/4、LLaMA、Qwen、DeepSeek 等当代主流大语言模型都基于 decoder-only 架构。++### 3.3 Encoder-Decoder:T5、BART++保留原始 Transformer 的完整 encoder-decoder 结构,适用于翻译、摘要等序列到+序列任务。++## 4. 效率优化++### 4.1 注意力近似++标准自注意力的时间和空间复杂度均为 O(N²),对长序列不友好。近似方法包括:+Sparse Attention(Longformer、BigBird)、低秩近似(Performer、Linformer)、+线性注意力等。这些方法以轻微质量损失换取显著速度提升。++### 4.2 IO 感知优化++FlashAttention(Dao et al., 2022)不近似注意力矩阵,而是通过分块计算避免+将完整的 N×N 矩阵写入 HBM。它是精确注意力,但在 GPU 上的实际 wall-clock+速度比 PyTorch 原生实现快 2-4 倍,已成为训练与推理的事实标准。++### 4.3 参数高效微调++在模型规模突破千亿参数后,全量微调(full fine-tuning)成本过高。LoRA(Hu et al.,+2021)通过在注意力权重旁增加低秩矩阵,仅训练极少量参数即可达到与全量微调+相当的效果,极大降低了微调成本。++## 5. Scaling Law++Kaplan et al. (2020) 和 Hoffmann et al. (Chinchilla, 2022) 的研究表明,+Transformer 的性能遵循明确的 scaling law:随模型参数量 N、训练数据量 D、计算+量 C 的幂律提升。这启发了 GPT-4、LLaMA-3、Qwen3 等更大规模模型的训练策略,+也为"更大即更好"提供了理论依据。++## 6. 未来方向++目前的研究热点包括:超长上下文(1M+ token)、多模态融合、专家混合+(Mixture of Experts, MoE)架构、以及推理链式思维(Chain-of-Thought)等。+Transformer 作为基础架构仍在持续演进。diff --git a/src/test-helpers/scenarios/enrich-scenarios.ts b/src/test-helpers/scenarios/enrich-scenarios.tsindex 9dff06b0..2574097d 100644--- a/src/test-helpers/scenarios/enrich-scenarios.ts+++ b/src/test-helpers/scenarios/enrich-scenarios.ts@@ -1,9 +1,12 @@import type { EnrichScenario } from "./types"/**- * Reminder: enrichWithWikilinks only writes back to disk if the LLM- * response length is at least 50% of the original content length- * (guards against LLM errors returning something short and bogus).+ * v2: enrichWithWikilinks now asks the LLM to return a JSON list of+ * {term, target} substitutions instead of rewriting the whole page. Code+ * does the actual string replacement. See enrich-wikilinks.ts for the+ * design note.+ *+ * These mocked scenarios exercise the JSON→substitution path.*/const WIKI_INDEX_WITH_TRANSFORMER = `# Index@@ -15,13 +18,13 @@ const WIKI_INDEX_WITH_TRANSFORMER = `# Index`export const enrichScenarios: EnrichScenario[] = [- // 1. adds-wikilinks — LLM wraps recognized terms with [[...]]+ // 1. adds-wikilinks — LLM returns a JSON list; code adds [[brackets]].{name: "adds-wikilinks",description:- "A page mentions 'Transformer' without wikilinks. LLM returns the " +- "same content with [[Transformer]] added on first mention. " +- "writeFile must be called with the enriched content.",+ "LLM returns a JSON list identifying Transformer and Attention as " ++ "terms to link. Code applies [[brackets]] around the first literal " ++ "occurrence of each.",initialWiki: {"wiki/index.md": WIKI_INDEX_WITH_TRANSFORMER,"wiki/survey.md":@@ -31,14 +34,16 @@ export const enrichScenarios: EnrichScenario[] = ["Attention is the key mechanism that makes it work.\n",},pageToEnrich: "wiki/survey.md",- // Enriched version — same length-ish (LLM guard: >= 50% of original length).- llmResponse:- "# Deep Learning Survey\n\n" +- "Modern NLP relies on [[Transformer]] architectures for most tasks. " +- "The Transformer was introduced in 2017 and has since dominated. " +- "[[Attention]] is the key mechanism that makes it work.\n",+ llmResponse: JSON.stringify({+ links: [+ { term: "Transformer", target: "transformer" },+ { term: "Attention", target: "attention" },+ ],+ }),expected: {writeCalled: true,+ // When term and target match case-insensitively, applyLinks emits+ // [[term]] (original casing preserved) rather than [[target|term]].expectedContent:"# Deep Learning Survey\n\n" +"Modern NLP relies on [[Transformer]] architectures for most tasks. " +@@ -47,13 +52,13 @@ export const enrichScenarios: EnrichScenario[] = [},},- // 2. preserves-frontmatter — YAML block must survive enrichment verbatim+ // 2. preserves-frontmatter — YAML block is never touched by code{name: "preserves-frontmatter",description:- "Page has YAML frontmatter with title, tags, sources. LLM response " +- "must preserve the frontmatter exactly. writeFile is called and the " +- "content starts with the original frontmatter.",+ "Frontmatter preservation is now a code-level guarantee: the " ++ "applier splits off the frontmatter and only operates on the body. " ++ "LLM just returns the term→target list.",initialWiki: {"wiki/index.md": WIKI_INDEX_WITH_TRANSFORMER,"wiki/attention.md":@@ -67,15 +72,9 @@ export const enrichScenarios: EnrichScenario[] = ["uses these scores to weight values. Detailed derivation below.\n",},pageToEnrich: "wiki/attention.md",- llmResponse:- "---\n" +- "title: Attention\n" +- "tags: [deep-learning, transformer]\n" +- "sources: [paper-2017.pdf]\n" +- "---\n\n" +- "# Attention\n\n" +- "Attention scores are computed by the [[encoder]]. The [[encoder]] layer " +- "uses these scores to weight values. Detailed derivation below.\n",+ llmResponse: JSON.stringify({+ links: [{ term: "encoder", target: "encoder" }],+ }),expected: {writeCalled: true,expectedContent:@@ -85,40 +84,37 @@ export const enrichScenarios: EnrichScenario[] = ["sources: [paper-2017.pdf]\n" +"---\n\n" +"# Attention\n\n" +- "Attention scores are computed by the [[encoder]]. The [[encoder]] layer " ++ "Attention scores are computed by the [[encoder]]. The encoder layer " +"uses these scores to weight values. Detailed derivation below.\n",},},- // 3. short-response-rejected — guards against truncated LLM replies+ // 3. no-matches-no-write — LLM returns empty list; nothing written{- name: "short-response-rejected",+ name: "no-matches-no-write",description:- "Original content is long (~400 chars) but LLM returns only a brief " +- "snippet (<50% original length). The guard rejects the write to avoid " +- "data loss. writeFile MUST NOT be called.",+ "LLM returns {links:[]} — nothing to substitute. writeFile is not " ++ "called; the file stays unchanged.",initialWiki: {"wiki/index.md": WIKI_INDEX_WITH_TRANSFORMER,- "wiki/long-page.md":- "# Long Page\n\n" +- "This page has substantial content that must not be clobbered by a " +- "truncated LLM response. ".repeat(10) +- "\n\nFinal line here for good measure.\n",+ "wiki/unrelated.md":+ "# Unrelated Page\n\n" ++ "This page is about cats and dogs and has nothing to do with the " ++ "wiki's main topics. No terms should be linked here.\n",},- pageToEnrich: "wiki/long-page.md",- // Way shorter than original — must trigger the guard- llmResponse: "Short reply with [[attention]].",+ pageToEnrich: "wiki/unrelated.md",+ llmResponse: JSON.stringify({ links: [] }),expected: {writeCalled: false,},},- // 4. cjk-terms — Chinese content + Chinese wikilinks+ // 4. cjk-terms — Chinese substitutions{name: "cjk-terms",description:- "Chinese content with Chinese wiki index entries. LLM adds CJK " +- "wikilinks on first mention. UTF-8 round-trip must be clean.",+ "Chinese content; LLM returns list with Chinese term / target. " ++ "Byte-accurate substitution through UTF-8.",initialWiki: {"wiki/index.md": "# 索引\n\n- [[注意力机制]]\n- [[transformer]]\n","wiki/intro.md":@@ -127,10 +123,12 @@ export const enrichScenarios: EnrichScenario[] = ["注意力机制让模型能够关注序列中最相关的部分。\n",},pageToEnrich: "wiki/intro.md",- llmResponse:- "# 简介\n\n" +- "[[注意力机制]]是 [[transformer]] 架构的核心组件之一。" +- "注意力机制让模型能够关注序列中最相关的部分。\n",+ llmResponse: JSON.stringify({+ links: [+ { term: "注意力机制", target: "注意力机制" },+ { term: "transformer", target: "transformer" },+ ],+ }),expected: {writeCalled: true,expectedContent: