# Mapa Wiedzy i kontrola w RAG: jak wdrożyć „nowe podejście” w sposób inżynieryjny

## Executive summary

Autor posta (entity["people","Vladimir Alekseichenko","dataworkshop ceo"], entity["organization","DataWorkshop","ml/ai training poland"]) kontrastuje „klasyczny” RAG oparty o mechaniczne chunkowanie i wektoryzację z podejściem, w którym buduje się **Mapę Wiedzy**: „graf z metadanymi, powiązaniami i odniesieniami do źródeł” (w kontekście praktyki na danych z entity["organization","Giełda Papierów Wartościowych w Warszawie","warsaw stock exchange"]). citeturn2view0turn2view1

W tym raporcie formalizuję tę ideę jako **Knowledge‑Map RAG (KM‑RAG)**: RAG, w którym warstwa „R” nie jest tylko wyszukiwaniem semantycznym po losowych fragmentach, ale **kontrolowanym wyborem jednostek wiedzy** (sekcja, tabela, rekord, definicja, reguła) powiązanych grafowo, z pełną **proweniencją (skąd to jest), politykami dostępu, wersjonowaniem i testowalnością**. To jest spójne z tezą autora, że „R w RAG” to przede wszystkim **ryzyko**: jeśli retrieval jest błędny, model będzie „pewnie” odpowiadał na podstawie złego kontekstu. citeturn2view0turn6view0

Ponieważ nie podałeś ograniczeń (skala, budżet, SLA/latencja), przyjmuję **brak specyficznych constraintów** i podaję warianty: od małych wdrożeń (Postgres/pgvector) po architektury wielotenancy (Qdrant/Pinecone/Weaviate) oraz hybrydy graf + wektory. citeturn12search2turn14search1turn14search16turn14search0turn14search2

Najważniejsze rekomendacje wdrożeniowe:

Po pierwsze, zastąp „losowe chunki” **jednostkami sensu**: segmentacją strukturalną (nagłówki/sekcje/tabele) i/lub semantyczną, z metadanymi i relacjami (poprzedni/następny, należy do sekcji, cytuje, definiuje). citeturn6view0turn11search1turn11search29

Po drugie, zbuduj **Mapę Wiedzy jako graf** (property graph) + indeksy (wektorowy i leksykalny/hybrydowy). Praktycznie: graf przechowuje relacje i proweniencję, a wektory dają tani „candidate generation”; dopiero potem używasz grafu do „dociągnięcia” brakujących kontekstów i do audytu. To jest zgodne z rodziną podejść GraphRAG (np. publikacja entity["company","Microsoft","tech company"] o GraphRAG: graf encji + „community summaries” dla lepszych odpowiedzi na pytania globalne). citeturn0search1turn3search4turn3search20

Po trzecie, „kontrola zamiast nadziei” oznacza: (a) **mierniki retrieval i generation**, (b) automatyczne testy regresji i audyt ścieżki źródeł, (c) monitoring i alerty driftu oraz incydentów bezpieczeństwa (prompt injection, data leakage). W praktyce: RAGAS/TruLens + OWASP LLM Top 10 jako checklisty, plus logowanie „trace” (kontekst → odpowiedź → cytowania). citeturn4search1turn4search2turn4search6turn4search13turn4search7

## Definicja podejścia „Mapa Wiedzy zamiast losowych chunków”

W poście autor opisuje Mapę Wiedzy jako artefakt, który budujesz **w 3 dni**: „graf z metadanymi, powiązaniami i odniesieniami do źródeł” (wspomina też kontekst narzędziowy: repozytorium na entity["company","GitHub","code hosting platform"] i notatki w entity["company","Obsidian","note-taking app company"]). citeturn2view1

Jednocześnie w dłuższym materiale autor rozwija intuicję, dlaczego „chunking + vector DB” bywa drogą donikąd: mechaniczne cięcie rozrywa jednostki sensu (akapit, tabela), a model językowy zwykle **nie weryfikuje kontekstu** – odpowiada w oparciu o to, co mu dostarczysz, nawet jeśli kontekst jest sprzeczny (stąd losowość i halucynacje). citeturn6view0turn7view1

### Precyzyjna definicja operacyjna (KM‑RAG)

**Knowledge‑Map RAG (KM‑RAG)** to architektura RAG, w której warstwa „R” jest realizowana przez:

**Reprezentację wiedzy**: dokumenty są przekształcane do zbioru **jednostek wiedzy** (Knowledge Units) o stabilnej proweniencji (ID, wersja, lokalizacja w źródle) i spójnej semantyce (sekcja definicji, tabela, rozdział, procedura), a nie losowych wycinków znaków. citeturn6view0turn11search9turn16search0

**Mapę (graf) zależności**: jednostki są węzłami grafu (np. DOCUMENT → SECTION → UNIT; ENTITY ↔ UNIT; UNIT ↔ UNIT przez „refers_to/next/derives_from”), a krawędzie niosą informację ułatwiającą retrieval i audyt (np. „to jest definicja terminu X”, „to jest wyjątek od reguły”). citeturn2view1turn10search3turn3search4

**Polityki retrieval**: zapytanie jest mapowane na intencję i encje, a retrieval wykonuje plan: generuje kandydatów (wektory/keyword/hybrid), następnie rozszerza kontekst grafowo (np. sekcja nadrzędna, definicje encji, powiązane tabele), na końcu dokonuje selekcji (rerank/pruning) i buduje kontekst z cytowaniami. citeturn12search3turn12search11turn10search6turn10search31

**Kontrolę i audytowalność**: system jest projektowany tak, aby można było odpowiedzieć na pytania: „Dlaczego ten fragment?”, „Czy użytkownik miał uprawnienia?”, „Jaka wersja źródła?”, „Czy odpowiedź jest ugruntowana (grounded) w kontekście?”. Autor wprost wiąże „mapę wiedzy” z uszczelnianiem rozwiązań, wymaganiami prawnymi/bezpieczeństwa oraz audytowalnością. citeturn7view1turn14search2

### Dlaczego „losowe chunki” są słabą abstrakcją inżynieryjną

Mechaniczne chunkowanie jest często liczone w znakach/tokenach; nawet z overlapem rozrywa strukturę i wymusza „magiczne” heurystyki (większy chunk_size, więcej chunków w kontekście), które łatwo psują wcześniej działające przypadki i utrudniają stabilną ewaluację. citeturn6view0

Z perspektywy governance kluczowy problem jest też bezpieczeństwo: w jednym dokumencie mogą być fragmenty o różnych poziomach dostępu, więc „wrzucanie wszystkiego do jednego kontekstu” łamie zasady separacji i komplikuje zgodność (ten motyw pojawia się u autora wprost). citeturn7view1turn14search2

## Architektura referencyjna i komponenty

Poniżej przedstawiam architekturę komponentową KM‑RAG, obejmującą: ingestion, mapę wiedzy, strategie segmentacji, embeddingi i wektory, retrievery i rerankery, prompt engineering i grounding, oraz kontrolę halucynacji i ewaluację.

### Diagram architektury

```mermaid
flowchart LR
  subgraph Ingestion
    A[Źródła: PDF/HTML/DOCX/DB] --> B[Parsing + normalizacja]
    B --> C[Jednostki wiedzy: sekcje, tabele, rekordy]
    C --> D[Metadane: źródło, wersja, ACL, lokalizacja]
    C --> E[Ekstrakcja encji/relacji]
    E --> G[(Graf / Mapa Wiedzy)]
    C --> F[Embedding + indeks]
    F --> V[(Vector DB)]
  end

  subgraph QueryTime
    Q[Zapytanie użytkownika] --> R[Routing/intencja/encje]
    R --> V1[Candidate gen: vector/keyword/hybrid]
    V1 --> V
    V --> K[Top-K kandydatów]
    K --> G1[Graph expansion\n(definicje, zależności, sekcje)]
    G1 --> G
    G --> S[Context assembly + dedup + cytowania]
    S --> L[LLM generacja\n(z zasadą "answer from sources")]
    L --> O[Odpowiedź + cytowania + confidence]
  end

  subgraph Control
    O --> M[Logi/trace]
    M --> EV[Ewaluacja offline/online]
    M --> MON[Monitoring KPI + alerty]
  end
```

Model ten jest kompatybilny zarówno z „klasycznym RAG” w sensie pracy na wektorach (RAG w ujęciu Lewis et al. zakłada połączenie pamięci parametrycznej i nieparametrycznej poprzez retrieval z indeksu wektorowego), jak i z odmianami grafowymi (GraphRAG: budowa grafu encji i „community summaries” jako warstwa indeksu). citeturn0search2turn0search5turn0search1turn3search4

image_group{"layout":"carousel","aspect_ratio":"16:9","query":["GraphRAG architecture diagram","knowledge graph retrieval augmented generation diagram","vector database similarity search diagram","Neo4j graph visualization example"],"num_per_query":1}

### Ingestion: parsowanie, normalizacja i jednostki wiedzy

W KM‑RAG ingestion nie kończy się na „wyciągnij tekst z PDF”. Kluczowe jest zachowanie/rekonstrukcja struktury: tytuły, listy, tabele, numer stron, sekcje. Biblioteka entity["company","Unstructured","document processing company"] wprost opisuje „partitioning” jako ekstrakcję ustrukturyzowanych elementów (Title/NarrativeText/ListItem itd.), aby móc decydować, co zachować. citeturn16search0turn16search8turn16search4

Jeśli pracujesz na bardzo różnych formatach lub potrzebujesz także metadanych i obsługi np. zaszyfrowanych PDF, narzędzia z ekosystemu entity["organization","Apache Software Foundation","open source foundation"] (Apache Tika) podkreślają możliwość parsowania PDF, w tym obsługi dokumentów szyfrowanych przy podaniu hasła. citeturn16search1turn16search30

Wniosek projektowy: „Jednostka wiedzy” w KM‑RAG to obiekt typu np.:

- `unit_type`: `section`, `definition`, `table`, `row`, `procedure_step`, `policy_rule`
- `canonical_text` (tekst do embeddingu i rerankingu)
- `rendered_context` (tekst/fragment do wklejenia do prompta)
- `provenance`: `source_id`, `page`, `section_path`, `span_offsets`
- `governance`: `acl_tags`, `pii_class`, `retention_class`
- `links`: `prev/next`, `references`, `same_topic`

Taki model danych bezpośrednio adresuje problem autora: model nie „weźmie odpowiedzialności” za konfliktujący kontekst, więc to system ma pilnować jakości kontekstu i jego zaufania. citeturn6view0turn7view1

### Strategie segmentacji: od „chunków” do „węzłów” (Nodes)

Jeżeli musisz działać na tekście, i tak będziesz coś „dzielił” – różnica polega na tym, czy są to losowe fragmenty znaków, czy **węzły semantyczne**.

- W ekosystemie entity["company","LangChain","llm app framework company"] często proponuje się `RecursiveCharacterTextSplitter` jako „solidny default” dla wielu przypadków, ale to nadal jest heurystyka bazująca na znakach i separatorach. citeturn11search8turn11search0  
- entity["company","LlamaIndex","llm data framework company"] oferuje semantyczne parsowanie węzłów: `SemanticSplitterNodeParser` dzieli tekst na grupy zdań powiązane semantycznie (z użyciem embeddingów), a dokumentacja podkreśla, że to alternatywa dla stałego rozmiaru chunków. citeturn11search1turn11search9turn11search29

KM‑RAG traktuje segmentację jako element modelowania danych: węzły mają typ, hierarchię i relacje.

### Embeddingi i Vector DB: candidate generation + filtrowanie po metadanych

Embeddingi są nadal bardzo użyteczne, ale w KM‑RAG pełnią rolę „szybkiego generatora kandydatów”, a nie „wyroczni”.

Otwartoźródłowo, entity["company","Hugging Face","ml model hub company"] utrzymuje Sentence Transformers, które dostarcza zarówno modele embeddingowe (bi-encoders), jak i rerankery (cross-encoders). citeturn12search38turn12search3

Warstwa metadanych jest w KM‑RAG krytyczna: np. do ograniczania domeny, wersji dokumentu, języka, daty wejścia w życie, uprawnień.

- entity["company","Qdrant","vector database company"] opisuje payload/metadata i filtrowanie oraz zaleca indeksowanie pól payload dla efektywności filtrowania. citeturn11search2turn11search6turn11search37  
- entity["company","Pinecone","vector database company"] opisuje filtrowanie po metadanych oraz pokazuje wzorzec multitenancy przez namespaces. citeturn11search7turn14search16turn14search12  
- entity["company","Weaviate","vector database company"] opisuje hybrydę BM25F + wektory (fuzja wyników i wagi są konfigurowalne) oraz posiada natywną wielodzierżawność (tenant per request). citeturn12search0turn14search0  
- entity["company","Milvus","vector database project"] dokumentuje hybrydę sparse+dense i wskazuje scenariusze, w których połączenie poprawia wyniki (semantyka + dopasowanie słów kluczowych). citeturn12search1turn12search5

W KM‑RAG niemal zawsze warto rozważyć hybrid retrieval (dense + sparse), bo ogranicza „semantic drift” i poprawia precyzję przy terminach domenowych (np. numery, nazwy własne). Jest to wspólny wątek w dokumentacji Weaviate i Pinecone, opisującej fuzję wyników i podejścia do hybrydy. citeturn12search0turn11search3turn11search19

### Retrievery, rerankery i kontrola halucynacji

KM‑RAG rozdziela retrieval na etapy:

**Candidate generation (tani):** dense retriever (np. dual-encoder) i/lub sparse (BM25). Klasyczna praca o dense retrieval (DPR) pokazuje dual-encoder jako praktyczny mechanizm retrieval i porównuje go do BM25 w QA. citeturn8search0turn8search4

**Reranking (droższy):** cross-encoder reranker znacząco poprawia ranking, ale jest kosztowny, bo ocenia pary (query, doc) wspólnie w modelu. Sentence Transformers opisuje retrieve‑&‑rerank pipeline oraz rolę CrossEncodera. citeturn12search11turn12search19

**Graph expansion (precyzja i kompletność):** graf dostarcza „brakujących mostów” (definicje, zależności, wyjątki, kontekst sekcji) oraz daje audyt – to jest sedno „Mapy Wiedzy”. W wariantach GraphRAG (Microsoft) graf jest budowany z encji i relacji, a następnie grupowany w społeczności i streszczany, co poprawia odpowiedzi na pytania „globalne” (np. „jakie są główne tematy w korpusie?”), gdzie naiwny RAG zawodzi. citeturn0search1turn0search13turn3search4turn3search20

**Halucynacje i „kontrola”:** literatura proponuje pętle weryfikacji (np. Chain‑of‑Verification: draft → pytania weryfikacyjne → niezależne odpowiedzi → final) i mechanizmy samorefleksji (Self‑RAG) oraz korekty retrieval (CRAG). Są to techniki „kontroli” na poziomie architektury, a nie tylko promptu. citeturn8search3turn9search1turn9search2

## Opcje projektowe i trade‑offy

### Porównanie: klasyczny RAG vs KM‑RAG

| Wymiar | Klasyczny „chunk + vector DB” | KM‑RAG (Mapa Wiedzy) | Konsekwencja praktyczna |
|---|---|---|---|
| Jednostka indeksowania | fragment znaków/tokenów | jednostka sensu: sekcja/tabela/rekord + typ | mniej „urwanych” kontekstów, mniej przypadkowości |
| Reprezentacja | embedding + (czasem) metadata | embedding + metadata + graf relacji + proweniencja | lepsza ścieżka audytu i „dlaczego to” |
| Retrieval | top‑k similarity | plan retrieval: hybrid + graf expansion + rerank | wyższa precyzja i odporność na trudne pytania |
| Zmiany w danych | częsty re‑index, ryzyko regresji | wersjonowanie, testy regresji per typ jednostki | stabilniejsze wdrożenia i migracje |
| Bezpieczeństwo/ACL | łatwo mieszać fragmenty o różnych uprawnieniach | ACL na poziomie jednostki i ścieżki grafu | mniejsze ryzyko wycieku kontekstu |
| Debuggowanie | „dlaczego takie chunki?” | „jaki węzeł, z jakiego źródła, jaka relacja?” | szybsze RCA i audyt |

Uzasadnienie co do problemów chunkingu i „model ufa kontekstowi” pochodzi z materiału autora; definicja Mapy Wiedzy jako grafu z metadanymi i odniesieniami jest wprost w poście. citeturn6view0turn2view1turn7view1

### Wybory technologiczne: wektory, graf, hybryda

Poniżej pokazuję typowe opcje i kompromisy (bez narzuconych constraintów – dobór zależy od QPS, wolumenu i wymagań bezpieczeństwa).

**Vector store**

- Qdrant: mocne filtrowanie payload + mechanizmy multitenancy (w tym „tiered multitenancy”). citeturn11search6turn14search1turn14search18  
- Pinecone: proste multitenancy przez namespaces; dobrze opisane podejścia do hybrid search (single hybrid index vs osobne indeksy, z plusami i minusami). citeturn14search16turn11search3  
- Weaviate: wbudowany hybrid BM25F + wektor, oraz multi‑tenancy z tenantem w operacjach. citeturn12search0turn14search0  
- Milvus: rozbudowane podejścia do sparse+dense i multi‑vector, z dokumentacją dla hybrydy. citeturn12search1turn12search5turn12search33  
- pgvector: dobre, gdy chcesz „mniej systemów” i akceptujesz kompromisy wydajności; repo dokumentuje różnice IVFFlat vs HNSW (build time/memory vs speed‑recall). citeturn12search2turn12search14  
- Elasticsearch: istotny, gdy potrzebujesz „enterprise security” (RBAC, field/document‑level security) i hybrydowego wyszukiwania w jednej platformie. citeturn14search2turn14search15

**Graph / Knowledge Map store**

- Neo4j: bogate wzorce GraphRAG (graph traversal, full‑text, vector, text2cypher). Neo4j publikuje GraphRAG field guide i pakiet GraphRAG dla Pythona. citeturn10search18turn10search14turn10search31turn10search2  
- Microsoft GraphRAG: gotowy pipeline budowy grafowego indeksu (encje → społeczności → streszczenia), open‑source na GitHubie + dokumentacja „Getting started”. citeturn3search0turn3search31turn3search20turn0search1  
- LlamaIndex KnowledgeGraphIndex: praktyczna automatyzacja budowy grafu z tekstu i query po encjach. citeturn10search3turn10search11

**Kompromisy**

- Skalowalność: graf może zmniejszać liczbę „strzałów” w LLM (np. przez pre‑streszczenia społeczności w GraphRAG) kosztem cięższego ingestion i większej złożoności danych. citeturn0search1turn3search4  
- Latencja: rerankery cross‑encoder podnoszą jakość, ale zwiększają czas (N par do oceny); dlatego standardem jest retrieval → rerank top‑N, nie rerank całego korpusu. citeturn12search11turn12search19  
- Koszt: hybryda i graf często zwiększają koszt ingest (LLM do ekstrakcji encji/relacji), ale zmniejszają koszt „ratowania” jakości w runtime przez kolejne heurystyki. To jest w duchu argumentu autora o „dokładaniu mini‑klocków” versus poprawa fundamentu. citeturn6view0turn7view1  
- Maintainability: mniej „magicznych” parametrów chunk_size; więcej jawnych typów jednostek i testów per typ. citeturn7view1turn13search3  
- Security/data governance: najlepiej wspierać **permission‑aware retrieval** już w retrieverze (prefilter), bo wtedy model nie ma czego „wyciec”. Dokumentacja Elastic i wektor DB pokazuje mechanizmy RBAC/DLS, namespaces/tenants i filtrowanie po metadanych. citeturn14search2turn14search16turn14search0turn11search6

## Migracja z klasycznego RAG do KM‑RAG

Migracja jest łatwiejsza, jeśli potraktujesz ją jak refactoring warstwy danych i retrieval, a nie „przepisanie wszystkiego od zera”.

### Ścieżka migracji krok po kroku

**Krok pierwszy: ustal bazową prawdę (baseline) i testy.**  
Bez ewaluacji będziesz „liczyć na cud” – wprost przeciwieństwo postulatu „kontrola zamiast nadziei”. Zacznij od małego zestawu pytań i oczekiwań (golden set) oraz logowania kontekstu i odpowiedzi. W praktyce możesz użyć RAGAS (metryki retrieval i faithfulness bez konieczności pełnych anotacji) oraz TruLens (RAG triad: context relevance, groundedness, answer relevance). citeturn4search1turn4search2turn4search6

**Krok drugi: dołóż metadane i proweniencję zanim dołożysz graf.**  
W klasycznym RAG często brakuje stabilnych ID i lokalizacji w źródle; tymczasem autor wiąże mapę wiedzy z odniesieniami do źródeł. Minimalny zestaw to: `source_id`, `version`, `page/section`, `timestamp`, `acl_tags`. Mechanizmy filtrowania po metadanych są standardem m.in. w Pinecone i Qdrant. citeturn2view1turn11search7turn11search6

**Krok trzeci: zamień chunki na węzły o typach i relacjach.**  
Zamiast „1000 znaków”, twórz: `SectionNode`, `TableNode`, `DefinitionNode`, `PolicyNode`. Jeśli nie możesz od razu, przejdź etapowo przez semantyczne node parsers (LlamaIndex) lub segmentację po strukturze dokumentu (partitioning). citeturn11search9turn16search0turn11search1

**Krok czwarty: zbuduj Mapę Wiedzy (graf) i zacznij od najtańszego użycia w runtime.**  
Nie musisz od razu robić pełnego „GraphRAG global”. Najpierw używaj grafu do: (a) definicji i wyjątków, (b) dołączania kontekstu „nadrzędna sekcja” / „poprzedni‑następny”, (c) audytu ścieżki cytowań. Dopiero potem dokładaj stricte grafowe retrievery. citeturn10search6turn10search31turn3search4

**Krok piąty: wprowadź gating i rollout.**  
Zgodnie z najlepszymi praktykami ewaluacji: iteruj, porównuj wersje, ustaw continuous evaluation i progi akceptacji. citeturn13search3turn13search35

### Proponowana sekwencja wdrożenia

| Faza | Co dostarczasz | Typowy czas (brak constraintów) | Kryterium „done” |
|---|---|---:|---|
| Audit RAG | logi + golden set + baseline metryk | 1–2 tyg. | masz mierzalne recall/faithfulness + top failure modes |
| Metadata-first | proweniencja + filtry + ACL | 1–2 tyg. | brak „orphan” chunków bez źródła; prefiltrowanie działa |
| Nodes & map | węzły typowane + relacje | 2–4 tyg. | stable IDs, relacje prev/next/contains/refers_to |
| Hybrid + rerank | dense+sparse + rerank top‑N | 1–3 tyg. | poprawa metryk retrieval bez wzrostu halucynacji |
| Graph expansion | dołączanie kontekstu grafem | 2–4 tyg. | poprawa trudnych pytań „łączących fakty” |
| Produkcja | monitoring KPI + procedury incydentów | ciągłe | CE + alerty + playbook audytu |

Metryki i praktykę continuous evaluation wspiera dokumentacja OpenAI (zalecenia dot. progów context recall/precision i pipeline’u ewaluacji), co jest spójne z „kontrolą” jako procesem, nie jednorazową konfiguracją. citeturn13search3turn13search27

## Implementacje przykładowe

Poniższe implementacje są „szkieletami” (reference implementations). W obu wariantach zakładam brak narzuconych wymagań co do skali, więc pokazuję rozwiązania, które da się skalować horyzontalnie (wektor DB) i/lub uprościć (pgvector zamiast osobnej bazy).

### Stack A: open‑source embeddings + open‑source Vector DB (Sentence Transformers + Qdrant) + graf w Neo4j

**Kiedy wybrać:** gdy chcesz uniezależnić embeddingi od dostawcy, mieć pełną kontrolę nad danymi i implementować multitenancy/filtry wprost w wektor DB. Payload/filtry i multitenancy są natywnie wspierane w Qdrant. citeturn11search6turn14search1turn14search7

**Zależności (przykład):** `sentence-transformers`, `qdrant-client`, `neo4j`, parser dokumentów (`unstructured` lub Tika).

```python
# --- Ingestion: parse -> units -> embeddings -> Qdrant + graph ---
from dataclasses import dataclass
from typing import Iterable, Optional
import hashlib
import time

from sentence_transformers import SentenceTransformer, CrossEncoder
from qdrant_client import QdrantClient, models as qmodels
from neo4j import GraphDatabase

@dataclass
class KnowledgeUnit:
    unit_id: str
    source_id: str
    version: str
    unit_type: str              # e.g. "section", "definition", "table"
    text: str                   # canonical text for embedding
    page: Optional[int] = None
    section_path: Optional[str] = None
    acl: str = "public"         # e.g. role/tenant tag

def stable_id(source_id: str, version: str, unit_type: str, page: str, text: str) -> str:
    raw = f"{source_id}|{version}|{unit_type}|{page}|{text}".encode("utf-8")
    return hashlib.sha256(raw).hexdigest()[:24]

# 1) Embeddings (bi-encoder) + reranker (cross-encoder)
embed_model = SentenceTransformer("sentence-transformers/all-MiniLM-L6-v2")  # example
reranker = CrossEncoder("cross-encoder/ms-marco-MiniLM-L-6-v2")              # example

# 2) Vector DB: Qdrant
qdrant = QdrantClient(url="http://localhost:6333", timeout=30)
COLLECTION = "kmrag_units"

DIM = embed_model.get_sentence_embedding_dimension()
qdrant.recreate_collection(
    collection_name=COLLECTION,
    vectors_config=qmodels.VectorParams(size=DIM, distance=qmodels.Distance.COSINE),
)

# Index payload fields frequently used in filters (performance)
qdrant.create_payload_index(
    collection_name=COLLECTION,
    field_name="acl",
    field_schema=qmodels.PayloadSchemaType.KEYWORD,
)
qdrant.create_payload_index(
    collection_name=COLLECTION,
    field_name="source_id",
    field_schema=qmodels.PayloadSchemaType.KEYWORD,
)

# 3) Graph DB: Neo4j (property graph)
neo4j_driver = GraphDatabase.driver(
    "neo4j://localhost:7687", auth=("neo4j", "password")
)

def upsert_units(units: Iterable[KnowledgeUnit]) -> None:
    batch = list(units)
    # embeddings
    vectors = embed_model.encode([u.text for u in batch], normalize_embeddings=True)

    # upsert into Qdrant with payload metadata (provenance + ACL)
    qdrant.upsert(
        collection_name=COLLECTION,
        points=[
            qmodels.PointStruct(
                id=u.unit_id,
                vector=vectors[i].tolist(),
                payload={
                    "source_id": u.source_id,
                    "version": u.version,
                    "unit_type": u.unit_type,
                    "page": u.page,
                    "section_path": u.section_path,
                    "acl": u.acl,
                    "ingested_at": int(time.time()),
                },
            )
            for i, u in enumerate(batch)
        ],
    )

    # build/update graph nodes + relationships
    cypher = """
    UNWIND $rows AS r
    MERGE (d:Document {source_id: r.source_id, version: r.version})
    MERGE (u:Unit {unit_id: r.unit_id})
      SET u.unit_type = r.unit_type,
          u.page = r.page,
          u.section_path = r.section_path
    MERGE (d)-[:HAS_UNIT]->(u)
    """
    with neo4j_driver.session() as s:
        s.run(cypher, rows=[u.__dict__ for u in batch])

# --- Query-time retrieval: vector -> graph expansion -> rerank -> context ---
def retrieve(query: str, acl: str, top_k: int = 30, rerank_k: int = 8):
    qvec = embed_model.encode([query], normalize_embeddings=True)[0].tolist()

    # 1) Candidate generation with metadata filter (permission-aware)
    hits = qdrant.search(
        collection_name=COLLECTION,
        query_vector=qvec,
        limit=top_k,
        query_filter=qmodels.Filter(
            must=[qmodels.FieldCondition(key="acl", match=qmodels.MatchValue(value=acl))]
        ),
    )
    candidate_ids = [h.id for h in hits]

    # 2) Graph expansion: pull neighbor units from same document/section (simple example)
    expand_cypher = """
    MATCH (u:Unit) WHERE u.unit_id IN $ids
    OPTIONAL MATCH (d:Document)-[:HAS_UNIT]->(u)
    OPTIONAL MATCH (d)-[:HAS_UNIT]->(u2:Unit)
    WHERE u2.section_path = u.section_path
    RETURN DISTINCT u2.unit_id AS unit_id
    LIMIT 200
    """
    with neo4j_driver.session() as s:
        rows = s.run(expand_cypher, ids=candidate_ids).data()
    expanded_ids = list({r["unit_id"] for r in rows}) or candidate_ids

    # 3) Fetch texts for reranking (here: from Qdrant payload 'text' not stored; you'd load from your storage)
    # In production: keep canonical text in your doc store; Qdrant payload keeps provenance only.
    # For demo: assume we can map id->text elsewhere:
    id_to_text = load_texts(expanded_ids)  # implement in your system

    pairs = [(query, id_to_text[i]) for i in expanded_ids]
    scores = reranker.predict(pairs)
    ranked = sorted(zip(expanded_ids, scores), key=lambda x: x[1], reverse=True)[:rerank_k]

    return ranked  # list of (unit_id, score) + you can also return provenance from payload

def load_texts(unit_ids):
    # Placeholder: pull canonical text from your document store / data lake
    raise NotImplementedError
```

Co w tym szkielecie jest „Mapą Wiedzy”: Neo4j przechowuje relacje (Document→Unit, a dalej możesz dodać Entity↔Unit, REFERENCES, NEXT), a Qdrant przechowuje wektory + payload do filtrowania; filtrowanie i indeksowanie payload jest sformalizowane w dokumentacji Qdrant. citeturn11search6turn11search2turn14search7

Rerank to klasyczny krok „retrieve‑then‑rerank” opisywany przez Sentence Transformers, gdzie CrossEncoder podnosi jakość finalnych wyników kosztem obliczeń. citeturn12search11turn12search19

### Stack B: managed LLM + Vector DB (OpenAI + Pinecone) + graf (Neo4j GraphRAG / Text2Cypher)

**Kiedy wybrać:** gdy zależy Ci na szybkości iteracji, jakości modeli oraz gotowych mechanizmach „structured output”, a retrieval chcesz oprzeć o managed vector DB z namespaces i hybrid search. citeturn13search1turn14search16turn11search3

W wariancie managed sensownie jest też wykorzystać Structured Outputs do wymuszenia formatu odpowiedzi (np. `answer` + `citations[]`), co jest elementem „kontroli” i audytu. OpenAI opisuje Structured Outputs jako mechanizm gwarantujący zgodność odpowiedzi z JSON Schema. citeturn13search1turn13search8

```python
# --- Managed stack: OpenAI embeddings + Pinecone + structured outputs + graph retrieval ---
from openai import OpenAI
from pinecone import Pinecone
from neo4j_graphrag import GraphRAG  # example usage; adjust to actual package API

OPENAI_MODEL_EMB = "text-embedding-3-large"
OPENAI_MODEL_GEN = "gpt-5.4-mini"   # example; choose by latency/cost needs

client = OpenAI()
pc = Pinecone(api_key="PINECONE_API_KEY")
index = pc.Index("kmrag")

def embed(texts):
    resp = client.embeddings.create(model=OPENAI_MODEL_EMB, input=texts)
    return [d.embedding for d in resp.data]

def upsert_to_pinecone(units, namespace):
    vecs = embed([u["text"] for u in units])
    index.upsert(
        vectors=[
            (u["unit_id"], vecs[i], {
                "source_id": u["source_id"],
                "version": u["version"],
                "unit_type": u["unit_type"],
                "page": u.get("page"),
                "section_path": u.get("section_path"),
                "acl": u.get("acl"),
            })
            for i, u in enumerate(units)
        ],
        namespace=namespace,   # multitenancy / workspace isolation
    )

def retrieve_candidates(query, namespace, acl, top_k=30):
    qvec = embed([query])[0]
    res = index.query(
        vector=qvec,
        top_k=top_k,
        include_metadata=True,
        namespace=namespace,
        filter={"acl": {"$eq": acl}},
    )
    return res["matches"]

# Optional: graph retrieval pattern via Text2Cypher (Neo4j GraphRAG package)
# The idea: use graph schema + question -> generated Cypher -> execute -> return records as extra grounded context.
gr = GraphRAG(neo4j_uri="neo4j+s://...", user="neo4j", password="...")

ANSWER_SCHEMA = {
  "name": "kmrag_answer",
  "schema": {
    "type": "object",
    "properties": {
      "answer": {"type": "string"},
      "citations": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "unit_id": {"type": "string"},
            "source_id": {"type": "string"},
            "quote": {"type": "string"}
          },
          "required": ["unit_id", "source_id"]
        }
      },
      "confidence": {"type": "number", "minimum": 0, "maximum": 1}
    },
    "required": ["answer", "citations", "confidence"]
  }
}

def answer(query, namespace, acl):
    hits = retrieve_candidates(query, namespace, acl)
    text_context = "\n\n".join(
        f"[{m['id']}] ({m['metadata'].get('source_id')}) {load_unit_text(m['id'])}"
        for m in hits[:8]
    )

    graph_context = gr.text2cypher_retrieve(query)  # e.g. definitions, relationships

    system = (
        "Odpowiadasz wyłącznie na podstawie kontekstu i grafu.\n"
        "Jeśli brakuje danych, powiedz wprost, czego nie wiesz.\n"
        "Zwróć cytowania do unit_id/source_id."
    )

    resp = client.responses.create(
        model=OPENAI_MODEL_GEN,
        input=[
            {"role": "system", "content": system},
            {"role": "user", "content": f"Pytanie: {query}\n\nKontekst:\n{text_context}\n\nGraf:\n{graph_context}"}
        ],
        text={
            "format": {
                "type": "json_schema",
                "json_schema": {**ANSWER_SCHEMA, "strict": True}
            }
        }
    )
    return resp.output_text

def load_unit_text(unit_id):
    # fetch canonical unit text from your storage
    raise NotImplementedError
```

Źródła dla tego stosu: OpenAI opisuje nowe modele embeddingowe (`text-embedding-3-small/large`) i guide embeddings, a także Structured Outputs i evaluation best practices. citeturn13search2turn13search1turn13search3turn13search9  
Pinecone opisuje hybrydę oraz filtrowanie po metadanych i multitenancy przez namespaces. citeturn11search3turn11search7turn14search16  
Wzorzec Text2Cypher – tłumaczenie pytania + schematu grafu na Cypher i wykonanie query – jest opisany w materiałach Neo4j. citeturn10search2turn10search6turn10search10

## Kontrola jakości, audyt i monitoring

„Kontrola zamiast nadziei” warto potraktować jako trzy warstwy: (A) kontrola danych i retrieval, (B) kontrola generacji, (C) kontrola procesu (ewaluacja i monitoring).

### Metryki i ewaluacja

**Ewaluacja retrieval** (czyt. „czy przynosimy właściwy kontekst”)

- Recall@K / Precision@K / MRR / NDCG: standardowe metryki IR; w pracach o retrieval z grafami i/lub KG są one explicite używane do oceny retrieval (np. praca o RAG+KG dla customer service raportuje MRR/Recall@K/NDCG@K). citeturn10search1turn10search5  
- Offline test set buduj iteracyjnie na podstawie prawdziwych porażek (failure traces) – to jest zgodne z podejściem „evaluation flywheel” i continuous evaluation. citeturn13search35turn13search3

**Ewaluacja generation** (czyt. „czy odpowiedź jest ugruntowana w źródłach”)

- RAGAS: framework do „reference‑free evaluation” RAG, mierzący różne wymiary retrieval i generation. citeturn4search1turn4search5  
- TruLens: RAG triad – context relevance, groundedness, answer relevance – jako praktyczny zestaw ocen dla halucynacji. citeturn4search2turn4search6

**Progi jakości (przykład)**  
OpenAI w evaluation best practices podaje przykładowe targety (np. context recall ≥ 0.85, context precision > 0.7) jako część praktyk ewaluacji i porównywania wersji. Traktuj to jako punkt startowy, nie prawo natury. citeturn13search3

### Checklist audytu KM‑RAG

**Dane i ingestion**

- Czy parser zachowuje strukturę (sekcje/tabele/numery stron) i czy masz testy parsera na „trudnych dokumentach” (tabele, wielokolumnowe layouty)? citeturn16search0turn16search10turn6view0  
- Czy każda jednostka wiedzy ma stabilne `source_id`, `version`, lokalizację i politykę retencji/PII? citeturn7view1turn14search2

**Mapa Wiedzy**

- Czy graf ma jasno zdefiniowane typy węzłów i relacje (HAS_UNIT, DEFINES, EXCEPTION_OF, REFERENCES, NEXT), oraz czy masz reguły walidacji (np. brak cykli w „NEXT”, spójność sekcji)? citeturn2view1turn10search31  
- Czy ekstrakcja encji/relacji jest mierzalna (precision/recall) i odporna na duplikaty/rozbieżności nazw? (w praktyce: canonicalization + entity resolution). Koncepcja grafu encji jako indeksu jest centralna w GraphRAG. citeturn0search1turn0search13

**Retrieval**

- Czy stosujesz prefilter po ACL/tenant (permission-aware retrieval), zanim cokolwiek trafi do prompta? (mechanizmy namespaces/tenants i DLS/RBAC istnieją w narzędziach retrieval). citeturn14search16turn14search0turn14search2  
- Czy masz hybrydę dense+sparse tam, gdzie słowa kluczowe są krytyczne (regulacje, numery, tickery)? Pinecone i Weaviate opisują hybrydę jako fuzję wyników. citeturn11search3turn12search0  
- Czy reranking działa na top‑N, a nie na setkach wyników (koszt/latencja), i czy jest mierzony? citeturn12search11turn12search19

**Generacja i grounding**

- Czy model ma jasną instrukcję „answer from sources” oraz czy odpowiedź wymusza strukturę (JSON schema) i cytowania? Structured Outputs jest mechanizmem wspierającym niezawodność formatu. citeturn13search1turn13search8  
- Czy masz mechanizm „I don’t know / insufficient evidence” zamiast konfabulacji (np. minimalny próg evidence coverage)? Podejścia typu CoVe/Self‑RAG/CRAG pokazują, że pętle weryfikacji i korekty podnoszą factuality. citeturn8search3turn9search1turn9search2

**Bezpieczeństwo**

- Czy testujesz prompt injection na poziomie aplikacji, nie tylko promptu? OWASP opisuje prompt injection jako manipulację zachowaniem modelu przez wejście, a cheat sheet sugeruje praktyki obrony. citeturn4search3turn4search7turn4search13  
- Czy masz kontrolę kosztu (rate limits, timeouts, budżety tokenów) – to też „kontrola”, bo DoS na LLM to realny wektor ryzyka (OWASP LLM Top 10 zawiera kategorie dot. DoS i supply chain). citeturn4search13turn13search12

### KPI i monitoring w produkcji

Rekomendowany zestaw KPI (z podziałem na warstwy):

**Retrieval KPI**

- Context Recall@K / Context Precision@K (offline i online na próbie logów). citeturn13search3turn4search1  
- % zapytań, w których retrieval zwraca „pustkę” lub tylko niskie score (sugeruje routing lub brak danych).

**Generation KPI**

- Faithfulness/groundedness (TruLens/RAGAS). citeturn4search1turn4search6  
- Citation coverage: % zdań mających przypisane źródło, oraz „citation accuracy” (czy cytat faktycznie zawiera wspierający fragment). Self‑RAG raportuje poprawę citation accuracy w długich generacjach jako jeden z efektów frameworku. citeturn9search1turn9search9

**Ops KPI**

- Latencja p95/p99 per etap (retrieval, rerank, LLM).  
- Koszt per zapytanie (tokeny, liczba wywołań modeli) + alerty „unbounded consumption”. OpenAI publikuje production best practices i evaluation tooling jako część przejścia prototyp → produkcja. citeturn13search12turn13search3

**Narzędzia do obserwowalności**

- RAGAS opisuje łączenie ewaluacji z tracingiem/analizą (np. Phoenix). citeturn4search34  
- TruLens ma integracje i dokumentację quickstart dla trace + feedback. citeturn4search2turn4search27  
- Jeśli używasz OpenAI, masz też guidance dot. ewaluacji i ciągłego monitorowania regresji. citeturn13search3turn13search6

### Typowe failure modes KM‑RAG i mitigacje

**„Graf rośnie w chaos” (sprawl, duplikaty encji, zła kanonikalizacja).**  
Mitigacja: wprowadź entity resolution, reguły normalizacji nazw, walidację schematu grafu i testy na podzbiorze; zacznij od grafu dokument‑sekcja‑unit, dopiero potem dodawaj encje/relacje automatyczne. GraphRAG wprost zaczyna od grafu encji jako indeksu, ale też pipeline’u budowy i transformacji danych, co sugeruje konieczność procesu, nie jednorazowego prompta. citeturn3search0turn0search1

**„Retrieval jest poprawny semantycznie, ale zły merytorycznie” (conflicts).**  
Mitigacja: hybryda dense+sparse + rerank + kontrola jakości źródeł + mechanizmy korekty (CRAG: evaluator jakości retrieval i akcje naprawcze). citeturn9search2turn11search3turn12search0

**„Źródła przenoszą instrukcje (prompt injection z dokumentów)”**  
Mitigacja: separacja „instructions vs data”, sanitation, polityki „nie wykonuj instrukcji z kontekstu”, oraz przede wszystkim permission-aware retrieval (prefilter). OWASP opisuje prompt injection i praktyki obrony. citeturn4search3turn4search7turn14search2

**„Latency/cost eksploduje przez reranking i graf”**  
Mitigacja: ogranicz N rerankowanych kandydatów; cache embeddingów; cache wyników graf expansion; pre‑streszczenia (GraphRAG community summaries) dla klas pytań globalnych. citeturn12search11turn0search1turn3search4

**„Zgodność i audyt”**  
Mitigacja: loguj trace: query → (filtry ACL) → dokumenty → fragmenty → odpowiedź; uzupełnij o standardy zarządzania ryzykiem i bezpieczeństwem (entity["organization","NIST","us standards institute"] AI RMF; entity["organization","ISO","international standards body"]/IEC 27001; entity["organization","OWASP","security foundation"] LLM Top 10). Zapewnia to język kontroli dla audytu, nawet jeśli implementacje są różne. citeturn15search1turn15search2turn4search13turn15search3

### Źródła priorytetowe do dalszej pracy

Najbardziej „nośne” (load‑bearing) źródła do wdrożenia KM‑RAG, w kolejności praktycznej użyteczności:

Źródła autora: definicja Mapy Wiedzy (graf + metadane + odniesienia) oraz argument o „R jako ryzyku” i potrzebie kontroli retrieval. citeturn2view1turn7view1

Podstawy RAG: praca Lewis et al. (RAG jako retrieval + generacja z nieparametrycznej pamięci) – jako fundament terminologiczny. citeturn0search2turn0search5

GraphRAG: publikacja i repozytorium Microsoft (graf encji, społeczności, streszczenia) – jako referencyjny wariant Mapy Wiedzy w postaci pipeline’u. citeturn0search1turn3search0turn3search4turn3search20

KG‑RAG / hybrydy: prace o łączeniu KG i RAG (np. HybridRAG; RAG+KG w customer service) – pokazują, że graf zmniejsza skutki segmentacji i poprawia retrieval. citeturn10search0turn10search1

Ewaluacja i kontrola jakości: RAGAS + TruLens + best practices ewaluacji – jako praktyczny „system kontroli”. citeturn4search1turn4search2turn13search3

Bezpieczeństwo: OWASP prompt injection i LLM Top 10 – jako checklisty dla warstwy „R” i integracji z danymi. citeturn4search3turn4search13turn4search7