Een praktische gids voor AI-developers die vandaag kleine agentic, spraak- en visionmodellen op het apparaat zelf willen draaien. Wij installeren de opensource-engine van Cactus Compute, doen een toolcall, voegen confidence gating en een terugval naar een groter model toe, extraheren gestructureerde data, draaien spraak en vision, meten latentie en geheugen, en verpakken het geheel zodat het draait met het netwerk uitgeschakeld. Elk voorbeeld hieronder is op onze eigen hardware uitgevoerd, en wij laten zien wat het afdrukte, inclusief waar de modellen het mis hadden.
pip install cactus-compute geeft u drie kleine modellen op één native engine: Needle 3 (35,3 MB) zet een verzoek om in een aanroep van een van uw Python-functies of haalt velden uit tekst; Whistle (16,9 MB) transcribeert spraak in zeven Europese talen; Mirage (21,6 MB) geeft objecten, tekst en eenvoudige formulierantwoorden terug uit een afbeelding. Ze draaien op een CPU, offline na de eerste download. In onze runs duurde een toolcall ongeveer 70 tot 110 ms met een piekgeheugen van 136 MB. De modellen zijn smal en hebben het soms mis, dus gebruik in productie rust op drie gewoonten: strikte schema's, een confidencedrempel die u kiest op basis van uw eigen testset, en een escalatiepad naar een groter model of een mens.
Deze technote hoort bij ons blogbericht On-device AI onder 50 MB: wat de engine van Cactus betekent voor bedrijven, dat de businesscase behandelt. Eerst één correctie: deze engine wordt soms genoemd als NVIDIA-product. Dat is hij niet. Hij is gebouwd door Cactus Compute, een Y Combinator-bedrijf, en uitgebracht onder Apache 2.0 [1][9]. Feiten en versies zijn per 16 november 2026.
1. Voor wie dit is, wat u bouwt, wat u nodig hebt
Voor wie het is. Python-developers en ML-engineers die AI-functies willen die werken zonder een rondreis over het netwerk: spraakcommando's in een app voor buitendienstmedewerkers, een kiosk die documenten leest, een supporttool die een bericht omzet in een ticket, of een apparaat dat offline moet blijven werken.
Wat u bouwt. Een eerste toolcall; een agent met confidence gating die handelt, vraagt of escaleert naar een OpenAI-compatibel endpoint; extractie die verzonnen waarden weigert; spraak naar een toolcall; tekst lezen uit afbeeldingen; een latentiebenchmark en een evaluatieharness; en een offline container.
Vereisten. Python 3.9 of hoger [1]; macOS op Apple silicon, Linux (x86-64 of Arm64) of Windows, naast andere platforms die Cactus noemt [4]; ongeveer 200 MB vrije schijfruimte voor het pakket, de engine en alle drie de modellen; internettoegang alleen voor de eerste download. Er is geen GPU nodig. Wij gebruikten een Apple M4 Max met macOS 26.7, Python 3.15 en cactus-compute 4.2.2 (engine 4.1.1), plus Docker voor de Linux arm64-container.
2. Hoe de onderdelen in elkaar passen
Het Python-pakket is een dunne laag: het zet uw functies om in JSON-schema's, draait de agentloop, controleert of argumenten in de invoer zijn verankerd en rapporteert een confidencescore. Het roept één native enginebibliotheek aan, die per model een apart gewichtenbestand (.cact) laadt [2]. Bij het eerste gebruik worden engine en gewichten van Hugging Face gedownload op vastgepinde commits, gecontroleerd tegen SHA-256-checksums en gecachet onder ~/.cache/cactus [2][3].
Twee dingen om te weten voordat u begint. Ten eerste schrijft Needle 3 geen lopende tekst. Het geeft een toolcall terug, of een lege lijst als het verzoek buiten het onderwerp valt, wat een weigering is [2]. Als u geschreven antwoorden nodig hebt, hebt u een groter model nodig (zie de vergelijking in sectie 13). Ten tweede beschrijft Cactus de engine als "sub-1 MB" [2]; de ongecomprimeerde bibliotheken die wij downloadden, waren 1,4 MB op macOS en 1,8 MB op Linux Arm64. Elk model plus de engine blijft ruim onder de 50 MB.
3. Stap 1: installeren
python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install "cactus-compute==4.2.2"
# Optional: switch off anonymous usage counts for this shell
export CACTUS_TELEMETRY=0
Het vastpinnen is belangrijk: het pakket ging in november 2026 in elf dagen van 4.0.0 naar 4.2.3 [8]. import cactus haalt JAX niet binnen; JAX is alleen nodig voor de optionele fine-tuning-extra, cactus-compute[train] [2]. Het pakket verstuurt anonieme gebruikstellingen (functienaam, versie, OS en een willekeurige installatie-ID), tenzij CACTUS_TELEMETRY=0 of DO_NOT_TRACK=1 is ingesteld [1][2].
4. Stap 2: uw eerste toolcall
Dit is het README-voorbeeld [1], uitgebreid om beide manieren te laten zien waarop u de agent aanstuurt.
import json
import cactus
@cactus.tool
def get_weather(city: str):
"Get the current weather for a city."
return {"city": city, "temp_c": 27, "sky": "clear"}
with cactus.Cactus(tools=[get_weather]) as agent:
# One turn: the model proposes a call, you decide whether to run it
r = agent.complete("What's the weather in Lagos?")
print(json.dumps({k: r[k] for k in ("type", "function_calls", "confidence", "peak_ram_mb")}))
# Full loop: Cactus runs your function and returns its result
agent.reset()
print(agent.run("What's the weather in Lagos?")["results"])
Draai het met python hello.py. De eerste run downloadt de engine en de gewichten van 35 MB (bij ons ongeveer 10 seconden); latere runs laden in ruim minder dan een seconde uit de cache. Onze uitvoer:
{"type": "call", "function_calls": [{"name": "get_weather", "arguments": {"city": "Lagos"}}], "confidence": 0.9555, "peak_ram_mb": 134.2}
[{'city': 'Lagos', 'temp_c': 27, 'sky': 'clear'}]
Wat er gebeurde:
@cactus.toolzet de functiesignatuur en de docstring om in een JSON-schema. Type hints worden argumenttypen; een standaardwaarde maakt een argument optioneel [2].complete()draait één beurt en geeft de voorgestelde aanroep terug zonder iets uit te voeren. Gebruik het wanneer u wilt controleren of bevestigen voordat er wordt gehandeld.run()voert de loop uit: het model kiest aanroepen, Cactus voert uw functies uit, voert de resultaten terug en geeft ze terug onderresults[2].reset()wist het gesprek maar behoudt de tools. Eén toolset per agent: om tools te wijzigen, maakt u een nieuweCactusaan [2].
5. Stap 3: ontwerp tools die een klein model kan gebruiken
Een model van 35 MB leest uw hele toolset als onderdeel van de prompt en heeft geen retrievalstap, dus het ontwerp van de tools bepaalt de nauwkeurigheid. Cactus raadt vijf tools of minder aan, eenvoudige namen zonder gedeelde prefixen, gesloten keuzes als enums en begrensde getallen [2]. De engine compileert uw schema's tot een grammatica, zodat elk argument dat hij teruggeeft aan het schema voldoet; strakkere schema's laten dus minder ruimte voor fouten.
- Gebruik
typing.Literal[...]voor gesloten verzamelingen (ruimtes, prioriteiten, categorieën). - Begrens getallen met
Annotated[int, cactus.Field(ge=0, le=100)][2]. - Schrijf de docstring als één eenvoudige zin, met
Args:-regels voor alles wat dubbelzinnig is. - Geef feiten zoals de datum en de locale door via
system=, bijvoorbeeld"date: 2026-11-16 Mon 10:00; locale: en-GB", zodat "morgen om 7 uur" kan worden opgelost [2].
6. Stap 4: confidence gating en een terugvaloptie
Elk antwoord bevat een confidence-score tussen 0 en 1. De engine verplaatst aanroepen onder 0,1 al naar suppressed_calls; daarboven is de drempel een productbeslissing van uzelf [2]. Het script hieronder handelt bij 0,7 of hoger, vraagt daaronder om bevestiging en stuurt weigeringen naar een OpenAI-compatibel chatendpoint dat u zelf beheert (een vLLM- of llama.cpp-server op uw eigen GPU-machine, of een cloud-API waar de data dat toestaat). Zonder geconfigureerd endpoint geeft het het verzoek door aan een mens.
import json
import os
import urllib.request
from typing import Literal
import cactus
CONFIDENCE_FLOOR = 0.7 # tune per product on your own test set
@cactus.tool
def set_lights(room: Literal["kitchen", "lounge", "office"], brightness: int):
"""Set a room's light brightness.
Args:
room: which room
brightness: brightness in percent, 0 to 100
"""
return {"room": room, "brightness": brightness}
@cactus.tool
def create_ticket(summary: str, priority: Literal["low", "normal", "urgent"] = "normal"):
"""Open a support ticket.
Args:
summary: one-line description of the problem
"""
return {"ticket": "T-1001", "summary": summary, "priority": priority}
TOOLS = {"set_lights": set_lights, "create_ticket": create_ticket}
def cloud_fallback(text: str) -> dict:
"""Send the request to an OpenAI-compatible endpoint you control, if configured."""
url = os.environ.get("FALLBACK_URL") # e.g. http://gpu-box:8000/v1/chat/completions
if not url:
return {"route": "human", "note": "no fallback configured; ask the user to confirm"}
body = json.dumps({
"model": os.environ.get("FALLBACK_MODEL", "default"),
"messages": [{"role": "user", "content": text}],
}).encode()
req = urllib.request.Request(url, body, {"Content-Type": "application/json"})
with urllib.request.urlopen(req, timeout=20) as resp:
answer = json.load(resp)["choices"][0]["message"]["content"]
return {"route": "cloud", "answer": answer}
def handle(agent, text: str) -> dict:
agent.reset()
r = agent.complete(text)
calls, held = r["function_calls"], r.get("suppressed_calls") or []
conf = r["confidence"]
if calls and conf is not None and conf >= CONFIDENCE_FLOOR:
results = [TOOLS[c["name"]](**c["arguments"]) for c in calls]
return {"route": "local", "confidence": conf, "results": results}
if calls or held:
return {"route": "confirm", "confidence": conf, "proposed": calls or held}
return cloud_fallback(text)
if __name__ == "__main__":
with cactus.Cactus(tools=list(TOOLS.values()),
system="date: 2026-11-16 Mon 10:00; locale: en-GB") as agent:
for text in [
"dim the kitchen to 20 percent",
"the printer on floor 2 is on fire, raise it as urgent",
"write me a haiku about invoices",
]:
print(text, "->", json.dumps(handle(agent, text)))
Onze uitvoer, zonder geconfigureerde terugvaloptie:
dim the kitchen to 20 percent -> {"route": "local", "confidence": 0.9622, "results": [{"room": "kitchen", "brightness": 20}]}
the printer on floor 2 is on fire, raise it as urgent -> {"route": "confirm", "confidence": 0.3689, "proposed": [{"name": "set_lights", "arguments": {"room": "lounge", "brightness": 100}}]}
write me a haiku about invoices -> {"route": "human", "note": "no fallback configured; ask the user to confirm"}
De tweede regel is de reden voor de gate. Het model koos de volledig verkeerde tool, maar met lage confidence, dus de gebruiker zou een bevestigingsvraag hebben gezien in plaats van dat de lampen in de lounge aangingen. Het derde verzoek werd terecht geweigerd. Stel FALLBACK_URL (bijvoorbeeld http://gpu-box:8000/v1/chat/completions) en FALLBACK_MODEL in om weigeringen naar een groter model te routeren.
7. Stap 5: gestructureerde extractie die verzonnen waarden weigert
cactus.extract() declareert uw record als de enige tool en geeft de velden terug. In strikte modus (de standaard) werpt het ExtractionValidationError op als een waarde niet in de tekst is verankerd [2].
import cactus
INVOICE = {
"name": "invoice",
"description": "An invoice record",
"parameters": {
"type": "object",
"properties": {
"vendor": {"type": "string"},
"total": {"type": "number"},
"currency": {"type": "string"},
},
"required": ["vendor", "total"],
},
}
for text in [
"Invoice from Acme Ltd. Amount due: 1200 GBP.",
"Invoice from Acme Ltd, total GBP 1,200.00, due 30 November.",
]:
try:
print("ok:", cactus.extract(text, INVOICE))
except cactus.ExtractionValidationError as err:
print("rejected:", err)
print(" unchecked value would have been:", cactus.extract(text, INVOICE, strict=False))
ok: {'vendor': 'Acme Ltd. Amount', 'total': 1200.0}
rejected: extraction returned values not grounded in the input: total
unchecked value would have been: {'vendor': 'Acme Ltd', 'total': 12200.0, 'currency': 'GBP'}
Twee lessen uit één kleine test. De strikte modus ving een fout totaalbedrag (12.200 in plaats van 1.200) dat anders in uw systeem was beland. En het eerste resultaat kwam door de strikte modus met een rommelige leveranciersnaam ("Acme Ltd. Amount"), omdat verankering controleert of een waarde uit de tekst komt, niet of het het juiste fragment is. Houd uw eigen validatie aan voor alles wat ertoe doet.
8. Stap 6: spraak
Whistle heeft 16 kHz mono-WAV nodig, of 16 kHz float-samples. Maak een testfragment:
# macOS: synthesise a test clip and convert it to 16 kHz mono WAV
say -o lights.aiff "Turn the office lights down to forty percent."
afconvert -f WAVE -d LEI16@16000 -c 1 lights.aiff lights.wav
# Linux or Windows: convert any recording with ffmpeg
ffmpeg -i recording.m4a -ar 16000 -ac 1 lights.wav
import json
from typing import Literal
import cactus
@cactus.tool
def set_lights(room: Literal["kitchen", "lounge", "office"], brightness: int):
"""Set a room's light brightness.
Args:
room: which room
brightness: brightness in percent, 0 to 100
"""
return {"room": room, "brightness": brightness}
# 1. Plain transcription with word timestamps
t = cactus.transcribe("lights.wav", language="en", word_timestamps=True)
print(t["text"], "| ttft_ms:", t["ttft_ms"])
print([(w["word"] if "word" in w else w, w.get("start"), w.get("end")) for w in t["words"][:3]])
# 2. Speech straight to a tool call (no separate transcription step)
with cactus.Cactus(tools=[set_lights]) as agent:
r = agent.complete(audio="lights.wav", language="en")
print(r["audio_text"], "->", json.dumps(r["function_calls"]), r["confidence"])
Turn the office lights down to 40%. | ttft_ms: 298.1
[('Turn', 0.0, 0.24), ('the', 0.24, 0.4), ('office', 0.4, 0.64)]
Turn the office lights down to 40%. -> [{"name": "set_lights", "arguments": {"room": "office", "brightness": 40}}] 0.9515
Door audio= aan complete() mee te geven, gaat u in één stap van spraak naar een toolcall en krijgt u het transcript terug als audio_text [2]. Voor een fragment van 5 seconden duurde de transcriptie na het laden 0,74 seconden. Voor live microfooninvoer neemt cactus.stream() fragmenten van ongeveer een seconde en levert het definitieve tekst terwijl het loopt; installeer cactus-compute[mic] voor microfoonopname en resampling [2].
Beperkingen die het weten waard zijn: zeven talen (Engels, Duits, Frans, Spaans, Italiaans, Nederlands, Pools); stilte levert lege tekst op, maar muziek en ander geluid kunnen woorden opleveren, dus zet een voice activity detector of wake word voor een microfoon die altijd aanstaat [2]. Cactus meldt dat Whistle Whisper base verslaat op verschillende testsets voor word error rate en op andere verliest, bij 16,9 MB tegenover 145,3 MB [6]. Wij hebben die benchmarks niet gereproduceerd; onze testfragmenten waren synthetische spraak, wat makkelijker is dan een echte ruimte.
9. Stap 7: vision
import json
from PIL import Image, ImageDraw, ImageFont
from cactus import Mirage
# Make a test image so the example is self-contained
img = Image.new("RGB", (640, 400), "white")
draw = ImageDraw.Draw(img)
font = ImageFont.load_default(size=40)
draw.text((40, 40), "INVOICE 1042", fill="black", font=font)
draw.text((40, 120), "Total: GBP 1,200.00", fill="black", font=font)
draw.ellipse((420, 220, 560, 360), fill="red")
img.save("card.png")
vision = Mirage()
# Text lines with confidence (boxes are on a 0-1000 grid)
for line in vision.describe("card.png", sections=["text"])["text"]:
print(f'{line["score"]:.2f} {line["string"]} {line["bbox"]}')
# Fill a small form with closed choices
form = {
"document_type": {"enum": ["invoice", "receipt", "letter", "other"]},
"has_red_circle": {"enum": ["yes", "no"]},
}
for field, answer in vision.extract("card.png", form)["form"].items():
print(field, "->", answer["value"])
0.38 INVOICE [66, 113, 321, 210]
0.70 INVOICE 1042 [60, 108, 464, 216]
0.50 1042 [321, 109, 472, 216]
0.37 Total: GBP [55, 304, 369, 420]
0.67 Total: GBP 1,200.00 [52, 303, 620, 423]
0.51 1,200.00 [381, 310, 612, 418]
document_type -> invoice
has_red_circle -> None
Tekst lezen werkte, met overlappende kandidaten op verschillende confidenceniveaus; bewaar per regio de regel met de hoogste score. Kaders komen terug op een raster van 0 tot 1.000, niet in pixels (de rode cirkel in onze afbeelding van 640 bij 400 kwam terug rond x 650 tot 880). Het formulier beantwoordde de ene vraag en onthield zich bij de andere (None, met de kansen in het volledige resultaat). In een eerdere run met een ander lettertype beantwoordde het de vraag over de rode cirkel verkeerd. Mirage is nuttig voor het lezen van tekst en een ruwe lay-out; valideer voor beslissingen op uw eigen afbeeldingen en gate op de teruggegeven kansen.
10. Stap 8: latentie en geheugen meten
import os
import statistics
import time
import cactus
cactus.set_threads(int(os.environ.get("CACTUS_THREADS", "1")))
@cactus.tool
def set_lights(room: str, brightness: int):
"Set a room's light brightness in percent."
return {"room": room, "brightness": brightness}
QUERIES = ["dim the kitchen to 30 percent", "office lights to 80", "turn the lounge down to 10"]
t0 = time.perf_counter()
agent = cactus.Cactus(tools=[set_lights])
print(f"load: {time.perf_counter() - t0:.2f}s")
agent.complete(QUERIES[0]) # warm-up, not counted
wall, decode, ram = [], [], []
for i in range(30):
agent.reset()
t = time.perf_counter()
r = agent.complete(QUERIES[i % len(QUERIES)])
wall.append((time.perf_counter() - t) * 1000)
decode.append(r["decode_tps"])
ram.append(r["peak_ram_mb"])
agent.close()
wall.sort()
print(f"p50 {statistics.median(wall):.0f} ms p95 {wall[int(0.95 * len(wall)) - 1]:.0f} ms")
print(f"decode median {statistics.median(decode):.0f} tok/s peak RAM {max(ram):.0f} MB")
Draai het met CACTUS_THREADS=1 python bench.py, daarna met 0 (alle cores) en 4. Twee van onze runs:
CACTUS_THREADS=1: p50 105 ms p95 112 ms decode median 451 tok/s peak RAM 136 MB
CACTUS_THREADS=0: p50 81 ms p95 167 ms decode median 534 tok/s peak RAM 136 MB
Onze Mac werd gedeeld met andere zware jobs, wat nuttig bleek. Toen ander werk de cores volledig belastte, duwde de standaardinstelling de mediaan naar 1,4 seconden en gaven vier threads een p95 van 22 seconden, terwijl één thread rond de 110 ms bleef. Een telefoon die tegelijk een UI rendert, kan dezelfde concurrentie tegenkomen. Begin met één of twee threads en meet op het traagste apparaat dat u ondersteunt. peak_ram_mb in elk antwoord is het eigen cijfer van de engine; het hele Python-proces piekte in onze runs op ongeveer 176 tot 197 MB.
11. Stap 9: verpakken om offline te draaien
Op het apparaat van een klant of in productie mag niets worden gedownload. Haal de engine en gewichten op tijdens de build en verwijs het pakket ernaar [3].
Een container die draait met het netwerk uitgeschakeld
FROM python:3.12-slim
ENV CACTUS_TELEMETRY=0 \
XDG_CACHE_HOME=/opt/cache \
PIP_NO_CACHE_DIR=1
RUN pip install "cactus-compute==4.2.2"
# Fetch the engine and the weights at build time; nothing downloads at run time.
RUN cactus fetch \
&& cactus download needle3 --out /opt/models \
&& chmod -R a+rX /opt/cache /opt/models
ENV HF_HUB_OFFLINE=1 \
CACTUS_NEEDLE_WEIGHTS=/opt/models/needle3.cact
RUN useradd --create-home app
USER app
WORKDIR /app
COPY app.py .
CMD ["python", "app.py"]
docker build -t cactus-edge-demo .
docker run --rm --network none cactus-edge-demo
Wij bouwden dit op Apple silicon (dus een Linux arm64-image van ongeveer 134 MB) met gated.py als app.py, en het drukte met uitgeschakeld netwerk dezelfde drie routes af als in stap 4. Eén valkuil waar wij in liepen: cactus download needle3 op zich schrijft naar de huidige map, dus zonder --out en CACTUS_NEEDLE_WEIGHTS probeerde de non-rootgebruiker de gewichten tijdens runtime opnieuw te downloaden en faalde op een alleen-lezen cache.
Een air-gapped Linux-apparaat
# On a connected machine with the same OS, CPU architecture and Python as the device
pip download "cactus-compute==4.2.2" -d wheels
cactus fetch --platform-tag manylinux2014_aarch64 --out ./engine # Linux Arm64 engine
cactus download needle3 --out ./models
# Copy wheels/, engine/ and models/ to the device, then on the device:
pip install --no-index --find-links wheels cactus-compute
export HF_HUB_OFFLINE=1 CACTUS_TELEMETRY=0
export CACTUS_LIB_PATH=$PWD/engine/libcactus.so
export CACTUS_NEEDLE_WEIGHTS=$PWD/models/needle3.cact
Wij controleerden het equivalent op macOS met een lege cachemap, HF_HUB_OFFLINE=1 en de twee omgevingsvariabelen ingesteld: de toolcall draaide zonder het netwerk aan te raken. Gebruik CACTUS_WHISTLE_WEIGHTS en CACTUS_MIRAGE_WEIGHTS voor de andere modellen [3].
Mobiele apps en browserapps
Voor apps buiten Python haalt cactus download <platform> --model needle3 een native build op: iOS, tvOS en watchOS krijgen een statische bibliotheek en een C-header (cactus.h); Android en Linux krijgen ook een commandline-runner; het browserdoel is WebAssembly [5]. Voor deze notitie hebben wij geen mobiele app gebouwd; volg de deploymenthandleiding van Cactus en behandel het als een C-bibliotheek die u in Swift of Kotlin verpakt.
12. Testen en evalueren vóór u uitlevert
De enige nauwkeurigheidscijfers die ertoe doen, zijn die op uw verzoeken. Schrijf een testbestand met echte vragen en de verwachte aanroep, inclusief vragen die geweigerd moeten worden, en scoor het bij meerdere drempels:
{"query": "dim the kitchen to 20 percent", "expect": {"name": "set_lights", "arguments": {"room": "kitchen", "brightness": 20}}}
{"query": "the wifi in the office keeps dropping", "expect": {"name": "create_ticket"}}
{"query": "what's the capital of France?", "expect": null}
import json
import sys
import cactus
from gated import TOOLS # reuse the tool definitions
def matches(call, expect):
if expect is None:
return call is None
if call is None or call["name"] != expect["name"]:
return False
wanted = expect.get("arguments", {})
return all(call["arguments"].get(k) == v for k, v in wanted.items())
cases = [json.loads(line) for line in open(sys.argv[1])]
rows = []
with cactus.Cactus(tools=list(TOOLS.values()), system="locale: en-GB") as agent:
for case in cases:
agent.reset()
r = agent.complete(case["query"])
call = r["function_calls"][0] if r["function_calls"] else None
rows.append((r["confidence"] or 0.0, call is not None, matches(call, case["expect"]), case))
for threshold in (0.0, 0.5, 0.7, 0.9):
acted = [row for row in rows if row[1] and row[0] >= threshold]
wrong = [row for row in acted if not row[2]]
missed = sum(1 for row in rows if row[3]["expect"] is not None and row not in acted)
print(f"threshold {threshold:.1f}: acted on {len(acted)}/{len(rows)}, "
f"wrong actions {len(wrong)}, not acted (sent to confirm/fallback) {missed}")
for conf, has_call, ok, case in rows:
print(f"{conf:.2f} {'ok ' if ok else 'BAD'} {case['query']}")
Op ons bestand met zeven gevallen (sla het op als cases.jsonl naast gated.py en draai python evaluate.py cases.jsonl):
threshold 0.0: acted on 4/7, wrong actions 0, not acted (sent to confirm/fallback) 1
threshold 0.5: acted on 4/7, wrong actions 0, not acted (sent to confirm/fallback) 1
threshold 0.7: acted on 3/7, wrong actions 0, not acted (sent to confirm/fallback) 2
threshold 0.9: acted on 3/7, wrong actions 0, not acted (sent to confirm/fallback) 2
0.95 ok dim the kitchen to 20 percent
0.97 ok office lights to 75
0.96 ok make the lounge brighter, 90 percent
0.22 BAD the wifi in the office keeps dropping
0.62 ok log an urgent ticket: server room is overheating
0.96 ok what's the capital of France?
0.90 ok write me a poem
Zeven gevallen bewijzen statistisch niets; 100 tot 200 echte gevallen per tooloppervlak is een verstandig begin. Het gaat om de vorm: een hogere drempel ruilt acties in voor bevestigingen. Kies het punt waarop verkeerde acties zeldzaam genoeg zijn voor de taak, en draai het bestand opnieuw in CI telkens wanneer u de pakketversie, de gewichten of de tooldefinities wijzigt. Cactus levert zes kant-en-klare tooloppervlakken met acceptatiesuites in cactus.environments, en merkt op dat het basismodel vijf daarvan niet haalt bij de standaardgate [2], een nuttige herinnering dat de geschiktheid van een klein model afhangt van de tools.
Als het basismodel op uw tools niet nauwkeurig genoeg is, ondersteunt Cactus LoRA-fine-tuning (een goedkope manier om een model aan te passen door kleine extra gewichtsmatrices te trainen) lokaal met cactus-compute[train], of op het betaalde gehoste platform, wat een nieuwe .cact oplevert die u laadt met weights= [2]. Let op: lokaal gefinetunede gewichten bevatten de kalibratiekop niet, dus confidence komt terug als None [2]; u hebt dan een andere gate nodig.
13. Draaien in productie
- Pin alles vast. De pakketversie, en het gewichtenbestand waarmee u hebt getest. Wekelijkse releases zijn normaal voor dit project.
- Threads. Stel
cactus.set_threads()expliciet in, vóór het laden van modellen; begin met één of twee op gedeelde of mobiele CPU's. - Gelijktijdigheid. Tekst, spraak en vision delen één runtime en aanroepen worden over threads heen geserialiseerd [3]. Voor een server die veel verzoeken afhandelt, draait u meerdere workerprocessen in plaats van threads.
- Beveiliging. Het model kiest welke van uw functies wordt aangeroepen. Stel alleen functies beschikbaar die veilig zijn om uit te voeren met willekeurige argumenten die aan het schema voldoen, en controleer argumenten en rechten opnieuw in de functie zelf.
- Monitoring. Log de route (lokaal, bevestigen, terugval), confidence, latentie,
peak_ram_mben of de gebruiker de actie heeft gecorrigeerd. Log geen transcripten of geëxtraheerde persoonsgegevens, tenzij u ze nodig hebt en een grondslag hebt om ze te bewaren. - Privacy. Schakel telemetrie uit waar uw beleid dat vereist, en onthoud dat het terugvalpad data van het apparaat af stuurt: pas daar dezelfde dataregels toe.
14. Valkuilen en debuggen
- Overal lege
function_calls. Het verzoek past niet bij een tool, of de toolbeschrijving is onduidelijk. Controleer het veldreasoningen herschrijf de docstring. confidenceisNone. U hebt lokaal gefinetunede gewichten geladen zonder de kalibratiekop [2].ExtractionValidationError. Een waarde is niet in de tekst gevonden. Schakel niet over opstrict=Falseom het te laten verdwijnen; onderzoek het.- PermissionError bij het starten in een container. Het pakket probeert te downloaden naar een cache waarin het niet kan schrijven. Lever de bestanden mee en stel
CACTUS_NEEDLE_WEIGHTSenHF_HUB_OFFLINE=1in. - Latentiepieken. CPU-concurrentie bij multithreading. Probeer
set_threads(1). - Verkeerde samplerate. Whistle verwacht 16 kHz mono; converteer, of installeer de extra
[mic]voor resampling [1].
15. Hoe het zich verhoudt tot de alternatieven
| Optie | Wat u draait | Typische grootte | Het best voor | Afwegingen |
|---|---|---|---|---|
Cactus (cactus-compute) | De eigen Needle-, Whistle- en Mirage-modellen van Cactus op één engine | 17 tot 35 MB per model | Smalle toolcalls, extractie, korte spraak, OCR op elke CPU, offline | Geen vrije tekst; kleine toolsets; jong project; weinig onafhankelijke benchmarks |
| llama.cpp (en Ollama daarbovenop) | Open LLM's en sommige visionmodellen in GGUF-formaat [11] | Honderden MB tot tientallen GB | Algemene chat, teksten opstellen en toolgebruik met modellen van 1B tot 70B+ op laptops en servers | Veel meer geheugen; betrouwbaarheid van toolcalls verschilt per model |
| MLC LLM | Open LLM's gecompileerd voor telefoons, browsers en GPU's [14] | Honderden MB en meer | Modellen van chatklasse binnen mobiele apps en webapps | Compilatiestap per model en doelplatform |
| ONNX Runtime | Uw eigen model, geëxporteerd naar ONNX [12] | Wat u ook exporteert | Een zelf getraind model uitleveren over platforms en accelerators | U bent zelf verantwoordelijk voor training, export en pre-/postprocessing |
| ExecuTorch | Uw PyTorch-model, geëxporteerd voor edge-apparaten; 1.0 sinds oktober 2025 [13] | Wat u ook exporteert | PyTorch-teams die zich richten op telefoons en embedded NPU's | Meer engineering; u levert zelf het model |
| NVIDIA TensorRT Edge-LLM | LLM's, vision-language- en spraakmodellen op Jetson, DRIVE en DGX Spark [10] | Modellen in de GB-klasse | Robots, voertuigen en edge-systemen met NVIDIA-GPU's; de eigen Nemotron-modellen van NVIDIA | Alleen NVIDIA-hardware; engines per apparaat gebouwd |
De eigen on-devicekoers van NVIDIA is gericht op grotere modellen op NVIDIA-edgehardware: Nemotron 3 Nano Omni is bijvoorbeeld een mixture-of-expertsmodel met 30B parameters en ongeveer 3B actief per token, onder meer gericht op Jetson en DGX Spark [15]. Dat is een andere klasse dan een CPU-model van 35 MB. Een verstandige architectuur gebruikt vaak beide: een piepklein model op het apparaat van de gebruiker voor de frequente, smalle verzoeken, en een groter model op een GPU-server die u zelf beheert voor de terugval.
16. Veelgestelde vragen
Is dit een NVIDIA-product? Nee. Cactus Compute bouwt en publiceert het onder Apache 2.0, inclusief de vooraf gebouwde runtimebinaries [1]. De dichtstbijzijnde link met NVIDIA is dat Cactus ook een Mac-runner levert, cactus-mlx, voor gecomprimeerde checkpoints van de Nemotron-modellen van NVIDIA [1].
Kan Needle vragen beantwoorden of tekst samenvatten? Nee. Het geeft alleen toolcalls of geëxtraheerde velden terug. Gebruik een groter model voor lopende tekst.
Welke talen ondersteunt spraak? Engels, Duits, Frans, Spaans, Italiaans, Nederlands en Pools; met fine-tuning kunnen andere worden toegevoegd [2].
Mag ik het commercieel gebruiken? De code en runtimebinaries vallen onder Apache 2.0 [1], en de modelkaart van Mirage vermeldt Apache 2.0 [7]. Controleer voor elk model dat u uitlevert de licentie op de Hugging Face-kaart ervan.
Als u moet beslissen welk AI-werk op apparaten, op uw eigen GPU-servers of in de cloud moet draaien, en u de private kant gebouwd en beheerd wilt hebben, bekijk dan hoe wij private AI aanpakken.
Referenties
- cactus-compute/cactus: README, GitHub, Cactus Compute.
- Cactus API reference (llms.txt), Cactus Compute.
- Needle Python API and CLI documentation, Cactus Compute.
- Needle supported devices, Cactus Compute.
- Cactus runtime binaries and platforms, Hugging Face.
- Whistle announcement, Cactus Compute, 2 oktober 2026.
- Mirage model card, Hugging Face.
- cactus-compute op PyPI (releasegeschiedenis).
- Bedrijfspagina van Cactus Compute, Y Combinator.
- TensorRT Edge-LLM overview, NVIDIA.
- llama.cpp, GitHub.
- ONNX Runtime, Microsoft.
- Introducing ExecuTorch 1.0, PyTorch.
- MLC LLM, GitHub.
- NVIDIA Nemotron 3 Nano Omni, NVIDIA-blog, 28 april 2026.
Alle code in deze notitie is door Workstation uitgevoerd op 16 november 2026 met cactus-compute 4.2.2 op een Apple M4 Max en in een Linux arm64-container; de uitvoer is uit die runs gekopieerd. Prestatiecijfers zijn indicatief, gemeten op een gedeelde machine. Andere cijfers zijn claims van leveranciers. Deze notitie is onafhankelijk en wordt niet onderschreven door Cactus Compute of NVIDIA. NVIDIA, Jetson, DRIVE, DGX, Nemotron en TensorRT zijn handelsmerken van NVIDIA Corporation. Andere namen zijn eigendom van hun respectieve eigenaren.