B Blengi docs

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

TypeGebruik het voorWat we opnemen
urlEén specifieke pagina — of, met Crawl ook de pagina’s waarnaar deze pagina linkt, een hubpagina en de bijbehorende sectieCrawlen + hoofdinhoud extraheren + in stukken verdelen + insluiten; met ‘links volgen’ aan, zoek eerst naar links binnen dezelfde sectie (diepte 1–2) en crawl ze allemaal
sitemapEen hele site in één keerLees de sitemap, ga per URL naar één CrawlPageJob
feedRSS-/Atom-blogsHetzelfde als de sitemap, maar leest <item>-vermeldingen
textFAQ’s, fragmenten, alles wat je kunt plakkenSla het crawlen over, verdeel in stukjes en embed direct
notionNotion-pagina’sOAuth in Notion, ophalen via API, behandel elke pagina als een document
google_docGoogle Docs (Workspace)OAuth, ophalen via de Drive-API, importeren als document
google_sheetTabbladen in Google SheetsOAuth, haal elke niet-lege rij op, één documenttekst met Row N: …-markeringen
sqlExterne MySQL / PostgreSQLDirecte PDO SELECT (alleen-lezen); één document met Row N: …-markeringen. Inloggegevens worden in rust versleuteld met de app-sleutel (AES-256-CBC).
filePDF / DOCX / XLSX-uploadsGeparseerd via Cloudflare toMarkdown (gratis niveau), in stukjes verdeeld + ingesloten
woocommerce_productsWP / WooCommerce-winkelsGesynchroniseerd via de bijbehorende WordPress-plugin
autoPagina’s waar bezoekers terechtkomenAutomatisch 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:

  1. Open /app/agents/{id}/sources en scroll naar SQL-database toevoegen.
  2. Kies de driver (MySQL of PostgreSQL) — de poort wordt automatisch ingevuld met 3306 of 5432.
  3. Plak de host, databasenaam, gebruikersnaam en wachtwoord.
  4. Plak een SELECT-query — elke rij die wordt geretourneerd, wordt onderdeel van de kennisbank van de agent.
  5. 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.
  6. Klik op Verbinden & synchroniseren. De eerste SyncSqlSourceJob wordt uitgevoerd op de crawl-wachtrij, indexeert de rijen en schakelt de bron over naar indexed.

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-local 169.254.0.0/16 (AWS-metadata-IP) en elke naam die naar een privé-IP verwijst, worden allemaal geweigerd. De bron wordt omgezet naar failed met 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 trefwoorden INSERT, UPDATE, DELETE, DROP, ALTER, TRUNCATE, GRANT, REVOKE, CREATE, REPLACE, CALL, EXEC, EXECUTE, MERGE, LOAD en
  • 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 SELECT met een LIMIT als 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:

  1. Valideren. URL’s moeten http/https zijn; privéhosts (10.x, 192.168.x, 127.x, ::1) worden geblokkeerd om SSRF te voorkomen.
  2. Maak de bronrij aan met status = pending.
  3. Verzend een taak — CrawlSourceJob voor url/sitemap/feed; IngestNotionPageJob/IngestGoogleDocJob voor gekoppelde bronnen; IndexTextSourceJob voor geplakte tekst.
  4. De taak draait in de crawl-wachtrij, haalt inhoud op, maakt documentrijen aan en verstuurt vervolgens IndexDocumentJob naar de index-wachtrij.
  5. De status verandert van pending → crawling → indexed (of failed met 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 IndexDocumentJob is 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: BlengiBot met Allow: / op blengi.com ({AppName}Bot elders), zodat je AI-medewerker de site kan lezen terwijl User-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.txt voor 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.xml of https://example.com/products/sitemap.xml ) — wordt letterlijk opgehaald. De ‘discoverer’ voegde hier vroeger een tweede /sitemap.xml toe 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:

ExtensieParserNetwerkverzoek?
.pdf, .docx, .doc, .xlsx, .xls, .odt, .odsCloudflare Workers AI toMarkdown als CF-inloggegevens zijn ingesteld; Smalot\PdfParser / PhpOffice\PhpWord andersJa — één multipart POST per bestand naar /ai/tomarkdown (gratis, 0 Neurons)
.csvLeague\Csv — stuurt één segment per rij, opgemaakt als col: value | col: valueNee
.md, .markdown, .txtGewone tekst, opgesplitst op H1/H2-koppenNee

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:

  1. Splits op Markdown-koppen, daarna op lege regels (alinea’s).
  2. Verpak alinea’s zo veel mogelijk tot een streefgrootte (~2000 tekens / ~500 tokens).
  3. Als een alinea te groot is, val dan terug op zinsgrenzen.
  4. Het tekenvenster is echt alleen als allerlaatste redmiddel.
  5. 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 naar failed met 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-sources bronnen 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.