Een zelf gehoste API leest uw documenten op uw eigen server, met dezelfde motor en REST-aanroepen als een cloud-API. De documenten gaan dus niet naar ons. Wel controleert de container elke zes uur zijn licentie bij onze server, en dat zeggen we hier ook.
Wie het document in handen heeft
Een privacyfunctionaris vraagt bij nieuwe software meestal: waar is de verwerkersovereenkomst? Daarachter zit één vraag. Wie heeft het document in handen op het moment dat het wordt doorzocht?
Bij een cloud-API is dat de leverancier. Dat is handig, maar elk BSN, IBAN en elke geboortedatum komt dan bij een derde terecht voordat iemand vaststelt wat het is.
Bij een bureaubladtoepassing blijft het document op de computer, maar zit er een mens tussen elk bestand en het resultaat. Dat past niet bij een pijplijn die elke nacht duizend stukken verwerkt.
Een zelf gehoste API combineert beide: het document blijft in uw netwerk, en u houdt REST-aanroepen en een CLI. Het is dezelfde motor als in de toepassing, in een omgeving die u zelf beheert. Waarom veel gereedschap voor ontwikkelaars hier tekortschiet, bespraken we eerder.
Artikel 28 AVG gaat over verwerking in opdracht van een ander, en de Autoriteit Persoonsgegevens kijkt naar wat er feitelijk gebeurt. Een leverancier die uw documenten nooit ontvangt, verwerkt ze niet. Wat dat voor uw situatie betekent, beoordeelt uw functionaris voor gegevensbescherming. Voor advocaten en notarissen spelen ook het beroepsgeheim en het verschoningsrecht.
Wat er wel naar buiten gaat
Een eerdere versie van dit artikel beweerde dat de API na installatie nooit meer contact met ons opneemt. Dat klopte niet. Wie een uitgaande verbinding ontdekt die de leverancier niet noemde, gelooft daarna ook de rest niet meer.
Bij het starten valideert de API zijn sleutel bij onze licentieserver, en daarna elke zes uur opnieuw. Die aanroep bevat geen paginatekst en geen detectieresultaat. Is onze server onbereikbaar, dan valt de API terug op een offline cache van de laatste geldige controle. Na hooguit drie dagen stopt de container met verwerken, tot de licentieserver weer antwoordt.
De twee getallen horen bij elkaar. Blokkeert u de controle met een firewallregel, dan houdt de API het drie dagen vol. Werkt u met een allowlist voor uitgaand verkeer, dan is dit één regel: de container moet onze licentieserver kunnen bereiken. Voor de documenten zelf heeft hij verder niets van buiten nodig, tenzij u de optionele taalmodellaag op een externe dienst richt.
Wilt u volledig losgekoppeld draaien? De API heeft geen air-gapped modus, en de drie dagen zijn een buffer voor storingen. De bureaubladtoepassing heeft met Pro wel een air-gapped stand, zonder licentieaanroep en crashrapportage, maar dat is een ander mechanisme. ‘100% offline’ zeggen we alleen van die bureaubladtoepassing. De gratis browserversie stuurt bij het opstarten een anoniem signaal, en ook daar blijft het document op de machine.
Wat er binnen de container gebeurt
Detectie gebeurt in lagen. Patronen vinden waarden met een vaste vorm, zoals een BSN, IBAN of e-mailadres. Een entiteitenmodel naar keuze (spaCy, BERT of GLiNER) vindt namen, organisaties en adressen.
De derde laag is een taalmodel, optioneel en standaard uit. Zet u hem aan, dan draait hij met een lokaal model of op een eindpunt dat u opgeeft, bijvoorbeeld op uw eigen netwerk. Richt u hem op een externe dienst, dan gaat paginatekst naar die dienst.
De uitkomsten worden samengevoegd, ontdubbeld en over de pagina's doorgetrokken, zodat een naam van pagina 1 ook op pagina 4 wordt gemarkeerd. Daarna gaat er een ruisfilter overheen. Geen lokaal model herkent elk kenmerk, dus een mens hoort de vondsten na te kijken voordat een stuk de organisatie verlaat. Slaat uw pijplijn die stap over, leg dat dan vast in het ontwerp.
De pijplijn rendert een scan op 300 dpi en leest hem met Tesseract, in de taal van het document plus Engels. De gevonden gegevens worden als beeldgebieden afgedekt, met een doorzoekbare tekstlaag eronder. Er gaan zeven taalpakketten mee, en een scan met het verkeerde pakket levert zonder melding slechte tekst op.
Zwartlakken haalt de onderliggende inhoud weg en tekent er geen zwart vlak over. Bij de export worden ook de onzichtbare plekken behandeld: alt-teksten en vervangende tekst in getagde pdf's, XMP-metadata, PieceInfo, benoemde bestemmingen en formuliervelden met hun weergave. Daar komt de code van de waarde, of een neutrale markering als ze is gezwartlakt. Een eerder gerenderde miniatuur verdwijnt, want in een rasterbeeld valt niets te vervangen.
Codes gelden per groep
Kiest u voor Coderen, dan vervangt de API een waarde door een korte code en bewaart hij de koppeling in het Coderegister op uw server. Dat register is per groep ingedeeld (in de toepassing: per map), en groepen zien elkaars codes niet. Dezelfde persoon krijgt dus in twee los geüploade documenten twee verschillende codes.
Wilt u dat een dossier als één zaak leesbaar blijft, plaats de documenten dan in dezelfde groep, in de API via group_id. Alleen een code die een gebruiker met de hand vastzet, geldt buiten zijn groep. Decoderen is een aanroep naar POST /api/detokenize op uw eigen server, zonder dienst van ons ertussen.
In vijf minuten aan de slag
Installeer niet vanaf PyPI, want die naam is een verouderde plaatshouder. Vanuit een checkout van de broncode installeert u het pakket in de pakketmap met pip install -e .. Zet uw sleutel in PROMPTSHIELD_API_KEY en start de server met promptshield serve. Zonder sleutel start hij niet.
Met curl http://<host>:<poort>/health ziet u of hij draait. Dat is het enige eindpunt dat zonder sleutel antwoordt. Alle andere vragen de kop Authorization: Bearer. Een browser stuurt die niet mee bij een getypt adres, dus documentatiepagina's geven 401. Het schema haalt u op met curl -H "Authorization: Bearer $PROMPTSHIELD_API_KEY" http://<host>:<poort>/openapi.json.
Waarom we de licentiecontrole noemen
Wij hebben belang bij die verbinding: zonder licentiecontrole is een zelf gehoste API een kopie die we niet kunnen factureren. Daarom gaat de aanroep alleen over de sleutel. Een inkoper die dat vooraf weet, kan de rest toetsen in plaats van het te moeten geloven.
Vragen die ontwikkelaars stellen
Stuurt de API mijn documenten ergens naartoe?
Niet in de standaardinstelling. Naar onze licentieserver gaat elke zes uur een licentiecontrole zonder documentinhoud. Paginatekst verlaat uw netwerk alleen als u de optionele taalmodellaag op een externe dienst richt.
Kan de API helemaal zonder netwerk werken?
Nee, er is geen air-gapped modus voor de API. Zonder licentieserver werkt hij hooguit drie dagen door op een offline cache. De air-gapped stand van de bureaubladtoepassing met Pro is een ander mechanisme.
Hoe installeer ik de zelf gehoste API?
Vanuit een checkout, met pip install -e . in de pakketmap. Zet daarna uw sleutel in PROMPTSHIELD_API_KEY, start promptshield serve en controleer met /health of hij draait.
Krijgt dezelfde persoon bij elke aanroep dezelfde code?
Alleen binnen dezelfde groep. Los geüploade documenten krijgen elk hun eigen naamruimte. Plaats de documenten van één dossier in één groep, of zet een code met de hand vast.