Voer Mirage lokaal uit: OCR en objectdetectie vanuit één afbeelding

Eva Wong

IceWhale author

Eva Wong is de technisch schrijver en vaste knutselaar bij ZimaSpace. Als levenslange geek met een passie voor homelabs en open-sourcesoftwareis ze gespecialiseerd in het vertalen van complexe technische concepten naar toegankelijke, praktische handleidingen. Eva vindt dat self-hosting leuk moet zijn en niet intimiderend. Met haar tutorials helpt ze de community om hardware-installaties te doorgronden, van het bouwen van hun eerste NAS tot het beheersen van Docker-containers.

Run Mirage Locally: OCR and Object Detection from One Image - Zima Store Online

Mirage van Cactus Compute kan een lokale afbeelding analyseren en tekst, objectlocaties en gestructureerde velden retourneren. Het model van ongeveer 22 MB van de ontwikkelaar, met twee bits, is klein genoeg om uit te proberen zonder een vision-checkpoint van meerdere gigabytes te downloaden. Begin met een apparaatlabel of een heldere schermafbeelding en vergelijk de geretourneerde velden met de oorspronkelijke afbeelding voordat je een workflow automatiseert.

De officiële release beschrijft een visiemodel met 51,3 miljoen parameters, een lokale browserdemo en een installeerbare runtime. De release vermeldt 74 ms op één Samsung Galaxy S26 NPU-configuratie en 107 ms op de CPU van die telefoon. Die tijden gelden voor die configuratie. Controleer de prestaties en nauwkeurigheid met je eigen apparaat en invoer.

Voor welke taken is dit model geschikt?

Mirage kan scènes beschrijven, objecten detecteren, tekst lezen, maskers retourneren en vragen met beperkingen beantwoorden. Voor een inventarisatietaak kun je het model vragen een label te herkennen, het tekstgebied te extraheren en een beperkt aantal velden te retourneren. Bij foto's kun je objectlocaties gebruiken als aanwijzingen voor een menselijke beoordelaar. Een gestructureerd antwoord is nuttig als het een koppeling met het beeldmateriaal behoudt.

De ontwikkelaar vermeldt zeven talen voor afbeeldingsbeschrijvingen. Ga er niet van uit dat alle OCR-schriften uit die lijst worden ondersteund. De tekstlezer kan een accent missen, vergelijkbare cijfers verwarren of een klein gebied overslaan. Cactus toont zelf een onvolmaakt OCR-resultaat in de releasedemo. De modelkaart bevat links naar runtimevereisten en invoervoorbeelden.

Het gepubliceerde overzicht van Mirage door Cactus Compute, met OCR, maskers en scène-extractie. Oorspronkelijke bron

Hoe voer je het eerste lokale voorbeeld uit?

Probeer de browser-sandbox waarnaar Cactus linkt met een niet-gevoelige testafbeelding. Gebruik het Python-pakket daarna op een platform dat wordt ondersteund door de Cactus-runtime. Gebruik een schone omgeving en een afbeelding die je zelf beheert.

python -m venv .venv
source .venv/bin/activate
python -m pip install -U cactus-compute

Het gepubliceerde voorbeeld van het pakket is:

import cactus

model = cactus.Mirage()
print(model.describe("photo.png"))

Bij het eerste gebruik kan het pakket de engine en het model downloaden en in de cache opslaan. Meet die installatie apart van de inferentie. Om een latere offline workflow te controleren, voltooi je eerst de initiële installatie en test je daarna met netwerken uitgeschakeld en een lokaal bestand in een geïsoleerde omgeving. Controleer de runtimeversie en het cachegedrag in plaats van daaruit conclusies te trekken op basis van de pakketnaam.

Hoe stel je een kleine nauwkeurigheidstest op?

Maak drie foto's van hetzelfde label: één recht en gelijkmatig belicht, één gedraaid of spiegelend, en één met een ander label in de buurt. Houd een referentietranscriptie bij. Vergelijk de exacte tekens en de koppeling aan velden, niet alleen of de uitvoer een aannemelijke tekenreeks bevat. Controleer bij objectdetectie de kaders. Een correct label dat aan het verkeerde object is gekoppeld, kan een voorraadrecord verderop in de keten verstoren.

Invoer	Nuttige controle	Veelvoorkomende fout die gecontroleerd moet worden
Apparaatlabel	Exact serienummer en modelnaam	O in plaats van nul, schittering, afgebroken tekenreeksen.
Schermafbeelding	Tekst, begrenzingsgebied en leesvolgorde	Dunne lettertypen, overlappende panelen en kleine UI-labels.
Bon	Totaal, datum en valuta als afzonderlijke velden	Onduidelijke subtotalen, een verkeerd decimaalteken of ontbrekende regelitems.
Gemengde scène	Of elk object bij de juiste regio hoort	Dubbele labels, gemiste kleine objecten of verzonnen context.

Test een lege afbeelding, een afbeelding zonder relevant veld en een onleesbare uitsnede. Een bruikbare extractieworkflow moet expliciet een onbekende of lege status kunnen aangeven. Als de volgende stap een voorraadrecord wijzigt, plaats een ontbrekend of onzeker veld dan in een wachtrij voor controle in plaats van te gokken.

Hoeveel geheugen en welke latentie kun je verwachten?

De geadverteerde 22 MB verwijst naar de tweebitsmodelrepresentatie. Het runtimegeheugen omvat de inferentie-engine, de gedecodeerde invoer, tussentensors en de overhead van de applicatie. De afmetingen van afbeeldingen kunnen de voorbewerking en het geheugengebruik beïnvloeden, ook als het modelbestand even groot blijft. Houd naast de modelgrootte ook het piekgeheugenverbruik van het proces bij wanneer je bepaalt wat er naast je andere services kan draaien.

Meet de koude start, de inferentie na het opwarmen en de end-to-endlatentie, inclusief het decoderen van afbeeldingen en de nabewerking. Een benchmark op een telefoon-NPU vertelt niet hoe lang dit duurt op een NAS of een energiezuinige x86-CPU. Controleer of je besturingssysteem en apparaat worden ondersteund in de runtimevermelding en meet vervolgens met dezelfde afbeeldingen en code die je wilt uitrollen.

Hoe houd je de uitvoer bruikbaar en de invoer privé?

Houd herkenning en acties gescheiden. Sla velden op met een verwijzing naar de uitsnede van de bronafbeelding en een validatiestatus. Pas waar mogelijk deterministische controles toe: de verwachte lengte van een serienummer, toegestane tekens, datumindeling of hoeveelheidsbereik. Toon de uitsnede naast het voorgestelde veld als een beoordelaar dit moet corrigeren. Zo blijft er een weg terug naar het daadwerkelijke bewijsmateriaal.

Een lokaal modeleindpunt kan ervoor zorgen dat je bronafbeeldingen minder vaak hoeft over te dragen, maar controleer ook de browsercode, telemetrie, het cachegedrag en andere onderdelen. Een model met visueel redeneervermogen kan tekst in de afbeelding als inhoud interpreteren. Laat die tekst geen instructie worden voor een shell- of bestandsbewerking. Bekijk de gids om brongegevens uit AI-verzoeken te houden.

Welke rol speelt een thuisserver?

Bewaar de originele bestanden in een afgeschermde bibliotheek en stuur voor elke taak alleen de benodigde afbeelding naar het inferentieproces. Plaats de uitvoer in een aparte map of database om deze te controleren. Voer op een gedeelde server eerst een kleine batch uit en controleer of herkenningstaken back-ups, bestandsindexering of andere gebruikers hinderen. De vergelijking van reken- en opslagmogelijkheden voor privébestanden en de gids voor het isoleren van back-ups leggen uit welke rol die diensten kunnen spelen.

Veelgestelde vragen

Werkt de eerste keer volledig offline?

Het pakket kan de engine en gewichten bij het eerste gebruik ophalen. Controleer na installatie en het cachen van de benodigde bestanden of alles offline werkt.

Is 22 MB het geheugengebruik?

Dit beschrijft het geadverteerde gecomprimeerde model, terwijl het totale geheugengebruik van het proces ook de runtime en afbeeldingsbuffers omvat.

Kan Mirage alle kassabonnen en etiketten lezen?

Test de talen, belichting, lettertypen en lay-outs die je daadwerkelijk tegenkomt. Kleine of reflecterende tekst kan onjuiste of onvolledige uitvoer opleveren.

Kan ik handmatige controle overslaan?

Controleer de uitvoer wanneer die gegevens wijzigt of acties activeert, vooral als velden onzeker zijn of niet kunnen worden gevalideerd.

Kan ik de telefoonbenchmark gebruiken om een thuisserver te kiezen?

Gebruik dit als voorbeeld voor de geteste telefoon. Test de beoogde hardware en runtime met je eigen afbeeldingen.

Conclusie

Met Mirage begin je eenvoudig met een klein lokaal OCR- en beeldherkenningsexperiment. Installeer de ondersteunde runtime, test specifieke velden op een paar uitdagende afbeeldingen en zorg dat je de resultaten kunt controleren. Schaal pas op naar grotere batches als de metingen en foutafhandeling goed genoeg zijn voor de beoogde taak.