KnowledgeGraphService – saját gráf-ingestion külső forrásból

Mikor van szükség erre?

A KnowledgeGraphService egy @Service singleton – bármely plugin tool vagy saját service osztály @Autowired-del injektálhatja, függetlenül attól, hogy van-e a domainhez NER ingestion tool. Közvetlen használata akkor indokolt, ha:

• a forrásadat nem szöveges dokumentum, amit a platform document/embedding pipeline-ja dolgozott volna fel (pl. strukturált rekordok, egy külső rendszer REST API válasza, egy másik adatbázis export-ja)
• a plugin ennek ellenére gráf-reprezentációt akar építeni belőle – fogalmakat (csomópontokat) és a köztük lévő kapcsolatokat –, hogy egy másik tool ezt lekérdezhesse

Ilyenkor a plugin a AbstractNERIngestionTool egész gépezetét (Spark batch, LLM-alapú entitáskinyerés, mondatszintű mention-ek) megkerülve, közvetlenül hívja a KnowledgeGraphService UPSERT metódusait – a saját, már ismert struktúrájú adatból nincs szükség LLM-es kinyerésre, a mezők közvetlenül leolvashatók.

A gráf modell – collection-ok és named graph

A gráf három, domain-előtaggal ellátott ArangoDB collection-ből áll, ugyanazzal a névkonvencióval, mint a dokumentum-embedding collection-öknél:

Domain nélkül (domain = null) a prefix üres – ez egy alapértelmezett domain collection-jeit jelenti, amelyet lekérdezéskor nem kell külön megjelölni. A három collection-t és a rájuk épülő named graph-ot az initCollections(domain) hozza létre, idempotens módon (ha már léteznek, nem csinál semmit).

Írás: a gráf felépítése

upsertConcept(domain, system, label, type, aliases)

Felvisz vagy frissít egy fogalmat. A deduplikálás a label normalizált formája (normalizeLabel() – kisbetűsítés + ékezet-eltávolítás) és a type párosa alapján történik: ha már létezik ugyanilyen normalizedLabel + type kombinációjú csomópont, a hívás frissíti azt UPSERT-tel ahelyett, hogy duplikálná. Azonos label, de eltérő type esetén két külön csomópont jön létre. Visszatérési érték: a csomópont ArangoDB _key-e – ezt kell továbbadni az upsertRelation és saveMention hívásoknak.

String patientKey = knowledgeGraphService.upsertConcept(
    domain, system,
    "Kovács Mária",           // label
    "PATIENT",                // type – szabadon választott, saját taxonómia
    List.of("K. Mária")       // aliases – kereséskor is találatot ad
);

upsertRelation(domain, system, fromConceptKey, toConceptKey, relationType, bidirectional)

Felvisz vagy frissít egy irányított élt két korábban upsertConcept-tel létrehozott csomópont között. A dedup kulcsa (_from, _to, relationType) – ismételt előfordulás esetén a weight nő (kezdetben 1.0, minden ismétlésnél +0.5). A bidirectional flag csak metaadat – a gráf-bejárás iránya mindig _from → _to, a flag a lekérdező logikának ad jelzést arra, hogy az élt visszafelé is érdemes-e követni.

knowledgeGraphService.upsertRelation(
    domain, system,
    patientKey, conditionKey,
    "DIAGNOSED_WITH",   // relationType – saját taxonómia
    false              // bidirectional
);

saveMention(domain, system, conceptKey, documentSentenceKey, documentCollection, mentionContext) – opcionális

Ez a metódus köti össze a fogalmat egy konkrét, visszakereshető szöveges dokumentum-egységgel – a platform szövegalapú retrieval pipeline-jában ez egy PageEmbedding1024 bejegyzés kulcsa. Ha a forrásadatod nem ilyen szöveges oldal (mint egy strukturált külső rekord), nyugodtan kihagyhatod – a fogalmak és relációk enélkül is felépülnek és lekérdezhetők label alapján (lásd lentebb). A saveMention csak akkor szükséges, ha azt szeretnéd, hogy a findPageKeysByLabels ezen fogalmakhoz retrievelhető oldal-kulcsokat is visszaadjon a RAG kontextushoz.

deleteBySystem(domain, system) – tiszta újraingestion

Törli az adott system összes bejegyzését a domain gráfjából: a csak ehhez a system-hez tartozó fogalmakat és éleket teljesen törli, a több system között megosztottaknál csak a system-jelölést veszi le. Idempotens – ismételt hívás hibátlanul lefut akkor is, ha már nincs mit törölni. A bevett minta egy teljes újraingestion elején:

knowledgeGraphService.deleteBySystem(domain, system);
for (ExternalRecord record : source.fetchAll()) {
    // ... upsertConcept / upsertRelation minden rekordra
}

Teljes példa – saját ingestion service külső forrásból

Az alábbi minta egy plugin saját, nem-IIngestionTool service osztálya, amely egy külső rendszer strukturált rekordjaiból épít gráfot – nincs LLM-hívás, nincs Spark, a mezők közvetlenül a forrásból olvashatók:

@Service
public class MyExternalDataGraphIngestionService {

    @Autowired
    private KnowledgeGraphService knowledgeGraphService;

    public void ingest(String domain, String system, List<ExternalRecord> records) throws Exception {
        // Tiszta újraingestion: előző állapot törlése erről a system-ről
        knowledgeGraphService.deleteBySystem(domain, system);

        for (ExternalRecord record : records) {
            String parentKey = knowledgeGraphService.upsertConcept(
                domain, system,
                record.getParentLabel(), record.getParentType(),
                record.getParentAliases());

            String childKey = knowledgeGraphService.upsertConcept(
                domain, system,
                record.getChildLabel(), record.getChildType(),
                List.of());

            knowledgeGraphService.upsertRelation(
                domain, system,
                parentKey, childKey,
                record.getRelationType(), false);
        }
    }
}

Ezt a service-t egy IPluginConfigurer.configure() triggerelheti induláskor, vagy egy saját, ütemezett/manuálisan hívható tool – attól függően, hogy a külső forrás milyen gyakran változik.

Olvasás: a gráf lekérdezése egy másik tool-ból

A felépített gráfot bármelyik tool lekérdezheti, amely szintén @Autowired-eli a KnowledgeGraphService-t. A kész lekérdező metódusok mindegyike normalizeLabel()-lel normalizált kulcsszavakat vár bemenetként.

findAliasesByLabels(domain, normalizedLabels)

A megadott label-ekhez egyező fogalmak összes ismert (eredeti, ékezetes) alias-át adja vissza – az input label-ekkel megegyezőket kizárva. Csak a KnowledgeConcept collection-t nézi, ConceptMention függetlenül is működik.

findConceptInfoByLabels(domain, normalizedLabels)

A megadott label-ekhez egyező fogalmak strukturált metaadatát adja vissza: label, type, aliases – Map-ek listájaként. Ugyanúgy ConceptMention-független; ez a fő belépési pont, ha a forrásadatod nem szöveges, és egyszerűen csak "van-e ilyen fogalom, és mi a típusa, milyen alias-okon ismert" kérdésre keresel választ.

findConceptsByFuzzyLabel(domain, conceptTypes, normalizedTerm, maxDistance, limit)

Elgépelés-toleráns fogalom-keresés: a normalizedLabel mezőt és a normalizedAliases tömb egyes elemeit külön-külön Levenshtein-szerkesztési távolság alapján hasonlítja össze a keresett névvel (betűcsere/transzpozíció is egyetlen szerkesztési lépésnek számít), és a maxDistance-en belüli találatokat adja vissza key/label párokként. Arra való, amikor a pontos vagy szuffix-alapú névkeresés (findConceptInfoByLabels, vagy egy saját executeReadOnlyQuery-alapú lekérdezés) nulla találatot ad, és ennek indoka valószínűleg a felhasználó elgépelése, nem a fogalom tényleges hiánya.

A visszaadott jelöltek - pontosan úgy, mint egy alias-egyezés - nem garantáltan a keresett fogalomhoz tartoznak: egy kis szerkesztési távolság véletlenül egy teljesen más fogalomra is illeszkedhet. A bevett minta ezért a fuzzy találatokat egy LLM-alapú relevancia-szűrőn engedi át, mielőtt elfogadná őket - ugyanazon a szűrőn, amit egy alias-alapú találatra is használnál:

List<Map<String, Object>> directHits = findByExactOrSuffixMatch(domain, normalizedTerm);
if (directHits.isEmpty()) {
    int maxDistance = Math.min(3, Math.max(1, (normalizedTerm.length() + 3) / 4));
    List<Map<String, Object>> fuzzyHits = knowledgeGraphService.findConceptsByFuzzyLabel(
        domain, List.of("DRUG"), normalizedTerm, maxDistance, 10);
    // fuzzyHits minden elemét LLM-mel ellenőrizd, mielőtt elfogadnád találatnak
}

findPageKeysByLabels(domain, systems, normalizedLabels, allowedRelationTypes, minRelationWeight)

A megadott label-ekhez tartozó fogalmakhoz, majd (opcionálisan) az 1-hop gráf-szomszédaikhoz tartozó ConceptMention.documentSentenceKey értékeket adja vissza – ezek PageEmbedding1024 kulcsok, tehát a RAG kontextushoz retrievelhető oldalakat azonosítanak. Ha nem hívtál saveMention-t az adott fogalmakra, ez a metódus üres listával tér vissza rájuk – ez esetben a findConceptInfoByLabels / findAliasesByLabels a releváns lekérdező eszköz.

findConceptPagesByLabels(domain, systems, normalizedLabels, allowedRelationTypes, minRelationWeight)

Ugyanazokat a fogalmakat járja be, mint a findPageKeysByLabels, de az oldalakat nem egyesíti: fogalmanként ad vissza egy ConceptPages rekordot (a fogalom kulcsa, normalizált címkéje, az, hogy közvetlen egyezés vagy szomszéd, és az említéseinek oldalkulcsai). Akkor hasznos, ha a hívó maga dönti el, mely fogalmaknak van megkülönböztető ereje – például kihagyja azokat, amelyek szinte minden oldalon szerepelnek –, vagy azt vizsgálja, hány fogalom említi ugyanazt az oldalt. Csak az említéssel rendelkező fogalmak szerepelnek; hiba esetén üres listát ad. A paraméterek jelentése megegyezik a findPageKeysByLabels-ével.

countMentionedPages(domain, systems)

Azoknak az oldalaknak a száma, amelyeken a megadott system-ekben legalább egy fogalom-említés szerepel – a fogalmak oldalgyakoriságának viszonyítási alapja. Az eredmény domain és system-lista szerint néhány percig gyorsítótárazott, így egy frissen ingestált dokumentum rövid késéssel jelenik meg benne. Hiba esetén 0.

findConnectedConcepts(domain, normalizedLabels, relationType, reverse, targetType)

A megadott label-ekhez egyező fogalmakból kiindulva, egy megadott relationType értékű élen 1 lépésben elérhető fogalmakat adja vissza – opcionálisan a célfogalom type mezőjére szűrve. Általános, tetszőleges relációtípusra alkalmazható bejárás: a visszatérési érték a talált fogalmak key/label/ type metaadata (nem oldalkulcs, mint a findPageKeysByLabels-nél).

List<Map<String, Object>> results = knowledgeGraphService.findConnectedConcepts(
    domain,
    List.of(normalizedLabel),
    "DIAGNOSED_WITH",   // relationType
    true,               // reverse
    "PATIENT"           // targetType – null = nincs típusszűrés
);

Az irány paraméterezhető: reverse=false esetén a bejárás a matched fogalom felől kimenő élen megy (a matched fogalom az él _from oldalán áll), reverse=true esetén a bejárás a matched fogalom felé bejövő élen megy (a matched fogalom az él _to oldalán áll).

executeReadOnlyQuery(domain, aql, bindVars)

Tetszőleges, a hívó által összeállított, csak olvasó AQL lekérdezést futtat a domain tudásgráfján – olyan egyedi, több lépésben láncolt bejárási mintákhoz, amelyeket a findPageKeysByLabels (egy ugrás) és a findConnectedConcepts (egy relationType) nem fed le, például amikor egy fogalomhalmazból egy adott relációtípuson át elért fogalmakból egy második, eltérő relációtípusú ugrással kell tovább bejárni a gráfot.

A lekérdezés szövegében a három tudásgráf collection-re kizárólag négy lefoglalt placeholder néven keresztül lehet hivatkozni – a metódus ezeket a domainhez tartozó valódi collection-névre cseréli futtatás előtt, a hívó kód sosem szerez tudomást a tényleges elnevezési konvencióról:

Map<String, Object> bindVars = Map.of(
    "labels", List.of("fejfajas"),
    "minWeight", 2.0
);

String aql = """
    FOR c IN @@concept
        FILTER c.normalizedLabel IN @labels
        FOR r IN @@relation
            FILTER r._to == c._id OR r._from == c._id
            FILTER r.weight >= @minWeight
            LET other = r._from == c._id ? DOCUMENT(r._to) : DOCUMENT(r._from)
            RETURN { label: other.label, type: other.type, weight: r.weight }
    """;

List<Map<String, Object>> rows = knowledgeGraphService.executeReadOnlyQuery(domain, aql, bindVars);

A lekérdezés RETURN záradékának objektumot kell visszaadnia (pl. RETURN { label: c.label }), nem primitív értéket – a visszaadott List<Map<String, Object>> minden eleme egy-egy visszaadott sor mező-érték párjait tartalmazza.

Logikai törlés (kuka)

Egy fogalom nem csak a deleteBySystem-mel távolítható el fizikailag: a KnowledgeGraphService egy logikai törlési ("kuka") állapotot is támogat, amelyet tipikusan egy gráf-karbantartó feladat állít be olyan fogalmakra, amelyekről utólag kiderül, hogy tévesen kerültek a gráfba (pl. egy kinyerési hiba miatt). Logikailag törölt állapotban a fogalom-dokumentum, a hozzá kapcsolódó élek és mention-ök változatlanul megmaradnak, csak a fenti lekérdező metódusok elől válnak láthatatlanná - az adat nem vész el, a döntés visszavonható.

listDeletedConcepts(domain)

Az adott domainben jelenleg logikailag törölt állapotú összes fogalmat adja vissza - key, label, type, a törlés időpontja és a törlés mellett rögzített indoklás mezőkkel. Arra való, hogy egy adminisztrációs felület vagy karbantartó tool át tudja tekinteni, mi került a kukába, mielőtt döntene a visszaállításról vagy a végleges eltávolításról.

restoreConcept(domain, conceptKey)

Visszavonja egy fogalom logikai törlését - a fogalom ismét megjelenik a lekérdező metódusok találatai között, pontosan úgy, mintha sosem lett volna törölve. A hozzá kapcsolódó élek és mention-ök a törlés alatt is érintetlenek maradtak, így nincs mit helyreállítani rajtuk.

purgeDeletedConcepts(domain)

Az adott domainben logikailag törölt állapotú összes fogalmat, valamint a hozzájuk kapcsolódó éleket és mention-öket véglegesen, visszavonhatatlanul eltávolítja a tudásgráfból. Visszatérési érték: a véglegesen eltávolított fogalmak száma. Ezt a metódust csak akkor érdemes hívni, ha a listDeletedConcepts alapján megerősítést nyert, hogy a kukában lévő fogalmakra a jövőben sincs szükség - utána a restoreConcept már nem tudja visszahozni őket.

Viszonya a NER ingestion pipeline-hoz

A KnowledgeGraphService ugyanaz az alaprétege mindkét útnak: a 10. fejezetben tárgyalt AbstractNERIngestionTool valójában ugyanezeket az UPSERT metódusokat hívja a Spark-alapú, LLM-es entitáskinyerés eredményéből, plusz minden feldolgozott mondathoz saveMention-t is hív (mert ott a forrás mindig egy retrievelhető szöveges oldal). A különbség tehát nem a gráf-modellben van, hanem abban, hogy ki és honnan tölti fel: