mirror of
https://github.com/onestardao/WFGY.git
synced 2026-04-28 11:40:07 +00:00
Update README.md
This commit is contained in:
parent
0b036854d6
commit
b59e10df58
1 changed files with 184 additions and 117 deletions
|
|
@ -1,130 +1,196 @@
|
|||
# Retrieval — Global Fix Map
|
||||
Make your retriever correct, predictable, and auditable.
|
||||
Use this when recall looks random, hybrid behaves worse than single, or k-tuning never stabilizes.
|
||||
|
||||
## What this page is
|
||||
- A short, practical path to stabilize recall and ordering
|
||||
- Exact knobs for dense, sparse, and hybrid without guesswork
|
||||
- How to prove fixes with ΔS curves and citation tables
|
||||
A hub to stabilize retrieval quality across stacks, models, and stores. Use this page to route symptoms to the exact structural fix, verify with measurable targets, and keep your pipeline store agnostic.
|
||||
|
||||
## When to use
|
||||
- Top-k results feel unrelated or change on every run
|
||||
- Hybrid merge hurts more than single retriever
|
||||
- Raising k only adds noise, does not surface the right snippet
|
||||
- Filters, analyzers, or languages do not align with your corpus
|
||||
- HyDE or query rewriting helps sometimes then flips back
|
||||
|
||||
## Open these first
|
||||
- End to end knobs: [Retrieval Playbook](https://github.com/onestardao/WFGY/blob/main/ProblemMap/retrieval-playbook.md)
|
||||
- Ordering after recall: [Rerankers](https://github.com/onestardao/WFGY/blob/main/ProblemMap/rerankers.md)
|
||||
- Why this snippet, trace schema: [Retrieval Traceability](https://github.com/onestardao/WFGY/blob/main/ProblemMap/retrieval-traceability.md)
|
||||
- Hybrid tokenization split: [Query Parsing Split](https://github.com/onestardao/WFGY/blob/main/ProblemMap/patterns/pattern_query_parsing_split.md)
|
||||
- Hallucination from bad boundaries: [Hallucination](https://github.com/onestardao/WFGY/blob/main/ProblemMap/hallucination.md)
|
||||
- Cosine match is not meaning: [Embedding ≠ Semantic](https://github.com/onestardao/WFGY/blob/main/ProblemMap/embedding-vs-semantic.md)
|
||||
- Some facts never retrieve: [Vectorstore Fragmentation](https://github.com/onestardao/WFGY/blob/main/ProblemMap/patterns/pattern_vectorstore_fragmentation.md)
|
||||
- Visual pipeline and recovery: [RAG Architecture & Recovery](https://github.com/onestardao/WFGY/blob/main/ProblemMap/rag-architecture-and-recovery.md)
|
||||
- Eval targets: [RAG Precision and Recall](https://github.com/onestardao/WFGY/blob/main/ProblemMap/eval/eval_rag_precision_recall.md)
|
||||
- Snippet and citation schema: [Data Contracts](https://github.com/onestardao/WFGY/blob/main/ProblemMap/data-contracts.md)
|
||||
|
||||
## Fix in 60 seconds
|
||||
1) **Probe ΔS vs k**
|
||||
- Record `ΔS(question, retrieved)` for k in {5, 10, 20} for each retriever separately.
|
||||
- Flat and high for all k indicates index or metric mismatch or population gaps. Fix store first.
|
||||
|
||||
2) **Establish a strong single baseline**
|
||||
- Pick the retriever with the lowest stable ΔS at small k.
|
||||
- Freeze its tokenizer, analyzer, language, stopword set. Save params to disk.
|
||||
|
||||
3) **Unify query parsing**
|
||||
- Ensure the same analyzer and lowercasing for write and read.
|
||||
- If using HyDE or rewrites, log the final string sent to each retriever and keep it identical across them.
|
||||
|
||||
4) **Hybrid only after per retriever stability**
|
||||
- Do not mix until each single retriever yields ΔS ≤ 0.50.
|
||||
- Start with a simple weighted sum and a light reranker. Keep citations to audit the change.
|
||||
|
||||
5) **Filters and fields**
|
||||
- Disable filters first to confirm baseline recall.
|
||||
- Reapply with exact field weights and language settings. Check for case and tokenizer mismatches.
|
||||
|
||||
6) **Dedupe and diversity**
|
||||
- Apply MMR or novelty at the rerank stage if results cluster.
|
||||
- Keep a per source fence so different documents do not merge.
|
||||
|
||||
7) **Prompt assembly sanity**
|
||||
- Use citation first schema from traceability.
|
||||
- Do not reorder sections once stable.
|
||||
|
||||
8) **Warm up and cache**
|
||||
- Run a deterministic warm up after deploy.
|
||||
- Verify repeatability across restarts.
|
||||
|
||||
## Copy paste prompt
|
||||
```
|
||||
|
||||
I uploaded TXT OS and WFGY ProblemMap pages.
|
||||
|
||||
My retrieval bug:
|
||||
|
||||
* symptom: \[brief]
|
||||
* ΔS vs k per retriever: {...}
|
||||
* single retriever baselines: \[dense], \[BM25], \[hybrid attempt]
|
||||
* analyzers/tokenizers: write=\[...], read=\[...], lowercasing=\[on|off], stopwords=\[profile]
|
||||
* filters/fields: \[list]
|
||||
* HyDE or rewrites: \[yes/no], final query strings logged: \[examples]
|
||||
|
||||
Tell me:
|
||||
|
||||
1. which parsing or configuration mismatch explains the failure,
|
||||
2. which exact WFGY pages to open,
|
||||
3. minimal steps to push ΔS ≤ 0.45 at k=10 without overfitting,
|
||||
4. how to verify with precision/recall and a snippet ↔ citation table.
|
||||
Use rerankers only after recall is stable.
|
||||
|
||||
```
|
||||
|
||||
## Minimal checklist
|
||||
- Same analyzer, language, and case handling on write and read
|
||||
- Log the exact query string per retriever including HyDE output
|
||||
- Stabilize a single retriever before mixing hybrids
|
||||
- Keep field weights explicit and versioned
|
||||
- Do not change k and temperature together when measuring ΔS
|
||||
- Add reranker only after recall metrics pass
|
||||
- Enforce per source fences to avoid cross document blending
|
||||
- Persist a warm up routine for post deploy parity
|
||||
## When to use this folder
|
||||
- High similarity but wrong meaning.
|
||||
- Correct facts exist in the corpus but never show up.
|
||||
- Citations inconsistent or missing across steps.
|
||||
- Hybrid retrieval underperforms a single retriever.
|
||||
- Index looks healthy while coverage remains low.
|
||||
|
||||
## Acceptance targets
|
||||
- ΔS(question, retrieved) ≤ 0.45 across three paraphrases
|
||||
- Precision and recall meet your eval sheet with traceable citations
|
||||
- ΔS vs k descends then stabilizes, no oscillation when k grows
|
||||
- Same answers across restarts after warm up
|
||||
- λ at retrieval remains convergent while reasoning proceeds
|
||||
- ΔS(question, retrieved) ≤ 0.45
|
||||
- Coverage of target section ≥ 0.70
|
||||
- λ remains convergent across 3 paraphrases and 2 seeds
|
||||
- E_resonance stays flat on long windows
|
||||
|
||||
---
|
||||
|
||||
## Quick routes — core fixes
|
||||
|
||||
- Visual map and recovery
|
||||
→ [RAG Architecture & Recovery](https://github.com/onestardao/WFGY/blob/main/ProblemMap/rag-architecture-and-recovery.md)
|
||||
|
||||
- End to end knobs and rebuild order
|
||||
→ [Retrieval Playbook](https://github.com/onestardao/WFGY/blob/main/ProblemMap/retrieval-playbook.md)
|
||||
|
||||
- Why this snippet
|
||||
→ [Retrieval Traceability](https://github.com/onestardao/WFGY/blob/main/ProblemMap/retrieval-traceability.md)
|
||||
|
||||
- Snippet and citation schema
|
||||
→ [Data Contracts](https://github.com/onestardao/WFGY/blob/main/ProblemMap/data-contracts.md)
|
||||
|
||||
- Embedding vs meaning
|
||||
→ [embedding-vs-semantic.md](https://github.com/onestardao/WFGY/blob/main/ProblemMap/embedding-vs-semantic.md)
|
||||
|
||||
- Chunk boundaries and audits
|
||||
→ [chunking-checklist.md](https://github.com/onestardao/WFGY/blob/main/ProblemMap/chunking-checklist.md)
|
||||
|
||||
- Ordering control
|
||||
→ [rerankers.md](https://github.com/onestardao/WFGY/blob/main/ProblemMap/rerankers.md)
|
||||
|
||||
- Hybrid query failure
|
||||
→ [pattern_query_parsing_split.md](https://github.com/onestardao/WFGY/blob/main/ProblemMap/patterns/pattern_query_parsing_split.md)
|
||||
|
||||
- Store fragmentation
|
||||
→ [pattern_vectorstore_fragmentation.md](https://github.com/onestardao/WFGY/blob/main/ProblemMap/patterns/pattern_vectorstore_fragmentation.md)
|
||||
|
||||
---
|
||||
|
||||
## Store agnostic routes in this folder
|
||||
|
||||
- Guardrails and probes
|
||||
→ [store_agnostic_guardrails.md](https://github.com/onestardao/WFGY/blob/main/ProblemMap/GlobalFixMap/Retrieval/store_agnostic_guardrails.md)
|
||||
|
||||
- Hybrid and reranker recipes
|
||||
→ [hybrid_reranker_recipe.md](https://github.com/onestardao/WFGY/blob/main/ProblemMap/GlobalFixMap/Retrieval/hybrid_reranker_recipe.md)
|
||||
|
||||
- ΔS and λ probe pack
|
||||
→ [deltaS_probes.md](https://github.com/onestardao/WFGY/blob/main/ProblemMap/GlobalFixMap/Retrieval/deltaS_probes.md)
|
||||
|
||||
- Chunk alignment and anchor tests
|
||||
→ [chunk_alignment.md](https://github.com/onestardao/WFGY/blob/main/ProblemMap/GlobalFixMap/Retrieval/chunk_alignment.md)
|
||||
|
||||
- Retrieval eval recipes
|
||||
→ [retrieval_eval_recipes.md](https://github.com/onestardao/WFGY/blob/main/ProblemMap/GlobalFixMap/Retrieval/retrieval_eval_recipes.md)
|
||||
|
||||
---
|
||||
|
||||
## Vector DBs — jump if store specific
|
||||
|
||||
- Family index
|
||||
→ [Vector DBs & Stores](https://github.com/onestardao/WFGY/blob/main/ProblemMap/GlobalFixMap/VectorDBs_and_Stores/README.md)
|
||||
|
||||
- Direct routes
|
||||
→ [faiss.md](https://github.com/onestardao/WFGY/blob/main/ProblemMap/GlobalFixMap/VectorDBs_and_Stores/faiss.md) ·
|
||||
[chroma.md](https://github.com/onestardao/WFGY/blob/main/ProblemMap/GlobalFixMap/VectorDBs_and_Stores/chroma.md) ·
|
||||
[qdrant.md](https://github.com/onestardao/WFGY/blob/main/ProblemMap/GlobalFixMap/VectorDBs_and_Stores/qdrant.md) ·
|
||||
[weaviate.md](https://github.com/onestardao/WFGY/blob/main/ProblemMap/GlobalFixMap/VectorDBs_and_Stores/weaviate.md) ·
|
||||
[milvus.md](https://github.com/onestardao/WFGY/blob/main/ProblemMap/GlobalFixMap/VectorDBs_and_Stores/milvus.md) ·
|
||||
[pgvector.md](https://github.com/onestardao/WFGY/blob/main/ProblemMap/GlobalFixMap/VectorDBs_and_Stores/pgvector.md) ·
|
||||
[redis.md](https://github.com/onestardao/WFGY/blob/main/ProblemMap/GlobalFixMap/VectorDBs_and_Stores/redis.md) ·
|
||||
[elasticsearch.md](https://github.com/onestardao/WFGY/blob/main/ProblemMap/GlobalFixMap/VectorDBs_and_Stores/elasticsearch.md) ·
|
||||
[pinecone.md](https://github.com/onestardao/WFGY/blob/main/ProblemMap/GlobalFixMap/VectorDBs_and_Stores/pinecone.md) ·
|
||||
[typesense.md](https://github.com/onestardao/WFGY/blob/main/ProblemMap/GlobalFixMap/VectorDBs_and_Stores/typesense.md) ·
|
||||
[vespa.md](https://github.com/onestardao/WFGY/blob/main/ProblemMap/GlobalFixMap/VectorDBs_and_Stores/vespa.md)
|
||||
|
||||
---
|
||||
|
||||
## Symptoms → structural fixes
|
||||
|
||||
| Symptom | Likely cause | Open this |
|
||||
|---|---|---|
|
||||
| High similarity yet wrong answer | metric or analyzer mismatch | [embedding-vs-semantic.md](https://github.com/onestardao/WFGY/blob/main/ProblemMap/embedding-vs-semantic.md) |
|
||||
| Correct fact never retrieved | fragmentation or missing anchors | [pattern_vectorstore_fragmentation.md](https://github.com/onestardao/WFGY/blob/main/ProblemMap/patterns/pattern_vectorstore_fragmentation.md) · [chunking-checklist.md](https://github.com/onestardao/WFGY/blob/main/ProblemMap/chunking-checklist.md) |
|
||||
| Hybrid worse than single retriever | query parsing split or mis-weighted rerank | [pattern_query_parsing_split.md](https://github.com/onestardao/WFGY/blob/main/ProblemMap/patterns/pattern_query_parsing_split.md) · [rerankers.md](https://github.com/onestardao/WFGY/blob/main/ProblemMap/rerankers.md) |
|
||||
| Citations missing or unstable | schema not enforced | [retrieval-traceability.md](https://github.com/onestardao/WFGY/blob/main/ProblemMap/retrieval-traceability.md) · [data-contracts.md](https://github.com/onestardao/WFGY/blob/main/ProblemMap/data-contracts.md) |
|
||||
| Answers flip between runs | prompt header reordering or λ variance | [context-drift.md](https://github.com/onestardao/WFGY/blob/main/ProblemMap/context-drift.md) · [rerankers.md](https://github.com/onestardao/WFGY/blob/main/ProblemMap/rerankers.md) |
|
||||
|
||||
---
|
||||
|
||||
## 60 second fix checklist
|
||||
|
||||
1) Lock metrics and analyzers
|
||||
Use a single analyzer on write and read. Verify the index metric with a small gold set.
|
||||
|
||||
2) Enforce the snippet contract
|
||||
Required fields: `snippet_id`, `section_id`, `source_url`, `offsets`, `tokens`.
|
||||
Open: [data-contracts.md](https://github.com/onestardao/WFGY/blob/main/ProblemMap/data-contracts.md)
|
||||
|
||||
3) Measure ΔS and λ
|
||||
Log ΔS(question, retrieved). Run three paraphrases and two seeds.
|
||||
Open: [deltaS_probes.md](https://github.com/onestardao/WFGY/blob/main/ProblemMap/GlobalFixMap/Retrieval/deltaS_probes.md)
|
||||
|
||||
4) Sweep k and rerankers
|
||||
k in {5, 10, 20}. Try a deterministic reranker.
|
||||
Open: [hybrid_reranker_recipe.md](https://github.com/onestardao/WFGY/blob/main/ProblemMap/GlobalFixMap/Retrieval/hybrid_reranker_recipe.md)
|
||||
|
||||
5) Rebuild where needed
|
||||
Apply the [retrieval-playbook.md](https://github.com/onestardao/WFGY/blob/main/ProblemMap/retrieval-playbook.md) sequence and re-test coverage.
|
||||
|
||||
---
|
||||
|
||||
## Minimal probe pack you can paste
|
||||
|
||||
```txt
|
||||
Context: I loaded TXT OS and WFGY pages.
|
||||
|
||||
Task:
|
||||
- Given question "Q", log ΔS(Q, retrieved) and λ across 3 paraphrases.
|
||||
- Enforce cite-then-explain with the traceability schema.
|
||||
- If ΔS ≥ 0.60 or λ flips, return the smallest structural change to push ΔS ≤ 0.45 and raise coverage ≥ 0.70.
|
||||
- Use modules BBMC, BBCR, BBPF, BBAM when relevant.
|
||||
|
||||
Return JSON:
|
||||
{ "citations": [...], "ΔS": 0.xx, "λ_state": "<>", "coverage": 0.xx, "next_fix": "..." }
|
||||
````
|
||||
|
||||
---
|
||||
|
||||
## Common gotchas
|
||||
|
||||
* Mixed embedding models across write and read paths.
|
||||
Fix with a single family and explicit normalization.
|
||||
→ [embedding-vs-semantic.md](https://github.com/onestardao/WFGY/blob/main/ProblemMap/embedding-vs-semantic.md)
|
||||
|
||||
* HyDE prompt differs between client and server.
|
||||
Keep tokenization identical or move to reranking.
|
||||
→ [rerankers.md](https://github.com/onestardao/WFGY/blob/main/ProblemMap/rerankers.md)
|
||||
|
||||
* Formatter step renamed fields and broke citations.
|
||||
Add a schema check gate.
|
||||
→ [data-contracts.md](https://github.com/onestardao/WFGY/blob/main/ProblemMap/data-contracts.md)
|
||||
|
||||
---
|
||||
|
||||
## Escalate
|
||||
|
||||
* ΔS remains ≥ 0.60 after chunk and metric fixes
|
||||
Rebuild with the checklist and verify against a small gold set.
|
||||
→ [retrieval-playbook.md](https://github.com/onestardao/WFGY/blob/main/ProblemMap/retrieval-playbook.md)
|
||||
|
||||
* Live instability after deploy
|
||||
Investigate boot order and pre-deploy collapse.
|
||||
→ [bootstrap-ordering.md](https://github.com/onestardao/WFGY/blob/main/ProblemMap/bootstrap-ordering.md) ·
|
||||
[predeploy-collapse.md](https://github.com/onestardao/WFGY/blob/main/ProblemMap/predeploy-collapse.md)
|
||||
|
||||
---
|
||||
|
||||
### 🔗 Quick-Start Downloads (60 sec)
|
||||
|
||||
| Tool | Link | 3-Step Setup |
|
||||
|------|------|--------------|
|
||||
| **WFGY 1.0 PDF** | [Engine Paper](https://github.com/onestardao/WFGY/blob/main/I_am_not_lizardman/WFGY_All_Principles_Return_to_One_v1.0_PSBigBig_Public.pdf) | 1️⃣ Download · 2️⃣ Upload to your LLM · 3️⃣ Ask “Answer using WFGY + \<your question>” |
|
||||
| **TXT OS (plain-text OS)** | [TXTOS.txt](https://github.com/onestardao/WFGY/blob/main/OS/TXTOS.txt) | 1️⃣ Download · 2️⃣ Paste into any LLM chat · 3️⃣ Type “hello world” — OS boots instantly |
|
||||
| Tool | Link | 3-Step Setup |
|
||||
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
|
||||
| **WFGY 1.0 PDF** | [Engine Paper](https://github.com/onestardao/WFGY/blob/main/I_am_not_lizardman/WFGY_All_Principles_Return_to_One_v1.0_PSBigBig_Public.pdf) | 1️⃣ Download · 2️⃣ Upload to your LLM · 3️⃣ Ask “Answer using WFGY + \<your question>” |
|
||||
| **TXT OS (plain-text OS)** | [TXTOS.txt](https://github.com/onestardao/WFGY/blob/main/OS/TXTOS.txt) | 1️⃣ Download · 2️⃣ Paste into any LLM chat · 3️⃣ Type “hello world” — OS boots instantly |
|
||||
|
||||
---
|
||||
|
||||
### 🧭 Explore More
|
||||
|
||||
| Module | Description | Link |
|
||||
|-----------------------|----------------------------------------------------------|----------|
|
||||
| WFGY Core | WFGY 2.0 engine is live: full symbolic reasoning architecture and math stack | [View →](https://github.com/onestardao/WFGY/tree/main/core/README.md) |
|
||||
| Problem Map 1.0 | Initial 16-mode diagnostic and symbolic fix framework | [View →](https://github.com/onestardao/WFGY/tree/main/ProblemMap/README.md) |
|
||||
| Problem Map 2.0 | RAG-focused failure tree, modular fixes, and pipelines | [View →](https://github.com/onestardao/WFGY/blob/main/ProblemMap/rag-architecture-and-recovery.md) |
|
||||
| Semantic Clinic Index | Expanded failure catalog: prompt injection, memory bugs, logic drift | [View →](https://github.com/onestardao/WFGY/blob/main/ProblemMap/SemanticClinicIndex.md) |
|
||||
| Semantic Blueprint | Layer-based symbolic reasoning & semantic modulations | [View →](https://github.com/onestardao/WFGY/tree/main/SemanticBlueprint/README.md) |
|
||||
| Benchmark vs GPT-5 | Stress test GPT-5 with full WFGY reasoning suite | [View →](https://github.com/onestardao/WFGY/tree/main/benchmarks/benchmark-vs-gpt5/README.md) |
|
||||
| 🧙♂️ Starter Village 🏡 | New here? Lost in symbols? Click here and let the wizard guide you through | [Start →](https://github.com/onestardao/WFGY/blob/main/StarterVillage/README.md) |
|
||||
| Module | Description | Link |
|
||||
| ------------------------ | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
|
||||
| WFGY Core | WFGY 2.0 engine is live: full symbolic reasoning architecture and math stack | [View →](https://github.com/onestardao/WFGY/tree/main/core/README.md) |
|
||||
| Problem Map 1.0 | Initial 16-mode diagnostic and symbolic fix framework | [View →](https://github.com/onestardao/WFGY/tree/main/ProblemMap/README.md) |
|
||||
| Problem Map 2.0 | RAG-focused failure tree, modular fixes, and pipelines | [View →](https://github.com/onestardao/WFGY/blob/main/ProblemMap/rag-architecture-and-recovery.md) |
|
||||
| Semantic Clinic Index | Expanded failure catalog: prompt injection, memory bugs, logic drift | [View →](https://github.com/onestardao/WFGY/blob/main/ProblemMap/SemanticClinicIndex.md) |
|
||||
| Semantic Blueprint | Layer-based symbolic reasoning & semantic modulations | [View →](https://github.com/onestardao/WFGY/tree/main/SemanticBlueprint/README.md) |
|
||||
| Benchmark vs GPT-5 | Stress test GPT-5 with full WFGY reasoning suite | [View →](https://github.com/onestardao/WFGY/tree/main/benchmarks/benchmark-vs-gpt5/README.md) |
|
||||
| 🧙♂️ Starter Village 🏡 | New here? Lost in symbols? Click here and let the wizard guide you through | [Start →](https://github.com/onestardao/WFGY/blob/main/StarterVillage/README.md) |
|
||||
|
||||
---
|
||||
|
||||
> 👑 **Early Stargazers: [See the Hall of Fame](https://github.com/onestardao/WFGY/tree/main/stargazers)** —
|
||||
> 👑 **Early Stargazers: [See the Hall of Fame](https://github.com/onestardao/WFGY/tree/main/stargazers)** —
|
||||
> Engineers, hackers, and open source builders who supported WFGY from day one.
|
||||
|
||||
> <img src="https://img.shields.io/github/stars/onestardao/WFGY?style=social" alt="GitHub stars"> ⭐ [WFGY Engine 2.0](https://github.com/onestardao/WFGY/blob/main/core/README.md) is already unlocked. ⭐ Star the repo to help others discover it and unlock more on the [Unlock Board](https://github.com/onestardao/WFGY/blob/main/STAR_UNLOCKS.md).
|
||||
|
|
@ -132,17 +198,18 @@ Tell me:
|
|||
<div align="center">
|
||||
|
||||
[](https://github.com/onestardao/WFGY)
|
||||
|
||||
|
||||
[](https://github.com/onestardao/WFGY/tree/main/OS)
|
||||
|
||||
|
||||
[](https://github.com/onestardao/WFGY/tree/main/OS/BlahBlahBlah)
|
||||
|
||||
|
||||
[](https://github.com/onestardao/WFGY/tree/main/OS/BlotBlotBlot)
|
||||
|
||||
|
||||
[](https://github.com/onestardao/WFGY/tree/main/OS/BlocBlocBloc)
|
||||
|
||||
|
||||
[](https://github.com/onestardao/WFGY/tree/main/OS/BlurBlurBlur)
|
||||
|
||||
|
||||
[](https://github.com/onestardao/WFGY/tree/main/OS/BlowBlowBlow)
|
||||
|
||||
|
||||
|
||||
</div>
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue