Semantische ID's - Entity Enricher-documentatie

Semantische ID's

Verrijk hetzelfde soort entiteit keer op keer en je blijft dezelfde dingen uit de echte wereld opnieuw ontdekken — hetzelfde bedrijf, dezelfde bijwerking van een medicijn, dezelfde persoon — elke keer met net iets andere woorden beschreven. Een semantische ID is een stabiele, tot de organisatie beperkte identifier die Entity Enricher aan een object toekent op basis van zijn sleutelvelden, zodat die bijna-duplicaten samenvallen tot één identiteit waarop je kunt groeperen, dedupliceren en joinen.

Het probleem: hetzelfde, andere woorden

De identiteit van een object wordt opgebouwd uit de sleutelvelden — en dat kunnen er een of meerdere zijn. Twee voorbeelden:

Eén sleutel

Een neveneffect met sleutel `name`

Het verschijnt als Headache, Céphalée en Cephalalgia door verschillende runs en talen heen. Eén sleutelveld, drie schrijfwijzen, één echt concept.

Twee sleutels

Een bedrijf met als sleutel `naam` + `land`

Acme Inc. · United States en Acme Incorporated · United States zijn hetzelfde bedrijf — terwijl Acme Inc. · Germany een ander bedrijf is. De tweede sleutel maakt het onderscheid; daarom kan een object er meer dan één dragen.

Eenvoudige tekstvergelijking faalt bij al deze gevallen; een mens weet welke hetzelfde zijn. Semantische ID's leggen dat oordeel automatisch vast.

Wat een semantische ID is

•Eén enkele string-eigenschap op een object (standaard id genoemd), die een ondoorzichtige, stabiele identificator bevat.
•Stabiel & organisatiespecifiek — hetzelfde object uit de echte wereld levert dezelfde ID op over enrichments, batches en tijd heen, alleen binnen jouw organisatie.
•Automatisch toegewezen, nooit door de LLM — het wordt berekend in een verwerkingsstap na de enrichment, zodat het model het niet kan hallucineren. Het is een doorgeefveld (invoerwaarden stromen ongewijzigd door): altijd een string, nooit een key, nooit preserve, nooit meertalig, hooguit één per object.
•Toegestaan op elk object — de hele entiteit (root), een genest 1-op-1-object (bijv. een manufacturer), of elk item in een array (bijv. elke side_effect).

Hoe het werkt

Nadat het model zijn resultaat heeft teruggegeven, lost Entity Enricher elke semantische ID in zes stappen op — de goedkoopste eerst. De vier stappen vóór de embedding zijn pure tekstvergelijking, dus een identiteit die daar wordt vastgesteld kost helemaal niets:

Stel de identiteitstekst samen

Voeg de sleutelvelden die het object zelf identificeren samen tot één string, in je primaire taal. Een genest object dat op zichzelf een entiteit is, blijft buiten beschouwing: de sleutel ervan benoemt dat object, niet wat ernaar verwijst, en elk zusterveld dat naar dezelfde entiteit verwijst zou dezelfde waarde bevatten — twee missies met dezelfde lanceerplaats zouden vrijwel identiek lezen en dreigen samen te vallen tot één. Geneste objecten die alleen velden groeperen tellen wél mee; net als de sleutel van een gerelateerde entiteit als je die zelf toevoegt. Items in arrays worden nooit meegenomen: elk array-item heeft zijn eigen identiteit. De lijst identiteitsdeelnemers in de schema-editor laat precies zien welke waarden de tekst vormen en laat je ze herordenen of wijzigen — schema's die dezelfde deelnemers in dezelfde volgorde kiezen, leveren identieke ID's op. De tekst wordt genormaliseerd (kleine letters, tekst tussen haakjes verwijderd, spaties samengevoegd) om triviale verschillen te beperken. Als al die sleutelvelden leeg terugkomen, is er niets om het object mee te identificeren en kan er geen ID worden toegekend — het object wordt dan verwijderd in plaats van bewaard als een anoniem object waarop niets gegroepeerd, samengevoegd of ontdubbeld kan worden: een genest object wordt null in zijn ouderobject, en een item in een lijst verdwijnt uit de lijst. De verrijkte entiteit zelf wordt nooit verwijderd; die heeft simpelweg geen ID.

Zoek naar een exacte overeenkomst

Als diezelfde genormaliseerde tekst eerder in jouw organisatie is gezien, wordt de bestaande ID meteen hergebruikt — geen model-aanroep, geen kosten.

Matchen op een code, als die er is

Wanneer een van de identiteitssleutels een code is — een veld met een patroonbeperking, of een veld waarvan de voorbeelden op identificatiecodes lijken — wordt die als eerste samengesteld en apart vergeleken. Een exacte codeovereenkomst bepaalt de identiteit meteen, hoe de omringende tekst ook luidt, zodat LC-39A alle schrijfwijzen van de rest van de tekst verenigt. Minstens zo belangrijk: het werkt ook omgekeerd: een andere code blokkeert een samenvoeging die de embeddingstap anders had geaccepteerd, want twee dingen met verschillende identificatiecodes zijn twee dingen, hoe gelijk ze ook lezen.

Matchen op dezelfde woorden in willekeurige volgorde

Voordat er een embedding wordt uitgegeven, worden de woorden zelf als verzameling vergeleken: als de woorden van de ene tekst in die van de andere zitten, gaat het om dezelfde identiteit, alleen korter of langer opgeschreven — “Boeing” en “The Boeing Company”. Dit vangt precies de lengteverschillen op die embeddings als ver uit elkaar meten, en het kost niets: net als bij de stap met exacte tekst betekent een treffer hier geen embedding-aanroep en geen kosten.

Embedden en vergelijken

Anders wordt de tekst geëmbed en op betekenis vergeleken met bestaande concepten van hetzelfde concepttype (standaard de naam van het entiteitstype — in de editor aanpasbaar, zodat schema's met verschillende namen één conceptruimte delen) met behulp van vectorsimilariteit — zodat “Acme Inc.” en“Acme Incorporated” naast elkaar terechtkomen.

Hergebruiken of aanmaken

Als de dichtstbijzijnde overeenkomst boven de gelijkenisdrempel scoort (standaard 0.92, per eigenschap instelbaar), wordt de ID van dat concept hergebruikt. Anders wordt er een gloednieuwe ID aangemaakt en bewaard voor de volgende keer. Eén uitzondering gaat boven een hoge score: als beide teksten dezelfde woorden zijn maar anders geteld — “tweede trap” en“derde trap” — worden ze als verschillende dingen behandeld, want juist het tellen onderscheidt ze. Hetzelfde getal op twee manieren geschreven (2 enII) komt nog steeds overeen.

Drempel-afweging: een hogere drempel is strenger (minder onbedoelde samenvoegingen); een lagere is losser (agressievere deduplicatie). Stel deze per eigenschap af wanneer de standaardwaarde van 0,92 te veel of te weinig samenvoegt.

Invoer-ID's vs. gegenereerde ID's

Of er een ID wordt gegenereerd hangt ervan af of er al een aanwezig is in de invoer voor dat object. Dit is wat je in staat stelt om een round-trip te doen: verrijk één keer om ID's te verkrijgen en geef een bekend ID later terug bij volgende runs om nieuwe feiten aan dezelfde identiteit te koppelen — goedkoper en ondubbelzinnig.

ID al aanwezig in de invoer → behouden (lookup)

Als het object dat je verstuurt al een semantische ID bevat, wordt het als een lookup behandeld: de ID wordt letterlijk behouden, het record wordt aan dat bestaande concept gekoppeld en er is geen embedding — geen kosten, geen match-of-mint. Je vertelt het platform “dit object is al geïdentificeerd in onze database.”

Geen ID in de invoer → gegenereerd

Heeft het object geen semantische ID, dan genereert het platform er een met de bovenstaande stappen. Die ID is vanaf dat moment de stabiele identificator van het object in de database van je organisatie.

Een aanwezige maar onherkenbare waarde (geen echte concept-ID) wordt genegeerd en er wordt in plaats daarvan een ID gegenereerd.

Zo schakel je het in

Kies een embeddingmodel (eenmalig per organisatie)

Een eigenaar kiest onder Instellingen → Organisatie → Standaardwaarden een model dat embeddings ondersteunt als het standaard embeddingmodel van de organisatie (een instelling die van je abonnement afhangt; zie Modellen & Prijzen voor welke modellen kunnen embedden). Opgeslagen vectoren zijn niet vergelijkbaar tussen modellen, dus zodra er concepten bestaan kan de instelling alleen nog worden gewist — overschakelen verloopt als een migratie vanaf de pagina Semantische ID's, die elk concept opnieuw embedt en hun ID's behoudt. Zonder model worden semantische ID's simpelweg overgeslagen.

Semantische ID's toevoegen aan het schema

Twee manieren, allebei in de Workflow Editor:

Automatisch bij het genereren — vink “Semantic ID's voor types genereren” aan; elk object met een sleutel (een eigen sleutel of een sleutel op een 1-op-1 genest object) krijgt er een, inclusief de root-entity.
Handmatig — gebruik de knop “+ Semantische ID toevoegen” op een object of de entiteitsvoettekst.

Resolutie kost een klein beetje embeddinggebruik per enrichment (afgerekend zoals elke modelaanroep). De exacte-match-cache maakt herhalingen gratis en door de invoer aangeleverde ID's kosten niets.

Waar de ID's verschijnen en wat je ermee doet

Herleide ID’s verschijnen in de JSON-output van de verrijking (het veld id op elk object), bij de semantische concepten in het recorddetail, en allemaal samen op de pagina Semantische ID’s, waar je het vocabulaire dat ze vormen doorbladert en cureert. Gebruik ze om:

•Dedupliceer rijen over batches en in de tijd.
•Bouw een stabiele join-sleutel voor je datawarehouse of CRM.
•Reconcilieer dezelfde entiteit die op verschillende dagen of in verschillende talen is gezien.

Vult multi-model fusie aan

Fusie verzoent meningsverschillen tussen modellen binnen één run; semantische ID's verzoenen dezelfde entiteit over runs en tijd heen. De twee werken samen.

Kernconcepten

Zoek- en samenvoegsleutels, waarop semantische ID's voortbouwen

Meertalige verrijking

Cross-linguale spellingen samenvoegen tot één identiteit

Multimodelfusie

Reconcilieer over modellen heen binnen één run

Workfloweditor

Semantische ID's toevoegen aan elk object

De pagina Semantische ID’s

Blader door het resulterende vocabulaire, cureer het en verwijder duplicaten