Guide de déploiement 2026-04-11 10 min

2026 — Mise à jour mineure OpenClaw Gateway et évolution des points de terminaison compatibles OpenAI : /v1/embeddings et transfert de modèle sur Mac physique distant — runbook reproductible (changements breaking + FAQ 429 et dimensions)

Lorsque des équipes mondiales exécutent OpenClaw Gateway sur un Mac physique distant (par ex. nœud ZoneMac) et s’appuient sur des clients compatibles OpenAI pour la RAG et l’orchestration, les mises à jour mineures cassent le plus souvent le routage /v1/embeddings et les alias de modèle, ainsi que le transfert de modèle aval et le comportement HTTP 429 — parfois sans bruit jusqu’à l’échec de l’indexation. Cet article fournit une matrice de changements breaking, un runbook de migration en sept étapes, des chiffres et checklists prêts à citer, et des réponses ciblées sur le 429 et le décalage de dimension vectorielle. Figez la sémantique Base URL et Bearer avant de toucher aux embeddings — la doc client « format OpenAI » doit rester un contrat de bout en bout. Pour la stabilité longue durée des passerelles, voir Optimisation de la stabilité du Mac mini pour OpenClaw en 2026 : guide complet.

2026 — Migration embeddings OpenClaw Gateway et transfert de modèle sur Mac physique distant

1. Périmètre et public visé

Dans les écosystèmes « format OpenAI », le chat et les embeddings partagent souvent le préfixe /v1, mais ce sont le transfert de modèle côté passerelle et la résolution d’alias que les versions mineures modifient le plus souvent — alors que votre magasin vectoriel, les dimensions d’index et les jobs batch ne migrent pas automatiquement.

À retenir : conservez une requête curl embeddings « golden » et un tableau modèle → dimension avant et après mise à jour ; faites passer les tests de fumée de « chat seul » à chat + embeddings + un job batch avant de fusionner la release. Pour les chemins distants sécurisés vers le même hôte, voir SSH local forward vs Tailscale Serve vers un nœud macOS physique. Le contrat Base URL / Bearer détaillé se trouve dans OpenClaw Gateway en API compatible OpenAI : Cursor et scripts vers un Mac physique distant.

2. Points de friction

  1. Limites masquées derrière « on n’a testé que le chat ». Beaucoup d’équipes surchargent la Base URL et ne vérifient que /v1/chat/completions. Si un alias de modèle ne change que pour /v1/embeddings, la RAG peut échouer sur des erreurs de dimensions des jours plus tard.
  2. Coûts cachés dans le relais et les quotas. Lorsque la passerelle mappe text-embedding-3-small vers une région A ou un fournisseur B, les sémantiques 429 et Retry-After peuvent différer ; les scripts batch sans backoff élargissent les fenêtres de throttle.
  3. Stabilité liée au contrat d’index. Dimension vectorielle, métrique (cosinus vs produit scalaire) et normalisation doivent rester liés à la même révision de modèle ; un changement silencieux de dimension amont se manifeste souvent par une « recherche moins bonne », pas par un 4xx immédiat.

3. Changements breaking et transfert : matrice décisionnelle

Validez ce tableau avant de livrer ; la colonne de gauche décrit un raccourci fréquent, la droite la base recommandée.

Zone Raccourci risqué Base recommandée
Changements breaking Ne lire que les notes liées au chat Chercher « embedding », « alias », « routeur », « breaking » ; lister chaque chaîne de modèle affectée
/v1/embeddings Réutiliser un ancien chemin golden curl sans vérifier les préfixes Si le chat partage la même Base URL, ajoutez une requête golden embeddings explicite ; validez les limites de longueur du tableau input
Transfert de modèle Modifier les alias amont dans la passerelle sans mettre à jour les clients Maintenir modèle public → modèle amont → dimension attendue et le versionner
HTTP 429 Augmenter la concurrence pour « forcer le passage » Backoff, fractionner la concurrence, respecter Retry-After ; séparer quotas passerelle et amont
Décalage de dimensions Tronquer ou compléter les vecteurs dans l’application Reconstruire les index ou nouvelles collections ; ne jamais mélanger anciennes et nouvelles dimensions dans un même magasin
Acceptation Ne tester que le 200 localhost Localhost + HTTPS public + un chemin batch ; enregistrer la longueur du vecteur et un échantillon des premières dimensions

4. Runbook en sept étapes (Mac physique distant)

  1. Figez versions et notes. Enregistrez digest ou semver passerelle et amont avant mise à jour ; surlignez les lignes de release notes concernant embeddings, routeur ou alias.
  2. Golden localhost embeddings. En SSH sur le Mac, envoyez un POST /v1/embeddings minimal vers 127.0.0.1 avec model et input ; enregistrez data[0].embedding.length.
  3. Freeze Base URL et cartographie. Alignez-vous sur le contrat du guide compatible OpenAI ; partagez une seule OPENAI_BASE_URL et une page de cartographie des modèles.
  4. Acceptation double chemin. Rejouez le même corps vers 127.0.0.1 et le HTTPS public ; si seul le chemin public renvoie 429, inspectez bord/WAF, quotas compte et Retry-After.
  5. Lots et backoff. Plafonnez la concurrence des jobs hors ligne (départ à 4) avec backoff exponentiel ; journalisez request_id sur chaque 429 pour le support amont.
  6. Alignement magasin vectoriel. Migrez ou reconstruisez les index vers la nouvelle dimension ; pendant la fenêtre, désactivez les écritures des anciens modèles vers les nouvelles tables.
  7. Archive et alertes. Archivez le curl golden, le tableau de cartographie et les commandes de rollback (digest ou binaire précédent) dans le runbook ; alertez sur 429 soutenus et échecs de validation de dimension.

5. Triage 429 vs décalage de dimensions

Séparez « limité en débit » et « contrat cassé » avant de modifier la configuration.

Symptôme Soupçonner en premier Vérifier
429 + Retry-After Quota passerelle ou amont ; rafales de lots Baisser la concurrence, respecter Retry-After ; comparer requête unique vs erreurs batch
200 en localhost, 429 en public Limites bord/WAF ou quotas compte asymétriques Comparer l’IP de sortie publique aux tableaux de bord fournisseur ; envisager autre région ou sortie
Erreur dimension magasin vectoriel à l’écriture Changement de carte modèle ayant modifié la largeur de sortie Afficher embedding.length vs schéma ; ré-embedder le même texte avant/après
Récupération dégradée, pas de 4xx Dimensions mélangées ou métrique incohérente Segmenter par collection ; garder requêtes et documents sur un même modèle et une même politique de normalisation

6. Faits réutilisables pour les runbooks

  • Paquet de contrat : journalisez l’URL complète /v1/embeddings, la chaîne model, la dimension attendue, et les versions passerelle plus amont (au moins semver major.minor.patch).
  • Concurrence initiale des lots : sans tests de charge, partez de 4 requêtes concurrentes, observez le taux de 429, puis doublez ; alignez avec les limites TPM/RPM du fournisseur.
  • Commande partagée : conservez un curl embeddings minimal et réutilisez les mêmes noms de variables d’environnement dans les tests d’intégration SDK.

7. FAQ

Q : Les dimensions sont passées de 1536 à 3072 après mise à jour — puis-je seulement élargir la colonne ?
Non. Traitez cela comme un nouvel index : ré-embedding complet ou migration en double écriture ; la troncature ou le padding cassent la similarité et les seuils réglés.

Q : Les journaux passerelle incluent-ils le texte brut des embeddings ?
Ils doivent être masqués par défaut. Pour le triage, journalisez temporairement des hashes ou des longueurs avec liste blanche IP, puis coupez le mode verbeux.

Q : Lien avec l’article chat / Base URL ?
Ce guide couvre Base URL et Bearer ; celui-ci couvre les contrats embeddings et transfert après mise à jour — ensemble ils complètent une migration compatible OpenAI.

8. Synthèse et choix du nœud

Dans les mises à jour mineures, embeddings et transfert de modèle sont ce que les tests « chat seul » oublient ; curl golden + tableau de dimensions + acceptation trois chemins gardent les échecs dans la fenêtre de release.

Faire tourner passerelles, jobs batch et pipelines vectoriels sur un Mac physique distant, c’est d’abord des services Unix longue durée et une stabilité disque — macOS associe Terminal natif, SSH, launchd et Homebrew à ce flux. Le Mac mini M4 offre l’efficacité Apple Silicon et une consommation au repos en ordre de quelques watts, adaptée aux nœuds multi-régions ; la mémoire unifiée aide lorsque embeddings et caches locaux cohabitent. Gatekeeper et SIP réduisent la surface d’inquiétude quand une API reste exposée des mois durant.

Si vous voulez cette migration et ce triage sur du matériel stable, silencieux et peu coûteux en attention, le Mac mini M4 reste l’un des points d’entrée les plus prévisibles en coût — obtenez un Mac physique distant via ZoneMac et figez chat et embeddings sur un même contrat de passerelle.

Passerelle Mac distante

Un Mac physique distant pour OpenClaw et les lots d’embeddings ?

ZoneMac propose la location de Mac mini haute performance : exécutez passerelle et scripts sur la même machine et réduisez les surprises de quotas transfrontaliers.

À la demande Matériel physique SSH direct
Location cloud macOS Offre à durée limitée
Obtenir maintenant