Lorsque vous déployez de la génération augmentée par récupération (RAG) sur un Mac distant loué, Chroma est souvent choisi comme magasin vectoriel local : faible friction, intégration embarquée et colocalisation avec une passerelle OpenClaw. L’écart démo ↔ prod tient à l’opérationnel : chemins persistants, sauvegardes cohérentes, sondes de vie et plafonds de latence requête pour ne pas bloquer les sessions agent. Ce tutoriel cible les équipes qui livrent de la puissance de calcul IA sur du matériel Apple à distance. Base passerelle : OpenClaw Docker, durcissement et dépannage ; observabilité : métriques passerelle et alertes type Prometheus. Chroma et conteneurs sur le même disque : voir la matrice Docker/Podman et cache de couches (marge APFS).
Répertoire de persistance Chroma et étapes de snapshot
Les modes embarqué et serveur de Chroma finissent par persister l’état sous un répertoire de persistance que vous choisissez. Sur un Mac loué, traitez ce répertoire comme une petite base : un seul chemin absolu canonique, propriété de l’utilisateur d’automatisation, sur un volume à espace libre prévisible — idéalement pas uniquement la tranche système racine. Exportez par exemple CHROMA_PERSIST_DIRECTORY=/Volumes/Data/chroma-prod dans le profil shell, un plist launchd ou un bind mount Docker, et réutilisez la même variable dans le paquet de compétences OpenClaw qui ouvre les collections.
Recette snapshot (cohérente au niveau fichiers, reproductible). D’abord, arrêter les écrivains : quitter le processus Python embarqué ou stopper le conteneur chroma serveur afin que SQLite et les segments ne soient pas en transaction. Ensuite, consigner un manifeste : noms de collections, identifiant du modèle d’embedding et version de Chroma — les exercices de restauration échouent quand la version client majeure diverge du format disque. Troisièmement, archiver avec un outil qui préserve les métadonnées :
# adapter les chemins ; exécuter uniquement lorsque Chroma est arrêté
export SRC="$CHROMA_PERSIST_DIRECTORY"
export STAMP=$(date -u +%Y%m%dT%H%M%SZ)
tar -C "$(dirname "$SRC")" -czf "/backup/chroma-${STAMP}.tgz" "$(basename "$SRC")"
shasum -a 256 /backup/chroma-${STAMP}.tgz > /backup/chroma-${STAMP}.tgz.sha256rsync -a --delete vers un stockage réseau ou une passerelle objet convient tout autant lorsque le chemin réseau est fiable ; conservez au moins deux générations localement plus une copie hors machine si le Mac constitue un point unique de défaillance. Quatrièmement, vérifier : extraire dans un répertoire de test sur une autre machine, instancier un client en lecture seule si votre version le permet, ou exécuter un simple count() par collection. Cinquièmement, réactiver le serveur et documenter la commande de restauration à côté de la tâche planifiée de sauvegarde.
Pourquoi éviter la copie à chaud ? Chroma mélange SQLite et segments ; une copie active peut produire database is locked ou des pages incohérentes. RPO très court : backend prévu pour sauvegarde en ligne, ou courte fenêtre de maintenance (souvent acceptable en batch nocturne).
Sondes de santé OpenClaw et modèles d’alertes
La passerelle OpenClaw expose /healthz et /readyz sur l’écoute HTTP (par défaut 127.0.0.1:18789). Ces points sont vos battements de plan de contrôle : s’ils échouent, aucune compétence — Chroma ou autre — ne doit faire croire que l’assistant est utilisable. Depuis SSH :
curl -fsS http://127.0.0.1:18789/healthz
curl -fsS http://127.0.0.1:18789/readyzRéutilisez le même schéma de scrape que pour Prometheus ou une sonde managée ; l’essentiel est le libellé — balisez env=prod, role=openclaw-gateway et l’identifiant d’instance fournisseur pour router correctement la pagination.
Les alertes façon quota disque complètent la santé passerelle. La croissance de Chroma suit le nombre de documents, la dimension d’embedding et les fusions de segments ; un disque plein silencieux tue à la fois SQLite et le cache page du système. Exportez l’espace libre via node_exporter, un cron trivial df -Pk écrivant un fichier métrique, ou l’agent de votre hébergeur. Partez d’un avertissement lorsque l’espace disponible sur le volume Chroma passe sous environ 20 Go (à ajuster selon la taille des lots d’embedding) et d’un critique sous 5 Go ou lorsque le temps projeté avant saturation tombe sous deux heures au débit d’ingestion récent.
| Signal | Condition de départ | Notes |
|---|---|---|
| Passerelle /healthz | Code HTTP ≠ 200 sur 2 vérifications consécutives | Intervalle 15–30 s sur les piles orientées utilisateur |
| Passerelle /readyz | Échecs alors que /healthz est OK | Souvent dépendance ou config ; consulter les journaux avant Chroma |
| Octets libres volume | avail < 20e9 avert. / < 5e9 crit. | Par volume, pas d’agrégat racine global |
| HTTP Chroma (optionnel) | Sonde TCP ou HTTP sur le port connu | Uniquement en mode serveur sur une interface connue |
Branchez Slack, PagerDuty ou courriel ; ajoutez des liens runbook dans l’annotation (jeton passerelle, disque, restauration archive Chroma).
Paramètres de timeout et de disjoncteur pour les requêtes
La latence des requêtes Chroma augmente avec la taille des collections, la complexité des filtres et l’accès concurrent à l’index HNSW. Un outil OpenClaw qui bloque sans deadline peut affamer le worker de session et amplifier les retries sur les canaux. Fixez les timeouts à la couche la plus étroite — la fonction qui appelle collection.query ou le client HTTP parlant à chroma run — et non seulement sur un vague « timeout LLM » en amont.
Ordres de grandeur de départ pour des outils RAG interactifs. Utilisez une deadline client de 4 à 8 secondes pour une similarité top-k avec filtres modestes sur des collections jusqu’à quelques millions de vecteurs sur Apple Silicon ; montez vers 15 à 30 secondes uniquement pour des jobs de réconciliation batch hors chemin critique. Associez la deadline à une concurrence maximale (par exemple deux à quatre requêtes parallèles par processus passerelle) pour que les rafales de salons de discussion n’écrasent pas l’index.
Esquisse de disjoncteur. Maintenez une fenêtre glissante d’échecs (timeouts, 5xx ou erreurs « index vide »). Après trois échecs consécutifs en cinq minutes, ouvrez le disjoncteur pendant 30 à 120 secondes : renvoyez un message déterministe dégradé à l’agent (« magasin vectoriel temporairement indisponible — résumé mis en cache ») et journalisez un error_class=chroma_breaker_open structuré. Demi-ouverture après la temporisation avec une seule requête sonde. Ce motif s’accorde bien avec des budgets API par projet si vous plafonnez aussi les appels d’embedding amont.
# échéance asyncio (illustratif)
import asyncio
async def query_with_cap(coro, seconds=6.0):
return await asyncio.wait_for(coro, timeout=seconds)Pour les piles synchrones, httpx.Client(timeout=6.0) ou les options de canal gRPC remplissent le même contrat. Documentez les valeurs retenues à côté du manifeste du paquet de compétences OpenClaw afin que l’astreinte sache si un timeout relève du réglage ou d’une panne réelle.
FAQ : erreurs courantes de permissions et de chemins
PermissionError: [Errno 13] sur le chemin de persistance. L’utilisateur loueur qui exécute OpenClaw n’est pas propriétaire du répertoire — fréquent après clonage d’image disque ou restauration Time Machine. Corriger avec sudo chown -R $USER:staff "$CHROMA_PERSIST_DIRECTORY" ou recréer l’arborescence et rsync -a les données.
sqlite3.OperationalError: database is locked. Deux processus ont ouvert le même répertoire de persistance, ou une sauvegarde a copié *.sqlite* pendant des écritures. Arrêter toute instance Chroma, confirmer avec lsof sur le chemin, puis ne relancer qu’un seul propriétaire.
Chemins relatifs qui diffèrent entre launchd et SSH. Utilisez toujours des chemins absolus dans les plists et compose ; ~/chroma ne se résout pas pareil pour les sessions GUI et SSH.
Pièges de sensibilité à la casse. Si des volumes externes montent avec une sensibilité à la casse APFS différente des portables de développement, normalisez les noms de dossiers collections et snapshots en minuscules pour éviter les « fichier introuvable » en automatisation.
Bind mounts Docker sur Mac. Lorsque Chroma tourne en conteneur, le chemin hôte doit exister avant docker compose up et correspondre aux labels SELinux ou permissions si vous migrez vers des workers Linux — le modèle mental reste le même même si cet article cible surtout des Mac loués bare metal.
Synthèse
Chroma sur un Mac loué à distance reste « ennuyeux au bon sens » lorsque la persistance vit sur un volume dédié, que les snapshots sont à froid (écrivains arrêtés) et que les sondes de santé OpenClaw partent avant que les utilisateurs ne s’en aperçoivent. Ajoutez tôt des alertes quota disque : les tables vectorielles deviennent bruyantes une fois le système de fichiers tendu. Terminez par des deadlines explicites sur les requêtes et un petit disjoncteur pour qu’un mauvais jour d’index ne se propage pas à toutes les sessions agent.
Les pages publiques Tarifs, Achat et Aide décrivent les forfaits de puissance de calcul MacCompute sans mur de connexion ; l’aide couvre l’accès et la facturation lorsque vous stabilisez cette pile sur du métal longue durée.