rag-architect
Architect-level retrieval-augmented generation design — chunking and parsing strategy, embedding and index choice, hybrid search and reranking, citation and grounding contracts, freshness and re-indexing, and the retrieval evals that separate real grounding from plausible text. Use when answers must come from a private corpus.
- License 许可
- MIT
- 最近更新
- 2026-11-13
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- rag-architect
- license
- MIT
- metadata
- { "crusor-path": "ai-ml-architect/retrieval-architect/rag-architect", "crusor-domain": "ai-ml-architect", "crusor-origin": "original", "crusor-sources": "arxiv.org/abs/2005.11401; github.com/pgvector/pgvector; docs.llamaindex.ai", "crusor-triggers": "rag, retrieval, vector database, embedding, chunking, semantic search, reranking, hybrid search, knowledge base, citations, pgvector, hallucination, hallucinating, grounding, make things up, makes things up", "crusor-verified-on": "2026-10-30" }
- description
- Architect-level retrieval-augmented generation design — chunking and parsing strategy, embedding and index choice, hybrid search and reranking, citation and grounding contracts, freshness and re-indexing, and the retrieval evals that separate real grounding from plausible text. Use when answers must come from a private corpus.
- compatibility
- pgvector, Qdrant, Weaviate, OpenSearch, Pinecone
03 SKILL.md 正文
RAG Architect
Retrieval quality is the ceiling on answer quality. A perfect model over bad chunks produces confident nonsense.
When to use
- Answers must be grounded in a defined corpus (docs, tickets, contracts, code).
- The knowledge changes and cannot live in weights.
- Answers must cite sources for trust or audit.
When NOT to use
- The corpus fits comfortably in a cached context window and changes rarely — paste it and skip the retrieval system.
- The question requires reasoning over the whole corpus at once (aggregation) — that is a query engine problem, not a similarity problem.
Decision 1 — Pipeline stages, each measurable
ingest → parse → chunk → embed → index → retrieve → rerank → assemble → generate
↑ ↑
retrieval evals answer evals
Every stage has an owner and a metric. Most RAG failures are parse and chunk failures wearing a model costume.
Decision 2 — Parsing and chunking
| Corpus | Approach |
|---|---|
| PDFs | layout-aware parser, keep tables as tables |
| HTML docs | strip nav, keep heading hierarchy |
| code | function/class boundaries, keep signatures |
| tickets/chat | one thread, resolved state first |
| spreadsheets | row-group chunks with headers attached |
- Chunk by semantic boundary, 300–800 tokens, with 10–20% overlap.
- Carry metadata on every chunk: source, section, timestamp, tenant, permissions.
- Never embed a chunk you cannot cite back to an exact location.
Decision 3 — Embedding and index
- One embedding model per index; changing it means a full re-index — plan the migration before you need it.
- Dimension and distance metric are architectural constants; document them.
- Vector store choice by operational fit: pgvector if you already run Postgres and the corpus is modest; a dedicated store when scale, filtering, or hybrid search demand it.
- Metadata filters are part of the query contract: tenant, permission, freshness, document type.
Decision 4 — Retrieve well
- Hybrid: BM25/keyword + dense vectors, fused (RRF). Exact terms, IDs and names fail pure-vector search.
- Retrieve 20–50 candidates, rerank with a cross-encoder to the top 5–8.
- Query rewriting for conversational input; decompose multi-part questions.
- No results is a valid outcome: answer "I don't know" rather than filling the gap.
Decision 5 — Grounding contract
- Every claim maps to a chunk id; render citations with source and location.
- Assembly: put the strongest chunks first, delimit them as data, and instruct the model to refuse when the context does not contain the answer.
- Permission filtering happens before retrieval results enter the prompt — never rely on the model to redact.
Decision 6 — Freshness and re-indexing
- Ingestion is a pipeline with idempotent upserts keyed by content hash.
- Deletes propagate: a removed document must disappear from the index, or it will be cited forever.
- Re-embedding runs as a background migration into a new collection, then a swap.
- Track index lag; a stale index is a correctness bug with a delay.
Failure modes at scale
- Chunks split mid-table; the model reads half a price list.
- Pure vector search missing an exact error code the user pasted.
- Citations generated from memory of the prompt rather than returned metadata.
- Tenant leakage through a missing metadata filter.
- Deleting a source document that keeps appearing in answers.
Verification receipts
- Retrieval eval: recall@k and MRR on a labelled question set.
- Answer eval: groundedness and citation accuracy, judged against the corpus.
- Chunk inspector screenshot for one hard document (tables, headings intact).
- Permission test: a query from tenant B never returns tenant A chunks.
- Delete test: removed document no longer retrievable, verified by query.
04 同仓库更多 Skills
interaction-patterns-architect
Architect-level interaction design in code — choosing established patterns over invented ones, feedback and latency behaviour, destructive-action safeguards, navigation and overlay conventions, and the state model behind every interactive surface. Use when a screen has to behave, not just look.
design-system-ops-architect
Architect-level operation of a design system in code — token pipelines and versioning, component API and variant policy, the catalogue as the contract, adoption metrics, and the governance that stops a system from forking into three. Use when a component library must survive several teams.
design-handoff-architect
Architect-level design handoff — what must be specified before implementation starts, tokens over raw values, responsive and content-limit contracts, state matrices, and the review loop that catches drift between design and code. Use when a design is about to become code.
content-microcopy-architect
Architect-level UI content — where strings live, voice and terminology consistency, error and empty-state copy as part of the interface, translation-ready authoring, and the content model a product needs before it multiplies screens. Use when the words in the interface matter as much as the pixels.
ui-ux-implementation-architect
Architect-level direction for turning a design into working UI — the handoff contract, component ownership versus screen-level layout, interaction and state conventions, design QA gates, and the review habits that keep an implementation faithful without frozen pixels. Use before any specific UI implementation skill.
test-strategy-architect
Architect-level test strategy — allocating assertions across unit, integration, contract and end-to-end layers, designing for testability through dependency boundaries, fixture and data strategy, and the flake and coverage policies that keep a suite trustworthy. Use when defining how a codebase is tested.