Der Shop ist online

Wir bauen Workstation AI-Maschinen für Websites, KI-Agenten und LLM-Training – online konfigurieren und kaufen.

Händlerpreise erhalten
KI-Produkte
KI-LabsOpenAI-AgentenClaude-AgentenGrok-BotWorkstation AI-natives CRMMarketingAlle Produkte
KI-Lösungen
Angewandte KIKI-AgentenGenerative KIKI-AutomatisierungKI-WeiterbildungKI-Pakete für KMUEnterprise AI LabKI-WorkstationsNVIDIA-Hardware & -SoftwareNVIDIA Accelerated ComputingPrivate KIGPU-Private-CloudGPU-ClusterEdge-KIKI nach Branche
KI-Services
PlattformmodernisierungDigital EngineeringDatengrundlagen & KIAutonomer BetriebKI-BeratungDevOps-AutomatisierungCybersicherheitSoftwareentwicklungAgentenentwicklungMLOps-EinrichtungGPU-LeasingGPU-Private-Cloud
Über uns
UnternehmenUnsere GeschichtePartnerKundengeschichten
KI-Rechenzentren
KI-RechenzentrenGPU-Private-CloudGPU-ClusterGPU-Leasing
KI-EinblickeJev-ReiheBenchmark LabModellauswahl
Technische Hinweise
Dokumentation
Linux-BetriebssystemeUbuntuRed Hat Enterprise LinuxSUSE LinuxAlpine LinuxDebian, Rocky & AlmaLinux
KI-Cloud-PlattformenAWS & Amazon BedrockGoogle Cloud & Vertex AIMicrosoft Azure & AI FoundryGPU-Clouds & Marktplätze
Private KI-RechenzentrenFür AnwaltskanzleienFür Steuer- und WirtschaftsprüfungskanzleienOn-Premises-PlattformenVollständig abgesicherte Cloud
ToolsRing PromoterJobshout
News
Blog
KontaktAnmelden

KI-Workstations, Multi-Agenten-KI-Software, GPU-Infrastruktur und intelligente Agentenlösungen für moderne Unternehmen.

Kontakt

KI-Lösungen

Angewandte KIKI-AgentenGenerative KIKI-AutomatisierungKI-WeiterbildungKI-Pakete für KMUEnterprise AI LabKI nach Branche

Produkte

Alle ProdukteWorkstation AI-natives CRM & ERPMarketingOpenAI-AgentenRing PromoterJobshout

Unternehmen

Über unsUnternehmenKI-RechenzentrenWarum WorkstationPartnerKundengeschichtenPreiseKontaktTenthMatrix

Ressourcen

KI-EinblickeTechnische HinweiseDokumentationLinux-BetriebssystemeKI-Cloud-PlattformenPrivate KI-RechenzentrenBlogSucheSitemap
Büro Belgien
Workstation SRL, Rue Vanderkindere 34, 1180 Uccle, BrusselsBE 0751.518.683Mo – Fr: 9:00 – 18:00 Uhr MEZ
+32 492 45 67 46
Hauptsitz Großbritannien
77-79 Marlowes, Hemel Hempstead HP1 1LFAnfahrt – Ausfahrt 20 der M25 (Outer London)Handelsregisternr.: 11641870Mo – Fr: 9:00 – 18:00 Uhr GMT
+44 7515 356 146
Büro Indien
#159 Sector 9, Pocket 1, DDA Flats, 110077 Dwarka, New Delhi
+91 98881 98841
Büro Taiwan
3F, No. 2-4, Aisi Rd., Ren'ai Dist., Keelung City 200, Taiwan基隆市仁愛區愛四路2之4號3樓Mo – Fr: 9:00 – 18:00 Uhr Taiwan-Zeit (GMT+8)
+886 926 892 701+32 492 45 67 46
Büro Estland
Aleksander Puškini tn 30-25, 20306 Narva, EstoniaMo - Fr: 9:00 - 18:00 Uhr estnischer Zeit (EET)
+32 492 45 67 46

© 2026 Workstation AI. Alle Rechte vorbehalten.

DatenschutzDatenlöschungCookiesNutzungsbedingungenWebsite-Sitemap

NVIDIA, das NVIDIA-Logo, RTX, RTX PRO, Blackwell, CUDA, NVLink, MGX, Omniverse, Spectrum-X, Quantum, BlueField, DGX und HGX sind Marken und/oder eingetragene Marken der NVIDIA Corporation in den USA und anderen Ländern. AMD, das AMD-Arrow-Logo, EPYC, Instinct, Ryzen und Threadripper sind Marken von Advanced Micro Devices, Inc. Dell und PowerEdge sind Marken der Dell Inc. oder ihrer Tochtergesellschaften. Intel und Xeon sind Marken der Intel Corporation oder ihrer Tochtergesellschaften. AMAX, AceleMax und LiquidMax sind Marken der AMAX Engineering Corporation. Alle anderen Produktnamen, Logos und Marken sind Eigentum ihrer jeweiligen Inhaber. Wir verwenden sie ausschließlich, um die Produkte zu kennzeichnen, die wir beschreiben, liefern oder unterstützen; ihre Verwendung bedeutet nicht, dass ihre Inhaber uns empfehlen.

Startseite / Technische Hinweise / Technology
AIAI AgentsPythonLLM

Agentische, Sprach- und Bildmodelle auf dem Gerät mit Cactus betreiben: Ein Praxisleitfaden (2026)

cactus-compute installieren, Tool-Calls ausführen, per Konfidenzschwelle mit Rückfall auf ein größeres Modell absichern, strukturierte Daten extrahieren, Sprache und Bilder verarbeiten, Latenz und Speicher messen und einen Offline-Container ausliefern, mit jedem Beispiel ausgeführt und einem Vergleich mit llama.cpp, ONNX Runtime, ExecuTorch, MLC LLM und TensorRT Edge-LLM

16. November 2026Technology22 min read

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.

Ein Terminal, das pip install cactus-compute und einen JSON-Tool-Call ausführt, verbunden mit einem Laptop, einem Smartphone und einem Einplatinencomputer, die dasselbe Modell offline ausführen.

Zusammenfassung. 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].

Architektur: Ihre Python-Anwendung, die Python-Schicht von cactus, die native Engine libcactus und drei Gewichtsdateien, mit einem Download von Hugging Face in einen lokalen Cache bei der ersten Nutzung.
Eine Engine, drei Gewichtsdateien, eine dünne Python-Schicht. Die Größen sind die von uns gemessenen Dateien.

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.tool wandelt 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 unter results [2].
  • reset() löscht die Konversation, behält aber die Tools. Ein Toolset pro Agent: Um Tools zu ändern, erstellen Sie ein neues Cactus [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.

Routing einer Cactus-Antwort: Aufrufe mit einer Konfidenz auf oder über der Schwelle laufen lokal; Aufrufe darunter oder unterdrückte Aufrufe gehen an die Nutzerbestätigung; ohne Aufrufe wird an ein größeres Modell oder einen Menschen eskaliert.
Drei Ergebnisse, entschieden anhand von Feldern, die die Engine bereits zurückgibt.

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
Latenz nach Thread-Anzahl. Moderate Last: alle Kerne 81 ms, ein Thread 105 ms, vier Threads 129 ms. Ausgelastete Maschine: ein Thread 110 ms, alle Kerne 1.392 ms, vier Threads 1.475 ms bei einem p95 von 21,8 Sekunden.
Auf einer ruhigen Maschine halfen mehr Threads ein wenig; auf einer ausgelasteten verschlechterten sie die Latenz erheblich. Ein Thread blieb durchgehend stabil.

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.

Build-Zeit mit Internet: pip install einer fixierten Version, cactus fetch, cactus download needle3. Laufzeit ohne Netzwerk: HF_HUB_OFFLINE=1, CACTUS_TELEMETRY=0 und CACTUS_NEEDLE_WEIGHTS mit Verweis auf die mitgelieferte Datei.
Zur Build-Zeit herunterladen, ohne Netzwerk ausführen.

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_mb und 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 Feld reasoning und schreiben Sie den Docstring um.
  • confidence ist None. Sie haben lokal feinabgestimmte Gewichte ohne den Kalibrierungskopf geladen [2].
  • ExtractionValidationError. Ein Wert wurde im Text nicht gefunden. Wechseln Sie nicht zu strict=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_WEIGHTS und HF_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

OptionWas Sie ausführenTypische GrößeAm besten fürKompromisse
Cactus (cactus-compute)Die eigenen Modelle Needle, Whistle und Mirage von Cactus auf einer Engine17 bis 35 MB pro ModellEng umrissene Tool-Calls, Extraktion, kurze Spracheingaben, OCR auf jeder CPU, offlineKein 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 GBAllgemeiner Chat, Entwürfe und Tool-Nutzung mit Modellen von 1B bis 70B+ auf Laptops und ServernWeit mehr Speicher; die Zuverlässigkeit beim Tool-Calling variiert je nach Modell
MLC LLMOffene LLMs, kompiliert für Smartphones, Browser und GPUs [14]Hunderte MB und mehrChat-taugliche Modelle in mobilen Apps und Web-AppsKompilierungsschritt pro Modell und Ziel
ONNX RuntimeIhr eigenes, nach ONNX exportiertes Modell [12]Was immer Sie exportierenAuslieferung eines selbst trainierten Modells über Plattformen und Beschleuniger hinwegTraining, Export sowie Vor- und Nachverarbeitung liegen bei Ihnen
ExecuTorchIhr PyTorch-Modell, exportiert für Edge-Geräte; seit Oktober 2025 in Version 1.0 [13]Was immer Sie exportierenPyTorch-Teams, die auf Smartphones und eingebettete NPUs abzielenMehr Engineering; Sie bringen das Modell mit
NVIDIA TensorRT Edge-LLMLLMs, Vision-Language- und Sprachmodelle auf Jetson, DRIVE und DGX Spark [10]Modelle der GB-KlasseRoboter, Fahrzeuge und Edge-Boxen mit NVIDIA-GPUs; die eigenen Nemotron-Modelle von NVIDIANur 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

  1. cactus-compute/cactus: README, GitHub, Cactus Compute.
  2. Cactus-API-Referenz (llms.txt), Cactus Compute.
  3. Dokumentation zu Python-API und CLI von Needle, Cactus Compute.
  4. Von Needle unterstützte Geräte, Cactus Compute.
  5. Laufzeit-Binärdateien und Plattformen von Cactus, Hugging Face.
  6. Ankündigung von Whistle, Cactus Compute, 2. Oktober 2026.
  7. Model Card von Mirage, Hugging Face.
  8. cactus-compute auf PyPI (Release-Historie).
  9. Unternehmensseite von Cactus Compute, Y Combinator.
  10. Überblick über TensorRT Edge-LLM, NVIDIA.
  11. llama.cpp, GitHub.
  12. ONNX Runtime, Microsoft.
  13. Introducing ExecuTorch 1.0, PyTorch.
  14. MLC LLM, GitHub.
  15. 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.

Diesen Artikel teilen

Mehr zu Technology

Laptops für KI-Entwickler: LLMs lokal unter Linux mit GPUs mit 16 GB und 24 GB betreiben (Leitfaden 2026)

Laptops für KI-Entwickler: LLMs lokal unter Linux mit GPUs mit 16 GB und 24 GB betreiben (Leitfaden 2026)

Was auf eine RTX 5080 oder RTX 5090 Laptop GPU passt, die Speicherrechnung, die lohnenden offenen Modelle, die Einrichtung von Ubuntu 26.04 mit dem NVIDIA-Stack, Ollama, llama.cpp und vLLM, Coding-Assistenten, LoRA-Fine-Tuning, Sicherheit und wann Arbeit auf einen Server gehört

Weiterlesen
ML- und LLM-Systeme testen, deren Korrektheit sich nicht beweisen lässt: ein Python-Evidenz-Kit

ML- und LLM-Systeme testen, deren Korrektheit sich nicht beweisen lässt: ein Python-Evidenz-Kit

Evidenz statt Beweise, in etwa 400 Zeilen Python mit echter Ausgabe: Slice-Metriken mit Bootstrap-Intervallen und einem Pass/Fail-Vertrag, Property- und metamorphe Tests mit Hypothesis, Kalibrierung und Conformal Prediction, Pydantic-Verträge und Regressionsevaluierungen für LLM-Ausgaben, Drift-Prüfungen, ein CI-Gate und die exakte Verifikation eines kleinen neuronalen Netzes

Weiterlesen
TorchCurves in der Praxis: lernbare B-Spline- und Legendre-Kurven in PyTorch

TorchCurves in der Praxis: lernbare B-Spline- und Legendre-Kurven in PyTorch

torchcurves installieren, eine Kurve anpassen und dimensionieren, B-Spline oder Legendre und die Eingabeabbildung wählen, eine monotone Kalibrierungskurve und ein additives Modell auf tabellarischen Daten bauen, mit SciPy, scikit-learn, einem KAN und einem MLP vergleichen, Koeffizienten nach JSON exportieren, testen und in der Produktion betreiben, mit echten Ausgaben

Weiterlesen