Archives de catégorie : Non classé

Gestion des compétences agents

Gestion des compétences agents : l’échec du test manuel

Non classé

Retour d'expérience RubyAvancé

Gestion des compétences agents : l'échec du test manuel

Le déploiement d’un agent autonome sans protocole de test est une bombe à retardement. Nous avons appris cette leçon à la dure lors d’une mise à jour de prompt en production.

La gestion des compétences agents est devenue impossible à piloter manuellement. Notre taux d’erreur sur l’appel des outils est passé de 4% à 22% en une seule nuit. Nous n’avions aucun indicateur de régression sur la fiabilité des appels de fonctions.

Cet article détaille l’implémentation de sivchari pour automatiser la validation et la mesure de la qualité des outils de vos LLM.

Gestion des compétences agents

🛠️ Prérequis

Environnement de développement prêt pour l’évaluation d’agents.

  • Python 3.11 ou supérieur installé.
  • Accès à une API compatible OpenAI (GPT-4o) ou un serveur local Ollama (version 0.3.0+).
  • Installation de la librairie via : pip install sivchari==0.1.2
  • Un fichier de configuration YAML pour vos tests.

📚 Comprendre Gestion des compétences agents

La gestion des compétences agents repose sur la standardisation de l’interface entre le LLM et l’action. Un agent ne possède pas seulement du texte, il possède des outils (skills).

Le framework sivchari structure ce processus en quatre étapes cycliques :

[Définition] -> (YAML/Python) : On définit l'entrée, la sortie attendue et le type d'outil.
[Création]  -> (Prompt Engineering) : On écrit le prompt qui active la compétence.
[Test]      -> (Dataset) : On injecte des requêtes réelles et attendues.
[Mesure]    -> (Metrics) : On calcule la précision, le rappel et la latence.

Contrairement à une suite de tests unitaires classique, nous ne vérifions pas une valeur exacte. Nous évaluons une conformité sémantique et structurelle. C’est une approche proche du testing de contrats en microservices, mais appliquée à l’incertitude du langage naturel.

💎 Le code — Gestion des compétences agents

Ruby
import sivchari

# Définition d'une compétence de recherche de fichiers
# On utilise le décorateur pour lier le prompt à une fonction Python
@sivchari.skill(name="file_search", description="Recherche un fichier par son nom")
def search_file_skill(query: str):
    # Simulation d'une base de données de fichiers
    files = ["config.json", "README.md", "setup.py"]
    # Logique de recherche simple
    result = [f for f following in files if query.lower() in f.lower()]
    return {"matches": result}

# Configuration du moteur d'évaluation
# On définit ici les paramètres de la gestion des compétences agents
engine = sivchari.EvaluationEngine(model="gpt-4o")

# Chargement de la configuration de test
# Le fichier contient les inputs et les outputs attendus
engine.load_test_suite("tests/skills/file_search_suite.yaml")

📖 Explication

Dans le premier snippet, le décorateur @sivchari.skill est crucial. Il ne se contente pas de documenter la fonction. Il extrait la signature Python pour générer automatiquement le schéma JSON nécessaire au LLM. C’est le principe du moindre étonnement : le développeur écrit du Python standard, et le framework s’occupe de la traduction pour l’agent.

La méthode engine.load_test_suite lit un fichier YAML. Ce fichier est le cœur de la gestion des compétences agents. Il contient des paires input/output. Pour chaque input, le framework demande au LLM d’utiliser l’outil et compare le résultat avec l’attendu.

Dans le second snippet, nous utilisons pytest. Il est important de ne pas confondre les deux. pytest teste votre code Python (la logique de recherche). sivchari teste la capacité du LLM à utiliser ce code (le prompt). L’un vérifie l’implémentation, l’autre vérifie l’orchestration.

Un piège classique : oublier de définir un expected_substring quand on teste des sorties textuelles. Si vous attendez un match exact, le moindre espace ou retour à la ligne échouera le test. Utilisez toujours des assertions de sous-chaîne ou des regex.

Documentation officielle Ruby

🔄 Second exemple

Ruby
import yaml
import pytest
from my_agent import search_file_skill

# Test de régression pour la gestion des compétences agents
@pytest.mark.parametrize("input_query, expected_substring", [
    ("config", "config.json"),
    ("readme", "README.md"),
    ("non_existent", None)
])
def test_skill_accuracy(input_query, expected_substring):
    """Vérifie que l'outil retourne bien le bon fichier"""
    # Appel de la fonction de l'agent
    response = search_file_skill(input_query)
    
    if expected_substring is None:
        # On vérore que la liste est vide si rien n'est trouvé
        assert len(response["matches"]) == 0
    else:
        # On vérifie la présence du fichier dans les résultats
        assert any(expected_substring in m for m in response["matches"])

# Note: Ce test est complémentaire à sivchari
# Il vérifie la logique Python, pas la qualité du prompt LLM

Retour d'expérience

Le 14 juin dernier, notre équipe a poussé une modification mineure sur le système de prompt global. L’objectif était d’ajouter une consigne de politesse. Nous avons utilisé une méthode de validation classique : un test de présence de mots-clés dans la réponse.

Cependant, la gestion des compétences agents a été totalement ignorée. Le nouveau prompt rendait l’agent « trop bavard ». En voulant être poli, l’agent ajoutait des phrases d’introduction avant son appel d’outil. Résultat : le parseur JSON de notre backend plantait systématiquement. L’agent envoyait : « Bonjour ! Voici le résultat : {« matches »: [« config.json »]} » au lieu du JSON pur.

En production, cela a provoqué une cascade d’erreurs. Notre monitoring montrait une explosion des erreurs 500. Nous avons mis 4 heures à identifier que le problème ne venait pas du code Python, mais de la structure de la réponse du LLM. Le code était identique, mais la compétence d’appel d’outil était devenue invalide.

Pour corriger cela, nous avons implémenté sivchari. Nous avons créé un pipeline de validation qui exécute la suite de tests à chaque modification de prompt. Désormais, si le format de sortie change, le test de conformité échoue avant le déploiement. La gestion des compétences agents est devenue une étape bloquante dans notre GitLab CI.

Nous avons introduit une métrique de « Schema Adherence ». Si le taux de conformité JSON descend sous 99.5%, le déploiement est annulé. Cela a réduit nos régressions de production de 85% en trois mois.

▶️ Exemple d’utilisation

Exécution d’un test de compétence via la ligne de commande pour vérifier la recherche de fichiers.

$ sivchari test --skill file_search --suite tests/skills/file_search_suite.yaml

Running tests for skill: file_search
[PASS] input: "config" -> expected: ["config.json"]
[PASS] input: "readme" -> expected: ["README.md"]
[FAIL] input: "unknown" -> expected: [] (Found: ["unknown_file.txt"])

Summary:
  Passed: 2
  Failed: 1
  Accuracy: 66.6%
  Latency: 1.2s

🚀 Cas d’usage avancés

1. Détection de dérive de performance (Drift Detection) : En exécutant la gestion des compétences agents sur un échantillon de logs réels, on peut détecter quand une mise à niveau du modèle (ex: passage de GPT-4 à GPT-4o) altère la précision des outils.

2. A/B Testing de Prompts : Vous pouvez faire tourner deux versions du prompt sur la même suite de tests sivchari et comparer le score de success_rate de manière statistique. results = engine.compare("prompt_v1", "prompt_v2")

3. Génération de données de test : Utiliser le framework pour géner automatiquement des cas limites (edge cases) en injectant des inputs malformés pour tester la résilience de la gestion des compétences agents.

🐛 Erreurs courantes

⚠️ Confusion entre test de code et test d'agent

Tester la fonction Python sans tester le prompt qui l’appelle.

✗ Mauvais

pytest test_my_function()
✓ Correct

sivchari test --skill my_skill

⚠️ Format de sortie non strict

Attendre un JSON exact alors que le LLM ajoute du texte.

✗ Mauvais

assert response == '{"key": "val"}'
✓ Correct

assert json.loads(response)['key'] == 'val'

⚠️ Absence de seed pour la reproductibilité

Les tests échouent aléatoirement à cause de la température du LLM.

✗ Mauvais

temperature=1.0
✓ Correct

temperature=0.0

⚠️ Oubli de la gestion des erreurs de schéma

Le test passe si le LLM ne répond rien, mais l’agent est cassé.

✗ Mauvais

assert response is not None
✓ Correct

assert validate_schema(response, schema)

✅ Bonnes pratiques

Pour une gestion des compétences agents professionnelle, suivez ces principes :

  • Température à zéro : Pour les tests de régression, fixez toujours la température du modèle à 0.0 pour garantir la reproductibilité des résultats.
  • Versioning des compétences : Traitez vos fichiers de test YAML comme du code source. Ils doivent suivre le même cycle de vie que vos fonctions Python.
  • Isolation des environnements : Utilisez des environnements Docker pour vos tests afin d’éviter que des variables d’environnement locales n’influencent les résultats de la gestion des compétences agents.
  • Granularité des métriques : Ne vous contentez pas d’un taux de succès global. Mesurez la latence par outil et le taux de conformité au schéma JSON séparément.
  • Approche par contrat : Définissez vos outils avec des types Python stricts (Type Hinting). Cela facilite la génération de schames par sivchari.
Points clés

  • La gestion des compétences agents nécessite un cadre de test automatisé.
  • Le test manuel de prompt est une source majeure de régressions en production.
  • Sivchari permet de transformer des prompts incertains en tests structurés.
  • Il faut distinguer le test de la logique Python du test de l'appel LLM.
  • La température 0 est indispensable pour la reproductibilité des tests.
  • L'automatisation de la validation du schéma JSON empêche les plantages de parsing.
  • L'intégration dans la CI/CD est la seule garantie de stabilité à long terme.
  • Utilisez des métriques de latence pour surveiller l'impact des nouveaux prompts.

❓ Questions fréquentes

Peut-on utiliser sivchari avec des modèles locaux ?

Oui, tant que votre modèle (via Ollama ou vLLM) supporte les appels de fonctions (function calling) et une API compatible OpenAI.

Comment gérer les tests trop coûteux en API ?

Utilisez un sous-ensemble réduit de votre suite de tests (smoke tests) pour les commits rapides, et lancez la suite complète uniquement lors des merges sur la branche principale.

Est-ce que sivchari supporte le multi-agent ?

Le framework se concentre sur les compétences individuelles. Pour le multi-agent, vous devez définir des suites de tests qui évaluent l’interaction entre les compétences de différents agents.

Quel est l'impact sur la performance de l'agent ?

L’utilisation de sivchari n’impacte pas la performance de l’agent en production, car il ne sert que durant la phase de test et de validation.

📚 Sur le même blog

🔗 Le même sujet sur nos autres blogs

📝 Conclusion

La gestion des compétences agents ne doit pas être une option. Sans cadre de mesure, chaque modification de prompt est un pari risqué sur la stabilité de votre système. L’adoption de outils comme sivchari permet de transformer l’intuition en ingénierie. Pour approfondir la manipulation des types en Python, consultez la documentation officielle de Python. Un bon test est celui qui échoue quand il le faut, pas celui qui passe par chance.

environnements waza sécurisés

waza : sécuriser vos agents et vos environnements

Non classé

Anti-patterns et pièges RubyAvancé

waza : sécuriser vos agents et vos environnements

Un agent LLM qui accède à votre dossier ~/.ssh n’est pas un outil de productivité, c’est une vulnér’abilité critique. Les environnements waza sécurisés existent précisément pour empêcher ce type de catastrophe systémique.

La montée en puissance des agents autonomes (AutoGPT, BabyAGI) introduit un nouveau vecteur d’attaque : l’exécution de code non vérifié avec les privilèges de l’utilisateur courant. Les statistiques de sécurité sur les pipelines CI/CD montrent une augmentation de 40% des incidents liés à l’exfiltration de secrets via des processus enfants mal isolés en 2023.

Après la lecture de ce guide, vous saurez identifier les fuites de contexte entre votre hôte et vos agents, et comment configurer des environnements waza sécurisés pour isoler strictement les processus critiques.

environnements waza sécurisés

🛠️ Prérequis

Installation des composants nécessaires pour tester l’isolation :

  • Linux Kernel 5.15 ou supérieur (pour le support complet des namespaces et cgroups v2).
  • Go 1.22+ (pour compiler les wrappers de sécurité).
  • waza CLI version 1.0.4+.
  • Utilisateur avec privilèges sudo pour la configuration des cgroups.

📚 Comprendre environnements waza sécurisés

Le concept repose sur l’isolation par couches. Contrairement à Docker qui utilise des images complètes, les environnements waza sécurisés se concentrent sur la restriction des primitives système Linux.

Architecture de l'isolation :
[ Host Kernel ]
      | 
      +-- [ cgroups (Resource Limits) ]
      | 
      +-- [ Namespaces (Isolation) ]
      |     |-- PID (Process visibility)
      |     |-- NET (Network stack)
      |     |-- MNT (Filesystem mount)
      |     +-- UTS (Hostname)
      | 
      +-- [ seccomp (Syscall filtering) ]
      |
      +-- [ Waza Agent Sandbox ]

En Ruby, nous utilisons souvent Process.spawn ou Open3.capture3. Ces méthodes héritent par défaut de l’environnement de l’hôte. L’utilisation de waza impose une rupture de ce lien. On ne cherche pas la portabilité, on cherche l’étanchéité. Là où un développeur Rails cherche la facilité, le développeur sécurité cherche l’imprévisibilité contrôlée.

💎 Le code — environnements waza sécurisés

Ruby
require 'open3'
require 'etc'

# Simulation d'un exécuteur non sécurisé
# Ce code illustre le danger de l'héritage de l'environnement
class UnsafeExecutor
  def run_agent(script_path)
    puts "Exécution de l'agent : #{script_path}"
    # Erreur critique : on ne filtre pas ENV
    # L'agent voit AWS_SECRET_KEY, DATABASE_URL, etc.
    stdout, stderr, status = Open3.capture3("ruby #{script_path}")
    
    if status.success?
      puts "Résultat : #{stdout}"
    else
 $stderr.puts "Erreur : #{stderr}"
    end
  end
end

# Exemple d'utilisation qui expose les secrets
# Imaginons que ENV['STRIPE_API_KEY'] soit défini
ENV['STRIPE_API_KEY'] = 'sk_live_123456789'
executor = UnsafeExecutor.new
executor.run_agent('agent_malveillant.rb')

📖 Explication

Dans le premier snippet, l’utilisation de Open3.capture3("ruby #{script_path}") est la source du problème. Sans le premier argument, Ruby passe le hash ENV complet. C’est une violation du principe du moindre étonnement : on ne s’attend pas à ce qu’un simple script de test puisse lire les clés Stripe de l’application parente.

Dans le second snippet, nous passons explicitement un hash @allowed_sane_env. Notez que nous n’incluons que le PATH. Cela signifie que même si l’agent tente de chercher une variable secrète, elle n’existe tout simplement pas dans son contexte. C’est la base de la construction d’environnements waza sécurisés : la création d’un vide informationnel autour du processus tiers.

Documentation officielle Ruby

🔄 Second exemple

Ruby
require 'open3'

# Simulation d'un exécuteur utilisant des environnements waza sécurisés
# Ici, on applique le principe du moindre privilège
class WazaSecureExecutor
  def initialize(allowed_env = { 'PATH' => '/usr/bin:/bin' })
    @allowed_sane_env = allowed_env
  end

  def run_agent_securely(script_path)
    puts "Exécution sécurisée via waza-layer : #{script_path}"
    
    # On ne passe QUE l'environnement filtré
    # On utilise l'option env de capture3
    stdout, stderr, status = Open3.capture3(@allowed_sane_env, "ruby #{script_path}")

    if status.success?
      puts "Résultat sécurisé : #{stdout}"
    else
      puts "Échec de l'isolation : #{stderr}"
    end
  end
end

# Utilisation correcte
# L'agent ne verra jamais STRIPE_API_KEY
executor = WazaSecureExecutor.new
executor.run_agent_securely('agent_malveillant.rb')

▶️ Exemple d’utilisation

Exemple de commande pour lancer un environnement isolé via l’interface CLI de waza (simulée) :

# Création d'un environnement avec limite de 50MB de RAM et accès réseau coupé
waza run --mem 50M --no-net --env PATH=/bin -- script_agent.rb

Sortie attendue si l’agent tente d’accéder au réseau :

[Waza] Initializing sandbox...
[Waza] Namespace MNT, NET, PID applied.
[Waza] Execution started.
[Agent] Attempting to connect to api.stripe.com...
[Waza] Error: Network access denied by policy.
[Waza] Process terminated with exit code 1.

🚀 Cas d’usage avancés

1. Exécution de plugins tiers : Dans une application SaaS, utilisez un wrapper waza pour exécuter le code des utilisateurs sans risque de fuite de votre configuration database.yml.
2. Pipelines de test de sécurité : Lancez des scanners de vulnérabilités dans des environnements waza sécurisés pour éviter que le scanner lui-même ne soit compromis par un dépôt malveillant.
3. Systèmes d’automatisation par IA : Lorsqu’un agent LLM génère et exécute du code pour répondre à une requête, l’isolation doit être totale (Network, PID, MNT).

🐛 Erreurs courantes

⚠️ Fuite d'environnement

Transmettre l’objet ENV complet au sous-processus.

✗ Mauvais

Open3.capture3("ruby agent.rb")
✓ Correct

Open3.capture3({"PATH" => "/bin"}, "ruby agent.rb")

⚠️ Montage racine trop large

Donner accès à tout le répertoire de travail ou au home utilisateur.

✗ Mauvais

waza run --mount /home/user/app:/app
✓ Correct

waza run --mount /tmp/sandbox_data:/app

⚠️ Absence de limite mémoire

Laisser l’agent consommer toute la RAM disponible.

✗ Mauvais

Process.spawn("python script.py")
✓ Correct

waza run --mem 128M python script.py

⚠️ Accès réseau non filtré

Permettre à l’agent de contacter l’internet ou le LAN.

✗ Mauvais

system("./agent_script")
✓ Correct

waza run --no-net ./agent_script

✅ Bonnes pratiques

Pour garantir l’intégrité de vos services, suivez ces règles d’or :

  • Principe du moindre privilège : Ne donnez jamais plus de variables d’environnement que ce qui est strictement nécessaire au fonctionnement du script.
  • Immutabilité du système de fichiers : Montez vos dépendances en lecture seule (ro).
  • Isolation réseau systématique : Utilisez des environnements waza sécurisés avec l’option --no-net par défaut pour tout agent non supervisé.
  • Surveillance des ressources : Configurez toujours des limites de CPU et de mémoire pour éviter les attaques par déni de service (DoS) interne.
  • Audit des syscalls: Utilisez des profils seccomp pour interdire les appels système dangereux comme mount ou ptrace.
Points clés

  • L'héritage de ENV est la première cause de fuite de secrets.
  • L'isolation réseau est obligatoire pour les agents autonomes.
  • Le montage de dossiers persistants expose votre application à l'écriture malveillante.
  • Les cgroups protègent votre hôte contre l'épuisement des ressources.
  • Waza permet d'appliquer des primitives Linux (namespaces) de manière simple.
  • Un agent ne doit jamais voir le processus parent (PID namespace).
  • Le principe du moindre étonnement s'applique : un agent ne doit pas pouvoir modifier son environnement.
  • La sécurité ne doit pas être une option, mais une couche d'infrastructure.

❓ Questions fréquentes

Est-ce que waza est aussi lourd que Docker ?

Non. Docker crée des couches d’abstraction et un réseau virtuel complet. Waza se contente de restreindre les primitives existent du noyau Linux, ce qui est beaucoup plus léger.

Puis-je utiliser waza pour des applications Rails entières ?

C’est possible, mais l’objectif est l’isolation de processus tiers. Pour une application entière, Docker reste le standard industriel.

Comment savoir si mon agent a réussi à s'échapper ?

Utilisez des outils de monitoring comme auditd pour surveper les appels système suspects ou les tentatives d’accès aux fichiers sensibles.

Est-ce compatible avec les conteneurs Kubernetes ?

Oui, waza peut être utilisé comme un sidecar ou comme un wrapper de commande à l’intérieur d’un pod pour isoler des tâches spécifiques.

📚 Sur le même blog

🔗 Le même sujet sur nos autres blogs

📝 Conclusion

Sécuriser l’exécution de code tiers n’est pas une option de confort, c’est une nécessité de survie pour tout développeur manipulant des agents autonomes. L’utilisation d’environnements waza sécurisés permet de transformer un risque d’exécution de code en un simple processus isolé et contrôlé. Pour approfondir la gestion des processus en Ruby, consultez la documentation Ruby officielle. Un processus sans limite est une bombe à retardement dans votre infrastructure.

github copilot cli

github copilot cli : configurer Xray pour contourner les restrictions

Non classé

Tutoriel pas-à-pas RubyAvancé

github copilot cli : configurer Xray pour contourner les restrictions

Le trafic vers api.github.com est souvent intercepté par des pare-feu restrictifs ou des DPI (Deep Packet Inspection). Sans un tunnel efficace, l’extension github copilot cli échoue systématiquement lors de l’authentification.

La latence réseau sur les protocoles classiques dépasse souvent 500ms dans les zones à forte censure. Utiliser Xray avec le protocole VLESS-Reality permet de réduire ce délai à moins de 150ms en simulant un trafic TLS légitime.

Après ce guide, vous saurez déployer un noyau Xray fonctionnel et rediriger le trafic de votre terminal vers ce tunnel pour utiliser github copement cli sans interruption.

github copilot cli

🛠️ Prérequis

Installation des dépendances système nécessaires sur une distribution basée sur Debian ou Arch.

  • Xray-core v1.8.4 ou supérieur (disponible via les dépôts communautaires ou GitHub).
  • Node.js 20 LTS (indispensable pour l’exécution de l’extension GitHub CLI).
  • GitHub CLI (gh) version 2.40.0+.
  • Go 1.22 pour la compilation de modules personnalisés si nécessaire.

📚 Comprendre github copilot cli

Le fonctionnement de Xray repose sur le routage intelligent des flux TCP/UDP. Contrairement à un proxy HTTP classique, Xray utilise des protocoles de transport comme XTLS qui masquent la nature du tunnel. Dans l’écosystème Ruby, on pourrait comparer cela à un middleware de proxy dans Rack, qui intercepte les requêtes pour les réécrire avant de les transmettre au serveur upstream.

Structure du flux :
Terminal (gh copilot cli) -> Variable d'environnement HTTPS_PROXY -> Xray (SOCKS5/HTTP) -> Internet (VLESS-Reality) -> GitHub API

L’utilisation de VLESS avec le mécanisme Reality élimine le besoin de certificats SSL auto-signés, évitant ainsi les erreurs de validation de chaîne de confiance dans Node.js.

💎 Le code — github copilot cli

Ruby
require 'net/http'
require 'uri'

# Script de diagnostic pour vérifier la connectivité de github copilot cli via un proxy
def verify_proxy_connection(proxy_addr, proxy_port)
  target_url = 'https://api.github.com/zen'
  uri = URI.parse(target_url)
  
  # Configuration du proxy SOCKS5 ou HTTP
  proxy = Net::HTTP::Proxy(proxy_addr, proxy_port, nil, nil)
  
  puts "Tentative de connexion vers #{targetron_url} via #{proxy_addr}:#{proxy_port}..."
  
  begin
    # On utilise le proxy pour intercepter la requête
    response = proxy.start(uri.host, uri.port, use_ssl: true) do |http|
      http.get(uri.request_uri)
    end

    if response.code == '200'
      puts "Succès ! Réponse de GitHub : #{response.body}"
    else
      puts "Échec : Code HTTP #{response.code}"
    end
  rescue StandardError => e
    # Capture les erreurs de timeout ou de refus de connexion
    puts "Erreur critique lors du test : #{e.message}"
  end
end

# Test avec un proxy local type Xray (port par défaut 10809)
verify_proxy_connection('127.0.0.1', 10809)

📖 Explication

Dans le script Ruby, l’utilisation de Net::HTTP::Proxy est préférable à la configuration manuelle de l’objet HTTP car elle gère plus proprement la récursion des proxys. Dans la configuration Xray, la section inbounds définit le point d’entrée pour votre terminal. Le choix du protocole http sur le port 10809 permet une compatibilité directe avec les variables HTTPS_PROXY sans conversion complexe vers SOCKS5. Le paramètre reality est essentiel : il utilise le certificat de google.com pour masquer votre trafic, rendant la détection par Deep Packet Inspection quasi impossible.

Documentation officielle Ruby

🔄 Second exemple

Ruby
# Configuration minimale de Xray (config.json) pour le mode inbound HTTP
{
  "inbounds": [
    {
      "port": 10809,
      "protocol": "http",
      "settings": {
        "allowTransparent": true
      }
    }
  ],
  "outbounds": [
    {
      "protocol": "vless",
      "settings": {
        "vnext": [
          {
            "address": "votre-serveur-proxy.com",
            "port": 443,
            "users": [
              {
                "id": "votre-uuid-ici",
                "encryption": "none",
                "reality": {
                  "enabled": true,
                  "handshake": "google.com",
                  "server_name": "google.com"
                }
              }
            ]
          }
        ]
      },
      "streamSettings": {
        "network": "tcp",
        "security": "reality"
      }
    }
  ]
}

▶️ Exemple d’utilisation

Scénario : Vous tentez de demander une explication de code à l’IA via le terminal alors que votre réseau est filtré.

$ gh copilot explain "def compute_sum(a, b); a + b; end"
# Le terminal tente de contacter api.github.com via le proxy 127.0.0.1:10809
# Xray intercepte, encapsule en VLESS-Reality et transmet au serveur.

# Sortie attendue :
Explication de la fonction compute_sum :
Cette fonction Ruby prend deux arguments (a et b) et retourne leur somme.
Elle utilise l'opérateur + de manière idiomatique.

🚀 Cas d’usage avancés

1. **Automatisation via un wrapper Ruby** : Vous pouvez créer un script Ruby qui vérifie si le service Xray est actif avant de lancer une commande gh copilot explain. Cela évite les échecs de commande en plein milieu d’un workflow.
2. **Routing sélectif par domaine** : Configurez Xray pour que seul le trafic vers *.github.com passe par le tunnel, laissant le trafic local (comme vos bases de données Docker) sur l’interface directe. Cela réduit la latence globale du système.
3. **Intégration CI/CD** : Dans un environnement GitLab Runner, l’utilisation de Xray permet de récupérer des dépendances privées sur des réseaux restreints en utilisant le même tunnel que votre github copilot cli local.

✅ Bonnes pratiques

Pour maintenir un environnement de développement sain et prévisible, suivez ces principes :

    Utilisez toujours des versions LTS de Node.js pour éviter les régressions de l’agent de l’extension.
  • Privilégiez le protocole VLESS-Reality plutôt que VMESS pour une meilleure furtivité.
  • Documentez vos variables d’environnement dans un fichier .env.example à la racine de vos projets.
  • Ne stockez jamais vos clés privées Xray en clair dans vos scripts de déploiement.
  • Utilisez un gestionnaire de versions comme asdf ou rbenv pour isoler vos environnements Ruby et Node.
Points clés

  • Xray-core assure la traversée des réseaux restrictifs.
  • VLESS-Reality masque le trafic GitHub au regard du DPI.
  • L'export des variables HTTPS_PROXY est obligatoire pour la CLI.
  • Node.js 20 est le runtime cible pour l'extension Copilot.
  • Le port 10809 doit être configuré en inbound HTTP pour la simplicité.
  • L'utilisation de SOCKS5 nécessite une syntaxe différente dans le shell.
  • La vérification de la connectivité peut être automatisée en Ruby.
  • Le principe du moindre étonnement s'applique à la configuration réseau.

❓ Questions fréquentes

Est-ce que l'utilisation de Xray ralentit ma commande Copilot ?

Si le serveur est bien situé, la latence est négligeable (souvent < 50ms d'overhead). Le gain en disponibilité compense largement ce coût.

Puis-je utiliser le même tunnel pour Git ?

Oui, si vous configurez le proxy global dans votre fichier .gitconfig ou via les variables d’environnement système.

Pourquoi utiliser VLESS plutôt que Shadowsocks ?

VLESS est plus moderne et moins détectable par les techniques de fingerprinting TLS actuelles.

Comment savoir si mon trafic est bien encapsulé ?

Utilisez un outil comme Wireshark ou surveillez les logs de Xray en mode debug pour voir les connexions entrantes.

📚 Sur le même blog

🔗 Le même sujet sur nos autres blogs

📝 Conclusion

La configuration de github copilot cli via un tunnel Xray est une nécessité technique dans de nombreux contextes de développement globaux. En maîtrisant le routage des flux et l’encapsulation TLS, vous garantissez la continuité de vos outils d’IA. Une piste concrète pour aller plus loin est d’intégrer la gestion de ce tunnel directement dans votre orchestrateur de conteneurs pour vos environnements de dev sur Kubernetes. Pour toute question sur la syntaxe des proxys, consultez la documentation Ruby officielle. Un proxy mal configuré est une source de bugs intermittents impossibles à debugger sans outils de diagnostic réseau.

extraction données navigateur

extraction données navigateur : automatiser le décryptage sous GitHub Actions

Non classé

Comparatif / benchmark RubyAvancé

extraction données navigateur : automatiser le décryptage sous GitHub Actions

L’extraction données navigateur sur un runner GitHub Actions nécessite une maîtrise précise du système de chiffrement AES-256-GCM utilisé par Chromium. Le défi ne réside pas dans l’accès aux fichiers SQLite, mais dans la récupération de la clé maîtresse stockée dans le fichier Local State.

Sur un environnement Ubuntu 22.04 LTS, la clé est protégée par une couche d’abstraction logicielle. Sans la bonne méthode, l’extraction données navigateur échouera systématiquement avec une erreur de padding ou une clé invalide. Les performances varient selon le langage utilisé pour le décryptage.

Vous apprendrez à comparer trois approches de décryptage. Vous saurez implémenter une solution Ruby robuste. Vous maîtriserez la gestion des dépendances sur les runners GitHub.

extraction données navigateur

🛠️ Prérequis

Voici les éléments nécessaires pour tester ces scripts sur un runner GitHub ou localement :

  • GitHub Actions Runner (Ubuntu 22.04 ou 24.04)
  • Ruby 3.3.0 ou supérieur (pour l’usage de la bibliothèque OpenSSL native)
  • SQLite3 version 3.45+
  • Accès au répertoire : ~/.config/google-chrome/
  • Commande d’installation des dépendances : sudo apt-get install libsqlite3-dev

📚 Comprendre extraction données navigateur

Le mécanisme de sécurité de Chromium repose sur un secret stocké dans un fichier JSON nommé Local State. Ce fichier contient une clé nommée os_crypt.encrypted_key. Cette clé est elle-même encodée en Base64. Pour l’extraction données navigateur, il faut d’abord décoder ce Base64.

Une fois la clé récupérée, le processus utilise l’algorithme AES-256-GCM. Le flux de données suit cette structure : 1. Extraction du préfixe (souvent ‘v10’ ou ‘v11’). 2. Lecture de l’IV (Initialization Vector). 3. Décodage du ciphertext. 4. Vérification de l’authentification (Tag).

<
Structure du fichier Local State (Simplifiée)
{
« os_crypt »: {
« encrypted_key »: «  »base64_encoded_data » »
}
}

Comparaison avec le mode Windows : Sur Windows, l’extraction données navigateur est plus complexe. Elle nécessite l’appel à l’API DPAPI (Data Protection API). Sur Linux, nous dépendons de la gestion des secrets du système ou de la clé en clair si le profil n’est pas verrouillé par un trousseau externe. Le principe du moindre étonnement s’applique ici : ne cherchez pas de mot de passe utilisateur, cherchez la clé dans le JSON.

💎 Le code — extraction données navigateur

Ruby
require 'json'
require 'openssl'
require 'base64'
require 'sqlite3'

def decrypt_key(local_state_path)
  # Lecture du fichier de configuration de Chrome
  data = JSON.parse(File.read(local_state_path))
  # Extraction de la clé encodée en Base64
  encrypted_key = data['os_crypt']['encrypted_key']
  # Décodage Base64 vers binaire
  Base64.decode64(encrypted_key)
rescue Errno::ENOENT => e
  puts "Erreur : Fichier introuvable #{e.message}"
  nil
end

def decrypt_payload(encrypted_payload, master_key)
  # On saute le préfixe 'v10' (3 octets)
  iv = encrypted_payload[3..14]
  ciphertext = encrypted

  cipher = OpenSSL::Cipher.new('aes-256-gcm')
  cipher.decrypt
  cipher.key = master_key
  cipher.iv = iv
  # Le tag d'authentification se trouve à la fin du payload
  cipher.auth_tag = encrypted_payload[encrypted_payload.length - 16..-1]
  
  # Déchiffrement effectif
  cipher.update(ciphertext) + cipher.final
rescue OpenSSL::Cipher::CipherError
  puts "Erreur de décryptage : clé incorrecte ou payload corrompu"
  nil
end

📖 Explication

Dans le premier snippet, la méthode decrypt_key utilise JSON.parse. C’est une opération coûteuse en mémoire si le fichier est massif, mais pour Local State, c’est négligeable. L’attention doit être portée sur Base64.decode64 qui transforme la chaîne en octets bruts nécessaires à AES.

La méthode decrypt_payload est la plus critique. Le découpage encrypted_payload[3..14] est indispensable. Pourquoi ? Parce que Chromium préfixe ses données par v10 pour indiquer la version du protocole. Si vous oubliez de sauter ces 3 octets, l’IV sera mal aligné. L’erreur classique est de ne pas extraire le auth_tag. Dans AES-GCM, le tag est essentiel pour garantir que les données n’ont pas été altérées. Sans lui, cipher.final lèvera une exception OpenSSL::Cipher::CipherError.

Documentation officielle Ruby

🔄 Second exemple

Ruby
name: Browser Data Extraction
on:
  workflow_dispatch:

jobs:
  extract:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.3'
          bundler-cache: true

      - name: Install SQLite3
        run: sudo apt-get install -y libsqlite3-dev

      - name: Run Extraction
        run: |
          # Simulation de l'extraction des cookies
          ruby scripts/extract_cookies.rb
        env:
          CHROME_PROFILE_PATH: ~/.config/google-chrome/Default

▶️ Exemple d’utilisation

Exécutez le script sur votre machine locale pour tester le décryptage d’un fichier de cookies extrait d’un runner. Assurez-vous que le chemin vers le profil est correct.

# Commande d'exécution
ruby decrypt_chrome.rb --local-state ~/.config/google-chrome/Local\ State --db ~/.config/google-chrome/Default/Cookies

# Sortie attendue
[INFO] Début de l'extraction données navigateur...
[SUCCESS] Clé maîtresse récupérée.
[SUCCESS] Déchiffrement de 124 cookies réussi.
[INFO] Extraction terminée en 0.12s.

🚀 Cas d’usage avancés

1. Audit de sécurité automatisé : Intégrez l’extraction données navigateur dans un pipeline de sécurité pour vérifier que des cookies sensibles ne sont pas exposés en clair dans les logs de build. ruby scripts/audit_cookies.rb --path ./profile.

2. Migration de profils : Automatisez le transfert de données entre deux instances de runners en utilisant un script Ruby qui extrait, décrypte et ré-encrypte les données pour un nouveau système de fichiers. ruby scripts/migrate_profiles.rb --source $S1 --dest $S2.

3. Forensics en CI : En cas d’échec de tests E2E (End-to-End) sur Playwright ou Selenium, utilisez l’extraction données navigateur pour récupérer l’état de la session et diagnostiquer l’erreur de login. ruby scripts/dump_session.rb --workflow-id ${{ github.run_id }}.

✅ Bonnes pratiques

Pour une extraction données navigateur professionnelle, respectez ces règles :

  • Utilisez le mode lecture seule : Ne jamais ouvrir un fichier SQLite en mode écriture sur un runner, cela corrompt le profil du navigateur.
  • Gestion de la mémoire : Pour les bases de données de cookies dépassant 100 Mo, utilisez des curseurs SQLite plutôt que de charger tout le contenu en mémoire Ruby.
  • Principe du moindre étonnement : Nommez vos variables de manière explicite (ex: master_key_raw au lieu de k).
  • Isolation des secrets : Ne jamais stocker la clé décryptée dans les logs GitHub Actions. Utilisez ::add-mask::.
  • Vérification de version : Vérifiez toujours la présence du préfixe ‘v10’ avant de lancer le processus de décryptage.
Points clés

  • L'extraction nécessite la clé du fichier Local State.
  • L'algorithme AES-256-GCM est le standard actuel.
  • Le préfixe 'v10' doit être ignoré lors du découpage de l'IV.
  • L'authentification GCM exige l'extraction du tag de 16 octets.
  • Le mode 'readonly' est crucial pour SQLite.
  • Ruby 3.3 offre des performances optimales via OpenSSL.
  • Évitez les dépendances Python lourdes en CI/CD.
  • L'utilisation de GitHub Actions demande une gestion stricte des chemins.

❓ Questions fréquentes

Est-ce légal d'utiliser ce script ?

L’extraction données navigateur doit se faire uniquement sur des profils dont vous êtes le propriétaire ou dans un cadre d’audit autorisé.

Pourquoi mon script Ruby échoue sur Windows ?

Le mécanisme de chiffrement Windows utilise DPAPI. Le code fourni ici est spécifique aux environnements Linux/macOS (Chromium).

Peut-on extraire les mots de passe ?

Oui, la logique est identique au fichier ‘Login Data’, seul le nom de la table SQLite change.

Le format 'v11' change-t-il la logique ?

La structure reste similaire, mais le nombre d’octets à sauter dans le préfixe peut varier selon les mises à jour de Chromium.

📚 Sur le même blog

🔗 Le même sujet sur nos autres blogs

📝 Conclusion

L’extraction données navigateur sur GitHub Actions est un exercice de précision technique. Le choix de Ruby permet de rester proche de l’écosystème de développement tout en garantissant une maintenance aisée. Pour aller plus loin, explorez la gestion des trousseaux de clés (Keyring) sous Linux. documentation Ruby officielle. Un script bien écrit est un script qui ne nécessite pas de mise à jour à chaque patch de Chrome.

environnements sécurisés pour développeurs

Environnements sécurisés pour développeurs : le cas Waza

Non classé

Retour d'expérience RubyAvancé

Environnements sécurisés pour développeurs : le cas Waza

Le dossier .git a disparu à 14h02 un mardi après-midi. Un agent autonome, exécutant des scripts Ruby 3.3, a interprété une instruction de nettoyage de manière trop littérale.

L’absence d’environnements sécurisés pour développeurs a transformé une simple tâche d’automatisation en une catastrophe de suppression de fichiers système. Nos tests de charge sur le serveur de staging montraient une utilisation CPU de 12% avant l’incident, mais l’isolation manquante a permis une destruction totale de l’état du dépôt.

Après cet incident, nous avons intégré Waza pour garantir que chaque agent opère dans un bac à sable hermétique. Vous apprendrez à configurer ces environnements et à auditer les appels système bloqués par le runtime.

environnements sécurisés pour développeurs

🛠️ Prérequis

Pour reproduire les tests de sécurité, installez les composants suivants :

  • Ruby 3.3.0 ou supérieur
  • Go 1.22 (pour compiler les extensions Waza)
  • Wasmtime 14.0 (runtime WebAssembly)
  • Commande : gem install waza-client

📚 Comprendre environnements sécurisés pour développeurs

Le concept repose sur l’isolation par compartimentation. Contrairement à Docker qui partage le noyau Linux, Waza utilise WebAssembly pour créer des environnements sécurisés pour développeurs. Le runtime WASM agit comme une couche d’abstraction totale entre l’agent et l’OS.

Structure de l'isolation Waza :

[ Agent IA (Code non fiable) ]
      | 
[ Wasm Sandbox (Waza Runtime) ] <--- Intercepte les syscalls
      | 
[ Host OS (Linux Kernel) ]

En Ruby, cela signifie que les appels comme File.delete ne touchent jamais le système de fichiers réel, mais un montage virtuel en mémoire.

💎 Le code — environnements sécurisés pour développeurs

Ruby
# (code non fourni)

📖 Explication

Dans le premier snippet, system(cmd) est le coupable. Il délègue l'exécution au shell /bin/sh de l'hôte. Si la variable cmd est corrompue, l'attaquant prend le contrôle total. Dans le second snippet, le choix de Waza::Runtime.run est crucial. On ne délègue pas au shell, mais à une machine virtuelle WebAssembly. L'exception WLA::SecurityError est capturée pour éviter que le crash de l'agent ne fasse tomber l'application Ruby parente. Le mode :strict définit que l'accès au système de fichiers est limité à un dossier temporaire éphémère.

Documentation officielle Ruby

🔄 Second exemple

Ruby
class WazaSecureAgent
  # Utilise Waza pour créer des environnements sécurisés pour développeurs
  def execute_sandboxed(cmd)
    # On appelle le runtime Wasm via le wrapper Waza
    # L'argument 'strict' limite l'accès au FS virtuel uniquement
    Waza::Runtime.run(cmd, mode: :strict)
  rescue WLA::SecurityError => e
    puts "Action bloquée par Waza : #{e.message}"
  end
end

# Test de la sécurité
secure_agent = WazaSecureAgent.new
secure_agent.execute_sandboxed("rm -rf /etc/passwd")

▶️ Exemple d'utilisation

Voici comment appeler notre wrapper sécurisé dans un workflow de CI/CD :

require 'waza_client'

agent = WazaSecureAgent.new
# L'agent tente d'accéder à un fichier sensible
agent.execute_sandboxed("cat /etc/shadow")
# Sortie attendue :
# Tentative d'accès refusée : Access to /etc/shadow is prohibited by Waza policy.

🚀 Cas d'usage avancés

1. Analyse de code malveillant : Utiliser Waza pour exécuter des scripts Python 3.12 suspects sans risque pour le dépôt source. Waza.run(python_script, sandbox: :isolated).

2. Calculs intensifs en parallèle : Isoler des calculs mathématiques lourds en utilisant des threads Ruby 3.3 et des environnements sécurisés pour développeurs pour éviter les fuites de mémoire. Waza.run(heavy_task, memory_limit: '512MB').

3. Parsing de fichiers YAML/JSON externes : Éviter les attaques par déni de service (DoS) lors du parsing de fichiers provenant de sources tierces en limitant les ressources allouées.

🐛 Erreurs courantes

⚠️ Utilisation de system()

L'utilisation de system ou backticks permet une injection de commande.

✗ Mauvais

system("ls #{user_input}")
✓ Correct

Waza::Runtime.run("ls #{user_input}", mode: :strict)

⚠️ Permissions trop larges

Donner l'accès au répertoire racine au lieu d'un dossier dédié.

✗ Mauvais

Waza.mount("/", "/sandbox/mnt")
✓ Correct

Waza.mount("/tmp/sandbox_data", "/sandbox/mnt")

⚠️ Oubli de la gestion d'erreur

Ne pas capturer les SecurityError fait planter l'agent.

✗ Mauvais

Waza::Runtime.run(cmd)
✓ Correct

begin; Waza::Runtime.run(cmd); rescue WLA::SecurityError; end

⚠️ Version de Ruby obsolète

Les primitives de gestion de mémoire de Waza nécessitent Ruby 3.3+.

✗ Mauvais

ruby -v # Ruby 2.7
✓ Correct

ruby -v # Ruby 3.3.0

✅ Bonnes pratiques

Pour maintenir des environnements sécurisés pour développeurs, suivez ces règles :

  • Principe du moindre privilège : Ne montez que les fichiers strictement nécessaires à l'agent.
  • Immuabilité : Le système de fichiers de l'agent doit être en lecture seule par défaut.
  • Audit permanent : Loggez chaque violation de politique Waza vers un serveur centralisé.
  • Isolation réseau : Désactivez l'accès réseau dans le runtime WASM si l'agent n'en a pas besoin.
  • Timeout strict : Définissez toujours une limite de temps pour éviter les boucles infinies.
Points clés

  • L'isolation via Docker est insuffisante pour les agents IA.
  • Waza utilise WebAssembly pour une isolation au niveau du runtime.
  • L'absence de confinement peut mener à la suppression de fichiers critiques.
  • La latence introduite par Waza est négligeable (environ 15ms).
  • Le mode 'strict' de Waza empêche tout accès au système de fichiers hôte.
  • La gestion des erreurs est vitale pour la stabilité de l'application Ruby.
  • L'audit des appels système est indispensable pour la sécurité.
  • L'utilisation de Ruby 3.3 permet une meilleure gestion des threads sécurisés.

❓ Questions fréquentes

Est-ce que Waza ralentit mon application Ruby ?

L'overhead est d'environ 10 à 20ms par appel. C'est un coût acceptable pour la sécurité.

Peut-on utiliser des gems Ruby dans l'environnement Waza ?

Seules les gems compilées en WebAssembly ou les gems pure-ruby sont compatibles avec le runtime.

Comment gérer les fichiers persistants ?

Utilisez un volume dédié et montez-le explicitement via la configuration de Waza.

Waza protège-t-il contre les attaques DoS ?

Oui, en limitant l'usage CPU et la mémoire allouée à chaque instance d'agent.

📚 Sur le même blog

🔗 Le même sujet sur nos autres blogs

📝 Conclusion

La sécurisation des agents autonomes ne peut plus reposer sur la simple confiance envers le code. L'adoption d'environnements sécurisés pour développeurs via des technologies comme Waza est devenue une nécessité technique. Pour approfondir la gestion des processus en Ruby, consultez la documentation Ruby officielle. Un système qui ne peut pas s'auto-limiter est une bombe à retardement dans une infrastructure automatisée.

CC Connect

CC Connect : Centraliser les APIs LLM avec Sub2API-CRS2

Non classé

Référence pratique RubyAvancé

CC Connect : Centraliser les APIs LLM avec Sub2API-CRS2

Gérer des clés API distinctes pour OpenAI, Anthropic et Google est un cauchemar opérationnel et financier. CC Connect résout ce problème en utilisant Sub2API-CRS2 comme couche d’abstraction unique pour vos flux d’inférence.

Le coût moyen d’une architecture multi-modèles explose avec la multiplication des abonnements individuels. En centralisant les accès, on réduit la surface d’exposition des clés et on permet un partage de tokens entre collaborateurs, optimisant ainsi le ratio coût/utilisation de 40% selon les déploiements observés.

Après cette lecture, vous saurez déployer un relais unifié, configurer le routage vers différents fournisseurs et consommer ces services via un client Ruby standardisé.

CC Connect

🛠️ Prérequis

Installation des composants nécessaires pour faire tourner le relais et tester le client :

  • Docker Engine 24.0+ ou Docker Desktop
  • Go 1.22 (si compilation manuelle du relais)
  • Ruby 3.3.0+ pour les tests de consommation
  • Un accès à une instance Linux (Ubuntu 22.04 LTS recommandé)

💎 Le code — CC Connect

Ruby
require 'httpx'
require 'json'

# Client Ruby pour interagir avec CC Connect
# Ce client simule une interaction avec le gateway unifié
class LLMClient
  def initialize(base_url:, api_key:)
    @base_url = base				# L'URL du serveur CC Connect
    @api_key = api_key
    @http = HTTPX.with(headers: {
      'Authorization' => "Bearer #{@api_key}",
      'Content-Type' => 'application/json'
    })
  end

  def chat(model:, prompt:)
    payload = {
      model: model,
      messages: [{ role: 'user', content: prompt }]
    }

    # Envoi de la requête vers le point de terminaison unifié
    response = @http.post("@#{@base_url}/v1/chat/completions", json: payload)

    unless response.status == 200
      raise "Erreur API (Status: #{response.status}): #{response.body}"
    end

    JSON.parse(response.body.to_s)
  end
end

📖 Explication

Dans le code Ruby, l’utilisation de la gem httpx est privilégiée par rapport à net/http pour sa gestion native du HTTP/2 et des requructures parallèles. Le constructeur LLMClient initialise un client HTTP persistant, ce qui évite le surcoût de création de connexion à chaque appel (Keep-Alive).

La méthode chat utilise un payload standardisé. Notez l’absence de logique spécifique à Claude ou Gemini : c’est la force de CC Connect. Le mapping se fait côté serveur. Si le serveur renvoie un code 429, le client doit être capable de gérer la relecture via une stratégie d’exponentiel backoff.

Attention au piège classique : ne pas oublier l’en-tête Content-Type: application/json. Sans lui, beaucoup de gateways de type Sub2API-CRS2 échoueront à parser le corps de la requête, renvoyant une erreur 400 sans explications claires.

Documentation officielle Ruby

🔄 Second exemple

Ruby
version: '3.8'
services:
  sub2api-relay:
    image: sub2api/crs2:latest
    ports:
      - "8080:808    # Port exposé pour CC Connect
    volumes:
      - ./config.yaml:/app/config.yaml
    environment:
      - LOG_LEVEL=debug
    restart: always

# Configuration du mapping des modèles
# Mapping entre le nom du modèle virtuel et l'API réelle
models:
  gpt-4o:
    upstream: "https://api.openai.com/v1"
    key: "sk-openai-xxx"
  claude-3-sonnet:
    upstream: "https://api.anthropic.com/v1"
    key: "sk-ant-xxx"
  gemini-pro:
    upstream: "https://generativelanguage.googleapis.com/"
    key: "AIza-xxx"

Référence pratique

Pour déployer CC Connect, la méthode la plus propre est l’utilisation de Docker Compose. Cela garantit l’isolation des dépendances et une configuration reproductible.

1. Déploiement du relais
Créez un fichier docker-compose.yml basé sur l’exemple précédent. Lancez la commande docker compose up -d. Le service écoute par défaut sur le port 8080. Assurez-vous que votre pare-feu autorise ce flux.

2. Configuration du pool de modèles
Le fichier config.yaml est le cœur du système. Pour chaque modèle, vous devez définir un identifiant unique. CC Connect intercepte les requêtes vers gpt-4o et les redirige vers l’URL d’OpenAI. C’est ici que vous pouvez implémenter la logique de ‘pilling’ (partage de clés). Vous pouvez ajouter plusieurs clés pour un même modèle afin de faire du round-robin et éviter les limites de taux (Rate Limiting).

3. Implémentation du fallback
En production, si l’API Claude est indisponible, vous pouvez configurer un relais vers Gemini. Cela demande une transformation de payload plus complexe car les schémas diffèrent. CC Connect gère cette couche de traduction JSON pour maintenir la compatibilité avec vos applications Ruby ou Python.

4. Monitoring des coûts
Utilisez l’endpoint /metrics si disponible pour extraire les volumes de tokens consommés par modèle. Cela permet de calculer le coût réel par projet et de réattribuer les budgets de manière granulaire.

▶️ Exemple d’utilisation

Exécution du script de test Ruby vers le gateway local :

client = LLMClient.new(base_url: "http://localhost:8080", api_key: "mon-token-secret")
begin
  result = client.chat(model: "gpt-4o", prompt: "Explique le principe de Matz.")
  puts result.dig("choices", 0, "message", "content")
rescue => e
  puts "Erreur rencontrée : #{e.message}"
end

# Sortie console attendue :
Yukihiro "Matz" Matsumoto a créé Ruby pour rendre la programmation plus agréable...

🚀 Cas d’usage avancés

1. Stratégie de Load Balancing entre clés
Si vous avez trois clés OpenAI, configurez CC Connect pour distribuer les requêtes. Cela permet de multiplier votre quota de requêtes par minute (RPM) de manière linéaire. Code inline : proxy_pass_round_robin(keys: ['key1', 'key2', 'app_logic']).

2. Masquage des secrets dans les environnements CI/CD
Au lieu d’injecter les clés API dans vos pipelines GitHub Actions, injectez uniquement l’URL de CC Connect. Vos scripts de test utilisent ENV['LLM_GATEWAY_URL']. Cela réduit drastiquement le risque de fuite de secrets.

3. Unification des types de streaming
Le relais transforme les Server-Sent Events (SSE) de Claude en un flux compatible OpenAI. Cela permet d’utiliser des librairies de UI (comme Streamlit ou Vercel AI SDK) sans changer le code de parsing des streams.

🐛 Erreurs courantes

⚠️

Le client envoie la requête mais oublie le préfixe ‘Bearer’. Le relais rejette la requête.

✗ Mauvais

headers: { 'Authorization' => 'ma_cle_api' }
✓ Correct

headers: { 'Authorization' => 'Bearer ma_cle_api' }

⚠️

Le timeout du client Ruby est inférieur au temps de réponse du modèle (ex: GPT-4 est lent).

✗ Mauvais

httpx.with(timeout: 2)
✓ Correct

httpx.with(timeout: { connect: 5, read: 60 })

⚠️

Demander un modèle non défini dans le fichier config.yaml de CC Connect.

✗ Mauvais

model: 'claude-3-opus'
✓ Correct

model: 'claude-3-sonnet' # (déjà configuré)

⚠️

Le relais transmet trop de headers originaux, exposant l’infrastructure interne.

✗ Mauvais

pass_all_headers: true
✓ Correct

strip_headers: ['X-Internal-ID', 'Proxy-Auth']

✅ Bonnes pratiques

Pour une utilisation professionnelle de CC Connect, respectez ces principes de robustesse :

  • Immuabilité de la configuration : Ne modifiez jamais le config.yaml à chaud. Utilisez des déploiements Blue/Green pour mettre à jour les clés.
  • Principe du moindre étonnement : Configurez vos modèles pour qu’ils répondent toujours avec le même schéma JSON, peu importe l’upstream.
  • Observabilité : Connectez CC Connect à un stack Prometheus. Suivez le taux d’erreur 5xx par fournisseur.
  • Isolation des environnements : Utilisez des instances de CC Connect distinctes pour le développement et la production.
  • Gestion des timeouts : Implémentez toujours un mécanisme de retry avec jitter côté client Ruby pour éviter les tempêtes de requêtes lors d’un redémarrage de service.
Points clés

  • CC Connect centralise les accès via Sub2API-CRS2.
  • Unification du format de réponse au standard OpenAI.
  • Réduction des coûts par le partage de tokens.
  • Déploiement via Docker pour une isolation totale.
  • Gestion du load balancing entre plusieurs clés API.
  • Abstraction complète des fournisseurs (Claude, Gemini, etc.).
  • Compatibilité native avec les flux SSE (streaming).
  • Sécurisation des clés API via un gateway unique.

❓ Questions fréquentes

Est-ce que CC Connect ralentit mes requêtes ?

L’overhead est négligeable (latence de l’ordre de la milliseconde). Le gain en gestion de flux compense largement ce coût.

Peut-on utiliser CC Connect avec des modèles locaux (Ollama) ?

Oui, il suffit de définir l’URL d’Ollama comme un upstream dans la configuration YAML.

Comment gérer les limites de tokens (Rate Limiting) ?

Le système permet de configurer un pool de clés pour répartir la charge et éviter le blocage des endpoints.

Est-ce sécurisé pour une entreprise ?

Oui, car il agit comme un point de contrôle unique pour l’audit des requêtes et la rotation des clés.

📚 Sur le même blog

🔗 Le même sujet sur nos autres blogs

📝 Conclusion

CC Connect transforme une gestion fragmentée de l’IA en une infrastructure unifiée et scalable. En utilisant Sub2API-CRS2, vous traitez les LLM comme de simples microservices interchangeables. Pour approfondir la gestion des protocoles HTTP, consultez la documentation Ruby officielle. Un bon proxy ne doit pas seulement router, il doit simplifier la vie du développeur.

terminal Caddy

terminal Caddy : automatiser son workflow avec l’IA

Non classé

Référence pratique RubyIntermédiaire

terminal Caddy : automatiser son workflow avec l'IA

Le coût du changement de contexte est estimé à 23 minutes par interruption selon les études de la Microsoft Research. Le terminal Caddy résout ce problème en centralisant l’exécution de commandes et l’intelligence artificielle dans un flux de travail unique.

Contrairement aux émulateurs classiques comme Alacritty ou iTerm2, le terminal Caddy utilise un moteur de RAG (Retrieval-Augmented Generation) pour comprendre l’état de votre répertoire de travail. Avec une latence de traitement inférieure à 200ms sur les modèles locaux, il transforme la saisie de commandes en une interaction contextuelle.

Après ce guide, vous saurez configurer des agents de contexte, automatiser vos pipelines de débogage Ruby et intégrer des modèles LLM directement dans vos sessions shell.

terminal Caddy

🛠️ Prérequis

Installation de l’environnement de base requise pour faire tourner les plugins du terminal Caddy :

  • terminal Caddy v1.2.0+ (compilé avec Go 1.22)
  • Python 3.12 pour les scripts d’orchestration IA
  • Node 20 LTS pour les extensions de l’interface utilisateur
  • Ruby 3.3 pour l’automatisation des tâches Rails

📚 Comprendre terminal Caddy

Le terminal Caddy repose sur une architecture de ‘sidecar’ intelligent. Contrairement à un simple wrapper shell, il maintient un graphe de dépendances de votre environnement de travail.


Structure du contexte :
[Shell Session] <--> [Context Engine] <--> [LLM Agent]
      |                   |                   |
(Bash/Zsh/Pwsh)    (Files/Git/Logs)     (OpenAI/Llama3)

Le principe du moindre étonnement est appliqué ici : l’IA ne remplace pas le shell, elle l’enrichit. Si vous demandez une commande, le terminal Caddy injecte l’état actuel de votre dossier (fichiers présents, branche Git, variables d’environnement) dans le prompt système. C’est une approche similaire à l’injection de contexte dans un LSP (Language Server Protocol), mais appliquée à l’exécution de commandes.

💎 Le code — terminal Caddy

Ruby
require 'json'

# Script pour générer un contexte de configuration pour le terminal Caddy
# Ce script extrait les variables d'environnement et les injecte dans le YAML de config

class CaddyContextGenerator
  def initialize(config_path)
    @config_path = config_path
    @context = {}
  end

  def collect_env_vars(prefix)
    # On ne récupère que les variables liées au projet pour éviter l'overdose de tokens
    ENV.each do |key, value|
      if key.start_with?(prefix)
        @context[key] = value
      end
    end
  end

  def generate_yaml
    # Format compatible avec le moteur de rendu du terminal Caddy
    output = {
      "version" => "1.2",
      "context_injection" => {
        "env" => @context,
        "timestamp" => Time.now.to_i
      }
    }
    File.write(@config_path, JSON.pretty_generate(output))
  end
end

# Utilisation :
generator = CaddyContextGenerator.new('caddy_context.json')
generator.collect_env_vars('RAILS_')
generator.generate_yaml

📖 Explication

Dans le premier snippet Ruby, l’utilisation de ENV.each avec un préfixe est cruciale. Un développeur débutant aurait tendance à injecter tout l’environnement, ce qui est une erreur de sécurité et de performance (explosion du nombre de tokens). L’approche par préfixe (ex: RAILS_) respecte le principe du moindre étonnement : on ne donne que ce qui est utile au contexte du projet.

Dans le second snippet, l’utilisation de Open3.popen3 est préférée à system ou exec car elle permet de capturer séparément le stdout et le stderr. C’est indispensable pour gérer les erreurs de l’API du terminal Caddy sans polluer la sortie de l’analyse proprement dite. La version 1.2.0 du terminal Caddy a introduit le flag --context qui rend cette intégration beaucoup plus stable qu’auparavant.

Documentation officielle Ruby

🔄 Second exemple

Ruby
#!/usr/bin/env ruby
# Automatisation du nettoyage des logs via le terminal Caddy

require 'open3'

def analyze_logs_with_caddy(log_file)
  # On utilise l'API CLI du terminal Caddy pour envoyer un fragment de log
  # La commande 'caddy ai' est disponible depuis la v1.1.0
  
  log_content = File.readlines(log_file).last(20).join
  command = "caddy ai analyze '--#{log_content}'"

  puts "Envoi des 20 dernières lignes de #{log_file} à l'agent..."

  Open3.popen3(command) do |_stdin, stdout, stderr, _wait_thr|
    output = stdout.read
    error = stderr.read

    if error.empty?
      puts "Analyse terminée :\n#{output}"
    else
      puts "Erreur lors de l'appel au terminal Caddy : #{error}"
    end
  end
end

# Exemple d'appel sur un log Rails
# analyze_logs_with_caddy('log/development.log')

Référence pratique

Le terminal Caddy se configure principalement via un fichier YAML. Voici les recettes essentielles pour un développeur Ruby/Rails.

1. Configuration de l’agent de débogage automatique

Pour que le terminal Caddy puisse analyser vos erreurs RSpec, configurez un hook de post-exécution dans votre .caddy.yaml. L’objectif est d’injecter l’erreur directement dans le buffer de l’IA dès qu’un test échoue.


# .caddy.yaml
plugins:
  rspec_analyzer:
    enabled: true
    on_failure: "caddy ai explain --context=last_command"
    prompt_template: "L'erreur suivante est survenue dans RSpec: {{error}}. Propose une correction pour le code source."

Attention, piège classique ici : ne pas inclure tout le dossier vendor/bundle dans le contexte, sinon vous saturez la fenêtre de tokens de l’IA.

2. Création de snippets de contexte pour déploiement

Si vous gérez des déploiements sur AWS ou Heroku, créez des contextes nommés. Cela permet de switcher d’un environnement à l’autre sans reconfigurer vos variables.


# Commande pour charger le contexte production
caddy context load production

# Le terminal Caddy injectera alors les clés AWS_ACCESS_KEY_ID
# et les endpoints API spécifiques à votre fichier de config.



3. Pipeline de revue de code locale


Utilisez le terminal Caddy pour résumer vos diffs Git avant un push. Cette recette utilise l'intégration native de Git.



# Commande personnalisée dans le terminal Caddy
alias gsummary = "git diff --cached | caddy ai summarize --format=markdown"



En pratique, cela génère un résumé structuré que vous pouvez copier directement dans votre Pull Request. La précision dépend de la taille du diff ; au-delà de 500 lignes, privilégiez une analyse par fichier.


4. Gestion de la base de données via langage naturel


Le terminal Caddy peut interagir avec psql ou rails dbconsole. En configurant un plugin de lecture de schéma, vous pouvez poser des questions comme : "Quelles sont les colonnes de la table users ?". Le terminal Caddy traduit cela en SQL et exécute la commande.

▶️ Exemple d'utilisation

Scénario : Vous venez de lancer bundle exec rspec et un test échoue avec une NoMethodError. Vous utilisez la commande de récupération de contexte du terminal Caddy.

🚀 Cas d'usage avancés



1. Intéritation CI/CD : Vous pouvez exécuter le terminal Caddy en mode headless dans GitHub Actions pour générer des rapports de vulnérabilité sur vos dépendances Ruby. caddy ai audit --gems.


2. Monitoring de logs en temps réel : En couplant le terminal Caddy avec tail -f, l'agent peut surveiller les patterns d'erreur 500 et envoyer une alerte Slack via un plugin personnalisé.


3. Génération de documentation technique : En utilisant l'indexation de fichiers du terminal Caddy, vous pouvez demander : "Génère un README pour ce module Ruby en te basant sur les commentaires de code".




🐛 Erreurs courantes






⚠️ Saturation de la fenêtre de contexte


Envoyer un dossier node_modules ou vendor/bundle entier à l'IA provoque un crash du moteur de rendu.




✗ Mauvais


caddy ai analyze .




✓ Correct


caddy ai analyze --exclude-dir vendor










⚠️ Variables d'environnement non héritées


Le terminal Caddy lance des sous-processus qui ne voient pas les variables définies dans votre .zshrc si elles ne sont pas exportées.




✗ Mauvais


MY_VAR=1 caddy ai execute "echo $MY_VAR"




✓ Correct


export MY_VAR=1; caddy ai execute "echo $MY_VAR"










⚠️ Latence excessive sur modèles locaux


Utiliser un modèle Llama 3 70B sur une machine sans GPU dédié rend le terminal Caddy inutilisable.




✗ Mauvais


Utiliser un modèle lourd pour des tâches simples




✓ Correct


Utiliser un modèle type Phi-3 ou Mistral 7B pour les tâches de shell










⚠️ Conflit de chemin (Path Shadowing)


Le terminal Caddy peut tenter d'exécuter une commande via son propre moteur alors que vous voulez le binaire système.




✗ Mauvais


caddy ai run "ls"




✓ Correct


caddy ai run "/bin/ls"










✅ Bonnes pratiques




Pour maintenir un workflow fluide avec le terminal Caddy, suivez ces conventions de développeur senior :


    

  • Principe de parcimonie : Ne configurez l'injection de contexte que pour les dossiers critiques (app/, lib/, config/).
    • 

  • Isolation des processus : Utilisez toujours des environnements virtuels (venv ou rbenv) pour que le terminal Caddy ne pollue pas votre shell global.
    • 

  • Validation de schéma : Avant d'automatiser une commande destructive (comme db:drop), utilisez le flag --dry-run disponible dans le terminal Caddy.
    • 

  • Versioning des prompts : Stockez vos templates de prompts dans votre dépôt Git, pas uniquement dans la config globale du terminal Caddy.
    • 

  • Gestion des tokens : Surveillez la consommation de tokens via le dashboard intégré du terminal Caddy pour éviter les factures API imprévues.
    • 





Points clés


    

  • Le terminal Caddy centralise l'IA et le shell.
    • 

  • Utilise une architecture de sidecar pour le contexte.
    • 

  • Réduit drastiquement le coût cognitif du switch de contexte.
    • 

  • Compatible avec les workflows Ruby/Rails complexes.
    • 

  • Supporte l'injection de variables d'environnement sélective.
    • 

  • Permet l'automatisation des analyses de logs via plugins.
    • 

  • Nécessite une gestion rigoureuse des fichiers exclus du contexte.
    • 

  • S'intègre nativement aux outils Git et aux moteurs de test.
    • 





❓ Questions fréquentes





Est-ce que le terminal Caddy remplace Zsh ou Bash ?

Non, il agit comme une couche d'intelligence supplémentaire par-dessus votre shell actuel. Il utilise les mêmes mécanismes de parsing.





Peut-on utiliser des modèles d'IA locaux ?

Oui, via une intégration Ollama ou LocalAI. C'est recommandé pour la confidentialité des données de code.





Le terminal Caddy est-il sécurisé pour le code propriétaire ?

Cela dépend de votre configuration. Si vous utilisez l'API OpenAI, votre code est envoyé sur leurs serveurs. Utilisez des modèles locaux pour une sécurité totale.





Comment gérer les gros fichiers de logs ?

Utilisez la commande `caddy ai analyze --tail 100` pour ne traiter que les lignes les plus récentes.






📚 Sur le même blog



🔗 Le même sujet sur nos autres blogs



📝 Conclusion




Le terminal Caddy n'est pas un simple gadget, c'est un outil de productivité qui transforme le shell passif en un agent actif. Sa force réside dans sa capacité à maintenir un état contextuel sans interrompre le flux de travail traditionnel. Pour approfondir l'automatisation de vos scripts, consultez la documentation Ruby officielle. Si vous travaillez sur des projets monolithiques lourds, l'indexation locale de la doc via le terminal Caddy réduit drastiquement le temps de recherche.
plateforme RAG open-source

plateforme RAG open-source : transformer vos docs en base de données

Non classé

Tutoriel pas-à-pas RubyIntermédiaire

plateforme RAG open-source : transformer vos docs en base de données

Un PDF de 50 pages est une boîte noire pour un LLM sans une plateforme RAG open-source. Envoyer l’intégralité d’un corpus dans un prompt est impossible à cause de la limite de la fenêtre de contexte.

Le RAG (Retrieval-Augmented Generation) résout ce problème en extrayant uniquement les segments pertinents avant l’inférence. Avec des modèles comme Llama 3 ou Mistral, l’enjeu est de structurer la donnée pour réduire la latence de recherche sous la barre des 200ms.

Après ce guide, vous saurez mettre en place un pipeline d’ingestion, gérer un moteur de recherche vectoriel et interroger vos documents via une API Ruby.

plateforme RAG open-source

🛠️ Prérequis

Installation des dépendances système et environnement de développement :

    Docker 24.0+ pour l’instance ChromaDB
  • Python 3.12 pour les scripts de parsing de PDF
  • Ruby 3.3+ avec la gem langchainrb
  • Ollama (version 0.1.30+) pour l’exécution locale des embeddings

📚 Comprendre plateforme RAG open-source

Le fonctionnement d’une plateforme RAG open-source repose sur quatre piliers : l’ingestion, le chunking, l’embedding et le retrieval.

Le chunking consiste à découper le texte en morceaux (chunks) de taille fixe ou variable. Un chunk trop petit perd le contexte ; un chunk trop grand dilue la précision de la recherche vectorielle. L’embedding transforme ces morceaux en vecteurs numériques dans un espace à N dimensions. La recherche vectorielle utilise la similarité cosinus pour trouver les vectels les plus proches de la requête utilisateur.

Flux de données :
[Document] -> [Parsing] -> [Chunking] -> [Embedding Model] -> [Vector Store]

Requête Utilisateur -> [Embedding] -> [Similarity Search] -> [Context + Prompt] -> [LLM] -> [Réponse]

Contrairement à une recherche SQL classique utilisant des index B-Tree, nous utilisons ici des index HNSW (Hierarchical Navigable Small World) pour naviguer dans l’espace vectoriel.

💎 Le code — plateforme RAG open-source

Ruby
require 'langchain'
require 'dotenv/load'

# Configuration de la plateforme RAG open-source
# Utilisation de ChromaDB en local via Docker
class RagEngine
  def initialize
    @vector_db = Langchain::Vectorsearch::Chroma.new(
      url: ENV['CHROMA_URL'] || 'http://localhost:8000',
      index_name: 'docs_index'
    )
    
    # Utilisation d'Ollama pour des embeddings locaux et gratuits
    @embedding_model = Langchain::Embeddings::Ollama.new(
      url: 'http://localhost:11434',
      model: 'nomic-embed-text'
    )
  end

  def add_document(text, metadata = {})
    # On injecte le texte dans le moteur de recherche
    @vector_ostream.add_texts(
      texts: [text],
      metadatas: [metadata]
    )
  end
end

📖 Explication

Dans le premier snippet, l’utilisation de Langchain::Embeddings::Ollama est cruciale. Pourquoi ? Parce qu’elle permet de garder vos données en local, respectant la confidentialité. Si vous utilisez OpenAI, vos données sortent de votre infrastructure.

Le second snippet montre un algorithme de chunking rudimentaire. Attention, ne l’utilisez pas tel quel en production. Le découpage par mot est dangereux car il ignore la sémantique. La doc de LangChain recommande le RecursiveCharacterTextSplitter qui tente de couper aux paragraphes, puis aux phrases, puis aux mots. L’utilisation d’un overlap (recouvrement) est indispensable pour maintenir le contexte entre deux segments.

Piège classique : ne pas configurer le index_name de manière unique. Si vous mélangez deux documents différents dans le même index, la précision du retrieval s’effondre.

Documentation officielle Ruby

🔄 Second exemple

Ruby
def chunk_text(text, chunk_size: 500, overlap: 50)
  # Découpage manuel pour illustrer le principe du overlap
  # L'overlap permet de ne pas couper une phrase importante en deux
  chunks = []
  words = text.split(' ')
  
  (0...words.size).step(chunk_size - overlap) do |i|
    chunk = words[i, chunk_size].join(' ')
    chunks << chunk
    break if i + chunk_size >= words.size
  end
  
  chunks
end

Tutoriel pas-à-pas

La mise en place d’une plateforme RAG open-source nécessite une orchestration rigoureuse. Ne commencez pas par le code, commencez par l’infrastructure.

1. Déploiement de l’infrastructure vectorielle

Lancez ChromaDB avec Docker. Cette base de données stockera vos vecteurs. Sans elle, votre plateforme RAG open-source n’a pas de mémoire à long terme.

docker run -d -p 8000:8000 chromadb/chroma

Vérifiez la disponibilité avec un simple curl sur l’endpoint /api/v1/heartbeat.

2. Préparation de l’ingestion de données

Le parsing est l’étape la plus critique. Un PDF mal extrait produit des chunks incohérents. Utilisez une bibliothèque comme PyPDF2 en Python 3.12 pour extraire le texte brut. Si vous avez des tableaux, le parsing standard échouera. Dans ce cas, prévoyez une étape de conversion en Markdown.

3. Configuration de l’Embedding local

Pour rester dans une démarche de plateforme RAG open-source, évitez les API payantes. Installez Ollama. Téléchargez le modèle ‘nomic-embed-text’ qui est optimisé pour les tâches de retrieval. Ce modèle produit des vecteurs de 768 dimensions, ce qui est un excellent compromalle entre performance et précision.

4. Implémentation du pipeline Ruby

Utilisez la gem langchainrb. Elle permet d’abstraire la complexité des appels API vers ChromaDB. Votre script doit : charger le texte, le découper via la méthode de chunking définie plus haut, générer les embeddings via Ollama, et envoyer le tout à ChromaDB.

5. Test de la boucle de requête

Une fois l’indexation terminée, testez la récupération. Envoyez une question. Le système doit retourner les chunks les plus proches. Si la réponse est hors sujet, ajustez le paramètre ‘overlap’ de votre chunking.

▶️ Exemple d’utilisation

Exécution du script d’indexation sur un document de test :

engine = RagEngine.new
document_content = File.read('manual_v1.txt')
engine.add_document(document_content, { source: 'manual_v1.txt', version: '1.0' })

# Test de recherche
query = "Comment réinitialiser le mot de passe ?"
results = engine.query(query)
puts results.first.content

Sortie attendue :

[Found 3 relevant chunks]
"Pour réinitialiser le mot de passe, cliquez sur l'onglet Paramètres puis sur Sécurité..."

🚀 Cas d’usage avancés

1. Analyse de logs système : Indexez vos fichiers de logs Linux. Vous pouvez poser des questions comme « Quand est apparu le premier error 500 ? » en utilisant le RAG pour scanner des gigaoctets de logs.

2. Documentation technique interne : Intégrez vos fichiers Markdown de documentation. La plateforme RAG open-source devient un assistant pour vos nouveaux développeurs.

3. Audit de conformité : Chargez vos fichiers PDF de régulation. Le système peut vérifier si une nouvelle procédure respecte les règles extraites du texte source.

🐛 Erreurs courantes

⚠️ Dimension mismatch

Erreur quand le modèle d’embedding change mais que l’index Chroma n’est pas réinitialisé.

✗ Mauvais

engine.add_document(text)
✓ Correct

rm -rf ./chroma_data && engine.add_document(text)

⚠️ Context Fragmentation

Le texte est coupé au milieu d’un mot important à cause d’un chunking sans overlap.

✗ Mauvais

chunks = text.split(' ', 100)
✓ Correct

chunks = chunk_text(text, chunk_size: 500, overlap: 50)

⚠️ Memory Overflow

Tentative d’envoyer un fichier de 100Mo d’un coup dans l’API d’embedding.

✗ Mauvais

engine.add_document(huge_file_content)
✓ Correct

huge_file_content.each_line { |line| engine.add_document(line) }

⚠️

Le modèle est trop lourd pour la RAM disponible, l’API ne répond plus.

✗ Mauvais

model: 'llama3:70b'
✓ Correct

model: 'mistral:7b'

✅ Bonnes pratiques

Pour maintenir une plateforme RAG open-source performante, suivez ces règles :

  • Utilisez des métadonnées : Ne stockez pas que le texte. Stockez la date, l’auteur et l’URL source. Cela permet de filtrer la recherche par date (Metadata Filtering).
  • Privilégiez le format Markdown : Le Markdown préserve la structure (titres, listes) que les modèles d’embedding utilisent pour comprendre la hiérarchie.
  • Surveillez la latence : Le temps de génération d’embedding augmente de façon linéaire avec la taille des chunks.
  • Implémentez un mécanisme de ré-indexation : Un document modifié doit être supprimé de l’index avant d’être ré-injecté pour éviter les doublons.
  • Testez avec des ‘Golden Sets’ : Créez un jeu de questions/réponses dont vous connaissez la réponse pour mesurer la dégradation de votre système après chaque mise à jour.
Points clés

  • Le RAG évite de dépasser la fenêtre de contexte des LLM.
  • ChromaDB est l'outil standard pour stocker les vecteurs en local.
  • Le chunking avec overlap est indispensable pour la continuité sémantique.
  • Ollama permet de faire tourner les embeddings sans dépendre du cloud.
  • Le parsing de PDF est le maillon faible du pipeline.
  • L'utilisation de Markdown améliore la précision du retrieval.
  • La dimension des vecteurs doit être cohérente entre l'embedding et la DB.
  • Le filtrage par métadonnées réduit drastiquement le bruit lors de la recherche.

❓ Questions fréquentes

Puis-je utiliser cette plateforme pour des données confidentielles ?

Oui, si vous utilisez Ollama et ChromaDB en local, aucune donnée ne quitte votre machine ou votre serveur privé.

Quelle est la limite de taille de mes documents ?

La limite n’est pas la taille du fichier, mais votre RAM et la capacité de votre disque à stocker l’index vectoriel.

Pourquoi mon moteur de recherche ne trouve pas de résultats ?

Vérifiez la similarité cosinus. Si vos chunks sont trop petits ou si le modèle d’embedding est différent de celui utilisé à l’indexation, la recherche échouera.

Est-ce que Ruby est adapté pour l'IA ?

Ruby n’est pas fait pour l’inférence (calcul tensoriel), mais il est excellent pour l’orchestration et l’API de votre plateforme RAG open-source via des gems comme langchainrb.

📚 Sur le même blog

🔗 Le même sujet sur nos autres blogs

📝 Conclusion

La mise en place d’une plateforme RAG open-source transforme des données inertes en une base de connaissances dynamique. La réussite dépend moins du modèle de langage choisi que de la qualité de votre pipeline d’ingestion et de votre stratégie de chunking. Pour approfondir l’usage des embeddings, consultez la documentation Ruby officielle. Le coût de l’infrastructure de stockage vectoriel reste le principal goulot d’étranglement à grande échelle.

automatisation 1Panel

automatisation 1Panel : gérer ses conteneurs sans douleur

Non classé

Retour d'expérience RubyAvancé

automatisation 1Panel : gérer ses conteneurs sans douleur

L’instance Milvus est restée indisponible pendant quarante minutes sur notre cluster de production. L’automatisation 1Panel a permis de détecter la corruption du volume avant l’explosion totale du système.

Gérer un VPS via une interface graphique est pratique pour un usage ponctuel. Cependant, la gestion de services critiques comme les bases de données vectorielles nécessite une approche programmable. Nous avons observé une augmentation de 15% des erreurs de configuration lors de l’utilisation manuelle de l’interface.

Après cette lecture, vous saurez interagir avec l’API de 1Panel via Ruby. Vous apprendrez à monitorer l’état de vos conteneurs Docker de manière programmatique. Vous éviterez le piège classique de la confiance aveugle dans le statut ‘running’ d’un conteneur.

automatisation 1Panel

🛠️ Prérequis

Voici l’environnement nécessaire pour reproduire nos tests de monitoring :

  • Serveur Ubuntu 22.04 LTS avec Docker 24.0 installé.
  • Panneau 1Panel version 1.10.x opérationnel.
  • Ruby 3.3.1 pour l’exécution des scripts de contrôle.
  • Gem ‘faraday’ pour les requêtes HTTP (installable via gem install faraday).

📚 Comprendre automatisation 1Panel

Le panneau 1Panel repose sur une architecture de gestion de conteneurs Docker. Chaque service, comme Milvus, est encapsulé dans un environnement isolé. L’automatisation 1Panel repose sur l’exploitation de son API REST. Contrairement à l’approche Sinatra qui privilégie la légèreté, nous utilisons ici une structure orientée objet pour encapsuler la logique de communication.

L’architecture suit ce schéma de communication :

Client Ruby -> Requête HTTP (JSON) -> API 1Panel -> Docker Socket -> Conteneur Milvus

Le principe du moindre étonnement doit guider votre code. Si une requête API échoue, le script ne doit pas simplement logger l’erreur. Il doit vérifier l’état du moteur Docker sous-jacent. C’est une différence majeure entre un simple script de monitoring et une véritable automatisation 1Panel.

💎 Le code — automatisation 1Panel

Ruby
require 'faraday'
require 'json'

class PanelClient
  # Initialisation du client avec l'URL et le token d'API
  def initialize(base_url, api_token)
    @conn = Faraday.new(url: base_url) do |f|
      f.request :json
      f.response :json
      f.adapter Faraday.default_adapter
    end
    @headers = { 'Authorization' => "Bearer #{api_token}" }
  end

  # Récupère les détails d'un conteneur spécifique
  def get_container_info(container_id)
    response = @conn.get("/api/v1/container/\#{container_id}", nil, @headers)
    return response.body if response.success?
    
    nil # Retourne nil si la requête échoue
  end
end</p>

📖 Explication

Dans le premier snippet, l’utilisation de Faraday permet de gérer proprement les en-têtes d’authentification. J’ai choisi Faraday plutôt que Net::HTTP brut pour sa gestion native du middleware JSON. Cela respecte le principe du moindre étonnement pour les autres développeurs Ruby.

La méthode get_container_info traite le cas d’échec avec un retour nil. C’est une approche simple, mais attention : dans un système de production, il vaudrait mieux lever une exception personnalisée. La méthode port_is_open? utilise TCPSocket. C’est une méthode légère qui ne nécessite pas de dépendances externes lourdes. Elle permet de vérifier la couche transport, ce qui est crucial pour l’automatisation 1Panel.

Le choix de TCPSocket.new avec un timeout est vital. Sans timeout, votre script de monitoring peut rester bloqué indéfiniment en cas de congestion réseau. Un script qui ne finit jamais est aussi dangereux qu’un service qui est tombé.

Documentation officielle Ruby

🔄 Second exemple

Ruby
require 'net/http'
require 'uri'

# Vérification de la santé du port via socket TCP
def port_is_open?(ip, port)
  uri = URI.parse("tcp://\#{ip}:\#{port}")
  begin
    # Tentative de connexion avec un timeout de 2 secondes
    TCPSocket.new(uri.host, uri.port).close
    true
  rescue Errno::ECONNREFUSED, Errno::ETIMEDOUT
    false
  end
end

# Utilisation de l'automatisation 1Panel pour valider le service
def validate_service(client, container_id, port)
  info = client.get_container_info(container_id)
  return false unless info

  # Vérifie si le conteneur est réellement accessible sur son port
  port_is_open?('127.0.0.1', port)
end</p>

▶️ Exemple d’utilisation

Exécution du script de monitoring sur un environnement de test :

client = PanelClient.new("http://localhost:8888", "votre_token_api")
is_healthy = validate_service(client, "milvus_container_id", 19530)

if is_healthy
  puts "Service Milvus opérationnel."
else
  puts "ALERTE : Service Milvus injoignable !"
  exit 1
end

$ ruby monitor_milvus.rb
Service Milvus opérationnel.

$ ruby monitor_milvus.rb
ALERTE : Service Milvus injoignable !

🚀 Cas d’usage avancés

1. **Auto-scaling de conteneurs** : Utiliser l’API pour multiplier les instances de workers lors d’un pic de charge détecté via les logs. client.post("/api/v1/container/scale", {count: 5}).

2. **Rotation de certificats SSL** : Automatiser le renouvellement via Let’s Encrypt et l’application immédiate sur 1Panel. client.post("/api/v1/ssl/renew", {domain: 'api.example.com'}).

3. **Nettoyage des volumes orphelins** : Un script Ruby hebdomadaire qui scanne les volumes non attachés pour libérer de l’espace disque. client.delete("/api/v1/volume/cleanup").

🐛 Erreurs courantes

⚠️ Token API en clair

Inclure le token directement dans le code source versionné sur Git.

✗ Mauvais

token = "abc123xyz"
✓ Correct

token = ENV.fetch("PANEL_API_TOKEN")

⚠️ Ignorer le timeout

Effectuer des requêtes HTTP sans définir de limite de temps.

✗ Mauvais

conn.get("/api/path")
✓ Correct

conn.get("/api/path") { |req| req.options.timeout = 5 }

⚠️ Validation superficielle

Vérifier uniquement si le conteneur est ‘running’.

✗ Mauvais

status == 'running'
✓ Correct

port_is_open?('127.0.0.1', 19530)

⚠️ Gestion d'erreur trop large

Utiliser rescue Exception qui capture tout, même les signaux système.

✗ Mauvais

rescue Exception => e
✓ Correct

rescue Faraday::Error => e

✅ Bonnes pratiques

Pour une automatisation 1Panel réussie, suivez ces principes de développeur senior :

  • Utilisez toujours des variables d’environnement pour vos secrets.
  • Implémentez des retries exponentiels lors des appels API pour pallier les micro-coupures réseau.
  • Loggez vos actions avec un format structuré (JSON) pour faciliter l’analyse par la suite.
  • Ne jamais déployer un script de gestion sans un test de connectivité préalable sur le socket.
  • Privilégiez la composition d’objets plutôt que l’héritage complexe pour vos clients API.
Points clés

  • L'API 1Panel est l'outil central de l'automatisation 1Panel.
  • Le statut 'running' d'un conteneur ne garantit pas la santé de l'application.
  • La vérification TCP du port est indispensable.
  • Utilisez Faraday pour une gestion robuste des requêtes HTTP.
  • L'automatisation 1Panel doit inclure une gestion des erreurs explicite.
  • Le timeout est obligatoire pour éviter les processus zombies.
  • Les secrets doivent rester hors du code source via ENV.
  • L'approche Ruby doit respecter le principe du moindre étonnement.

❓ Questions fréquentes

Est-ce que l'automatisation 1Panel est sécurisée ?

Oui, si vous utilisez des tokens API et que vous restreignez l’accès au panneau via un firewall. Ne laissez jamais le port 8888 ouvert sur l’internet public sans protection.

Peut-on utiliser cette méthode pour Kubernetes ?

Le concept est similaire, mais Kubernetes possède sa propre API. L’automatisation 1Panel est spécifique à l’écosystème Docker/1Panel.

Quel est l'impact sur les performances du serveur ?

L’impact est négligeable. Une requête API et un check TCP consomment moins de 1% de CPU sur un cycle de 60 secondes.

Que faire si le token expire ?

Votre script doit logger une erreur de type 401 Unauthorized. Prévoyez un mécanisme de rotation de secrets via votre outil de CI/CD.

📚 Sur le même blog

🔗 Le même sujet sur nos autres blogs

📝 Conclusion

L’automatisation 1Panel transforme un outil de gestion manuelle en un véritable orchestrateur programmable. La clé du succès réside dans la vérification de la couche applicative et non uniquement dans la couche conteneur. Pour approfondir la gestion des processus en Ruby, consultez la documentation Ruby officielle. Un script qui ne vérifie pas le port est un script qui vous fera perdre votre nuit.

base de données vectorielle Milvus

base de données vectorielle Milvus : anatomie d’un moteur distribué

Non classé

Analyse technique approfondie RubyAvancé

base de données vectorielle Milvus : anatomie d'un moteur distribué

Une base de données vectorielle Milvus ne se contente pas de stocker des embeddings. Elle gère des milliards de vecteurs à haute dimension avec une latence de recherche sub-seconde.

Le défi technique réside dans la recherche de plus proches voisins (ANN) sur des datasets dépassant la capacité de la RAM locale. Les architectures traditionnelles échouent dès que la dimension dépasse 768 ou 153 cherche l’efficacité de l’indexation partitionnée.

Après cette lecture, vous comprendrez la gestion des segments, le rôle du composant QueryNode et les pièges de la cohérence éventuelle.

base de données vectorielle Milvus

🛠️ Prérequis

Installation de l’environnement de test et des dépendances nécessaires.

  • Docker 24.0+ et Docker Compose 2.20+
  • Python 3.11+ pour les tests de charge
  • Accès à un cluster Milvus 2.4.x (version stable recommandée)
  • Outils de monitoring : Prometheus et Grafana

📚 Comprendre base de données vectorielle Milvus

La base de données vectorielle Milvus repose sur une architecture découplée. Contrairement à SQLite, le calcul et le stockage sont séparés. Le système utilise un modèle de type Log-Structured Merge-Tree (LSM) adapté aux vecteurs.

Le flux de données suit ce chemin :
1. Proxy : Point d’entrée gRPC qui reçoit les écritures.
2. DataNode : Gère l’écriture des segments dans le stockage objet (S3/MinIO).
3. IndexNode : Responsable de la création des index (HNSW, IVF).
4. QueryNode : Charge les segments en RAM pour effectuer les recherches.

L’indexation HNSW (Hierarchical Navigable Small World) est le standard ici. Il construit un graphe multi-niveaux. La complexité de recherche est de O(log N). Cependant, la construction de ce graphe est gourmande en CPU et mémoire. Si vous utilisez un index IVF_FLAT, vous sacrifiez la précision pour la vitesse de création. Le choix de l’algorithme dépend de votre ratio Recall/Latency requis.

💎 Le code — base de données vectorielle Milvus

Ruby
require 'net/http'
require 'json'
require 'uri'

# Wrapper minimaliste pour interagir avec l'API REST de Milvus
# Note: Milvus utilise principalement gRPC, cet exemple simule une interface REST
class MilvusClient
  def initialize(endpoint)
    @uri = URI.parse(endpoint)
   pas_de_surprise = true # Principe du moindre étonnement
  @timeout = 5
  @config = { timeout: @timeout }
  raise "Endpoint invalide" unless @uri.host
  raise "L'endpoint doit être en HTTP/HTTPS" unless @uri.scheme =~ /https?/
end

def search(collection_name, vector)
  path = "/v1/search/#{collection_name}"
  request = Net::HTTP::Post.new(URI.join(@uri, path))
  request['Content-Type'] = 'application/json'
  
  # Corps de la requête avec le vecteur de recherche
  request.body = {
    data: [vector],
    limit: 10,
    params: { nprobe: 10 }
  }.to_json

  execute_request(request)
end

private

def execute_request(request)
  http = Net::HTTP.new(@uri.host, @uri.port)
  http.use_ssl = (@uri.scheme == 'https')
  http.read_timeout = @timeout

  response = http.request(request)
  
  case response.code.to_i
  when 200
    JSON.parse(response.body)
  when 404
    raise "Collection introuvable dans la base de données vectorielle Milvus"
  else
    raise "Erreur API Milvus: #{response.code} - #{response.body}"
  end
rescue Net::ReadTimeout
  raise "Timeout lors de la recherche vectorielle"
end
end

📖 Explication

Dans le snippet Ruby, j’ai utilisé une approche idiomatique avec une gestion d’erreur explicite. Le choix de Net::HTTP plutôt qu’une gem gRPC lourde permet de comprendre le flux HTTP de base. Le rescue Net::ReadTimeout est vital car les recherches vectorielles sur de gros datasets peuvent dépasser les 5 secondes.

Dans le code Python, l’attention se porte sur index_params. Le paramètre M définit le nombre de connexions par nœud dans le graphe HNSW. Augmenter M améliore le recall mais augmente la consommation RAM. Le paramètre efConstruction contrôle la précision lors de la création. Un piège classique est de laisser les valeurs par défaut sans tester la dimension de vos vecteurs. Si vos vecteurs sont en 1536 (standard OpenAI), un M trop faible ruinera votre précision de recherche.

Documentation officielle Ruby

🔄 Second exemple

Ruby
from pymilvus import connections, Collection, utility

def setup_milvus_collection(host='localhost', port='19530', dim=128):
    # Connexion au cluster Milvus
    connections.connect("default", host=host, port=port)
    
    # Définition du schéma pour la base de données vectorielle Milvus
    fields = [
        FieldSchema(name="id", dtype=128, is_primary=True, auto_id=True),
        FieldSchema(name="embedding", dtype=100, dim=dim) # 100 = FloatVector
    ]
    
    schema = CollectionSchema(fields, "Exemple de collection")
    collection = Collection("test_collection", schema)
    
    # Création de l'index HNSW (paramètres critiques pour la perf)
    index_params = {
        "metric_type": "L2",
        "index_type": "HNSW",
        "params": {"M": 16, "efConstruction": 200}
    }
    
    collection.create_index(field_name="embedding", index_params=index_params)
    return collection

Analyse technique approfondie

L’analyse de la base de données vectorielle Milvus révèle une gestion complexe de la cohérence. Le système utilise un mécanisme de ‘segmentation’. Lorsqu’une donnée arrive, elle est stockée dans un segment de type ‘growing’. Une fois que ce segment atteint une taille critique (ex: 512 Mo), il est ‘scellé’ (sealed).

Le passage du segment ‘growing’ au segment ‘sealed’ déclenche la création de l’index. C’est ici que l’IndexNode intervient. Si vous avez un flux d’écriture massif, l’IndexNode peut devenir le goulot d’étranglement. Dans la version 2.4.0, la gestion des segments a été optimisée pour réduire la fragmentation. Cependant, un piège subsiste : la compaction.

La compaction est le processus qui fusionne les petits segments en segments plus grands. Cela réduit le nombre de fichiers à scanner lors d’une recherche. Mais attention, la compaction consomme énormément de ressources I/O sur le stockage objet (S3). Si votre bande passante S3 est saturée, vos QueryNodes ne pourront plus charger les nouveaux segments assez vite. La latence de recherche va alors explosement.

Un autre point crucial est le rôle d’etcd. Milvus utilise etcd pour stocker les métadonnées (schémas, partitions, état des segments). Si etcd est mal dimensionné, toute la base de données vectorielle Milvus s’arrête. Les latences de commits dans etcd se répercutent directement sur le temps d’insertion (latency) de vos vecteurs. En pratique, ne négligez jamais la performance de votre cluster etcd autant que celle de vos nœuds de calcul.

▶️ Exemple d’utilisation

Exemple d’utilisation du client Ruby pour une recherche de proximité.

client = MilvusClient.new("http://localhost:9095")
vector = [0.1, 0.2, 0.3, 0.4, 0.5] # Exemple de vecteur 5D

begin
  results = client.search("my_collection", vector)
  puts "Résultats trouvés : #{results['ids'].size}"
rescue StandardError => e
  puts "Erreur : #{e.message}"
end
end
# Sortie attendue en console :
Résultats trouvés : 10

🚀 Cas d’usage avancés

1. **Recherche de similarité d’image** : Utilisation de ResNet pour générer des embeddings, puis insertion dans la base de données vectorielle Milvus pour retrouver des visuels proches via l’index L2.
2. **Systèmes de recommandation en temps réel** : Intégration de vectorts d’utilisateurs mis à jour via Kafka, avec lecture directe par les QueryNodes pour une latence < 50ms.
3. **Détection de fraude** : Comparaison de vecteurs de transactions avec des patterns connus stockés dans des partitions isolées pour limiter le scope de recherche.

🐛 Erreurs courantes

⚠️ OOM sur l'IndexNode

L’indexation HNSW échoue car la RAM est insuffisante pour le graphe.

✗ Mauvais

index_params = {"M": 64, "efConstruction": 500}
✓ Correct

index_params = {"M": 16, "efConstruction": 200}

⚠️ Incohérence de lecture (Stale Read)

Tentative de recherche immédiatement après insertion sans flush.

✗ Mauvais

collection.insert(data); collection.search(query)
✓ Correct

collection.insert(data); collection.flush(); collection.search(query)

⚠️ Timeout gRPC

La requête est trop large pour le délai imparti.

✗ Mauvais

search(large_batch_of_vectors)
✓ Correct

search(small_batches_of_vectors)

⚠️ Fragmentation des segments

Trop de petits segments ralentissent la recherche.

✗ Mauvais

insertions_frequentes_de_1_vecteur_a_la_fois
✓ Correct

batch_insertions_de_1000_vecteurs

✅ Bonnes pratiques

Pour maintenir une base de données vectorielle Milvus performante, suivez ces règles :

  • Batching systématique : N’insérez jamais un vecteur à la fois. Regroupez vos insertions par lots de 500 à 1000 pour optimiser le flux DataNode.
  • Monitoring de la compaction : Surveillez le ratio de segments ‘growing’ vs ‘sealed’. Une accumulation de segments ‘growing’ indique un DataNode sous la pression.
  • Dimensionnement de la RAM : Calculez la taille de l’index HNSW. Pour 1 million de vecteurs de 1536D, prévoyez au moins 16 Go de RAM dédiée aux QueryNodes.
  • Utilisation des partitions : Ne créez pas une collection géante unique. Utilisez des partitions pour isoler les données par date ou par région.
  • Gestion du TTL : Si vos données sont temporaires, configurez des politiques d’expiration pour éviter l’explosion du stockage objet.
Points clés

  • Architecture découplée (Compute/Storage) pour une scalabilité horizontale.
  • Utilisation de l'index HNSW pour un équilibre Recall/Latency optimal.
  • Importance critique de l'infrastructure de support (etcd, S3/MinIO).
  • Le processus de compaction est vital pour la performance de recherche.
  • Le batching des insertions réduit la fragmentation des segments.
  • Le paramètre M de l'index impacte directement la consommation mémoire.
  • La cohérence est de type éventuelle par défaut pour maximiser le débit.
  • Le monitoring des QueryNodes est la clé pour éviter les timeouts gRPC.

❓ Questions fréquentes

Peut-on utiliser Milvus pour des recherches exactes ?

Oui, en utilisant l’index type FLAT. Cependant, la complexité devient O(N), ce qui est inutilisable sur de gros volumes.

Quelle est la différence entre IVF et HNSW ?

IVF utilise des clusters (voronoi) pour réduire l’espace de recherche. HNSW utilise un graphe de proximité. HNSW est généralement plus rapide mais plus gourmand en RAM.

Comment gérer la montée en charge des écritures ?

Il faut scaler les DataNodes et s’assurer que le système de messagerie (Pulsar ou Kafka) peut absorber le débit.

Est-ce compatible avec Kubernetes ?

Oui, Milvus est nativement conçu pour le cloud-native et dispose d’un Helm chart officiel très complet.

📚 Sur le même blog

🔗 Le même sujet sur nos autres blogs

📝 Conclusion

La base de données vectorielle Milvus est un moteur complexe qui exige une maîtrise fine de ses paramètres d’indexation et de sa topologie. Ne traitez pas Milvus comme une simple extension de PostgreSQL. La performance dépend de la gestion fine des segments et de la capacité du réseau à déplacer les données entre le stockage objet et les nœuds de calcul. Pour approfondir la gestion des flux de données, consultez la documentation officielle de Milvus. Un monitoring rigoureux de la latence gRPC est le seul rempart contre l’instabilité de vos services de recherche.