Ein Praxisleitfaden für KI-Entwickler, die schon heute kleine agentische, Sprach- und Bildmodelle auf dem Gerät betreiben möchten. Wir installieren die Open-Source-Engine von Cactus Compute, führen einen Tool-Call aus, ergänzen eine Konfidenzschwelle und einen Rückfall auf ein größeres Modell, extrahieren strukturierte Daten, verarbeiten Sprache und Bilder, messen Latenz und Speicher und paketieren schließlich alles so, dass es bei abgeschaltetem Netzwerk läuft. Jedes der folgenden Beispiele wurde auf unserer eigenen Hardware ausgeführt, und wir zeigen die tatsächliche Ausgabe, einschließlich der Stellen, an denen die Modelle falschlagen.
pip install cactus-compute liefert Ihnen drei kleine Modelle auf einer nativen Engine: Needle 3 (35,3 MB) verwandelt eine Anfrage in einen Aufruf einer Ihrer Python-Funktionen oder extrahiert Felder aus Text; Whistle (16,9 MB) transkribiert Sprache in sieben europäischen Sprachen; Mirage (21,6 MB) liefert Objekte, Text und einfache Formularantworten aus einem Bild. Sie laufen auf einer CPU, nach dem ersten Download offline. In unseren Läufen dauerte ein Tool-Call etwa 70 bis 110 ms bei 136 MB Spitzenspeicher. Die Modelle sind eng spezialisiert und liegen manchmal falsch, daher beruht der Produktiveinsatz auf drei Gewohnheiten: strikte Schemas, eine anhand Ihres eigenen Testsets gewählte Konfidenzschwelle und ein Eskalationspfad zu einem größeren Modell oder einem Menschen.
Diese Technote begleitet unseren Blogbeitrag On-Device-KI unter 50 MB: Was die Engine von Cactus für Unternehmen bedeutet, der den Business Case behandelt. Vorab eine Richtigstellung: Diese Engine wird mitunter als NVIDIA-Produkt bezeichnet. Das ist sie nicht. Sie wird von Cactus Compute entwickelt, einem Y-Combinator-Unternehmen, und unter Apache 2.0 veröffentlicht [1][9]. Stand der Fakten und Versionen: 16. November 2026.
1. Für wen, was Sie bauen werden, was Sie brauchen
Für wen. Python-Entwickler und ML-Ingenieure, die KI-Funktionen ohne Netzwerk-Roundtrip wünschen: Sprachbefehle in einer Außendienst-App, ein Kiosk, der Dokumente liest, ein Support-Tool, das aus einer Nachricht ein Ticket macht, oder ein Gerät, das offline weiterarbeiten muss.
Was Sie bauen werden. Einen ersten Tool-Call; einen per Konfidenzschwelle abgesicherten Agenten, der handelt, nachfragt oder an einen OpenAI-kompatiblen Endpunkt eskaliert; eine Extraktion, die erfundene Werte ablehnt; Sprache zu einem Tool-Call; Texterkennung in Bildern; einen Latenz-Benchmark und ein Evaluierungs-Harness; und einen Offline-Container.
Voraussetzungen. Python 3.9 oder neuer [1]; macOS auf Apple Silicon, Linux (x86-64 oder Arm64) oder Windows, unter den von Cactus genannten Plattformen [4]; etwa 200 MB freier Speicherplatz für Paket, Engine und alle drei Modelle; Internetzugang nur für den ersten Download. Eine GPU ist nicht erforderlich. Wir haben einen Apple M4 Max mit macOS 26.7, Python 3.15 und cactus-compute 4.2.2 (Engine 4.1.1) verwendet, dazu Docker für den Linux-arm64-Container.
2. Wie die Teile zusammenpassen
Das Python-Paket ist eine dünne Schicht: Es wandelt Ihre Funktionen in JSON-Schemas um, führt die Agentenschleife aus, prüft, ob Argumente in der Eingabe verankert sind, und meldet einen Konfidenzwert. Es ruft eine native Engine-Bibliothek auf, die pro Modell eine separate Gewichtsdatei (.cact) lädt [2]. Bei der ersten Nutzung werden Engine und Gewichte zu fixierten Commits von Hugging Face heruntergeladen, gegen SHA-256-Prüfsummen geprüft und unter ~/.cache/cactus zwischengespeichert [2][3].
Zwei Dinge sollten Sie vorab wissen. Erstens schreibt Needle 3 keine Prosa. Es gibt einen Tool-Call zurück oder eine leere Liste, wenn die Anfrage nicht zum Thema passt, was einer Ablehnung entspricht [2]. Wenn Sie geschriebene Antworten benötigen, brauchen Sie ein größeres Modell (siehe den Vergleich in Abschnitt 13). Zweitens beschreibt Cactus die Engine als „unter 1 MB“ [2]; die unkomprimierten Bibliotheken, die wir heruntergeladen haben, waren unter macOS 1,4 MB und unter Linux Arm64 1,8 MB groß. Jedes Modell zusammen mit der Engine liegt dennoch deutlich unter 50 MB.
3. Schritt 1: Installation
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
Die Versionsfixierung ist wichtig: Das Paket ging im November 2026 innerhalb von elf Tagen von 4.0.0 auf 4.2.3 [8]. import cactus zieht kein JAX nach; JAX wird nur für das optionale Fine-Tuning-Extra cactus-compute[train] benötigt [2]. Das Paket sendet anonyme Nutzungszählungen (Funktionsname, Version, Betriebssystem und eine zufällige Installations-ID), sofern nicht CACTUS_TELEMETRY=0 oder DO_NOT_TRACK=1 gesetzt ist [1][2].
4. Schritt 2: Ihr erster Tool-Call
Dies ist das README-Beispiel [1], erweitert, um beide Arten der Agentensteuerung zu zeigen.
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"])
Führen Sie es mit python hello.py aus. Beim ersten Lauf werden die Engine und die 35-MB-Gewichte heruntergeladen (bei uns etwa 10 Sekunden); spätere Läufe laden in deutlich unter einer Sekunde aus dem Cache. Unsere Ausgabe:
{"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'}]
Was passiert ist:
@cactus.toolwandelt Funktionssignatur und Docstring in ein JSON-Schema um. Type Hints werden zu Argumenttypen; ein Standardwert macht ein Argument optional [2].complete()führt einen Durchgang aus und gibt den vorgeschlagenen Aufruf zurück, ohne etwas auszuführen. Verwenden Sie es, wenn Sie vor dem Handeln prüfen oder bestätigen möchten.run()führt die Schleife aus: Das Modell wählt Aufrufe, Cactus führt Ihre Funktionen aus, gibt die Ergebnisse zurück und liefert sie unterresults[2].reset()löscht die Konversation, behält aber die Tools. Ein Toolset pro Agent: Um Tools zu ändern, erstellen Sie ein neuesCactus[2].
5. Schritt 3: Tools entwerfen, die ein kleines Modell nutzen kann
Ein 35-MB-Modell liest Ihr gesamtes Toolset als Teil seines Prompts und hat keinen Retrieval-Schritt, daher bestimmt das Tool-Design die Genauigkeit. Cactus empfiehlt höchstens fünf Tools, einfache Namen ohne gemeinsame Präfixe, geschlossene Auswahlmöglichkeiten als Enums und begrenzte Zahlen [2]. Die Engine kompiliert Ihre Schemas zu einer Grammatik, sodass jedes zurückgegebene Argument dem Schema entspricht; engere Schemas lassen daher weniger Raum für Fehler.
- Verwenden Sie
typing.Literal[...]für geschlossene Mengen (Räume, Prioritäten, Kategorien). - Begrenzen Sie Zahlen mit
Annotated[int, cactus.Field(ge=0, le=100)][2]. - Schreiben Sie den Docstring als einen einfachen Satz, mit
Args:-Zeilen für alles Mehrdeutige. - Übergeben Sie Fakten wie Datum und Gebietsschema über
system=, zum Beispiel"date: 2026-11-16 Mon 10:00; locale: en-GB", damit „morgen um 7“ aufgelöst werden kann [2].
6. Schritt 4: Konfidenzschwelle und Rückfallpfad
Jede Antwort enthält einen confidence-Wert zwischen 0 und 1. Die Engine verschiebt Aufrufe unter 0,1 bereits nach suppressed_calls; darüber ist die Schwelle Ihre Produktentscheidung [2]. Das folgende Skript handelt bei 0,7 oder mehr, fragt darunter nach einer Bestätigung und sendet Ablehnungen an einen OpenAI-kompatiblen Chat-Endpunkt, den Sie kontrollieren (ein vLLM- oder llama.cpp-Server auf Ihrem eigenen GPU-Rechner oder eine Cloud-API, sofern die Daten es erlauben). Ist kein Endpunkt konfiguriert, übergibt es die Anfrage an einen Menschen.
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)))
Unsere Ausgabe, ohne konfigurierten Rückfallpfad:
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"}
Die zweite Zeile ist der Grund für die Schwelle. Das Modell wählte ein völlig falsches Tool, aber mit geringer Konfidenz, sodass der Nutzer eine Bestätigungsabfrage gesehen hätte, statt dass das Licht im Wohnzimmer angeht. Die dritte Anfrage wurde korrekt abgelehnt. Setzen Sie FALLBACK_URL (zum Beispiel http://gpu-box:8000/v1/chat/completions) und FALLBACK_MODEL, um Ablehnungen an ein größeres Modell weiterzuleiten.
7. Schritt 5: Strukturierte Extraktion, die erfundene Werte ablehnt
cactus.extract() deklariert Ihren Datensatz als einziges Tool und gibt die Felder zurück. Im strikten Modus (der Standard) löst es ExtractionValidationError aus, wenn ein Wert nicht im Text verankert ist [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'}
Zwei Lehren aus einem kleinen Test. Der strikte Modus fing eine falsche Summe ab (12.200 statt 1.200), die sonst in Ihr System gelangt wäre. Und das erste Ergebnis bestand den strikten Modus mit einem unsauberen Lieferantennamen („Acme Ltd. Amount“), weil die Verankerungsprüfung kontrolliert, ob ein Wert aus dem Text stammt, nicht ob es der richtige Ausschnitt ist. Behalten Sie Ihre eigene Validierung für alles, was wichtig ist.
8. Schritt 6: Sprache
Whistle benötigt 16-kHz-Mono-WAV oder 16-kHz-Float-Samples. Erstellen Sie einen Testclip:
# 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
Wenn Sie audio= an complete() übergeben, gelangen Sie in einem Schritt von Sprache zu einem Tool-Call und erhalten das Transkript als audio_text [2]. Für einen 5-Sekunden-Clip dauerte die Transkription nach dem Laden 0,74 Sekunden. Für Live-Mikrofoneingaben nimmt cactus.stream() Abschnitte von etwa einer Sekunde entgegen und liefert fortlaufend bestätigten Text; installieren Sie cactus-compute[mic] für Mikrofonaufnahme und Resampling [2].
Wissenswerte Grenzen: sieben Sprachen (Englisch, Deutsch, Französisch, Spanisch, Italienisch, Niederländisch, Polnisch); Stille liefert leeren Text, Musik und andere Geräusche können aber Wörter erzeugen, schalten Sie daher vor ein ständig aktives Mikrofon eine Sprachaktivitätserkennung oder ein Aktivierungswort [2]. Cactus berichtet, dass Whistle Whisper base auf mehreren Testsets zur Wortfehlerrate schlägt und auf anderen unterliegt, bei 16,9 MB gegenüber 145,3 MB [6]. Wir haben diese Benchmarks nicht reproduziert; unsere Testclips waren synthetische Sprache, die einfacher ist als ein echter Raum.
9. Schritt 7: Bildverarbeitung
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
Die Texterkennung funktionierte, mit überlappenden Kandidaten auf unterschiedlichen Konfidenzniveaus; behalten Sie pro Bereich die Zeile mit dem höchsten Wert. Die Rahmen werden auf einem Raster von 0 bis 1.000 zurückgegeben, nicht in Pixeln (der rote Kreis unseres Bildes mit 640 mal 400 Pixeln kam bei etwa x 650 bis 880 zurück). Das Formular beantwortete eine Frage und enthielt sich bei der anderen (None, mit den Wahrscheinlichkeiten im vollständigen Ergebnis). In einem früheren Lauf mit einer anderen Schriftart beantwortete es die Frage zum roten Kreis falsch. Mirage ist nützlich zum Lesen von Text und für grobe Layouts; für Entscheidungen validieren Sie mit Ihren eigenen Bildern und setzen eine Schwelle auf die zurückgegebenen Wahrscheinlichkeiten.
10. Schritt 8: Latenz und Speicher messen
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")
Führen Sie es mit CACTUS_THREADS=1 python bench.py aus, dann mit 0 (alle Kerne) und 4. Zwei unserer Läufe:
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
Unser Mac wurde mit anderen rechenintensiven Jobs geteilt, was sich als nützlich erwies. Als andere Arbeit die Kerne auslastete, trieb die Standardeinstellung den Median auf 1,4 Sekunden, und vier Threads ergaben ein p95 von 22 Sekunden, während ein Thread bei etwa 110 ms blieb. Ein Smartphone, das gleichzeitig die Benutzeroberfläche rendert, kann auf dieselbe Konkurrenz stoßen. Beginnen Sie mit einem oder zwei Threads und messen Sie auf dem langsamsten Gerät, das Sie unterstützen. peak_ram_mb in jeder Antwort ist der eigene Wert der Engine; der gesamte Python-Prozess erreichte in unseren Läufen Spitzenwerte von etwa 176 bis 197 MB.
11. Schritt 9: Für den Offline-Betrieb paketieren
Auf dem Gerät eines Kunden oder in der Produktion sollte nichts heruntergeladen werden. Laden Sie Engine und Gewichte zur Build-Zeit herunter und verweisen Sie das Paket darauf [3].
Ein Container, der bei abgeschaltetem Netzwerk läuft
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
Wir haben dies auf Apple Silicon gebaut (also ein Linux-arm64-Image von etwa 134 MB) mit gated.py als app.py, und es gab bei deaktiviertem Netzwerk dieselben drei Routen aus wie in Schritt 4. Eine Falle, in die wir getappt sind: cactus download needle3 allein schreibt in das aktuelle Verzeichnis, sodass der Nicht-Root-Benutzer ohne --out und CACTUS_NEEDLE_WEIGHTS versuchte, die Gewichte zur Laufzeit erneut herunterzuladen, und an einem schreibgeschützten Cache scheiterte.
Ein Air-Gapped-Linux-Gerät
# 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
Wir haben das Äquivalent unter macOS mit einem leeren Cache-Verzeichnis, HF_HUB_OFFLINE=1 und den beiden gesetzten Umgebungsvariablen geprüft: Der Tool-Call lief, ohne das Netzwerk zu berühren. Verwenden Sie CACTUS_WHISTLE_WEIGHTS und CACTUS_MIRAGE_WEIGHTS für die anderen Modelle [3].
Mobile Apps und Browser-Apps
Für Apps außerhalb von Python lädt cactus download <platform> --model needle3 einen nativen Build herunter: iOS, tvOS und watchOS erhalten eine statische Bibliothek und einen C-Header (cactus.h); Android und Linux erhalten zusätzlich einen Kommandozeilen-Runner; das Browser-Ziel ist WebAssembly [5]. Für diese Technote haben wir keine mobile App gebaut; folgen Sie dem Deployment-Leitfaden von Cactus und behandeln Sie es als C-Bibliothek, die Sie in Swift oder Kotlin einbinden.
12. Vor der Auslieferung testen und evaluieren
Die einzigen Genauigkeitswerte, die zählen, sind die mit Ihren Anfragen. Schreiben Sie eine Testdatei mit echten Anfragen und dem erwarteten Aufruf, einschließlich solcher, die abgelehnt werden sollten, und bewerten Sie sie dann bei mehreren Schwellen:
{"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']}")
Mit unserer Datei mit sieben Fällen (speichern Sie sie als cases.jsonl neben gated.py und führen Sie python evaluate.py cases.jsonl aus):
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
Sieben Fälle beweisen statistisch nichts; 100 bis 200 echte Fälle pro Tool-Oberfläche sind ein sinnvoller Anfang. Entscheidend ist das Muster: Eine höhere Schwelle tauscht Aktionen gegen Bestätigungen. Wählen Sie den Punkt, an dem falsche Aktionen für die Aufgabe selten genug sind, und führen Sie die Datei in der CI erneut aus, wann immer Sie die Paketversion, die Gewichte oder die Tool-Definitionen ändern. Cactus liefert in cactus.environments sechs vorgefertigte Tool-Oberflächen mit Abnahmetests mit und weist darauf hin, dass das Basismodell fünf davon bei der Standardschwelle nicht besteht [2], eine nützliche Erinnerung daran, dass die Eignung eines kleinen Modells von den Tools abhängt.
Ist das Basismodell für Ihre Tools nicht genau genug, unterstützt Cactus LoRA-Fine-Tuning (eine günstige Methode, ein Modell durch das Training kleiner zusätzlicher Gewichtsmatrizen anzupassen) lokal mit cactus-compute[train] oder auf seiner kostenpflichtigen gehosteten Plattform, was eine neue .cact ergibt, die Sie mit weights= laden [2]. Beachten Sie, dass lokal feinabgestimmte Gewichte keinen Kalibrierungskopf enthalten, sodass confidence als None zurückkommt [2]; Sie bräuchten dann eine andere Schwelle.
13. Betrieb in der Produktion
- Fixieren Sie alles. Paketversion und die Gewichtsdatei, mit der Sie getestet haben. Wöchentliche Releases sind bei diesem Projekt normal.
- Threads. Setzen Sie
cactus.set_threads()explizit, bevor Sie Modelle laden; beginnen Sie auf gemeinsam genutzten oder mobilen CPUs mit einem oder zwei. - Parallelität. Text, Sprache und Bild teilen sich eine Laufzeitumgebung, und Aufrufe werden über Threads hinweg serialisiert [3]. Für einen Server mit vielen Anfragen betreiben Sie mehrere Worker-Prozesse statt Threads.
- Sicherheit. Das Modell wählt, welche Ihrer Funktionen aufgerufen wird. Stellen Sie nur Funktionen bereit, deren Ausführung mit beliebigen schemakonformen Argumenten sicher ist, und prüfen Sie Argumente und Berechtigungen in der Funktion selbst erneut.
- Monitoring. Protokollieren Sie Route (lokal, Bestätigung, Rückfall), Konfidenz, Latenz,
peak_ram_mbund ob der Nutzer die Aktion korrigiert hat. Vermeiden Sie die Protokollierung von Transkripten oder extrahierten personenbezogenen Daten, sofern Sie sie nicht benötigen und keine Grundlage für ihre Aufbewahrung haben. - Datenschutz. Deaktivieren Sie die Telemetrie, wo Ihre Richtlinien es verlangen, und denken Sie daran, dass der Rückfallpfad Daten vom Gerät sendet: Wenden Sie dort dieselben Datenregeln an.
14. Fallstricke und Fehlersuche
- Überall leere
function_calls. Die Anfrage lässt sich keinem Tool zuordnen, oder die Tool-Beschreibung ist unklar. Prüfen Sie das Feldreasoningund schreiben Sie den Docstring um. confidenceistNone. Sie haben lokal feinabgestimmte Gewichte ohne den Kalibrierungskopf geladen [2].ExtractionValidationError. Ein Wert wurde im Text nicht gefunden. Wechseln Sie nicht zustrict=False, um den Fehler loszuwerden; untersuchen Sie ihn.- PermissionError beim Start in einem Container. Das Paket versucht, in einen Cache herunterzuladen, in den es nicht schreiben kann. Bündeln Sie die Dateien und setzen Sie
CACTUS_NEEDLE_WEIGHTSundHF_HUB_OFFLINE=1. - Latenzspitzen. CPU-Konkurrenz durch Multithreading. Versuchen Sie
set_threads(1). - Falsche Abtastrate. Whistle erwartet 16 kHz mono; konvertieren Sie oder installieren Sie das Extra
[mic]für das Resampling [1].
15. Vergleich mit den Alternativen
| Option | Was Sie ausführen | Typische Größe | Am besten für | Kompromisse |
|---|---|---|---|---|
Cactus (cactus-compute) | Die eigenen Modelle Needle, Whistle und Mirage von Cactus auf einer Engine | 17 bis 35 MB pro Modell | Eng umrissene Tool-Calls, Extraktion, kurze Spracheingaben, OCR auf jeder CPU, offline | Kein freier Text; kleine Toolsets; junges Projekt; wenige unabhängige Benchmarks |
| llama.cpp (und Ollama darauf) | Offene LLMs und einige Bildmodelle im GGUF-Format [11] | Hunderte MB bis Dutzende GB | Allgemeiner Chat, Entwürfe und Tool-Nutzung mit Modellen von 1B bis 70B+ auf Laptops und Servern | Weit mehr Speicher; die Zuverlässigkeit beim Tool-Calling variiert je nach Modell |
| MLC LLM | Offene LLMs, kompiliert für Smartphones, Browser und GPUs [14] | Hunderte MB und mehr | Chat-taugliche Modelle in mobilen Apps und Web-Apps | Kompilierungsschritt pro Modell und Ziel |
| ONNX Runtime | Ihr eigenes, nach ONNX exportiertes Modell [12] | Was immer Sie exportieren | Auslieferung eines selbst trainierten Modells über Plattformen und Beschleuniger hinweg | Training, Export sowie Vor- und Nachverarbeitung liegen bei Ihnen |
| ExecuTorch | Ihr PyTorch-Modell, exportiert für Edge-Geräte; seit Oktober 2025 in Version 1.0 [13] | Was immer Sie exportieren | PyTorch-Teams, die auf Smartphones und eingebettete NPUs abzielen | Mehr Engineering; Sie bringen das Modell mit |
| NVIDIA TensorRT Edge-LLM | LLMs, Vision-Language- und Sprachmodelle auf Jetson, DRIVE und DGX Spark [10] | Modelle der GB-Klasse | Roboter, Fahrzeuge und Edge-Boxen mit NVIDIA-GPUs; die eigenen Nemotron-Modelle von NVIDIA | Nur NVIDIA-Hardware; Engines werden pro Gerät gebaut |
Die eigene On-Device-Ausrichtung von NVIDIA sind größere Modelle auf NVIDIA-Edge-Hardware: Nemotron 3 Nano Omni beispielsweise ist ein Mixture-of-Experts-Modell mit 30B Parametern und etwa 3B aktiven pro Token, das unter anderem auf Jetson und DGX Spark abzielt [15]. Das ist eine andere Klasse als ein CPU-Modell mit 35 MB. Eine sinnvolle Architektur nutzt oft beides: ein winziges Modell auf dem Gerät des Nutzers für die häufigen, eng umrissenen Anfragen und ein größeres Modell auf einem GPU-Server unter Ihrer Kontrolle für den Rückfall.
16. FAQ
Ist das ein NVIDIA-Produkt? Nein. Cactus Compute entwickelt und veröffentlicht es unter Apache 2.0, einschließlich der vorgefertigten Laufzeit-Binärdateien [1]. Die nächste Verbindung zu NVIDIA besteht darin, dass Cactus auch einen Mac-Runner, cactus-mlx, für komprimierte Checkpoints der Nemotron-Modelle von NVIDIA anbietet [1].
Kann Needle Fragen beantworten oder Texte zusammenfassen? Nein. Es gibt nur Tool-Calls oder extrahierte Felder zurück. Verwenden Sie für Prosa ein größeres Modell.
Welche Sprachen unterstützt die Spracherkennung? Englisch, Deutsch, Französisch, Spanisch, Italienisch, Niederländisch und Polnisch; durch Fine-Tuning lassen sich weitere hinzufügen [2].
Darf ich es kommerziell nutzen? Code und Laufzeit-Binärdateien stehen unter Apache 2.0 [1], und die Model Card von Mirage nennt Apache 2.0 [7]. Prüfen Sie die Lizenz jedes Modells, das Sie ausliefern, auf seiner Hugging-Face-Karte.
Wenn Sie entscheiden, welche KI-Arbeit auf Geräten, auf Ihren eigenen GPU-Servern oder in der Cloud laufen soll, und den privaten Teil aufgebaut und betrieben haben möchten, sehen Sie sich an, wie wir private KI angehen.
Quellen
- cactus-compute/cactus: README, GitHub, Cactus Compute.
- Cactus-API-Referenz (llms.txt), Cactus Compute.
- Dokumentation zu Python-API und CLI von Needle, Cactus Compute.
- Von Needle unterstützte Geräte, Cactus Compute.
- Laufzeit-Binärdateien und Plattformen von Cactus, Hugging Face.
- Ankündigung von Whistle, Cactus Compute, 2. Oktober 2026.
- Model Card von Mirage, Hugging Face.
- cactus-compute auf PyPI (Release-Historie).
- Unternehmensseite von Cactus Compute, Y Combinator.
- Überblick über TensorRT Edge-LLM, 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.
Der gesamte Code in dieser Technote wurde von Workstation am 16. November 2026 mit cactus-compute 4.2.2 auf einem Apple M4 Max und in einem Linux-arm64-Container ausgeführt; die Ausgaben sind aus diesen Läufen kopiert. Leistungsangaben sind Richtwerte von einer gemeinsam genutzten Maschine. Andere Angaben sind Herstellerangaben. Diese Technote ist unabhängig und wird weder von Cactus Compute noch von NVIDIA unterstützt. NVIDIA, Jetson, DRIVE, DGX, Nemotron und TensorRT sind Marken der NVIDIA Corporation. Andere Namen sind Eigentum ihrer jeweiligen Inhaber.