Configurer les évaluations en ligne

Attachez des juges à des variations de configuration pour un scoring automatique de la qualité à l'aide de la méthodologie LLM-as-a-judge. Les juges évaluent les réponses et retournent des scores entre 0,0 et 1,0.

Prérequis

• Compte LaunchDarkly avec AgentControl activé
• Token d'accès API avec permissions d'écriture
• Configuration existante avec variations (utiliser la skill configs-create)
• Pour l'enregistrement automatique des métriques et l'API consolidée de résultats de juges : Python AI SDK v0.20.0+ ou Node.js AI SDK v0.20.0+

Détection de clé API

1. Vérifier les variables d'environnement - LAUNCHDARKLY_API_KEY, LAUNCHDARKLY_API_TOKEN, LD_API_KEY
2. Vérifier la config MCP - Claude : ~/.claude/config.json -> mcpServers.launchdarkly.env.LAUNCHDARKLY_API_KEY
3. Demander à l'utilisateur - Seulement si la détection échoue

Concepts fondamentaux

Qu'est-ce que les juges ?

Les juges sont des configurations spécialisées en mode juge qui évaluent les réponses d'autres configurations. Elles utilisent un LLM pour noter les résultats et retournent des résultats structurés :

{
  "score": 0.85,
  "reasoning": "Answered correctly with one minor omission"
}

Juges intégrés

LaunchDarkly fournit trois juges préconfigurés :

Mode complètion uniquement

Les juges ne peuvent être attachés qu'aux configurations en mode complètion dans l'interface. Pour le mode agent ou les pipelines personnalisés, utilisez l'évaluation programmatique via le SDK.

Restrictions

• Impossible d'attacher des juges à des juges (pas de récursion)
• Impossible d'attacher plusieurs juges avec la même clé de métrique à une seule variation
• Impossible de voir/éditer les paramètres du modèle ou les outils sur les variations de juge

Flux de travail

Étape 1 : Créer des juges personnalisés (optionnel)

Pour une évaluation spécifique au domaine, créez des configurations de juge :

# Créer la configuration de juge
curl -X POST "https://app.launchdarkly.com/api/v2/projects/{projectKey}/ai-configs" \
  -H "Authorization: {api_token}" \
  -H "Content-Type: application/json" \
  -H "LD-API-Version: beta" \
  -d '{
    "key": "security-judge",
    "name": "Security Judge",
    "mode": "judge",
    "evaluationMetricKey": "security",
    "isInverted": false
  }'

Note : Définissez isInverted: true pour les métriques comme la toxicité où 0,0 est préférable.

Ensuite, ajoutez une variation avec l'invite d'évaluation :

curl -X POST "https://app.launchdarkly.com/api/v2/projects/{projectKey}/ai-configs/security-judge/variations" \
  -H "Authorization: {api_token}" \
  -H "Content-Type: application/json" \
  -H "LD-API-Version: beta" \
  -d '{
    "key": "default",
    "name": "Default",
    "messages": [
      {
        "role": "system",
        "content": "You are a security auditor. Score from 0.0 to 1.0:\n- 1.0: No security issues\n- 0.7-0.9: Minor issues\n- 0.4-0.6: Moderate issues\n- 0.1-0.3: Serious vulnerabilities\n- 0.0: Critical vulnerabilities\n\nCheck for: SQL injection, XSS, hardcoded secrets, command injection."
      }
    ],
    "modelConfigKey": "OpenAI.gpt-4o-mini",
    "model": {
      "parameters": {
        "temperature": 0.3
      }
    }
  }'

Étape 2 : Attacher les juges aux variations

Utilisez l'endpoint PATCH de variation :

curl -X PATCH "https://app.launchdarkly.com/api/v2/projects/{projectKey}/ai-configs/{configKey}/variations/{variationKey}" \
  -H "Authorization: {api_token}" \
  -H "Content-Type: application/json" \
  -H "LD-API-Version: beta" \
  -d '{
    "judgeConfiguration": {
      "judges": [
        {"judgeConfigKey": "security-judge", "samplingRate": 1.0},
        {"judgeConfigKey": "api-contract-judge", "samplingRate": 0.5}
      ]
    }
  }'

Important : Le tableau judges remplace tous les attachements de juge existants. Un tableau vide supprime tous les juges.

Étape 3 : Définir le fallthrough sur les juges

Chaque configuration de juge doit avoir son fallthrough défini sur la variation activée. Les configurations par défaut utilisent la variation « disabled » (index 0).

Note : turnTargetingOn ne fonctionne pas pour les configurations. Utilisez updateFallthroughVariationOrRollout à la place.

# D'abord, récupérer l'ID de variation pour « Default » depuis la réponse de ciblage GET
curl -X PATCH "https://app.launchdarkly.com/api/v2/projects/{projectKey}/ai-configs/security-judge/targeting" \
  -H "Authorization: {api_token}" \
  -H "Content-Type: application/json; domain-model=launchdarkly.semanticpatch" \
  -H "LD-API-Version: beta" \
  -d '{
    "environmentKey": "production",
    "instructions": [{
      "kind": "updateFallthroughVariationOrRollout",
      "variationId": "your-default-variation-uuid"
    }]
  }'

Implémentation Python

import requests
import os
from typing import Optional

class AIConfigJudges:
    """Manager for config judge attachments"""

    def __init__(self, api_token: str, project_key: str):
        self.api_token = api_token
        self.project_key = project_key
        self.base_url = "https://app.launchdarkly.com/api/v2"
        self.headers = {
            "Authorization": api_token,
            "Content-Type": "application/json",
            "LD-API-Version": "beta"
        }

    def attach_judges(self, config_key: str, variation_key: str,
                      judges: list[dict]) -> dict:
        """
        Attach judges to a variation.

        Args:
            config_key: config key
            variation_key: Variation key
            judges: List of {"judgeConfigKey": str, "samplingRate": float}
        """
        url = f"{self.base_url}/projects/{self.project_key}/ai-configs/{config_key}/variations/{variation_key}"

        response = requests.patch(url, headers=self.headers, json={
            "judgeConfiguration": {"judges": judges}
        })

        if response.status_code == 200:
            print(f"[OK] Attached {len(judges)} judges to {config_key}/{variation_key}")
            return response.json()
        print(f"[ERROR] {response.status_code}: {response.text}")
        return {}

    def create_judge(self, key: str, name: str, metric_key: str,
                     system_prompt: str, model: str = "OpenAI.gpt-4o-mini",
                     is_inverted: bool = False) -> dict:
        """
        Create a judge config.

        Args:
            key: Judge config key
            name: Display name
            metric_key: Metric key for scoring (appears as $ld:ai:judge:{metric_key})
            system_prompt: Evaluation instructions
            is_inverted: True if lower scores are better (e.g., toxicity)
        """
        # Create config
        config_url = f"{self.base_url}/projects/{self.project_key}/ai-configs"
        response = requests.post(config_url, headers=self.headers, json={
            "key": key,
            "name": name,
            "mode": "judge",
            "evaluationMetricKey": metric_key,
            "isInverted": is_inverted
        })

        if response.status_code not in [200, 201]:
            print(f"[ERROR] Creating config: {response.text}")
            return {}

        # Create variation
        var_url = f"{self.base_url}/projects/{self.project_key}/ai-configs/{key}/variations"
        response = requests.post(var_url, headers=self.headers, json={
            "key": "default",
            "name": "Default",
            "messages": [{"role": "system", "content": system_prompt}],
            "modelConfigKey": model,
            "model": {"parameters": {"temperature": 0.3}}
        })

        if response.status_code in [200, 201]:
            print(f"[OK] Created judge: {key}")
            return response.json()
        print(f"[ERROR] Creating variation: {response.text}")
        return {}

    def set_fallthrough(self, config_key: str, environment: str,
                        variation_key: str = "default") -> bool:
        """
        Set fallthrough to enable a judge config.

        Note: turnTargetingOn doesn't work for configs. Instead, set the
        fallthrough from disabled (index 0) to the enabled variation.
        """
        # Get variation ID
        url = f"{self.base_url}/projects/{self.project_key}/ai-configs/{config_key}/targeting"
        response = requests.get(url, headers=self.headers)

        if response.status_code != 200:
            print(f"[ERROR] {response.status_code}: {response.text}")
            return False

        targeting = response.json()
        variation_id = None
        for var in targeting.get("variations", []):
            if var.get("key") == variation_key or var.get("name") == variation_key:
                variation_id = var.get("_id")
                break

        if not variation_id:
            print(f"[ERROR] Variation '{variation_key}' not found")
            return False

        # Set fallthrough
        response = requests.patch(url, headers={
            **self.headers,
            "Content-Type": "application/json; domain-model=launchdarkly.semanticpatch"
        }, json={
            "environmentKey": environment,
            "instructions": [{
                "kind": "updateFallthroughVariationOrRollout",
                "variationId": variation_id
            }]
        })

        if response.status_code == 200:
            print(f"[OK] Fallthrough set for {config_key}")
            return True
        print(f"[ERROR] {response.status_code}: {response.text}")
        return False

SDK : Évaluation automatique

Lors de l'utilisation de create_model() + run(), les juges attachés évaluent automatiquement :

import os
import json
import asyncio
import ldclient
from ldclient import Context
from ldclient.config import Config
from ldai import LDAIClient, AICompletionConfigDefault

sdk_key = os.getenv('LAUNCHDARKLY_SDK_KEY')
ai_config_key = os.getenv('LAUNCHDARKLY_AI_CONFIG_KEY', 'sample-ai-config')

async def async_main():
    ldclient.set_config(Config(sdk_key))
    aiclient = LDAIClient(ldclient.get())

    context = (
        Context.builder('example-user-key')
        .kind('user')
        .name('Sandy')
        .build()
    )

    default_value = AICompletionConfigDefault(enabled=False)

    # create_model() initializes with judges from Config
    model = await aiclient.create_model(ai_config_key, context, default_value, {})

    if not model:
        print(f"agent configuration not enabled for: {ai_config_key}")
        return

    user_input = 'How can LaunchDarkly help me?'

    # run() automatically evaluates with attached judges
    result = await model.run(user_input)
    print("Response:", result.content)

    # Await evaluation results
    if result.evaluations and len(result.evaluations) > 0:
        eval_results = await asyncio.gather(*result.evaluations)
        results_to_display = [
            r.to_dict() if r is not None else "not evaluated"
            for r in eval_results
        ]
        print("Judge results:")
        print(json.dumps(results_to_display, indent=2, default=str))

    # Always flush events before closing — trailing events are at risk of being
    # lost otherwise, in short-lived scripts and long-running services alike.
    ldclient.get().flush()
    ldclient.get().close()

SDK : Évaluation directe de juge

Pour le mode agent ou les pipelines personnalisés, évaluez les paires entrée/sortie directement :

import os
import json
import asyncio
import ldclient
from ldclient import Context
from ldclient.config import Config
from ldai import LDAIClient, AIJudgeConfigDefault

sdk_key = os.getenv('LAUNCHDARKLY_SDK_KEY')
judge_key = os.getenv('LAUNCHDARKLY_AI_JUDGE_KEY', 'sample-ai-judge-accuracy')

async def async_main():
    ldclient.set_config(Config(sdk_key))
    aiclient = LDAIClient(ldclient.get())

    context = (
        Context.builder('example-user-key')
        .kind('user')
        .name('Sandy')
        .build()
    )

    judge_default_value = AIJudgeConfigDefault(enabled=False)

    # Get judge configuration from LaunchDarkly
    judge = aiclient.create_judge(judge_key, context, judge_default_value)

    if not judge:
        print(f"agent judge configuration not enabled for key: {judge_key}")
        return

    input_text = 'You are a helpful assistant. How can you help me?'
    output_text = 'I can answer any question you have.'

    # Evaluate the input/output pair — returns a JudgeResult.
    judge_result = await judge.evaluate(input_text, output_text)

    if not judge_result.sampled:
        print("Judge evaluation was skipped (sample rate or configuration issue)")
        return

    # Track the consolidated result on the Config tracker if needed:
    # tracker = ai_config.create_tracker()
    # tracker.track_judge_result(judge_result)

    print("Judge Result:")
    print(json.dumps(judge_result.to_dict(), default=str))

    # Always flush events before closing — trailing events are at risk of being
    # lost otherwise, in short-lived scripts and long-running services alike.
    ldclient.get().flush()
    ldclient.get().close()

Note : L'évaluation directe n'enregistre pas automatiquement les métriques. Obtenez un tracker via ai_config.create_tracker() / aiConfig.createTracker() et appelez tracker.track_judge_result(result) / tracker.trackJudgeResult(result) pour enregistrer les scores pour la configuration que vous évaluez.

Taux d'échantillonnage

Chaque réponse évaluée envoie une demande supplémentaire à votre fournisseur de modèle, ce qui augmente l'utilisation des tokens et les coûts. Commencez par un pourcentage d'échantillonnage plus faible et augmentez-le seulement si vous avez besoin d'une couverture d'évaluation plus importante.

Vous pouvez ajuster les taux d'échantillonnage à tout moment à partir de la section Juges d'une variation, ou désactiver un juge en définissant son échantillonnage à 0 %.

Affichage des résultats

1. Accédez à configs > sélectionnez votre config
2. Cliquez sur l'onglet Monitoring
3. Sélectionnez Evaluator metrics dans le menu déroulant
4. Consultez les scores par variation et plage horaire

Les résultats apparaissent dans 1 à 2 minutes après l'évaluation.

Utilisation dans les garde-fous et expériences

Les métriques d'évaluation s'intègrent avec :

• Déploiements gardés : Mettez en pause/revenez en arrière quand les scores chutent sous le seuil
• Expériences : Comparez les variations à l'aide des métriques d'évaluation comme objectifs

Gestion des erreurs

Étapes suivantes

Après avoir attaché les juges :

1. Définir le fallthrough sur les configurations de juge à une variation activée (requis)
2. Surveiller les résultats dans l'onglet Monitoring
3. Ajuster l'échantillonnage en fonction des besoins en coûts/couverture
4. Configurer des déploiements gardés pour la détection automatique de régression

Skills connexes

• configs-create - Créer des configurations et des juges
• configs-targeting - Configurer les règles de ciblage
• configs-variations - Gérer les variations

Références

• Online Evaluations
• Custom Judges

Exemples du SDK Python :

• create_judge_example.py - Évaluer les paires entrée/sortie directement via create_judge + evaluate
• create_model_example.py - Évaluation automatique avec create_model + run (les juges attachés s'exécutent pendant l'exécution)

Exemples du SDK Node.js :

• features/create-judge - Évaluer les paires entrée/sortie directement via createJudge + evaluate
• features/create-model - Évaluation automatique avec createModel + run (les juges attachés s'exécutent pendant l'exécution)