Je AI-medewerker bouwen
Kennisbronnen
Bronnen zijn de manier waarop een agent meer te weten komt over je bedrijf. Op deze pagina vind je informatie over alle soorten bronnen, de invoerpijplijn en wat je kunt verwachten nadat je op 'Toevoegen' hebt geklikt. Als verschillende delen van je site verschillende eerste antwoorden verdienen, groepeer bronnen dan in Smart Segments — het systeem geeft dan de voorkeur aan het segment dat overeenkomt met de pagina waarop de bezoeker zich bevindt.
De pagina ‘Bronnen’ is de eerste pagina van het tabblad Kennis van een AI-medewerker. Bronnen die niet konden worden gelezen, worden als eerste weergegeven, met de reden en een knop Opnieuw proberen ; de kop geeft aan wat er wel en niet is gelezen. De schakelaar ‘Leer welke pagina’s bezoekers openen ’ (zie Bezochte pagina’s automatisch indexeren ) staat bovenaan dezelfde pagina.
Je documenten scoren hoger dan je website
Er zijn twee soorten kennis die de assistent bereikt: samengestelde bronnen die je zelf maakt en bijhoudt (geplakte tekst, Google Docs en Sheets, Notion-pagina’s, geüploade bestanden, SQL), en webpagina’s die van je eigen site zijn gecrawld. Ze zijn niet gelijkwaardig. Een productpagina is verkooptekst waarin toevallig feiten worden genoemd; een bijgehouden document is een bewuste feitelijke verklaring.
Dus samengestelde bronnen winnen nipt in de rangschikking, elke bron wordt
in de prompt gelabeld met zijn oorsprong, en als de twee het oneens zijn — over
eigenschappen van een product, een getal, een waarde voor een bepaalde plaats of een ander
feit — krijgt de assistent de opdracht de gecureerde bron te volgen en nooit
formuleringen van de website over te nemen om een mogelijkheid te claimen die je documenten niet
vermelden. Een cijfer dat een bron vermeldt, wordt letterlijk geciteerd en nooit
opnieuw berekend door de assistent. Als er een meningsverschil opduikt in een chat, corrigeer dan de
kant die het bij het verkeerde eind heeft: de assistent kan de meer gezaghebbende
bron volgen, maar kan je niet vertellen welke verouderd is. De verbetering van de rangschikking
geldt voor elke AI-medewerker, met of zonder Smart Segments
(voorheen kregen alleen agenten zonder segmenten deze verbetering). Dit is
voorrang, geen uitsluiting — gecrawlde pagina’s bevatten nog steeds
prijzen, voorraadinformatie en links, en beantwoorden nog steeds alles wat je
documenten niet behandelen. Pas de sterkte aan met
RAG_CURATED_BOOST
(standaard 0.10
); stel het in op
0
om elke bron even zwaar te laten wegen.
Eén pagina, één stem.
Dezelfde pagina kan uiteindelijk
twee keer worden geïndexeerd — bijvoorbeeld één keer via een sitemap als /meppel/
en één keer
via automatische indexering door bezoekers
als /meppel
. Als beide
kopieën overeenkomen met een vraag, wordt alleen de kopie met de beste overeenkomst gebruikt, dus
kan een pagina niet twee antwoordplaatsen innemen en het ene document dat
het er niet mee eens is, overstemmen. Je eigen documenten worden nooit als een kopie behandeld, zelfs
niet als een geplakte tekst de URL van de pagina als bron vermeldt.
Als je website zichzelf tegenspreekt
Elke nacht worden de pagina’s van je AI-medewerker gecontroleerd op plekken waar je website twee verschillende dingen zegt, en je ziet ze op de startpagina (Vereist je aandacht ) en bovenaan de Bronnen-pagina van de agent:
- Gratis verzending — twee of meer verschillende bedragen, bijvoorbeeld "Gratis verzending vanaf € 75,-" op de meeste pagina’s en "Vanaf € 50,- betaal je geen verzendkosten" op de startpagina. Een apart bedrag voor een ander land (België, Duitsland…) is een beleid, geen tegenstrijdigheid, en wordt buiten beschouwing gelaten.
- Voorraad — een product waarvan op de eigen pagina staat dat het op voorraad is, terwijl op een categorie- of tagpagina ‘Niet op voorraad’ naast de naam staat, of andersom.
- Openingstijden — 24 uur per dag toegankelijk ("24/7 toegankelijk") op sommige pagina’s en een dagelijks tijdsvenster ("De toegangstijden zijn van 06:00 tot 23:00") op andere. Alleen zinnen over toegang of openingstijden tellen mee: een ‘24/7 AI-medewerker’ of camera’s die ‘24 uur per dag’ in de gaten houden, vallen niet onder openingstijden.
- Levertijd — dezelfde levering die op verschillende manieren wordt beloofd („binnen 1-2 werkdagen“ en „binnen 3 werkdagen“). Een ander land, terugbetalingen, antwoorden, retourzendingen, installatie, je voorwaarden, privacy- en cookiepagina’s (wettelijke termijnen zoals „binnen 30 dagen”) en alles wat langer duurt dan twee weken wordt buiten beschouwing gelaten; „2 dagen” en „2 werkdagen” tellen als dezelfde belofte.
Je AI-medewerker houdt al de productpagina’s en je beleidspagina’s bij, en haalt nooit informatie uit een categoriepagina — maar bezoekers lezen ze allemaal. Totdat je een van de andere punten aanpast: als er een vraag over komt, geeft je AI-medewerker de meer specifieke waarde — het dagelijkse tijdvenster, de levertijd op je beleidspagina, het bedrag voor gratis verzending dat op de meeste van je pagina’s staat — en zegt hij dat het kan variëren, in plaats van willekeurig iets te kiezen. Pas ze aan op je website; zodra een pagina niet langer beide dingen vermeldt, verdwijnt het item na de controle van de volgende nacht.
Je productcatalogus
Elke productpagina die je AI-medewerker leest, wordt onderdeel van een productcatalogus : maten, materialen, kleuren met hun voorraad, en de prijs, als velden in plaats van zinnen ergens op een pagina. Deze wordt opgebouwd uit de productgegevens die je winkel publiceert voor zoekmachines (de naam, prijs en voorraad van Schema.org Product), plus de maattabel en de samenstelling die op de pagina staat — een samenstelling telt alleen mee als de percentages samen 100% opleveren, dus ‘5% korting’ wordt nooit een materiaal, en als een pagina twee verschillende samenstellingen vermeldt neemt de catalogus degene die het vaakst wordt genoemd, of geen enkele als het niet kan bepalen welke (het loont de moeite om dit op je site aan te passen: bezoekers zien beide). Een lijst na een label zoals Materiaal: , met of zonder uitleg per onderdeel („38% katoen: zorgt voor zachtheid…“), die in totaal 60–97% bedraagt, wordt gebruikt zoals de pagina het vermeldt en wordt de aangegeven samenstelling op de Productpagina gemarkeerd als niet-op-100% uitkomend , in plaats van leeg gelaten. Apparaten krijgen twee extra velden als dat op hun pagina’s staat vermeld: aantal personen („4 tot 8 personen“, „8+ people“, uit de productnaam of een „geschikt voor“-zin) en garantie („10 jaar garantie“); beide vullen de antwoorden aan met de andere productgegevens. Kleurvarianten worden één product: STAPP Atlas Marine Sokken en STAPP Atlas Raf Sokken zijn STAPP Atlas Sokken in Marine (op voorraad) en Raf (uitverkocht). Een prijs wordt alleen vermeld als elke kleur evenveel kost. Een versie met een eigen naam blijft een apart product met een eigen prijs, ook als die naam een streepje bevat: Bouwkruiwagen staal 85 L — soft wiel (€ 162,50) is niet hetzelfde als Bouwkruiwagen staal 85 L (€ 152,50) .
Als een bezoeker een product noemt, of een pagina die voor het antwoord wordt gebruikt, dan wordt de catalogusregel van dat product bij het antwoord meegeleverd. „Waar is de Walking van gemaakt?” en „Heb je de Thermo Super in het zwart?” worden beantwoord vanuit de velden, zelfs als geen enkele pagina op zichzelf goed genoeg bij de vraag paste . Wat de catalogus zegt, is de maatstaf — die gaat boven categorie- en tagpagina’s — maar het is geen volledig overzicht: een eigenschap die er niet in staat, kan nog steeds worden beantwoord via de productpagina. Voordat een antwoord wordt verzonden, worden de productgegevens daarin vergeleken met de catalogus en gecorrigeerd als ze daarmee in tegenspraak zijn (zie Controleer de gegevens voordat je het verstuurt ).
Veel productpagina’s geven specificaties weer in een tabel — frame, wiel, band, gewicht. Je AI-medewerker kan ook vanuit die rijen antwoorden: de specificaties van elk product staan dan naast de prijs in de feiten waaruit hij antwoordt, zodat hij nooit het frame van een aangrenzend product overneemt. De rijen waar elke versie van een product het over eens is, worden gebruikt, zolang ze naast de prijs passen. Dit wordt per AI-medewerker ingeschakeld — vraag het ons maar; onder ‘Kennis › Producten’ zie je dan de specificaties van elk product. Het lezen ervan verandert nooit hoe je pagina’s worden doorzocht.
Als je een productregister bijhoudt (een document waarin elk
product met zijn maten en materialen staat vermeld), heeft het register voorrang voor elk
product dat erin staat en vult de catalogus de rest aan; alleen het register
telt als je volledige productlijst. De catalogus wordt tien minuten
na een wijziging op een productpagina opnieuw opgebouwd en elke nacht om 07:20, na de
hercrawls. Beheerders kunnen hem handmatig opnieuw opbouwen met
php artisan knowledge:build-catalog --agent=<id>; voeg
--dry-run toe om de producten te bekijken zonder ze op te slaan.
Bekijk en corrigeer je producten
Kennis › Producten (weergegeven voor winkels) toont elk product waar je AI-medewerker op reageert, precies zoals hij ze gebruikt: de producten uit je kassasysteem staan gemarkeerd als ‘Uit je productregister’ , de rest als ‘Uit je productpagina’s ’. Een product krijgt de markering ‘Controleer dit’ als de pagina’s ervan onduidelijk de catalogus verlaten — geen materiaal, twee verschillende samenstellingen (dan gebruikt het de meest genoemde), of geen maten — en ‘Moet worden gecontroleerd’ toont alleen die producten. Een ontbrekende materiaal- of matenlijst telt alleen mee als minstens de helft van je producten er een heeft, dus een winkel die nooit materialen vermeldt, wordt er niet naar gevraagd. Als een product gecontroleerd moet worden, geeft de startpagina dat aan onder ‘Vereist je aandacht’ , met een knop naar de gefilterde lijst.
Druk op Correct it naast een veld van een product op je
pagina’s en vul de juiste waarde in: de maten als bereik van laag naar hoog
(39-42, 43-46), het materiaal, de kleuren met elk hun
voorraad, de voorraad, of één prijs (12,95 — de valuta die je
pagina’s aangaven, blijft behouden). Je AI-medewerker past de correctie meteen toe,
in zijn antwoorden en bij het controleren van claims, en behoudt deze wanneer de catalogus
opnieuw wordt opgebouwd op basis van je pagina’s: per product en veld wordt een correctie opgeslagen
en bij elke heropbouw toegepast. Onder een gecorrigeerd veld zie je wat er op je
productpagina’s staat; als je de pagina’s opnieuw gebruikt, wordt je
correctie ongedaan gemaakt. Een product uit je register wordt in het register
zelf aangepast. Iedereen in de werkruimte kan de pagina openen; voor het corrigeren heb je
de bewerkingsrechten voor de AI-medewerker nodig.
Hoeveel het weet
Eén getal, overal hetzelfde: de pagina’s en bestanden die je AI-medewerker heeft gelezen. Op de startpagina staat “Kent 111 pagina’s. Uit 2 bronnen.”, de pagina ‘Kennis’ toont hetzelfde getal 111 naast het aantal passages — de stukken die hij doorzoekt als een bezoeker een vraag stelt — en elke bron op de pagina ‘Bronnen’ laat zien hoeveel van die pagina’s hij heeft binnengehaald. Een bron geeft geen ‘van’-totaal weer: wat daar vroeger stond, was de paginalimiet van de crawler, niet de grootte van je sitemap.
Bronsoorten
| Type | Gebruik het voor | Wat we opnemen |
|---|---|---|
url | Eén specifieke pagina — of, met Crawl ook de pagina’s waarnaar deze pagina linkt, een hubpagina en de bijbehorende sectie | Crawlen + hoofdinhoud extraheren + in stukken verdelen + insluiten; met ‘links volgen’ aan, zoek eerst naar links binnen dezelfde sectie (diepte 1–2) en crawl ze allemaal |
sitemap | Een hele site in één keer | Lees de sitemap, ga per URL naar één CrawlPageJob |
feed | RSS-/Atom-blogs | Hetzelfde als de sitemap, maar leest <item>-vermeldingen |
text | FAQ’s, fragmenten, alles wat je kunt plakken | Sla het crawlen over, verdeel in stukjes en embed direct |
notion | Notion-pagina’s | OAuth in Notion, ophalen via API, behandel elke pagina als een document |
google_doc | Google Docs (Workspace) | OAuth, ophalen via de Drive-API, importeren als document |
google_sheet | Tabbladen in Google Sheets | OAuth, haal elke niet-lege rij op, één documenttekst met Row N: …-markeringen |
sql | Externe MySQL / PostgreSQL | Directe PDO SELECT (alleen-lezen); één document met Row N: …-markeringen. Inloggegevens worden in rust versleuteld met de app-sleutel (AES-256-CBC). |
file | PDF / DOCX / XLSX-uploads | Geparseerd via Cloudflare toMarkdown (gratis niveau), in stukjes verdeeld + ingesloten |
woocommerce_products | WP / WooCommerce-winkels | Gesynchroniseerd via de bijbehorende WordPress-plugin |
auto | Pagina’s waar bezoekers terechtkomen | Automatisch in de wachtrij geplaatst door AutoIndexPageVisit vanuit /v1/widget/init |
Met een wachtwoord beveiligde websites
Een site achter een inlogscherm (HTTP basic auth, zoals de staging-site van een bureau) kun je nog steeds bekijken: ga naar Kennis › Webpagina en klik op ‘Deze site vraagt om een gebruikersnaam en wachtwoord’ en vul die in; in de broncode van een bestaande pagina vind je dezelfde velden onder Crawl-opties (een nieuwe gebruikersnaam met een leeg wachtwoord behoudt het opgeslagen wachtwoord, of verwijder de inloggegevens daar). De inloggegevens worden versleuteld opgeslagen, nooit meer getoond en alleen naar de eigen host van die site verzonden: een omleiding naar een andere host draagt ze nooit mee, en zo’n site wordt alleen via gewone HTTP gelezen (een browser zou op een inlogverzoek van elke host op de pagina reageren), dus de pagina’s mogen geen JavaScript nodig hebben om hun tekst weer te geven. Een robots.txt achter de inlogtijd telt als afwezig.
Houd een gedeelte buiten de kennisbank
Sommige delen van een pagina zijn geen kennis: een nep-chat in de hero, voorbeeldgegevens,
een carrousel met voorbeeldklanten. Markeer zo’n element met
het data-nosnippet-attribuut van Google, of met
data-ai-ignore, en het wordt weggelaten, samen met alles wat erin
staat, overal waar een pagina als tekst wordt verwerkt: de crawl (gewone HTTP en de browser-
lagen), de pagina’s die worden geïndexeerd op basis van bezoekers, en de paginacontext die de widget
meestuurt bij een vraag.
<section class="hero" data-nosnippet>
<!-- a mock chat or sample data -->
</section>
Klik vervolgens op Reindex in de paginabron, zodat de tekst die al is gelezen, wordt vervangen. Er verandert niets voor pagina’s zonder het attribuut.
Een bron met geplakte tekst bewerken
Bronnen met geplakte tekst (text
) kun je direct ter plekke bewerken — je
hoeft ze niet te verwijderen en opnieuw aan te maken. De hoofdtekst wordt bij het toevoegen opgeslagen op de
config
van de bron, dus de knop 'Bewerken'
(potlood) op een tekstrij opent het formulier opnieuw, vooraf ingevuld met de
huidige titel, bron-URL en inhoud. Opslaan voert
IndexTextSourceJob
opnieuw uit, waardoor de
oude geïndexeerde inhoud wordt vervangen
: het vorige document en de bijbehorende vectorfragmenten worden
verwijderd voordat de nieuwe tekst wordt ingebed, zodat verouderde antwoorden nooit
naast de bewerking blijven staan.
Oudere tekstbronnen die zijn aangemaakt voordat deze functie werd uitgebracht, hebben geen opgeslagen hoofdtekst, dus hun bewerkingsformulier opent met een leeg inhoudsveld — plak de bijgewerkte inhoud één keer en deze blijft vanaf dat moment bewaard.
Als je opnieuw indexeert
op een rij met geplakte tekst, wordt de
opgeslagen
hoofdtekst opnieuw ingebed — er wordt niets externs opgehaald (er is geen
externe bron), maar omdat de hoofdtekst is opgeslagen, wordt een
tekstbron die door een eerdere bug was achtergelaten failed
volledig hersteld. Om de inhoud
te wijzigen
, gebruik je in plaats daarvan Bewerken
; een tekstbron
bron zonder opgeslagen hoofdtekst (een oudere versie) vraagt je om deze te bewerken of opnieuw toe te voegen
in plaats van niets te doen.
"Wat de AI ziet" is een voorbeeld, niet de volledige tekst
De grijze tekst onder elke bron — en de lijst met fragmenten in het paneel Wat de AI ziet — is een voorbeeld , beperkt tot weergave alleen. De ingeklapte tekst toont de eerste ~600 tekens van het eerste fragment; het uitgeklapte paneel toont maximaal 20 fragmenten, elk ingekort tot 4.000 tekens. Dit is puur een weergavebeperking: de volledige bron is opgeslagen, in fragmenten verdeeld en ingesloten. Als een geplakt document eruitziet alsof het halverwege ‘stopt’ (bijv. midden in een lijst), is dat de grens van het voorbeeld, geen verloren inhoud — de rest staat in de latere chunks en kan volledig worden beantwoord.
Harde limieten die wel gelden: een bron met geplakte tekst is beperkt tot 200.000 tekens bij het indienen — plak je meer dan dat, dan wijst het formulier het af met een foutmelding (het wordt nooit stilletjes afgekapt). Door het opsplitsen in stukken ontstaat er een overlap aan het einde tussen aangrenzende stukken, dus feiten die over een stukgrens heen lopen, blijven bij het ophalen behouden. Gebruik het tekenaantal per stuk in het paneel om de volledige lengte van een stuk te controleren; er verschijnt een opmerking ‘+N tekens meer’ als een stuk langer is dan het voorbeeld op het scherm.
Spreadsheets: één rij, één chunk
Een tabel die te groot is voor één chunk — een geüpload Excel- of OpenDocument-blad, of een Google Sheet — wordt geïndexeerd met één rij per chunk. Elke rij-chunk begint met de bestandsnaam en het blad (Waterhardheid Nederland (2) — Blad1) en zet de rij volledig uit met de kolomnamen (postcode_4: 7955; plaatsnaam: IJhorst; waterbedrijf: WMD; hardheid_gem: 8,1; categorie: Gemiddeld); lege cellen worden weggelaten. Een vraag over één rij („wat is de waterhardheid in IJhorst?”) vindt dan precies die rij. Vroeger werd een grote tabel op basis van de grootte opgesplitst in stukken van zo’n 28 rijen zonder kolomnamen, en een enkele plek in een werkblad met 4.000 rijen werd praktisch nooit gevonden. Kleine tabellen binnen een pagina of document blijven bij hun tekst staan. Een werkblad met meer dan 5.000 rijen verdeelt een paar aangrenzende rijen over elke stuk, zodat één bestand nooit uit meer dan 5.000 stukken bestaat. Een werkblad dat vóór deze wijziging is geïndexeerd, moet één keer opnieuw worden geïndexeerd.
Codes en postcodes worden exact opgezocht
Een kaal getal zegt bijna niets voor de zoekfunctie die bronnen op betekenis vindt: een bezoeker die alleen zijn postcode, 7955, intypte, kreeg vroeger geen antwoord, ook al stond de rij postcode_4: 7955; plaatsnaam: IJhorst in het geüploade werkblad. Dus als een bericht een code bevat — vier of meer tekens met een cijfer, zoals een postcode, een artikelnummer of X-200 — wordt die code ook letterlijk opgezocht in je eigen documenten (geüploade bestanden, werkbladen, geplakte tekst, SQL, Notion, Google Docs; nooit in gecrawlde pagina’s). Een volledige Nederlandse postcode zoals 7955AB vindt ook een werkblad dat is geïndexeerd op 7955. Alleen de volledige code telt (7955 komt nooit overeen met 17955), en een getal dat op meer dan drie plaatsen voorkomt — een jaartal, 1000 liter — wordt niet als code behandeld. Bij een overeenkomst worden de bronnen voor dat antwoord weergegeven, ongeacht onder welk segment het is opgeslagen.
Cijfers worden exact overgenomen
Bij elk antwoord (niet alleen in de Strikte modus) krijgt de assistent de opdracht om elk getal uit je bronnen precies zo weer te geven als het geschreven staat — prijzen, plannamen en quotumgetallen behouden elk cijfer en elke scheidingsteken voor duizendtallen. Een klein model dat de vrijheid krijgt om te parafraseren, verandert „3.000 gesprekken / maand“ graag in „3 gesprekken“, wat niet alleen de bewoording maar ook de betekenis verandert. De prompt legt de exacte vorm vast, zodat het getal dat een bezoeker leest overeenkomt met het getal op jouw pagina. Een prijs wordt weergegeven met elk bedrag dat je bron ervoor vermeldt, inclusief eenmalige installatie- of opstartkosten (“€499/maand + €499 installatie”): als dit wordt weggelaten, wordt de prijs weergegeven als “installatie inbegrepen”.
Bij Cloudflare Workers AI had een ontbrekend getal in de duizenden nog een tweede oorzaak naast het model: de OpenAI-compatibele stream stuurt een waarde zoals „3.000“ als het cijfer 3, dus een Nederlands „3.000 conversaties” kwam aan als “3 conversaties”. Antwoorden komen nu via het eigen eindpunt van Cloudflare, dat de tekst behoudt zoals die is geschreven .
SQL-database als bron (MySQL + PostgreSQL)
Sluit een alleen-lezen MySQL- of PostgreSQL-database rechtstreeks aan als kennisbron
. Elke niet-lege rij die je SELECT-query oplevert, wordt onderdeel van de
trainingsdata van de agent, met citaten die de LLM kan gebruiken als Row N
referenties.
Stappen voor het instellen:
- Open
/app/agents/{id}/sourcesen scroll naar SQL-database toevoegen. - Kies de driver (MySQL of PostgreSQL) — de poort wordt automatisch ingevuld met
3306of5432. - Plak de host, databasenaam, gebruikersnaam en wachtwoord.
- Plak een
SELECT-query — elke rij die wordt geretourneerd, wordt onderdeel van de kennisbank van de agent. - Optionele kolomtoewijzing: kies een title_column (wordt gebruikt als rijlabel) en een body_column (wordt gebruikt als rijinhoud). Als je dit weglaat, worden alle kolommen samengevoegd als
colname: value-paren. - Klik op Verbinden & synchroniseren. De eerste
SyncSqlSourceJobwordt uitgevoerd op decrawl-wachtrij, indexeert de rijen en schakelt de bron over naarindexed.
Strikte regels die bij elke query worden toegepast:
- SSRF-beveiliging. De host wordt gecontroleerd via
UrlSafetyGuard::assertSafe()— dezelfde allowlist die de crawler gebruikt.127.0.0.1, RFC1918-bereiken, link-local169.254.0.0/16(AWS-metadata-IP) en elke naam die naar een privé-IP verwijst, worden allemaal geweigerd. De bron wordt omgezet naarfailedmet de melding: "Onveilige SQL-host: weigering om een interne / loopback / link-local host te crawlen." - Alleen SELECT. De query moet beginnen met
SELECT(hoofdlettergevoelig). Queries met meerdere instructies (die;bevatten) worden afgewezen. De trefwoordenINSERT,UPDATE,DELETE,DROP,ALTER,TRUNCATE,GRANT,REVOKE,CREATE,REPLACE,CALL,EXEC,EXECUTE,MERGE,LOADen - Alleen-lezen-transactie. De connector verpakt de query in
START TRANSACTION READ ONLY(MySQL) /BEGIN TRANSACTION READ ONLY(PostgreSQL), zodat zelfs een vrij toegankelijke query-string de status niet kan wijzigen. - Maximaal 5.000 rijen per synchronisatie. Beschermt het werkgeheugen en de Document-tabel tegen uit de hand gelopen query’s. Beperk je
SELECTmet eenLIMITals je een grote tabel hebt die je niet volledig geïndexeerd wilt hebben. - Time-out van 10 seconden voor verbindingen. Hosts die niet bereikbaar zijn, worden snel afgewezen — kopers zien de foutmelding direct in de pagina.
Inloggegevens in rust:
Wat wordt geïndexeerd:
Elke rij wordt een gelabelde regel in één documentlichaam. Als je
title_column = "title"
en body_column = "body"
instelt,
wordt een rij met { title: "Welcome", body: "Hello world" }
weergegeven als:
Welcome: Hello world
Zonder kolom in de documentbody valt het terug op een sleutel/waarde-koppeling van elke niet-null-kolom:
Row 1 — id: 42, name: ACME Corp, plan: Pro, last_seen: 2026-05-13
De documenttekst wordt vervolgens in stukken verdeeld en ingebed via dezelfde
IndexDocumentJob
-pijplijn die alle andere bronnen gebruiken, zodat
SQL-rijen bij het ophalen net zo te zien zijn als gecrawlde pagina’s of geplakte tekst.
Opnieuw synchroniseren: met de knop Reindex
van de bron, en één keer per week via pitchbar:refresh-stale-sources
(dagelijks om 03:30 uur, voor bronnen die meer dan 7 dagen geleden voor het laatst zijn gesynchroniseerd; dit volgt
hetzelfde pad als ‘Reindex’). (Notion-, Google Doc- en Google Sheet-bronnen
zijn anders: pitchbar:sync-oauth-sources synchroniseert ze
elk uur opnieuw.)
Pagina’s die geen kennis zijn: behalve
winkelwagen-, afreken-, inlog- en accountpagina’s worden bedankpagina’s (bedankt,
thank-you, danke, merci, order-received), testpagina’s en voorbeeldpagina’s van thema’s
(test, sample-page, hello-world, staging) overgeslagen en,
bij de volgende crawl, verwijderd. Een pagina die zoekmachines vraagt om
deze niet te indexeren (<meta name="robots" content="noindex">) of die
een andere pagina op dezelfde site als origineel
aangeeft (rel=canonical) wordt ook genegeerd, tenzij het precies het
adres is dat je als bron hebt toegevoegd. Een canonical-tag naar de startpagina wordt genegeerd,
omdat sommige sites elke pagina daarheen verwijzen. Als je site een map per
taal heeft (/en/, /de/), zorgt een vraag die in
het Nederlands is beantwoord ervoor dat de pagina’s uit andere taalmappen buiten beschouwing blijven, zolang er Nederlandse
pagina’s of pagina’s zonder taalmap zijn gevonden.
Tekst die op meerdere pagina’s terugkomt:
een
zin die op 30% of meer van je pagina’s terugkomt — een standaard
uitleg, "Bel naar … of mail naar …", een beoordelingsformulier, maatadvies — wordt
slechts op één pagina behouden (die met het kortste adres, meestal je
startpagina of contactpagina) en bij de indexering weggelaten van de andere pagina’s, zodat
de eigen inhoud van elke pagina het antwoord vormt. Pagina’s die hiervoor waren geïndexeerd, werden
opgeschoond met php artisan knowledge:strip-boilerplate
(--agent=
, --dry-run
).
Elke pagina, niet alleen elke bron: bij het
opnieuw crawlen van een bron worden de gevonden pagina’s opnieuw gelezen, dus een pagina die uit de sitemap is verdwenen,
de crawl-limiet heeft overschreden of tijdens een bezoek is ontdekt, kan wekenlang een oude kopie
behouden. pitchbar:recheck-stale-pages (dagelijks om 04:45) controleert opnieuw
elke gecrawlde pagina die al 7 dagen niet is gecontroleerd, en product- en prijspagina’s
(prijzen, tarieven, aanbiedingen, acties in het adres) na 1 dag, maximaal 400
pagina’s per run, met een tussenpoos van twee seconden. Een pagina die een 404- of 410-foutmelding geeft, of doorverwijst
naar een ander adres, blijft in de database staan met de stukjes informatie die erover zijn; een doorverwijzing naar
hetzelfde adres (https, www, een slash aan het einde) telt niet mee. Elke andere pagina
wordt op de normale manier opnieuw gelezen, waardoor een gewijzigde kopie wordt vernieuwd of als
gecontroleerd wordt gemarkeerd. Een site die niet bereikbaar is, wordt de volgende dag opnieuw geprobeerd.
Wat de wekelijkse verversing per bron doet: webpagina’s, sitemaps en feeds worden opnieuw gecrawld; pagina’s die via bezoekers zijn geleerd, worden pagina voor pagina opnieuw gecrawld; SQL-bronnen worden opnieuw gesynchroniseerd. Geplakte tekst en geüploade bestanden worden met rust gelaten — niets buiten het dashboard kan ze wijzigen.
Paginatypes
. Elke gecrawlde pagina wordt gemarkeerd als
een product
-pagina (deze bevat de eigen productgegevens van de winkel), een
listing
(een overzicht van tags, categorieën, collecties of merken) of
een policy
-pagina (verzending, retouren, veelgestelde vragen, voorwaarden, privacy, maattabel,
betaling, levering, garantie); andere pagina’s hebben geen type. Een lijstpagina
toont terloops veel producten, met voorraadindicatoren die een winkel niet altijd
actueel houdt, dus verliest deze een bijna-gelijkspel met de eigen productpagina bij
het ophalen, en de assistent krijgt te horen dat een overzichtspagina nooit bepalend is voor de
voorraad, prijs, kleuren of maten van een product als de eigen pagina van dat product
tot de bronnen behoort. De voorraadindicatoren van een lijstpagina (op voorraad
,
niet op voorraad
, uitverkocht
, out of stock
…)
worden verwijderd voordat de assistent ze leest, omdat winkels ze zelden
bijhouden; hij haalt de voorraad alleen van de eigen productpagina.
Er worden maximaal twee vermeldingen gebruikt voor één antwoord: de tagpagina’s van een winkel herhalen vaak hetzelfde maatfilter en productraster
, en zonder limiet zouden ze alle bronplaatsen innemen, waardoor geen enkele productpagina
pagina in het antwoord terechtkwam. Vermeldingen na de eerste twee maken plaats voor het
volgende product of een andere pagina die goed genoeg overeenkomt, en worden alleen gebruikt
als er niets anders is. De pagina waarop de bezoeker zich bevindt, telt nooit mee voor
die twee. Een vraag over maten — een vraag waarin een maat wordt genoemd (maat 47
,
mt 45
, size 42
) of waarin naar maten wordt gevraagd — haalt ook je
maattabel (een pagina op een adres zoals /maattabel
,
/size-guide
of /size-chart
) naar voren, net zoals een vraag over verzending
je verzendpagina naar voren haalt; je andere beleidspagina’s
worden hiervoor niet meegenomen. Als de zoekopdracht de maattabel helemaal niet naar voren bracht
— veel tagpagina’s die je maatfilter herhalen, kunnen deze naar beneden duwen —
wordt het deel van de maattabel dat het beste bij de vraag past (de maat die de
bezoeker noemde telt het zwaarst mee) toegevoegd als één extra bron. Het verhoogt nooit
de betrouwbaarheid van het antwoord, en er wordt niets toegevoegd als de zoekopdracht
niets heeft gevonden. Een vraag die haastig is getypt — "sokn vor wrk in de kou
mt 45"
— wordt gecorrigeerd op basis van woorden uit je eigen pagina’s als de zoekopdracht
niets vindt: een woord dat je pagina’s nooit gebruiken, wordt het meest voorkomende
woord op je pagina’s waar het in kan veranderen door maximaal drie letters toe te voegen
(sokn → sokken, vor → voor, wrk → werk
), en de zoekopdracht wordt nog een keer
uitgevoerd. Woorden waarvoor zo’n overeenkomst ontbreekt, begroetingen en korte woorden zoals
mt
blijven zoals je ze hebt getypt; een zoekopdracht die wel iets heeft gevonden, wordt nooit
aangepast. De conversatiedebugger toont de gecorrigeerde tekst. Een sitemap-bron
slaat ook account-, winkelwagen-, afreken-,
verlanglijst- (inclusief het
Nederlandse wenslijst
) en zoekpagina’s over, net zoals
door bezoekers aangeleerde pagina’s en gevolgde links dat al deden, en verwijdert dergelijke
pagina’s die eerder geïndexeerd waren. Documenten die hiervoor geïndexeerd waren, kregen hun type
van php artisan knowledge:classify-pages
.
Nu registreert elke gecrawlde pagina ook wanneer deze voor het laatst is
gecontroleerd
(documents.checked_at
), naast wanneer de
inhoud voor het laatst is gewijzigd
(fetched_at
): een ongewijzigde
pagina die deze week is bevestigd, ziet er niet langer weken oud uit. Een ongewijzigde pagina
waarvan de geïndexeerde tekst ontbrak (een mislukte of verloren indexrun) wordt
bij die controle opnieuw geïndexeerd. En bij het vernieuwen van een sitemap of het volgen van links worden ook
de eerder geïndexeerde pagina’s die niet meer in de lijst staan opnieuw gecontroleerd (maximaal
200 per run): er wordt niets verwijderd omdat het niet in een sitemap staat — een
pagina die nu een 404- of 410-foutmelding geeft, wordt verwijderd volgens de gebruikelijke regel voor verdwenen pagina’s
, en een pagina die nog steeds bestaat, wordt gewoon bevestigd.
Drivers die nog niet zijn meegeleverd: MSSQL en Oracle. Voor beide
zijn PHP-extensies nodig (pdo_sqlsrv / oci8) die
standaard niet zijn meegeleverd en niet op elke server beschikbaar zijn.
Dien een featureverzoek in als je ze nodig hebt.
Een bron toevoegen
Open /app/agents/{id}/sources (Kennis › Bronnen). De
pagina heeft één tabblad per brontype: Webpagina,
Sjablonen, SQL-database,
Tekst plakken, Google Sheets,
Google Docs, Notion en
Bestanden uploaden. Achter de schermen:
- Valideren. URL’s moeten http/https zijn; privéhosts (
10.x,192.168.x,127.x,::1) worden geblokkeerd om SSRF te voorkomen. - Maak de bronrij aan met
status = pending. - Verzend een taak —
CrawlSourceJobvoor url/sitemap/feed;IngestNotionPageJob/IngestGoogleDocJobvoor gekoppelde bronnen;IndexTextSourceJobvoor geplakte tekst. - De taak draait in de
crawl-wachtrij, haalt inhoud op, maakt documentrijen aan en verstuurt vervolgensIndexDocumentJobnaar deindex-wachtrij. - De status verandert van
pending → crawling → indexed(offailedmet een foutmelding die je in de gebruikersinterface kunt lezen).
"Indexeren is niet voltooid" — problemen met mislukte pagina's opsporen
Een pagina kan in de Knowledge-weergave terechtkomen met 0 chunks
en een oranje badge met de tekst "Indexeren is niet voltooid". De uitgevouwen rij toont nu
de daadwerkelijke fout van sources.error, indien aanwezig,
plus de gebruikte crawler en de tijdstempel van de laatste ophaalmoment. De meeste fouten vallen
onder een van de volgende categorieën:
- Pagina’s die alleen uit JavaScript bestaan / SPA-pagina’s zonder SSR-fallback — Cloudflare Browser Rendering voert JS uit, maar als de app volledig aan de clientzijde wordt geladen en geen schraapbare tekst blootgeeft, levert de extractor minder dan de drempel van 200 tekens op en wordt de bron als mislukt gemarkeerd.
- Bot-uitdaging / Cloudflare-beveiliging — de opgehaalde HTML is de uitdagingspagina, niet de echte inhoud. Gedetecteerd via
detectBlocker()-heuristiek. - Inlogscherm — de site vereist authenticatie; we voeren geen geauthenticeerde crawls uit.
- Zachte 404 — veel sites geven een 200-OK ‘niet gevonden’-pagina terug als een URL verkeerd is getypt.
looksLike404()wijst deze af. - Wachtrijverwerker loopt achter — de documentregel is aangemaakt, maar
IndexDocumentJobis nog niet uitgevoerd. Wacht even en ververs de pagina; als het probleem blijft bestaan, controleer dan de status van de wachtrij. - Het robots.txt-bestand van de site houdt crawlers buiten — de rij vermeldt dit en noemt de toegangsweg: een groep voor de eigen naam van de crawler,
User-agent: BlengiBotmetAllow: /op blengi.com ({AppName}Botelders), zodat je AI-medewerker de site kan lezen terwijlUser-agent: */Disallow: /zoekmachines buiten houden. robots.txt wordt gelezen volgens RFC 9309 (zie Crawlerketen). Klik vervolgens op Reindex. - Het robots.txt-bestand van de site kon niet worden gelezen — de site reageerde op robots.txt met een serverfout, ‘te veel verzoeken’ of helemaal niet. Een crawler moet dan wachten, dus de pagina is niet gelezen en behoudt wat hij had; de scan probeert het opnieuw, of druk later op Reindex.
Klik op Reindex bij een mislukte rij om dezelfde pijplijn opnieuw te proberen (URL opnieuw crawlen + indexeren, of bestand opnieuw parseren bij uploads). Als het steeds misgaat, betekent dit meestal dat de URL zelf niet te scrapen is — probeer dan een andere pagina op dezelfde site, of upload de inhoud als een bestand.
Een pagina en de pagina’s waarnaar deze linkt
Een bron met één URL crawlt precies die pagina — en dat is bewust: een
sitemap-fan-out haalde ooit honderden pagina’s binnen in een bron waar niemand
om had gevraagd. Maar sommige pagina’s zijn knooppunten waarvan de gelinkte pagina’s de
kennis vormen: Mooiwater’s /waterhardheid/ somt ~260
gemeentelijke pagina’s, een productfamiliepagina somt de varianten op, een help-
index somt de artikelen op. Vink Crawl ook de pagina’s waarnaar deze pagina
linkt aan bij een bron met één URL en de crawler
ontdekt eerst die links en crawlt ze vervolgens stuk voor stuk.
- Hoe diep — de pagina’s waarnaar deze pagina linkt (1), of die pagina’s en waarnaar die weer linken (2). Nooit dieper.
- Blijf binnen — standaard de eigen sectie van de pagina
(
/waterhardheid/volgt op/waterhardheid/meppel/, nooit op/contact/), of de hele website. - Alleen dezelfde website. URL’s voor winkelwagen, afrekenen, inloggen, account, zoeken en filteren/sorteren worden overgeslagen, net als bestanden. De limiet per bronpagina bepaalt het totaal.
- Discovery-verzoeken doorlopen dezelfde crawlerketen als de crawl zelf, dus een door JS weergegeven of door een bot beschermde hub levert nog steeds zijn links op.
- Elke gevonden pagina hoort bij deze bron, dus als je een bron aan een segment toewijst, komen ze allemaal in dat segment terecht — de reden om dit te gebruiken in plaats van een sitemap, want dan zouden de pagina’s die niets met de sitemap te maken hebben er ook bij komen.
- Bij herindexeren wordt de discovery opnieuw uitgevoerd, dus een gemeente die later aan de hub wordt toegevoegd, wordt opgepikt zonder dat je iets hoeft aan te passen.
- Heb je de bron al? Met de actie Crawl-opties in de betreffende rij kun je de optie in- of uitschakelen, of de diepte en reikwijdte aanpassen, en de detectie meteen opnieuw uitvoeren — pagina’s die al geïndexeerd zijn, blijven behouden.
Waar de titel van een pagina vandaan komt
De eigen <title>
van de pagina, zoals Readability die leest.
Pagina’s die via de Cloudflare Markdown-tier worden opgehaald, komen binnen met een
front-matter-blok (title: "…"
, gevolgd door een meta:
map); dat blok wordt nu omgezet in de titel en verwijderd
uit de tekst — vroeger kwam het in het eerste stuk terecht en werd de pagina
opgeslagen als „(geen titel)“. Als een pagina ons nog steeds niets geeft, wordt het
laatste URL-segment gebruikt („/waterhardheid/maasdonk/“ → „Maasdonk“),
zodat geen enkele pagina ooit zonder titel is. Rijen die vóór de fix zijn opgeslagen, worden
eenmalig aangepast met php artisan pitchbar:backfill-document-titles
(--dry-run
om te bekijken). Een herindexering
vernieuwt ook
de titel van een pagina, zelfs als de inhoud niet is veranderd
— een titelcorrectie kost nooit een herinvoeging.
Automatische detectie
Op de bronnenpagina neemt de knop Ontdekken een domein en zoekt daarin naar crawlbare pagina’s zonder dat je ze hoeft op te sommen. We:
- Lezen
robots.txtvoor sitemap-vermeldingen. - Doorzoeken we direct een sitemap als die aanwezig is.
- Geen sitemap? Dan lezen we de startpagina zelf en halen we de eigen links van dezelfde oorsprong eruit — zo kunnen sites zonder sitemap (wat vaak voorkomt bij kleine webwinkels) toch hun categorie- en infopagina’s vinden, ongeacht de taal of het URL-schema dat ze gebruiken. URL’s voor winkelwagen, afrekenen, inloggen/account en filteren/sorteren worden eruit gefilterd.
- Vul aan met een klein aantal veelvoorkomende paden als de resultaten nog steeds schaars zijn:
/about,/pricing,/features,/products,/faq,/docs,/help,/support,/contact. - Je krijgt een lijst te zien die je kunt controleren. Vink aan welke je wilt opnemen en klik op Geselecteerde toevoegen.
Alle zoekopdrachten sturen een standaard User-Agent van een browser — agents die op bots lijken worden aan de rand geblokkeerd door winkels die achter Shopify en Cloudflare draaien, waardoor een volkomen gezonde site er leeg uit zou zien.
Grote sites: als de discovery meer dan ~30 pagina’s vindt, groepeert de picker ze per URL-sectie met een ‘alles selecteren’-optie per sectie en een filtervak, zodat een webshop met 1.000 product-URL’s overzichtelijk blijft. Je hoeft over het algemeen niet elk product te indexeren — kies de categorie- en infopagina’s; afzonderlijke productpagina’s worden automatisch herkend vanuit de livepagina wanneer een bezoeker ze bekijkt.
"Automatisch geïndexeerd door bezoekers"
Elke agent heeft één rij met deze naam. Het is geen bron die je toevoegt; het is een bak die vanzelf volloopt: wanneer een bezoeker een pagina van je site opent die we nog niet hebben gecrawld, wordt die pagina in de wachtrij geplaatst en hier toegevoegd (beperkt door je toegestane bronnen, een filter voor privé-paden en een snelheidslimiet). Totdat de eerste van zulke pagina’s binnenkomt, staat er Luisteren in de rij, en is er geen ‘Re-indexeren’-knop omdat er nog niets is om opnieuw te indexeren. Zodra er pagina’s in staan, gedraagt het zich net als elke andere bron: met ‘Reindex’ worden de verzamelde pagina’s opnieuw gecrawld. Een pagina die al in een andere bron staat, wordt niet nog een keer toegevoegd, met of zonder de slash aan het einde (zie Auto-index ). Pagina’s komen in de wachtrij van dezelfde crawler terecht als al het andere, dus een bucket kan na installatie een tijdje Listening aangeven terwijl eerdere sitemaps nog worden ingelezen.
Sitemap-fan-out
Als je een bron van het type sitemap toevoegt, wordt er één
CrawlPageJob per URL in de sitemap verzonden, gespreid met een
kleine vertraging per pagina, zodat Cloudflare Browser Rendering geen
rate-limit toepast bij pieken. De discoverer (SitemapDiscoverer)
verwerkt drie soorten input:
"In de wachtrij" betekent precies dat.
De uitbreiding zelf —
één keer de sitemap ophalen — draait in de default
-wachtrij, dus
een net toegevoegde bron verandert binnen enkele seconden van In de wachtrij
naar
"crawling 0/N
". De pagina’s daarvan wachten dan in de
crawl
-wachtrij, die de enige worker als laatste afwerkt en in
volgorde: pagina’s van een eerder toegevoegde bron worden als eerste gelezen. Een tweede
sitemap die direct na de eerste wordt toegevoegd, laat daarom pas een stijgend aantal zien
als de pagina’s van de eerste klaar zijn. Dat is een positie in de wachtrij,
geen fout; een fout wordt weergegeven als failed
met de reden erbij.
-
Domeinroot
(
https://example.com) — controleert/sitemap.xml+/sitemap_index.xml. -
Directe sitemap-URL
(
https://example.com/sitemap.xmlofhttps://example.com/products/sitemap.xml) — wordt letterlijk opgehaald. De ‘discoverer’ voegde hier vroeger een tweede/sitemap.xmltoe en gaf een 404-foutmelding voor het verzoek. -
Sitemap-index
(de
<sitemapindex>XML die veel CMS’en — WordPress, Shopify, Webflow — standaard genereren) — gaat één niveau dieper in elke onderliggende sitemap en verzamelt pagina-URL’s.
Parsen van geüploade bestanden
Directe bestandsuploads (Bronnen → Bestanden uploaden) worden eerst lokaal geparseerd en vervolgens doorgegeven aan dezelfde chunk + embed- pijplijn die door gecrawlde pagina’s wordt gebruikt. De parser wordt gekozen op basis van de bestandsextensie:
| Extensie | Parser | Netwerkverzoek? |
|---|---|---|
.pdf, .docx, .doc, .xlsx, .xls, .odt, .ods | Cloudflare Workers AI toMarkdown als CF-inloggegevens zijn ingesteld; Smalot\PdfParser / PhpOffice\PhpWord anders | Ja — één multipart POST per bestand naar /ai/tomarkdown (gratis, 0 Neurons) |
.csv | League\Csv — stuurt één segment per rij, opgemaakt als col: value | col: value | Nee |
.md, .markdown, .txt | Gewone tekst, opgesplitst op H1/H2-koppen | Nee |
Het Cloudflare-pad heeft de voorkeur voor binaire Office-formaten, omdat
Smalot en PhpWord onbetrouwbaar zijn bij echte documenten: PDF’s die vanuit Word
zijn geëxporteerd en waarbij de hoofdtekst in één grote inhoudsstroom staat, gescande
PDF’s met een dunne tekstlaag en DOCX-bestanden met geneste tabellen of
tekstkaders worden vaak slecht geëxtraheerd.
toMarkdown
van Workers AI levert gestructureerde markdown op (koppen, lijsten en
tabellen blijven behouden), wat veel beter werkt voor de chunker.
Prijzen: toMarkdown is gratis voor alle bovenstaande formaten.
Alleen het omzetten van afbeeldingen naar Markdown verbruikt Workers AI Neurons (we
sturen geen afbeeldingen). Als er geen Cloudflare-inloggegevens zijn (BYOK
OpenAI-klanten, nieuwe installaties), of als de Cloudflare-aanroep
mislukt, nemen de ingebouwde PHP-parsers het over, zodat uploads van PDF / DOCX / CSV /
TXT / MD nooit stilletjes mislukken.
Welke parser er ook draait, de resulterende tekst wordt opgeslagen onder
storage/app/private/uploads/{source_id}/segment-N.txt
.
Dat is het bestand dat de knop ‘Reindex’ leest — je hoeft
het origineel niet opnieuw te uploaden om opnieuw te indexeren.
Chunking en inbedding
De tekst van de extractor gaat naar Chunker, een recursieve
splitter die de voorkeur geeft aan semantische grenzen:
- Splits op Markdown-koppen, daarna op lege regels (alinea’s).
- Verpak alinea’s zo veel mogelijk tot een streefgrootte (~2000 tekens / ~500 tokens).
- Als een alinea te groot is, val dan terug op zinsgrenzen.
- Het tekenvenster is echt alleen als allerlaatste redmiddel.
- Voeg een kleine overlap toe tussen de stukken, zodat feiten die in meerdere stukken voorkomen nog steeds aan elkaar gekoppeld kunnen worden.
De stukken worden ingedeeld in batches op basis van een geschat tokenbudget (maximaal 100 stukken en ruim onder de limiet van 60.000 tokens per verzoek van de provider; tekst met veel getallen en namen, zoals een spreadsheet, wordt in tokens verdeeld met ongeveer twee tekens per token, dus de schatting is bewust aan de lage kant). Als de provider een verzoek nog steeds afwijst omdat het te groot is, wordt de batch gehalveerd en opnieuw geprobeerd bij dezelfde provider, in plaats van doorgegeven aan een fallback-embedder, waarvan de vectoren niet zouden overeenkomen met de indexdimensie en
met metadata in de vectoropslag worden opgeslagen: agent_id,
document_id, chunk_id, url,
workspace_id, source_id, lang.
Beleid voor herhaling van crawlen
Elke CrawlPageJob wordt maximaal 3 keer geprobeerd met
backoff [30s, 90s, 180s]. Het herhalingspad wordt opgesplitst
op basis van de foutklasse:
- Snelheidsbeperking (HTTP 429, "te veel verzoeken" stroomopwaarts) — wordt teruggestuurd naar de wachtrij met een nieuwe vertraging van 60 seconden, zonder dat er een herpogingsslot wordt verbruikt. Elke fan-out-pagina in dezelfde werkruimte loopt vaak tegen dezelfde 429-golf aan; het gezamenlijk wachten is productief.
- Permanente fout (curl DNS-resolutie / verbinding geweigerd, HTTP 400 / 401 / 403 / 404 / 410 / 451, onjuist opgebouwde URL) — stopt meteen, zodat de bronrij direct de echte reden krijgt in plaats van vast te zitten achter nog twee pogingen die sowieso zullen mislukken. Er wordt nu geen
failed_jobs-rij geschreven: de weigering van een website wordt bij de bron weergegeven en telt niet mee als een mislukte taak. - Tijdelijk (5xx, netwerkstoring) — normale herpoging met backoff.
- Time-out per taak — 90 seconden.
failOnTimeout=true, zodat een SIGTERM voor een worker de bron nog steeds omzet naarfailedmet een voor de klant leesbare foutmelding.
Foutmeldingen voor klanten in de bronnenlijst worden opgeschoond
via SourceErrorPresenter — ruwe upstream JSON-
envelopes (Cloudflare 401-bodies, browserloze stacktraces) worden
herschreven naar vriendelijke teksten zoals "We konden deze pagina niet bereiken"
of "De crawldienst is momenteel bezet — we proberen het
automatisch opnieuw." Beheerders zien nog steeds het volledige ruwe bericht
onder 'Details weergeven'.
Opnieuw indexeren en voorbeeld bekijken
In de bronnenlijst bevat elke rij:
- Opnieuw indexeren — voert de voor het type geschikte pijplijn opnieuw uit: URL- en sitemapbronnen worden opnieuw gecrawld, OAuth-bronnen (Google Docs/Sheets, Notion) worden opnieuw opgehaald via hun API, de Auto-indexed from visitors-bucket crawlt elke verzamelde pagina opnieuw, en geüploade bestanden worden opnieuw in stukjes verdeeld en ingesloten vanuit de opgeslagen segmenttekst onder
storage/app/private/uploads/{source_id}/segment-N.txt— je hoeft het origineel niet opnieuw te uploaden. Als het opgeslagen bestand ontbreekt (uploads van vóór het opslaan of een schijfopruiming), blijft de al geïndexeerde inhoud gewoon werken en vraagt de gebruikersinterface alleen om een nieuwe upload om deze te verversen; het opnieuw indexeren mislukt nooit voor een bron waarvan de inhoud intact is. Bronnen met geplakte tekst hebben geen externe bron om opnieuw op te halen, dus ‘Reindex’ voegt de tekst die je op de bron hebt opgeslagen opnieuw in (wat ook een fout herstelt die door een oudere bug was veroorzaakt) — om de tekst zelf te wijzigen, gebruik je ‘Bewerken’. - Antwoord op elke pagina (wereldbolpictogram) — zie hieronder.
- Voorbeeld — toont de geëxtraheerde documenten en een voorbeeld van fragmenten, zodat je slechte extracties kunt opsporen (bijv. een navigatiebalk die de tekst verstoort).
- Verwijderen — verwijdert de bron; de documenten en fragmenten gaan mee (cascade-effect in de database). De vectoren worden niet uit de vectoropslag verwijderd; bij het ophalen worden ze overgeslagen omdat de bijbehorende fragmenten niet meer bestaan.
Antwoord op elke pagina (globale bronnen)
De zoekfunctie geeft de voorkeur aan informatie van de pagina waar de bezoeker zich bevindt (en, met Smart Segments , uit het segment van die pagina). Die precisie is meestal wat je wilt — maar sommige feiten zijn globaal : je adres, openingstijden, telefoonnummer, e-mail. Een bezoeker kan er vanaf elke pagina om vragen, maar als die inhoud alleen op (bijvoorbeeld) de Contactpagina is gecrawld, kan de score overal elders net onder de betrouwbaarheidsdrempel liggen en antwoordt de assistent “Dat kan ik niet bevestigen.”
Klik op de wereldbol knop bij een bron om deze te markeren als ‘Antwoord op elke pagina’. De stukjes informatie krijgen dan dezelfde boost als een match op de huidige pagina — vanaf elke pagina of elk segment — zodat het feit overal bereikbaar is. Er verschijnt een ‘Elke pagina ’-badge op de bron. De boost is relevantieafhankelijk en gemaximeerd: hij geldt alleen als de reranker het feit al relevant heeft bevonden voor de vraag (dus ‘wat zijn je prijzen?’ sleept het adres nooit erbij), en er worden maximaal twee globale stukjes per antwoord verplicht meegenomen, zodat een grote globale bron het echte antwoord niet kan verdringen.
Het beste voor een kleine, universeel relevante bron (een contactkaart, een opmerking over openingstijden). Het werkt meteen – geen herindexering – en geldt voor alle zoekresultaten in de hele werkruimte voor die agent.
Als je een hele sitemap of crawl als globaal markeert, krijgen webpagina’s bij elke vraag een boost. Die boost is groter dan die van je eigen documenten ten opzichte van webpagina’s, dus in twijfelgevallen krijgt een globale webpagina dan een hogere rangschikking dan je geüploade bestand of geplakte tekst.
Automatische herpogingen
Je hoeft nooit op de knop ‘Opnieuw indexeren’ te letten. Fouten lossen zichzelf op twee niveaus op:
- Herpogingen tijdens de taak — elke indexeringstaak probeert het maximaal 3 keer opnieuw met een geleidelijke vertraging, zodat een tijdelijke snelheidsbeperking of netwerkstoring binnen enkele minuten wordt opgelost zonder dat je er iets van merkt.
- Geplande scan — elke 15 minuten
zet
pitchbar:retry-sourcesbronnen die om tijdelijke redenen zijn mislukt (snelheidsbeperkingen, time-outs, upstream 5xx-fouten, een onbereikbare wachtrij) opnieuw in de wachtrij en redt bronnen die vastzitten in crawling/pending door een uitgevallen worker. Maximaal 3 automatische pogingen per storing (de teller wordt gereset na 24 rustige uren), dus een site die een dag of een week offline is, wordt drie keer per dag opnieuw geprobeerd totdat hij reageert. Een 5xx-fout telt als tijdelijk, hoe de crawler het ook noemt (HTTP 503, gewone HTTP die 500 teruggeeft, statuscode 502); vroeger gold dat alleen voor de eerste vorm, en door een nachtelijke storing van een klantensite bleven de pagina’s daarvan zes weken lang mislukken.
Permanente problemen — een pagina geblokkeerd door robots.txt, een 404, een inlog scherm, een verlopen Google-verbinding, een bestand dat opnieuw geüpload moet worden — worden nooit automatisch opnieuw geprobeerd: ze blijven zichtbaar als mislukt met een actiebericht totdat je de oorzaak hebt verholpen, en de crawl verbruikt er nooit crawlquota aan.
De kennis-e-mail
Eén keer per dag (pitchbar:check-source-health
, 08:30) krijgen de
eigenaren en beheerders van de werkruimte één e-mail met een lijst van de bronnen die
om een permanente reden zijn mislukt, één keer per storing. Nu staat erin
welk soort fout elke bron heeft. Een bron die nog steeds
inhoud bevat, is gestopt met updaten
: je AI-medewerker antwoordt op basis van wat
hij het laatst heeft gelezen. Een bron die geen inhoud bevat, omdat hij nooit is gelezen
of omdat de pagina verdwenen is, kon niet worden gelezen
: je AI-medewerker kan
er helemaal niets uit antwoorden. Elke regel geeft de reden weer in de taal van de lezer,
en de bezoekersbucket behoudt zijn naam:
‘Auto-indexed from visitors
’. Omdat alleen storingen die
nooit opnieuw worden geprobeerd in deze e-mail terechtkomen, belooft deze niet langer automatische
herpogingen: er staat dat ze niet vanzelf worden opgelost, en Reindex
voert de bron opnieuw uit zodra de oorzaak is verholpen.
Notion en Google Docs
Beide gebruiken OAuth. Maak één keer verbinding via /settings/integrations; het
token wordt in rust versleuteld. Nadat je verbinding hebt gemaakt, kun je in het bronvenster
direct pagina’s of documenten kiezen.
Google Docs worden geëxporteerd als Markdown, dus alinea- stijlen die in het document zijn gemarkeerd als Kop 1–6 blijven behouden als echte koppen. De chunker splitst op kopjes en voegt aan elk stukje de sectiekop toe — waardoor feiten uit de ene sectie (bijv. de specificaties van één product) niet in antwoorden over een andere sectie terechtkomen. Structureer documenten met echte kopstijlen, niet met vetgedrukte tekst: vetgedrukte regels vormen geen sectiegrenzen. Documenten die niet als Markdown kunnen worden geëxporteerd, worden automatisch omgezet naar platte tekst.
Het plakken van een docs.google.com-documentlink in het veld voor de gewone
URL werkt ook: het formulier herkent het en maakt een
correcte Google Docs-bron aan (de webcrawler kan Google Docs niet lezen, dus
het crawlen ervan als website zou altijd mislukken). Links naar Sheets worden
verwezen naar het Google Sheets-tabblad, waarvoor de tabbladnaam nodig is.
Excel-bestanden op Drive zijn geen Google Sheets.
Een
.xlsx
die naar Drive is geüpload, wordt geopend in de Sheets-editor en de
URL zegt nog steeds /spreadsheets/
, maar de Sheets-API weigert
Office-bestanden te lezen. Het formulier herkent dit (de veelbetekenende
rtpof=true
in de link) en legt uit hoe je het kunt oplossen: open het
bestand, kies Bestand → Opslaan als Google Sheets
, en plak de link
van de nieuwe,
geconverteerde kopie — de conversie maakt een apart bestand aan
met een eigen URL.
Bronnen uit Notion, Google Docs en Google Sheets worden elk uur opnieuw gesynchroniseerd
(pitchbar:sync-oauth-sources
, voor bronnen die
geïndexeerd zijn en meer dan een uur geleden voor het laatst gesynchroniseerd zijn). Om een
wijziging meteen op te pikken, klik je op Opnieuw indexeren
bij die
bron.
"Mijn agent weet niets van het bestand dat ik net heb geüpload"
Cloudflare Vectorize hanteert ‘eventual consistency’ bij op metagegevens gefilterde
zoekopdrachten — zelfs nadat een ‘upsert’ een 200 OK-status retourneert, levert een op
agent_id
gefilterde zoekopdracht tegen die vector doorgaans
0 resultaten op gedurende de eerste 30 tot 60 seconden
, terwijl
de metagegevensindex zich verspreidt over de edge-regio’s.
Praktisch gevolg: een pas geüpload bestand verschijnt meteen als
status=indexed
op de pagina ‘Bronnen’, maar de
agent kan er pas vragen over beantwoorden als de verspreidingsperiode
is afgelopen. De banner ‘Upload geslaagd’ herinnert de beheerder hieraan.
Als de agent na een minuut nog steeds geen relevante stukjes tekst teruggeeft,
open dan het voorbeeld
van de bron om te controleren of de geëxtraheerde
tekst niet leeg is — dat is een probleem aan de parserkant, niet aan de vectorzijde.
Hetzelfde geldt voor de allereerste upload nadat je voor het eerst een Cloudflare Vectorize-index hebt aangemaakt — de index zelf heeft een vertraging van ongeveer 2 minuten voordat zoekopdrachten resultaten opleveren, zelfs ongefilterde.
Opslag en bewaartermijn
- Postgres — bronnen, documenten, chunks (tekst + metadata).
- Vectoropslag — embeddings. Cloudflare Vectorize indien geconfigureerd, anders Qdrant.
- R2 / objectopslag — originele bestanden (PDF’s, afbeeldingen) bij het uploaden.
Als je een bron verwijdert, wordt de bijbehorende rij verwijderd en verwijdert de database in cascade ook de documenten en chunks ervan. De vectorpunten blijven in de vectoropslag staan (bij het ophalen worden ze overgeslagen, omdat de bijbehorende chunks weg zijn). Er is geen soft-delete voor bronnen.