Un guide pratique pour les développeurs d'IA qui veulent exécuter dès aujourd'hui de petits modèles agentiques, vocaux et de vision directement sur l'appareil. Nous installons le moteur open source de Cactus Compute, effectuons un appel d'outil, ajoutons un filtrage par niveau de confiance et un repli vers un modèle plus grand, extrayons des données structurées, exécutons la reconnaissance vocale et la vision, mesurons la latence et la mémoire, puis empaquetons l'ensemble pour qu'il fonctionne réseau coupé. Chaque exemple ci-dessous a été exécuté sur notre propre matériel, et nous montrons ce qu'il a affiché, y compris lorsque les modèles se sont trompés.
pip install cactus-compute vous donne trois petits modèles sur un même moteur natif : Needle 3 (35,3 MB) transforme une demande en appel à l'une de vos fonctions Python ou extrait des champs d'un texte ; Whistle (16,9 MB) transcrit la parole dans sept langues européennes ; Mirage (21,6 MB) renvoie les objets, le texte et des réponses simples sur des formulaires à partir d'une image. Ils s'exécutent sur un CPU, hors ligne après le premier téléchargement. Lors de nos essais, un appel d'outil a pris environ 70 à 110 ms avec un pic de mémoire de 136 MB. Les modèles sont spécialisés et parfois dans l'erreur ; une utilisation en production repose donc sur trois habitudes : des schémas stricts, un seuil de confiance choisi à partir de votre propre jeu de test, et une voie d'escalade vers un modèle plus grand ou vers une personne.
Cette note technique accompagne notre article de blog L'IA embarquée en moins de 50 MB : ce que le moteur de Cactus signifie pour les entreprises, qui présente l'argumentaire économique. Une correction d'abord : ce moteur est parfois présenté comme un produit NVIDIA. Ce n'en est pas un. Il est développé par Cactus Compute, une entreprise issue de Y Combinator, et publié sous licence Apache 2.0 [1][9]. Les informations et les versions sont à jour au 16 novembre 2026.
1. À qui s'adresse ce guide, ce que vous allez construire, ce dont vous avez besoin
À qui il s'adresse. Aux développeurs Python et aux ingénieurs ML qui veulent des fonctionnalités d'IA fonctionnant sans aller-retour réseau : commandes vocales dans une application de terrain, borne qui lit des documents, outil de support qui transforme un message en ticket, ou appareil qui doit continuer à fonctionner hors ligne.
Ce que vous allez construire. Un premier appel d'outil ; un agent filtré par niveau de confiance qui agit, pose une question ou escalade vers un point de terminaison compatible OpenAI ; une extraction qui refuse les valeurs inventées ; de la parole vers un appel d'outil ; la lecture du texte d'une image ; un benchmark de latence et un banc d'évaluation ; et un conteneur hors ligne.
Prérequis. Python 3.9 ou ultérieur [1] ; macOS sur Apple silicon, Linux (x86-64 ou Arm64) ou Windows, parmi les plateformes que Cactus mentionne [4] ; environ 200 MB d'espace disque libre pour le paquet, le moteur et les trois modèles ; un accès internet pour le premier téléchargement uniquement. Aucun GPU n'est nécessaire. Nous avons utilisé un Apple M4 Max sous macOS 26.7, Python 3.15 et cactus-compute 4.2.2 (moteur 4.1.1), ainsi que Docker pour le conteneur Linux arm64.
2. Comment les éléments s'articulent
Le paquet Python est une couche légère : il transforme vos fonctions en schémas JSON, exécute la boucle de l'agent, vérifie que les arguments sont fondés sur l'entrée et fournit un score de confiance. Il appelle une bibliothèque de moteur natif unique, qui charge un fichier de poids distinct (.cact) par modèle [2]. À la première utilisation, le moteur et les poids sont téléchargés depuis Hugging Face à des commits figés, vérifiés par sommes de contrôle SHA-256 et mis en cache sous ~/.cache/cactus [2][3].
Deux choses à savoir avant de commencer. Premièrement, Needle 3 ne rédige pas de texte. Il renvoie un appel d'outil, ou une liste vide lorsque la demande est hors sujet, ce qui constitue un refus [2]. Si vous avez besoin de réponses rédigées, il vous faut un modèle plus grand (voir la comparaison à la section 13). Deuxièmement, Cactus décrit le moteur comme pesant « moins de 1 MB » [2] ; les bibliothèques non compressées que nous avons téléchargées pesaient 1,4 MB sur macOS et 1,8 MB sur Linux Arm64. Chaque modèle, moteur compris, reste bien en dessous de 50 MB.
3. Étape 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
Figer la version est important : le paquet est passé de 4.0.0 à 4.2.3 en onze jours en novembre 2026 [8]. import cactus n'importe pas JAX ; JAX n'est nécessaire que pour l'extra optionnel d'affinage, cactus-compute[train] [2]. Le paquet envoie des statistiques d'utilisation anonymes (nom de fonction, version, système d'exploitation et identifiant d'installation aléatoire), sauf si CACTUS_TELEMETRY=0 ou DO_NOT_TRACK=1 est défini [1][2].
4. Étape 2 : votre premier appel d'outil
Voici l'exemple du README [1], étendu pour montrer les deux façons de piloter l'agent.
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"])
Exécutez-le avec python hello.py. La première exécution télécharge le moteur et les poids de 35 MB (environ 10 secondes chez nous) ; les exécutions suivantes chargent depuis le cache en bien moins d'une seconde. Notre sortie :
{"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'}]
Ce qui s'est passé :
@cactus.tooltransforme la signature et la docstring de la fonction en schéma JSON. Les annotations de type deviennent des types d'arguments ; une valeur par défaut rend un argument facultatif [2].complete()exécute un tour et renvoie l'appel proposé sans rien exécuter. Utilisez-le lorsque vous voulez vérifier ou confirmer avant d'agir.run()exécute la boucle : le modèle choisit les appels, Cactus exécute vos fonctions, réinjecte les résultats et les renvoie sousresults[2].reset()efface la conversation mais conserve les outils. Un jeu d'outils par agent : pour changer d'outils, créez un nouveauCactus[2].
5. Étape 3 : concevoir des outils qu'un petit modèle peut utiliser
Un modèle de 35 MB lit l'ensemble de votre jeu d'outils dans son prompt et ne dispose d'aucune étape de récupération ; la conception des outils détermine donc la précision. Cactus recommande au plus cinq outils, des noms simples sans préfixes communs, des choix fermés sous forme d'énumérations et des nombres bornés [2]. Le moteur compile vos schémas en une grammaire, de sorte que chaque argument renvoyé respecte le schéma ; des schémas plus stricts laissent donc moins de place à l'erreur.
- Utilisez
typing.Literal[...]pour les ensembles fermés (pièces, priorités, catégories). - Bornez les nombres avec
Annotated[int, cactus.Field(ge=0, le=100)][2]. - Rédigez la docstring en une phrase simple, avec des lignes
Args:pour tout ce qui est ambigu. - Transmettez des informations telles que la date et la langue via
system=, par exemple"date: 2026-11-16 Mon 10:00; locale: en-GB", afin que « demain à 7 h » puisse être résolu [2].
6. Étape 4 : filtrage par niveau de confiance et repli
Chaque réponse comporte un score confidence compris entre 0 et 1. Le moteur place déjà les appels inférieurs à 0,1 dans suppressed_calls ; au-delà, le seuil relève de votre décision produit [2]. Le script ci-dessous agit à partir de 0,7, demande une confirmation en dessous, et envoie les refus vers un point de terminaison de chat compatible OpenAI que vous maîtrisez (un serveur vLLM ou llama.cpp sur votre propre machine GPU, ou une API cloud lorsque les données le permettent). Si aucun point de terminaison n'est configuré, il transmet la demande à une personne.
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)))
Notre sortie, sans repli configuré :
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"}
La deuxième ligne justifie le filtrage. Le modèle a choisi un outil totalement erroné, mais avec une confiance faible ; l'utilisateur aurait donc vu une demande de confirmation au lieu de voir s'allumer les lumières du salon. La troisième demande a été correctement refusée. Définissez FALLBACK_URL (par exemple http://gpu-box:8000/v1/chat/completions) et FALLBACK_MODEL pour acheminer les refus vers un modèle plus grand.
7. Étape 5 : une extraction structurée qui refuse les valeurs inventées
cactus.extract() déclare votre enregistrement comme unique outil et renvoie les champs. En mode strict (par défaut), elle lève ExtractionValidationError si une valeur n'est pas fondée sur le texte [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'}
Deux enseignements tirés d'un seul petit test. Le mode strict a intercepté un total erroné (12 200 au lieu de 1 200) qui serait sinon entré dans votre système. Et le premier résultat a passé le mode strict avec un nom de fournisseur approximatif (« Acme Ltd. Amount »), car la vérification d'ancrage contrôle qu'une valeur provient du texte, et non qu'il s'agit du bon extrait. Conservez votre propre validation pour tout ce qui compte.
8. Étape 6 : la parole
Whistle nécessite un WAV mono à 16 kHz, ou des échantillons flottants à 16 kHz. Créez un extrait de test :
# 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
Passer audio= à complete() permet d'aller de la parole à l'appel d'outil en une seule étape et renvoie la transcription sous audio_text [2]. Pour un extrait de 5 secondes, la transcription a pris 0,74 seconde une fois le modèle chargé. Pour une entrée micro en direct, cactus.stream() prend des segments d'environ une seconde et produit le texte validé au fur et à mesure ; installez cactus-compute[mic] pour la capture micro et le rééchantillonnage [2].
Limites à connaître : sept langues (anglais, allemand, français, espagnol, italien, néerlandais, polonais) ; le silence renvoie un texte vide, mais la musique et d'autres bruits peuvent produire des mots ; placez donc un détecteur d'activité vocale ou un mot d'activation devant un micro toujours actif [2]. Cactus indique que Whistle bat Whisper base sur plusieurs jeux de test de taux d'erreur sur les mots et perd sur d'autres, pour 16,9 MB contre 145,3 MB [6]. Nous n'avons pas reproduit ces benchmarks ; nos extraits de test étaient de la parole synthétique, plus facile qu'une vraie pièce.
9. Étape 7 : la 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
La lecture de texte a fonctionné, avec des candidats qui se chevauchent à différents niveaux de confiance ; conservez la ligne au score le plus élevé pour chaque zone. Les cadres sont renvoyés sur une grille de 0 à 1 000, et non en pixels (le cercle rouge de notre image de 640 sur 400 a été renvoyé à peu près entre x 650 et 880). Le formulaire a répondu à une question et s'est abstenu sur l'autre (None, avec les probabilités dans le résultat complet). Lors d'une exécution antérieure avec une autre police, il a mal répondu à la question sur le cercle rouge. Mirage est utile pour lire du texte et appréhender grossièrement une mise en page ; pour des décisions, validez-le sur vos propres images et filtrez selon les probabilités renvoyées.
10. Étape 8 : mesurer la latence et la mémoire
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")
Exécutez-le avec CACTUS_THREADS=1 python bench.py, puis avec 0 (tous les cœurs) et 4. Deux de nos exécutions :
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
Notre Mac était partagé avec d'autres tâches lourdes, ce qui s'est avéré utile. Lorsque d'autres travaux saturaient les cœurs, le réglage par défaut a porté la médiane à 1,4 seconde et quatre threads ont donné un p95 de 22 secondes, tandis qu'un seul thread restait à environ 110 ms. Un téléphone qui affiche en même temps son interface peut subir la même contention. Commencez avec un ou deux threads et mesurez sur l'appareil le plus lent que vous prenez en charge. peak_ram_mb dans chaque réponse est le chiffre propre au moteur ; l'ensemble du processus Python a culminé à environ 176 à 197 MB lors de nos exécutions.
11. Étape 9 : empaqueter pour un fonctionnement hors ligne
Rien ne doit être téléchargé sur l'appareil d'un client ni en production. Récupérez le moteur et les poids au moment du build et indiquez leur emplacement au paquet [3].
Un conteneur qui fonctionne réseau désactivé
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
Nous l'avons construit sur Apple silicon (soit une image Linux arm64 d'environ 134 MB) avec gated.py en guise d'app.py, et il a affiché les trois mêmes routages qu'à l'étape 4 avec le réseau désactivé. Un piège dans lequel nous sommes tombés : cactus download needle3 seul écrit dans le répertoire courant ; sans --out ni CACTUS_NEEDLE_WEIGHTS, l'utilisateur non root a donc tenté de retélécharger les poids à l'exécution et a échoué sur un cache en lecture seule.
Un appareil Linux isolé (air gap)
# 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
Nous avons vérifié l'équivalent sur macOS avec un répertoire de cache vide, HF_HUB_OFFLINE=1 et les deux variables d'environnement définies : l'appel d'outil s'est exécuté sans solliciter le réseau. Utilisez CACTUS_WHISTLE_WEIGHTS et CACTUS_MIRAGE_WEIGHTS pour les autres modèles [3].
Applications mobiles et navigateur
Pour les applications hors Python, cactus download <platform> --model needle3 récupère un build natif : iOS, tvOS et watchOS reçoivent une bibliothèque statique et un en-tête C (cactus.h) ; Android et Linux reçoivent aussi un exécutable en ligne de commande ; la cible navigateur est WebAssembly [5]. Nous n'avons pas construit d'application mobile pour cette note ; suivez le guide de déploiement de Cactus et traitez-le comme une bibliothèque C que vous encapsulez en Swift ou en Kotlin.
12. Tester et évaluer avant de livrer
Les seuls chiffres de précision qui comptent sont ceux obtenus sur vos propres demandes. Rédigez un fichier de test de requêtes réelles avec l'appel attendu, y compris celles qui doivent être refusées, puis évaluez-le à plusieurs seuils :
{"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']}")
Sur notre fichier de sept cas (enregistrez-le sous cases.jsonl à côté de gated.py et exécutez 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
Sept cas ne prouvent rien statistiquement ; 100 à 200 cas réels par surface d'outils constituent un point de départ raisonnable. C'est la forme qui compte : relever le seuil échange des actions contre des confirmations. Choisissez le point où les actions erronées sont suffisamment rares pour la tâche, et réexécutez le fichier en CI chaque fois que vous changez la version du paquet, les poids ou les définitions d'outils. Cactus fournit dans cactus.environments six surfaces d'outils prêtes à l'emploi avec leurs suites d'acceptation, et indique que le modèle de base ne réussit pas cinq d'entre elles au seuil par défaut [2], ce qui rappelle utilement que l'adéquation d'un petit modèle dépend des outils.
Si le modèle de base n'est pas assez précis sur vos outils, Cactus prend en charge l'affinage LoRA (un moyen peu coûteux d'adapter un modèle en entraînant de petites matrices de poids supplémentaires) en local avec cactus-compute[train], ou sur sa plateforme hébergée payante, ce qui produit un nouveau .cact que vous chargez avec weights= [2]. Notez que les poids affinés en local n'incluent pas la tête de calibration ; confidence vaut donc None [2] et il vous faudrait un autre mécanisme de filtrage.
13. L'exploiter en production
- Figez tout. La version du paquet, et le fichier de poids avec lequel vous avez testé. Des publications hebdomadaires sont la norme pour ce projet.
- Threads. Définissez
cactus.set_threads()explicitement, avant de charger les modèles ; commencez à un ou deux sur des CPU partagés ou mobiles. - Simultanéité. Le texte, la parole et la vision partagent un même environnement d'exécution, et les appels sont sérialisés entre les threads [3]. Pour un serveur traitant de nombreuses requêtes, exécutez plusieurs processus workers plutôt que des threads.
- Sécurité. C'est le modèle qui choisit laquelle de vos fonctions appeler. N'exposez que des fonctions dont l'exécution est sûre avec n'importe quels arguments conformes au schéma, et revérifiez les arguments et les autorisations dans la fonction elle-même.
- Supervision. Journalisez le routage (local, confirmation, repli), la confiance, la latence,
peak_ram_mbet le fait que l'utilisateur ait corrigé ou non l'action. Évitez de journaliser les transcriptions ou les données personnelles extraites, sauf si vous en avez besoin et disposez d'une base pour les conserver. - Confidentialité. Désactivez la télémétrie lorsque votre politique l'exige, et n'oubliez pas que la voie de repli envoie des données hors de l'appareil : appliquez-y les mêmes règles en matière de données.
14. Pièges et débogage
function_callsvide partout. La demande ne correspond à aucun outil, ou la description de l'outil n'est pas claire. Consultez le champreasoninget réécrivez la docstring.confidencevautNone. Vous avez chargé des poids affinés en local sans la tête de calibration [2].ExtractionValidationError. Une valeur n'a pas été trouvée dans le texte. Ne passez pas àstrict=Falsepour faire disparaître l'erreur ; examinez-la.- PermissionError au démarrage dans un conteneur. Le paquet tente de télécharger dans un cache où il ne peut pas écrire. Embarquez les fichiers et définissez
CACTUS_NEEDLE_WEIGHTSetHF_HUB_OFFLINE=1. - Pics de latence. Contention CPU due au multithreading. Essayez
set_threads(1). - Mauvaise fréquence d'échantillonnage. Whistle attend du mono à 16 kHz ; convertissez, ou installez l'extra
[mic]pour le rééchantillonnage [1].
15. Comparaison avec les alternatives
| Option | Ce que vous exécutez | Taille typique | Usage idéal | Compromis |
|---|---|---|---|---|
Cactus (cactus-compute) | Les modèles Needle, Whistle et Mirage de Cactus sur un même moteur | 17 à 35 MB par modèle | Appels d'outils ciblés, extraction, parole courte, OCR sur n'importe quel CPU, hors ligne | Pas de texte libre ; petits jeux d'outils ; projet jeune ; peu de benchmarks indépendants |
| llama.cpp (et Ollama par-dessus) | LLM ouverts et certains modèles de vision au format GGUF [11] | De centaines de MB à des dizaines de GB | Conversation généraliste, rédaction et utilisation d'outils avec des modèles de 1B à plus de 70B sur portables et serveurs | Beaucoup plus de mémoire ; fiabilité des appels d'outils variable selon le modèle |
| MLC LLM | LLM ouverts compilés pour téléphones, navigateurs et GPU [14] | Des centaines de MB et plus | Modèles de type chat dans des applications mobiles et web | Une étape de compilation par modèle et par cible |
| ONNX Runtime | Votre propre modèle exporté en ONNX [12] | Selon ce que vous exportez | Livrer un modèle entraîné sur mesure sur plusieurs plateformes et accélérateurs | L'entraînement, l'export et le pré/post-traitement sont à votre charge |
| ExecuTorch | Votre modèle PyTorch, exporté pour des appareils en périphérie ; version 1.0 depuis octobre 2025 [13] | Selon ce que vous exportez | Équipes PyTorch ciblant des téléphones et des NPU embarqués | Davantage d'ingénierie ; vous fournissez le modèle |
| NVIDIA TensorRT Edge-LLM | LLM, modèles vision-langage et modèles vocaux sur Jetson, DRIVE et DGX Spark [10] | Modèles de l'ordre du GB | Robots, véhicules et boîtiers de périphérie équipés de GPU NVIDIA ; modèles Nemotron de NVIDIA | Matériel NVIDIA uniquement ; moteurs construits pour chaque appareil |
L'orientation de NVIDIA pour l'IA embarquée privilégie des modèles plus grands sur du matériel de périphérie NVIDIA : son Nemotron 3 Nano Omni, par exemple, est un modèle à mélange d'experts de 30B paramètres, avec environ 3B actifs par token, destiné notamment à Jetson et DGX Spark [15]. C'est une autre catégorie qu'un modèle CPU de 35 MB. Une architecture raisonnable utilise souvent les deux : un tout petit modèle sur l'appareil de l'utilisateur pour les demandes fréquentes et ciblées, et un modèle plus grand sur un serveur GPU que vous maîtrisez pour le repli.
16. FAQ
Est-ce un produit NVIDIA ? Non. Cactus Compute le développe et le publie sous licence Apache 2.0, y compris les binaires précompilés de l'environnement d'exécution [1]. Le lien le plus proche avec NVIDIA est que Cactus fournit aussi un exécuteur pour Mac, cactus-mlx, pour des checkpoints compressés des modèles Nemotron de NVIDIA [1].
Needle peut-il répondre à des questions ou résumer un texte ? Non. Il renvoie uniquement des appels d'outils ou des champs extraits. Utilisez un modèle plus grand pour la rédaction.
Quelles langues la reconnaissance vocale prend-elle en charge ? L'anglais, l'allemand, le français, l'espagnol, l'italien, le néerlandais et le polonais ; l'affinage peut en ajouter d'autres [2].
Puis-je l'utiliser commercialement ? Le code et les binaires de l'environnement d'exécution sont sous licence Apache 2.0 [1], et la fiche du modèle Mirage indique Apache 2.0 [7]. Vérifiez la licence de chaque modèle que vous livrez sur sa fiche Hugging Face.
Si vous devez décider quels travaux d'IA exécuter sur les appareils, sur vos propres serveurs GPU ou dans le cloud, et avez besoin que la partie privée soit construite et exploitée, découvrez notre approche de l'IA privée.
Références
- cactus-compute/cactus : README, GitHub, Cactus Compute.
- Référence de l'API Cactus (llms.txt), Cactus Compute.
- Documentation de l'API Python et de la CLI de Needle, Cactus Compute.
- Appareils pris en charge par Needle, Cactus Compute.
- Binaires et plateformes de l'environnement d'exécution Cactus, Hugging Face.
- Annonce de Whistle, Cactus Compute, 2 octobre 2026.
- Fiche du modèle Mirage, Hugging Face.
- cactus-compute sur PyPI (historique des versions).
- Page de l'entreprise Cactus Compute, Y Combinator.
- Présentation de TensorRT Edge-LLM, NVIDIA.
- llama.cpp, GitHub.
- ONNX Runtime, Microsoft.
- Introducing ExecuTorch 1.0, PyTorch.
- MLC LLM, GitHub.
- NVIDIA Nemotron 3 Nano Omni, blog NVIDIA, 28 avril 2026.
Tout le code de cette note a été exécuté par Workstation le 16 novembre 2026 avec cactus-compute 4.2.2 sur un Apple M4 Max et dans un conteneur Linux arm64 ; les sorties sont copiées de ces exécutions. Les chiffres de performance sont indicatifs et proviennent d'une machine partagée. Les autres chiffres sont des affirmations des fournisseurs. Cette note est indépendante et n'est approuvée ni par Cactus Compute ni par NVIDIA. NVIDIA, Jetson, DRIVE, DGX, Nemotron et TensorRT sont des marques de NVIDIA Corporation. Les autres noms sont la propriété de leurs détenteurs respectifs.