Generieke Chatbot API

De Generieke Chatbot API is een herbruikbare backend voor chatbot-clients die antwoorden geven op basis van expliciet opgehaalde brondocumentatie. De API is ontwikkeld om meerdere chatbottoepassingen te ondersteunen zonder voor elke use case opnieuw een volledige backend te bouwen.

De toepassing combineert generatieve AI met gecontroleerde bronontsluiting, documentcache, hybride retrieval en evidence-grounded antwoordgeneratie. Daardoor kan een gebruiker via een aangesloten client een vraag in natuurlijke taal stellen, terwijl de API op de achtergrond de juiste bronnen zoekt, relevante fragmenten selecteert en een antwoord formuleert dat is onderbouwd met concrete broninformatie.

Managementsamenvatting

De Generieke Chatbot API maakt het mogelijk om chatbotfunctionaliteit centraal en gestandaardiseerd aan te bieden. In plaats van per chatbot opnieuw bronkoppelingen, retrieval, promptlogica, streaming en logging te ontwikkelen, biedt deze API een generieke basis waarop verschillende profielen kunnen worden aangesloten.

Een profiel bepaalt hoe de chatbot zich gedraagt. Zo is er een DSO-profiel voor vragen over omgevingsregels op een specifieke locatie en is er een Kaatje-profiel als basis voor kennisbankachtige toepassingen. Per profiel kunnen andere bronnen, prompts, routekeuzes en antwoordstrategieën worden ingericht.

De API is vooral waardevol omdat antwoorden niet alleen door een taalmodel worden gegenereerd, maar worden gebaseerd op opgehaalde broninformatie. Waar onvoldoende informatie beschikbaar is, hoort de API terughoudend te antwoorden. Dit is belangrijk bij juridische of regelgerichte vragen, waarbij een geforceerde conclusie onwenselijk is.

Hoe werkt het op hoofdlijnen?

De API doorloopt een aantal stappen:

De gebruiker stelt een vraag via een client of frontend.
De API valideert de API-key en controleert of de client toegang heeft tot het gekozen profiel.
Een taalmodel analyseert de vraag en bepaalt of extra informatie nodig is, zoals een locatie.
Locatiegegevens kunnen waar nodig worden verrijkt, bijvoorbeeld via PDOK.
De API bepaalt welke bronroutes relevant zijn voor de vraag.
Brondocumenten worden opgehaald uit gekoppelde bronnen of uit de cache geladen.
Documenten worden verwerkt tot kleinere tekstfragmenten met metadata.
De fragmenten worden doorzocht met hybride retrieval: vector search, BM25 en fuzzy matching.
Relevante passages worden geselecteerd en opnieuw beoordeeld.
Een taalmodel formuleert het antwoord op basis van de geselecteerde bronpassages.
Evidence wordt gecontroleerd en gekoppeld aan het antwoord.
Het antwoord wordt als streaming response teruggegeven aan de gebruiker.

Architectuur

Onderstaande architectuurplaat toont de belangrijkste onderdelen van de Generieke Chatbot API: de koppeling met clients, streaming events, API-routes, authenticatie, backend-aansturing, bronintegraties, cache-database, LLM-backend, antwoordgeneratie en evaluatie.

Belangrijkste onderdelen

API en streaming

De backend is gebouwd met FastAPI. De chatroute werkt met Server-Sent Events, waardoor de gebruiker tijdens het verwerken al voortgang kan zien. De stream kan onder andere events teruggeven zoals ontvangstbevestiging, heartbeat, voortgang, eindantwoord en complete-metadata.

Profielen

De API werkt profielgestuurd. Een profiel bepaalt welke promptlogica, bronselectie en antwoordstrategie wordt gebruikt. Hierdoor kan dezelfde backend meerdere chatbottoepassingen ondersteunen.

Voorbeelden van profielen zijn:

dso: vragen over omgevingsregels, plannen en juridische of beleidsmatige informatie op een specifieke locatie
kaatje: vragen over beschikbare Kadaster-content

Bronintegratie

Voor het DSO-profiel kunnen verschillende bronnen worden gecombineerd, zoals:

PDOK Locatieserver voor locatieverrijking
Toepasbare Regels
DSO Ozon
Ruimtelijke Plannen

De API bepaalt per vraag welke bronroute het meest relevant is en gebruikt fallbackroutes wanneer onvoldoende informatie wordt gevonden.

Cache en retrieval

Opgehaalde documenten worden verwerkt tot chunks en opgeslagen in PostgreSQL. Daarbij worden ook embeddingcontext, embeddings en BM25-velden opgeslagen. Hierdoor kunnen documenten en berekende embeddings opnieuw worden gebruikt.

De retrieval aan database-kant combineert:

vector search met pgvector
exacte lexicale zoekresultaten met BM25
fuzzy matching met trigram similarity
Reciprocal Rank Fusion om de resultaten samen te voegen

Antwoordgeneratie

De API gebruikt meerdere modelrollen:

een groot taalmodel voor vraaganalyse en antwoordgeneratie
een klein taalmodel voor passage-extractie en passage-reranking
een embeddingmodel voor query- en chunkembeddings

Het antwoord wordt gegenereerd op basis van geselecteerde passages. Daarna wordt gecontroleerd of de evidence daadwerkelijk het antwoord onderbouwt. Als het model evidence mist dan kan een extra herstelronde worden uitgevoerd.

Waarom is dit relevant?

De Generieke Chatbot API helpt om chatbotontwikkeling binnen het Kadaster te standaardiseren. Nieuwe toepassingen kunnen sneller worden ontwikkeld doordat generieke onderdelen zoals authenticatie, streaming, retrieval, caching, bronontsluiting, promptbudgettering, logging en evidence-grounding al beschikbaar zijn.

Daarmee ontstaat een schaalbare basis voor meerdere AI-assistenten, met meer controle over brongebruik, kwaliteit, uitlegbaarheid en beheerbaarheid.

Wat levert het op?

Eén generieke backend voor meerdere chatbottoepassingen
Antwoorden op basis van broninformatie in plaats van alleen modelkennis
Hergebruik van documentcache en embeddings
Streaming voortgang richting gebruikers
Evidence bij antwoorden
Betere beheerbaarheid door profielgestuurde configuratie
Mogelijkheid om nieuwe bronroutes en profielen toe te voegen
Logging, metrics en evaluatiemogelijkheden voor doorontwikkeling

Randvoorwaarden en aandachtspunten

De API is bedoeld voor gecontroleerde toepassingen en niet als vrij toegankelijke publieke chatbot. Afgeschermde routes werken met API-key-authenticatie en profieltoegang.

Bij locatiegebonden of juridische vragen blijft zorgvuldigheid belangrijk. De API ondersteunt brongebaseerde beantwoording, maar neemt geen juridische verantwoordelijkheid over van de gebruiker, behandelaar of bronhouder. Als de beschikbare brondocumentatie onvoldoende beslissend is, moet het antwoord terughoudend blijven.

Meer weten?

De Generieke Chatbot API is ontwikkeld als technische basis voor herbruikbare chatbottoepassingen. Meer informatie of eens van gedachten wisselen? Neem contact op via datascience@kadaster.nl.