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:
PSBigBig
GitHub
parent
50e11389e3
commit
86558444b5
1 changed files with 70 additions and 125 deletions
|
|
@ -1,136 +1,110 @@
|
|||
# Retrieval — Global Fix Map
|
||||
|
||||
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.
|
||||
A compact hub to stabilize retrieval quality across stacks, models, and stores.
|
||||
Use this page to route symptoms to the exact structural fix and verify with measurable targets. No infra change required.
|
||||
|
||||
---
|
||||
|
||||
## Orientation: what each page does
|
||||
|
||||
| Page | What it solves | Typical symptom |
|
||||
|---|---|---|
|
||||
| [Retrieval Playbook](https://github.com/onestardao/WFGY/blob/main/ProblemMap/retrieval-playbook.md) | End to end rebuild order and knobs | You fixed one thing and another breaks |
|
||||
| [Retrieval Traceability](https://github.com/onestardao/WFGY/blob/main/ProblemMap/retrieval-traceability.md) | Cite-then-explain schema with required fields | Citations miss the exact section or cannot be verified |
|
||||
| [Rerankers](https://github.com/onestardao/WFGY/blob/main/ProblemMap/rerankers.md) | Deterministic reranking across BM25 + ANN | Hybrid worse than single retriever |
|
||||
| [Query Parsing Split](https://github.com/onestardao/WFGY/blob/main/ProblemMap/patterns/pattern_query_parsing_split.md) | One query, two meanings; detect and route | Answers jump between two unrelated sections |
|
||||
| [Chunk Alignment](https://github.com/onestardao/WFGY/blob/main/ProblemMap/GlobalFixMap/Retrieval/chunk_alignment.md) | Chunking aligned with the model’s semantic window | Snippets cut mid-thought; anchors missing |
|
||||
| [ΔS Probes](https://github.com/onestardao/WFGY/blob/main/ProblemMap/GlobalFixMap/Retrieval/deltaS_probes.md) | Quick health check using ΔS and λ_observe | Looks fine by eye but flips across runs |
|
||||
| [Retrieval Eval Recipes](https://github.com/onestardao/WFGY/blob/main/ProblemMap/GlobalFixMap/Retrieval/retrieval_eval_recipes.md) | Deterministic, SDK-free evaluation | No stable way to tell if “better” shipped |
|
||||
| [Store-Agnostic Guardrails](https://github.com/onestardao/WFGY/blob/main/ProblemMap/GlobalFixMap/Retrieval/store_agnostic_guardrails.md) | Locks for metrics, analyzers, versions | Index “healthy” but recall still low |
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
|
||||
- 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
|
||||
- Coverage of target section ≥ 0.70
|
||||
- λ remains convergent across 3 paraphrases and 2 seeds
|
||||
- E_resonance stays flat on long windows
|
||||
- λ_observe convergent across 3 paraphrases and 2 seeds
|
||||
- E_resonance flat on long windows
|
||||
|
||||
---
|
||||
|
||||
## Quick routes — core fixes
|
||||
## Symptoms → exact 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)
|
||||
| Symptom | Likely cause | Open this |
|
||||
|---|---|---|
|
||||
| High similarity yet wrong answer | Metric or analyzer mismatch | [Embedding ≠ Semantic](https://github.com/onestardao/WFGY/blob/main/ProblemMap/embedding-vs-semantic.md) |
|
||||
| Correct fact never retrieved | Fragmentation or missing anchors | [Vectorstore Fragmentation](https://github.com/onestardao/WFGY/blob/main/ProblemMap/patterns/pattern_vectorstore_fragmentation.md) · [Chunking Checklist](https://github.com/onestardao/WFGY/blob/main/ProblemMap/chunking-checklist.md) |
|
||||
| Hybrid worse than single | Query parsing split or mis-weighted rerank | [Query Parsing Split](https://github.com/onestardao/WFGY/blob/main/ProblemMap/patterns/pattern_query_parsing_split.md) · [Rerankers](https://github.com/onestardao/WFGY/blob/main/ProblemMap/rerankers.md) |
|
||||
| Citations missing or unstable | Schema not enforced | [Retrieval Traceability](https://github.com/onestardao/WFGY/blob/main/ProblemMap/retrieval-traceability.md) · [Data Contracts](https://github.com/onestardao/WFGY/blob/main/ProblemMap/data-contracts.md) |
|
||||
| Answers flip between runs | Prompt header reordering or λ variance | [Context Drift](https://github.com/onestardao/WFGY/blob/main/ProblemMap/context-drift.md) · [Rerankers](https://github.com/onestardao/WFGY/blob/main/ProblemMap/rerankers.md) |
|
||||
|
||||
---
|
||||
|
||||
## Store agnostic routes in this folder
|
||||
## 60-second fix checklist
|
||||
|
||||
- Guardrails and probes
|
||||
→ [store_agnostic_guardrails.md](https://github.com/onestardao/WFGY/blob/main/ProblemMap/GlobalFixMap/Retrieval/store_agnostic_guardrails.md)
|
||||
1) **Lock metrics and analyzers**
|
||||
One embedding model per field. One distance metric. Same analyzer for write and read.
|
||||
Guide: [Store-Agnostic Guardrails](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)
|
||||
2) **Enforce the snippet contract**
|
||||
Require `snippet_id`, `section_id`, `source_url`, `offsets`, `tokens`.
|
||||
Guide: [Data Contracts](https://github.com/onestardao/WFGY/blob/main/ProblemMap/data-contracts.md)
|
||||
|
||||
- ΔS and λ probe pack
|
||||
→ [deltaS_probes.md](https://github.com/onestardao/WFGY/blob/main/ProblemMap/GlobalFixMap/Retrieval/deltaS_probes.md)
|
||||
3) **Measure ΔS and λ**
|
||||
Run three paraphrases and two seeds.
|
||||
Guide: [ΔS Probes](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)
|
||||
4) **Sweep k and rerankers**
|
||||
Try k in {5, 10, 20}. Keep BM25 and ANN candidate lists.
|
||||
Guide: [Rerankers](https://github.com/onestardao/WFGY/blob/main/ProblemMap/rerankers.md)
|
||||
|
||||
- Retrieval eval recipes
|
||||
→ [retrieval_eval_recipes.md](https://github.com/onestardao/WFGY/blob/main/ProblemMap/GlobalFixMap/Retrieval/retrieval_eval_recipes.md)
|
||||
5) **Rebuild where needed**
|
||||
Follow the sequence in the playbook and re-test coverage.
|
||||
Guide: [Retrieval Playbook](https://github.com/onestardao/WFGY/blob/main/ProblemMap/retrieval-playbook.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)
|
||||
- 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.
|
||||
- Direct store guides:
|
||||
[FAISS](https://github.com/onestardao/WFGY/blob/main/ProblemMap/GlobalFixMap/VectorDBs_and_Stores/faiss.md) ·
|
||||
[Chroma](https://github.com/onestardao/WFGY/blob/main/ProblemMap/GlobalFixMap/VectorDBs_and_Stores/chroma.md) ·
|
||||
[Qdrant](https://github.com/onestardao/WFGY/blob/main/ProblemMap/GlobalFixMap/VectorDBs_and_Stores/qdrant.md) ·
|
||||
[Weaviate](https://github.com/onestardao/WFGY/blob/main/ProblemMap/GlobalFixMap/VectorDBs_and_Stores/weaviate.md) ·
|
||||
[Milvus](https://github.com/onestardao/WFGY/blob/main/ProblemMap/GlobalFixMap/VectorDBs_and_Stores/milvus.md) ·
|
||||
[pgvector](https://github.com/onestardao/WFGY/blob/main/ProblemMap/GlobalFixMap/VectorDBs_and_Stores/pgvector.md) ·
|
||||
[Redis](https://github.com/onestardao/WFGY/blob/main/ProblemMap/GlobalFixMap/VectorDBs_and_Stores/redis.md) ·
|
||||
[Elasticsearch](https://github.com/onestardao/WFGY/blob/main/ProblemMap/GlobalFixMap/VectorDBs_and_Stores/elasticsearch.md) ·
|
||||
[Pinecone](https://github.com/onestardao/WFGY/blob/main/ProblemMap/GlobalFixMap/VectorDBs_and_Stores/pinecone.md) ·
|
||||
[Typesense](https://github.com/onestardao/WFGY/blob/main/ProblemMap/GlobalFixMap/VectorDBs_and_Stores/typesense.md) ·
|
||||
[Vespa](https://github.com/onestardao/WFGY/blob/main/ProblemMap/GlobalFixMap/VectorDBs_and_Stores/vespa.md)
|
||||
|
||||
---
|
||||
|
||||
## Minimal probe pack you can paste
|
||||
|
||||
```txt
|
||||
Context: I loaded TXT OS and WFGY pages.
|
||||
Context: I loaded TXT OS and the 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.
|
||||
- If ΔS ≥ 0.60 or λ flips, return the smallest structural change to push ΔS ≤ 0.45 and coverage ≥ 0.70.
|
||||
- Use BBMC, BBCR, BBPF, BBAM when relevant.
|
||||
|
||||
Return JSON:
|
||||
{ "citations": [...], "ΔS": 0.xx, "λ_state": "<>", "coverage": 0.xx, "next_fix": "..." }
|
||||
|
|
@ -138,35 +112,6 @@ Return JSON:
|
|||
|
||||
---
|
||||
|
||||
## 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 |
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue