Vegoia — Gebruikersdocumentatie

Overzicht

Vegoia laat je in gewone taal vragen stellen over de data van jouw organisatie. In plaats van SQL te schrijven, dashboards door te klikken of rapportages op te vragen bij analisten, beschrijf je simpelweg wat je wilt weten.

In tegenstelling tot algemene AI-assistenten vertrouwt Vegoia niet alleen op een taalmodel. Het genereert SQL, voert deze uit op jouw datawarehouse, analyseert de resultaten en legt de conclusies uit. Elk antwoord bevat de redenering, de uitgevoerde SQL en de onderliggende data, waardoor antwoorden transparant en eenvoudig te verifiëren zijn.

Vragen kunnen variëren van een directe retrieval, zoals "Wat was onze gemiddelde leveringsvertraging vorige maand?", tot bredere onderzoeken zoals "Welke klanten lopen het meeste risico, en waarom?" of "Onderzoek waarom de operationele marge dit kwartaal is gedaald." Vegoia kiest automatisch de juiste aanpak. Precieze vragen worden direct beantwoord, terwijl bredere vragen een dieper onderzoek starten langs meerdere mogelijke verklaringen.

Hieronder liggen twee gedeelde kennislagen. Tijdens de onboarding genereert Victa de eerste fysieke laag uit jouw database. Daarna verrijkt jouw organisatie de kennis geleidelijk met concepten en beoordeelde voorstellen naarmate nieuwe bedrijfskennis ontstaat. Zie Kennislagen voor het volledige beeld.

Transparantie: Elk antwoord bevat de redenering, de uitgevoerde SQL en de data waartegen die is uitgevoerd. Antwoorden worden gegenereerd op basis van echte queryresultaten, en als een query niets teruggeeft, vermeldt het antwoord dat. In tegenstelling tot AI-systemen die simpelweg een antwoord produceren, laat Vegoia altijd zien hoe dat antwoord tot stand is gekomen.

Waarom Vegoia anders werkt

Traditionele AI-assistenten proberen bedrijfsbetekenis direct af te leiden uit ruwe databaseschema's, terwijl traditionele BI-systemen vereisen dat analisten elke metriek vooraf definiëren voordat gebruikers vragen kunnen stellen.

Vegoia combineert beide benaderingen. Het begrijpt automatisch de fysieke structuur van jouw data, terwijl het jouw organisatie de mogelijkheid geeft om bedrijfskennis stapsgewijs vast te leggen via concepten. Hierdoor kun je direct met Vegoia aan de slag, terwijl de kwaliteit van de antwoorden continu verbetert.

Kennislagen

Vegoia kan vragen beantwoorden dankzij twee complementaire kennislagen. De fysieke laag beschrijft hoe data is opgeslagen; de conceptlaag beschrijft wat jouw organisatie daarmee bedoelt. Samen vormen ze de basis voor correcte SQL en consistente antwoorden.

Fysieke laag

Gegenereerd door Victa tijdens onboarding, en beschrijft jouw database. Voor elke tabel en kolom slaat het op:

• een beschrijving van wat de tabel/kolom betekent en wat een enkele rij vertegenwoordigt
• een kolomtypeclassificatie: sleutel, categorisch, getal, temporeel of vrije tekst
• voor categorische kolommen, de gecodeerde waarden die automatisch uit de database worden opgehaald, plus hun zakelijke betekenissen — die starten leeg en worden door jouw team ingevuld via de Curation Hub
• waarschuwingen en quirks — waarschuwingen op kolomniveau markeren risico's specifiek voor één kolom; quirks op tabelniveau markeren dingen die elke query tegen een tabel beïnvloeden (bijv. een tabel die actuals en prognoses combineert en altijd een recordtype filter nodig heeft)
• joinhints — tijdens generatie stelt Vegoia automatisch joins voor door kolomnamen te matchen tegen andere tabellen. Deze voorgestelde joins zijn nog niet vertrouwd; een join wordt pas bevestigd zodra je die verifieert via de Curation Hub. Dit is waarom de agent soms een join gokt, en hoe je dat corrigeert als hij het mis heeft.

De betekenissen van enum-waarden invullen is meestal het eerste dat het waard is om te doen in de Curation Hub — bijvoorbeeld Vegoia vertellen dat ORDER_TYPE = YLS een geannuleerde order betekent, of dat NET_INVOICE_VALUE is opgeslagen als tekst met komma decimalen en conversie vereist.

Conceptlaag

De fysieke laag beschrijft de database. De conceptlaag beschrijft jouw organisatie. Veel definities bestaan niet in de database zelf, zoals wat onder omzet, een actieve klant of een geannuleerde order wordt verstaan. Die kennis wordt vastgelegd als herbruikbare concepten.

Ook wel de bedrijfslogicalaag genoemd — de meer concrete naam "concept" wordt vanaf nu gebruikt, maar het is dezelfde laag: opgebouwd en onderhouden door jouw organisatie in de loop van de tijd, start leeg en groeit naarmate jouw team definities toevoegt.

Wat een concept is. Een concept is een benoemde, herbruikbare bedrijfsdefinitie met:

• een korte beschrijving en een langere beschrijving
• een sectie en topic waartoe het behoort (voor organisatie en retrieval)
• een structuur die zijn parameters, filters, grain en formule beschrijft — en welke delen van die structuur vast zijn versus variabel van vraag tot vraag
• een optionele geverifieerde voorbeeldquery (kan leeg zijn als deze nog niet tegen echte data is getoetst)
• zoektermen — de woorden die een gebruiker op een natuurlijke manier zou typen als hij ernaar vraagt, inclusief synoniemen en afkortingen, zodat Vegoia toekomstige vragen er automatisch aan kan koppelen

Concepten hebben één uniforme vorm — er is geen taxonomie van concepttypen meer (metriek, filterregel, afgeleide kolom, enz.). Elk concept wordt op dezelfde manier beschreven.

Wat een concept goed maakt:

• zijn formule of filters zijn geverifieerd tegen echte data — getoetst met daadwerkelijke SQL tegen de fysieke laag — in plaats van gegokt
• zijn beschrijving is precies genoeg dat de agent correcte SQL kan afleiden uit de tekst alleen, zonder je opnieuw te moeten vragen
• zijn zoektermen zijn onderscheidend van de zoektermen van andere concepten, zodat retrieval het ene concept niet met het andere verwart

De Curation Hub hieronder is meestal niet nodig voor gewone gebruikers. Deze is vooral bedoeld voor beheerders die de gedeelde kennislagen onderhouden.

Curation Hub

De Curation Hub vervangt de oude chatcommando's (/sections, /concept, /update, /review), gedocumenteerd in Appendix: oude chatcommando's hieronder ter referentie. Het is een beheerpaneel om de kennislagen te organiseren, corrigeren en opbouwen.

Openen. Stel Vegoia eerst een vraag. Het Curation Hub icoon (een ster) staat in de werkbalk onder het antwoord van de assistent, dus je hebt minstens één antwoord nodig voordat je de hub kunt openen.

De hub is opgedeeld in conceptlaag-tabs (Concepten, Voorstellen, Secties) en fysieke-laag-tabs (Dubbelzinnigheden, Bladeren), plus een gecombineerde Home-werklijst.

Opstellen, verfijnen, opslaan. Elke wijziging volgt dezelfde stappen. Beschrijf wat je wilt, of kies iets om te verfijnen. Vegoia stelt een concept-versie voor. Verfijn deze zo vaak als nodig met extra instructies. Niets wordt opgeslagen totdat je het expliciet opslaat als actief, opslaat als voorstel, toepast, of accepteert/verwerpt. Een concept-banner en een voor/na-diff tonen precies wat er zou veranderen voordat je het bevestigt.

Werken met Vegoia

De meeste organisaties kunnen Vegoia direct na de uitrol gebruiken. Victa genereert tijdens de onboarding de eerste fysieke laag. Daarna stellen gebruikers simpelweg vragen. Wanneer nieuwe bedrijfskennis nodig blijkt, doet Vegoia voorstellen die een beheerder kan beoordelen. Zo groeit de kennis mee met dagelijks gebruik.

API-toegang

Vegoia biedt een OpenAI-compatibele HTTP API. Naast de chatinterface kun je deze ook rechtstreeks aanroepen vanuit scripts, geplande taken of andere tools — handig voor automatisering, proactieve rapportage, of het inbedden van Vegoia in een bredere workflow.

Wanneer gebruik je de API. De chatinterface is het makkelijkst voor interactief verkennen van je data. De API is beter geschikt als je terugkerende vragen wilt automatiseren (bijv. een dagelijkse samenvatting naar een dashboard of Slack), Vegoia-queries wilt uitvoeren vanuit een notebook of pipeline, of tooling wilt bouwen bovenop Vegoia-antwoorden.

Request

Stuur een POST naar /chat/completions. Het schema volgt het OpenAI Chat Completions-formaat met twee extra velden:

{
  "model":           "spot",
  "messages": [
    { "role": "user", "content": "Wat was de totale omzet vorige maand?" }
  ],
  "conversation_id": "sessie-abc",       // optioneel — koppelt verzoeken aan een backendsessie
  "message_id":      "bericht-xyz"       // optioneel — maakt payload-ophaling mogelijk
}

Python-voorbeeld

import requests

BASE_URL = "https://<jouw-vegoia-url>"
API_KEY  = "<jouw-api-sleutel>"

response = requests.post(
    f"{BASE_URL}/chat/completions",
    headers={"Datalk-API-key": API_KEY},
    json={
        "model":      "spot",
        "messages":   [{"role": "user", "content": "Wat was de totale omzet vorige maand?"}],
        "message_id": "bericht-001",    # sla payload op voor ophaling
    }
)

antwoord = response.json()["choices"][0]["message"]["content"]
print(antwoord)

Response

De response volgt het standaard OpenAI-formaat. Het antwoord van de assistent staat in choices[0].message.content. Stuur het volgende bericht met hetzelfde conversation_id om een gesprek met meerdere beurten voort te zetten.

{
  "id":      "chatcmpl-...",
  "object":  "chat.completion",
  "model":   "spot",
  "choices": [{
    "index": 0,
    "message": {
      "role":    "assistant",
      "content": "De totale omzet vorige maand was €4,2M over 11.284 facturen."
    },
    "finish_reason": "stop"
  }]
}

Payload ophalen

Als je een message_id hebt meegegeven, kun je na afronding de volledige redenering en ondersteunende details ophalen:

payload = requests.get(
    f"{BASE_URL}/chat/{message_id}/payload",
    headers={"Datalk-API-key": API_KEY},
).json()

# payload bevat:
# reasoning         — hoe de agent de vraag heeft geïnterpreteerd
# queries_path      — lijst van uitgevoerde SQL-queries
# latency_ms        — totale responstijd in milliseconden
# tokens            — { input, output, total }
# timing            — tijdsverdeling per fase
# matched_concepts  — concepten die de router aan deze vraag heeft gekoppeld

Payloads worden alleen opgeslagen voor definitieve antwoorden. API sleutels worden door Victa apart uitgegeven, los van Open WebUI accounts.

Feedback-gedreven voorstellen indienen

POST /chat/{message_id}/propose bestaat om een conceptvoorstel in te dienen dat is gegenereerd op basis van feedback op een specifiek antwoord. De meeste integraties hoeven dit niet rechtstreeks aan te roepen — het ondersteunt de "voorstellen"-actieknop in Open WebUI — maar is beschikbaar als je jouw eigen feedbackstroom bovenop de API bouwt.

Accounts & API sleutels

Open WebUI accounts

De Vegoia interface draait op Open WebUI. Iedereen die Vegoia gebruikt heeft een eigen account nodig: een combinatie van e-mailadres en wachtwoord.

Accounts niet delen. Sessies in Open WebUI zijn gekoppeld aan een gebruiker. Als twee mensen tegelijkertijd dezelfde login gebruiken, verstoren sessies elkaar en gesprekken mengen onvoorspelbaar.

Nieuwe gebruikers kunnen zichzelf registreren en komen dan in een Pending-status terecht, waarbij ze de front end niet kunnen gebruiken totdat een admin ze promoveert. De eerste gebruiker die inlogt wordt automatisch admin. Zodra het adminaccount van jouw organisatie door Victa is overgedragen, kan jouw eigen on-site admin ook direct gebruikers aanmaken en promoveren — je hoeft niet elk account bij Victa aan te vragen.

API sleutels en databasetoegang

Achter de schermen wordt elke Open WebUI verbinding ondersteund door een API sleutel geconfigureerd door Victa. Deze sleutel definieert:

• Databaseverbinding — welke database Vegoia bevraagt en met welke inloggegevens. Jouw organisatie levert deze inloggegevens en is verantwoordelijk voor welke data er via toegankelijk is.
• Semantisch model — welke fysieke laag en conceptlaag actief is voor deze verbinding. Verschillende API sleutels kunnen verschillende configuraties gebruiken, bijv. per rol of per team.

Het model in Open WebUI is spot. De keuze van denkmodus (retrieval of brainstorm) wordt automatisch door Vegoia bepaald op basis van jouw vraag — je selecteert deze niet zelf.

API sleutel rollen

Elke API sleutel heeft een rol die de toegang tot de Curation Hub bepaalt:

• Viewer (standaard) — kan data bevragen, opgeslagen concepten inzien en de fysieke laag alleen-lezen doorbladeren in de Curation Hub.
• Admin (schrijftoegang) — volledige toegang: concepten opstellen en opslaan, voorstellen beoordelen, secties genereren en de fysieke laag corrigeren.

De rol wordt ingesteld op de API sleutel door Victa. Als je schrijftoegang nodig hebt om concepten en beschrijvingen te beheren, vraag dan aan Victa om jouw sleutel op admin in te stellen.

Aan de slag

1. Maak jouw Open WebUI account aan — registreer jezelf (je start Pending totdat een admin je promoveert) of laat een admin (Victa, of jouw eigen on-site admin na overdracht) het account voor je aanmaken.
2. Log in via de Vegoia URL van jouw organisatie.
3. De databaseverbinding is vooraf geconfigureerd — geen instelling vereist van jouw kant.
4. Selecteer spot en stel jouw eerste vraag.

Data & beveiliging

Gegevensbereik

Vegoia bevraagt alleen de database geconfigureerd voor jouw organisatie. Het heeft geen toegang tot:

• Data van andere organisaties. Elke klant draait in een volledig geïsoleerde omgeving met aparte containers en dedicated infrastructuur. Er is geen gedeelde data tussen organisaties.
• Het internet. Vegoia zoekt niet op internet of haalt geen externe informatie op. Alle antwoorden zijn afgeleid van jouw database, samen met de fysieke laag en de conceptlaag. Vegoia verzint geen ontbrekende informatie; als de benodigde informatie niet beschikbaar is, meldt het antwoord dat.

Verantwoordelijkheid van jouw organisatie

Jouw organisatie bepaalt welke databasereferenties aan Vegoia worden verstrekt, en daarmee welke data bereikbaar is. Datatoegang wordt volledig bepaald door de rechten op die referenties — dit wordt beheerd op databaseniveau, niet binnen Vegoia. Er is geen automatische filtering van gevoelige data: de fysieke laag is een kennislaag, geen toegangsbeheerslaag. De agent werkt vanuit wat hij kent, maar als een gebruiker expliciet een tabel of kolom noemt, kan de agent die alsnog bevragen ook al is deze niet beschreven in het model, zolang de databasereferenties dat toestaan. Als bepaalde data niet toegankelijk moet zijn via Vegoia, beperk dit dan op het niveau van de databaserol.

API-toegangscontrole

Het API endpoint is publiek bereikbaar via internet; de API sleutel is de primaire toegangscontrole. Behandel jouw API sleutel als vertrouwelijk — iedereen die deze bezit kan alles bevragen wat de geconfigureerde databasereferenties van jouw organisatie blootstellen.

Infrastructuur en hosting

Alle componenten draaien binnen de Azure omgeving van Victa. Per klant wordt een aparte resourcegroep ingericht met geïsoleerde containers en toegang via private endpoints. De omgeving is niet publiek toegankelijk buiten de geconfigureerde ingress.

• Gehost in Europa. Alle infrastructuur draait op Microsoft Azure in Europese regio's. Taalmodelverzoeken worden verwerkt via Azure OpenAI gehost in Sweden Central. Data verlaat de Europese regio niet. Het gebruik van een centraal beheerde Vegoia-omgeving voorkomt bovendien dat medewerkers bedrijfsdata uploaden naar publieke AI-tools. Iedereen werkt vanuit dezelfde beheerde databron en gedeelde bedrijfsdefinities.
• Versleuteld in transit. Alle verbindingen tussen componenten maken gebruik van versleutelde kanalen. API sleutels en databasereferenties worden in rust versleuteld met AES-256 en opgeslagen in Azure Key Vault.
• Authenticatie. Toegang tot het beheerplatform (Control Plane) vereist Microsoft authenticatie. Gebruikerstoegang tot de Vegoia interface wordt per account beheerd door Victa beheerders.
• Geen persistente dataopslag. De backend verwerkt data in geheugen en slaat queryresultaten niet op na het afleveren van het antwoord. Als de frontend wordt gebruikt, wordt chatgeschiedenis per gebruiker opgeslagen binnen de Azure omgeving totdat deze wordt verwijderd.

Supporttoegang

Victa houdt een guest-adminaccount aan in de Entra tenant van jouw organisatie voor supporttoegang. Dit account wordt verwijderd bij offboarding — wanneer het Victa-teamlid vertrekt, of de samenwerking eindigt.

Verdeling van verantwoordelijkheden

• Jouw organisatie is verantwoordelijk voor: de beschikbaar gestelde data, toegangsrechten, naleving van toepasselijke wet- en regelgeving en contracten, en de beslissing de frontend in te zetten en chatopslag te accepteren.
• Victa is verantwoordelijk voor: veilige hosting, infrastructuurbeheer, isolatie tussen klanten en operationele logging en monitoring.

Als je toegang nodig hebt tot een nieuwe dataset of schema, neem dan contact op met Victa om deze toe te voegen aan het semantisch model.

Appendix: oude chatcommando's (verwijderd)

Deze commando's werken niet meer. Ze staan hier ter referentie; gebruik in plaats daarvan de Curation Hub.

Vier commando's waarmee je vroeger de kennislagen direct vanuit de chat kon organiseren, bijwerken en opbouwen. Commando's omzeilden de normale vraagpipeline volledig en gingen direct naar de laagbewerkingsstroom.

Hoe je deze vroeger gebruikte, in volgorde:

1. Voer eenmalig /sections generate uit, voordat je concepten aanmaakte. Secties moesten eerst bestaan.
2. Maak concepten aan met /concept en corrigeer de fysieke laag met /update, in beide volgorden, zo vaak als nodig.
3. Gebruik /review periodiek om te zien wat er nog moest worden ingevuld.

/sections — admin, behalve show

Organiseerde concepten in benoemde secties (bijv. "Verkoopprestaties", "Financiële planning") zodat de conceptbibliotheek leesbaar bleef naarmate deze groeide, en zodat retrieval kon bepalen welke concepten relevant waren voordat ze werden ingelezen.

/concept — admin, behalve all en <tag>

Stelde concepten (bedrijfsdefinities) voor, inspecteerde en beheerde ze in de conceptlaag.

Voorstellen uit feedback. Wanneer feedback van een gebruiker op een antwoord een nieuw of gewijzigd concept suggereerde, zette Vegoia dit klaar als een voorstel in plaats van rechtstreeks een /concept aanroep te doen:

Analyse. /concept analyze (admin) toonde feedbackstatistieken voor alle concepten, zodat je kon zien welke goed of slecht presteerden.

/update — admin, behalve show

Stelde correcties voor op hoe jouw data in de fysieke laag was beschreven. Wijzigingen werden geschreven naar een sandbox kopie — niets werd toegepast totdat je bevestigde.

/review — alle rollen

Toonde kolommen in de fysieke laag die nog aandacht nodig hadden.