Évaluer les applications AI¶

Scénario 1 : Traçage d’une fonction¶

Vous pouvez ajouter @instrument() avant la fonction à tracer. Cela permet de saisir automatiquement les entrées de la fonction, les sorties (valeurs de retour) et la latence de l’exécution. Par exemple, le code suivant montre le traçage d’une fonction answer_query qui capture automatiquement la requête d’entrée et la réponse finale :

@instrument()
def answer_query(self, query: str) -> str:
    context_str = self.retrieve_context(query)
    return self.generate_completion(query, context_str)

Scénario 2 : Traçage d’une fonction avec un type de span spécifique¶

Un type de span précise la nature de la fonction et améliore la lisibilité et la compréhension des traçages. Par exemple, dans une application RAG, vous pouvez spécifier le type de span comme « RETRIEVAL » pour votre service de recherche (ou récupérateur) et comme « GENERATION » pour l’appel d’inférence LLM. Les types de span suivants sont pris en charge :

• RETRIEVAL : Type de span pour les fonctions de récupération ou de recherche

• GENERATION : Type de span pour les appels à l’inférence de modèle provenant d’un LLM

• RECORD_ROOT : Type de span pour la fonction principale dans votre application

Si vous ne spécifiez pas de type de span avec @instrument(), un type de span UNKNOWN est attribué par défaut. Pour utiliser les attributs de span, ajoutez l’import suivant à votre application Python.

from trulens.otel.semconv.trace import SpanAttributes

L’extrait de code suivant illustre le traçage d’une application RAG. Le type de span doit toujours porter le préfixe SpanAttributes.SpanType.

@instrument(span_type=SpanAttributes.SpanType.RETRIEVAL)
def retrieve_context(self, query: str) -> list:
    """
    Retrieve relevant text from vector store.
    """
    return self.retrieve(query)

@instrument(span_type=SpanAttributes.SpanType.GENERATION)
def generate_completion(self, query: str, context_str: list) -> str:
    """
    Generate answer from context by calling an LLM.
    """
    return response

@instrument(span_type=SpanAttributes.SpanType.RECORD_ROOT)
def answer_query(self, query: str) -> str:
    context_str = self.retrieve_context(query)
    return self.generate_completion(query, context_str)

Scénario 3 : Traçage d’une fonction et calcul des évaluations¶

En plus de fournir des types de span, vous devez affecter les paramètres pertinents de votre application aux attributs de span pour calculer les métriques. Par exemple, pour calculer la pertinence du contexte dans une application RAG, vous devez affecter le paramètre de la requête pertinente et celui des résultats de la récupération aux attributs RETRIEVAL.QUERY_TEXT et RETRIEVAL.RETRIEVED_CONTEXTS appropriés, respectivement. Les attributs requis pour le calcul de chaque mesure individuelle peuvent être trouvés dans la page des métriques.

Les attributs de span suivants sont pris en charge pour chaque type de span :

• RECORD_ROOT: INPUT, OUTPUT, GROUND_TRUTH_OUTPUT

• RETRIEVAL: QUERY_TEXT, RETRIEVED_CONTEXTS

• GENERATION: Aucun

Pour utiliser les attributs de span, vous devez ajouter l’import suivant à votre application Python.

from trulens.otel.semconv.trace import SpanAttributes

L’extrait de code suivant donne un exemple de calcul de la pertinence du contexte pour un service de récupération. Les attributs doivent toujours respecter le format SpanAttributes.<span type>.<attribute name> (par exemple, SpanAttributes.RETRIEVAL.QUERY_TEXT).

@instrument(
    span_type=SpanAttributes.SpanType.RETRIEVAL,
    attributes={
        SpanAttributes.RETRIEVAL.QUERY_TEXT: "query",
        SpanAttributes.RETRIEVAL.RETRIEVED_CONTEXTS: "return",
    }
)
def retrieve_context(self, query: str) -> list:
    """
    Retrieve relevant text from vector store.
    """
    return self.retrieve(query)

Dans l’exemple précédent, query représente le paramètre d’entrée dans retrieve_context() et return représente la valeur retournée. Ceux-ci sont attribués aux attributs RETRIEVAL.QUERY_TEXT et RETRIEVAL.RETRIEVED_CONTEXTS pour calculer la pertinence du contexte.

Configuration du cycle¶

Un cycle est créé à partir d’une RunConfig

run_config = RunConfig(
    run_name=run_name,
    description="desc",
    label="custom tag useful for grouping comparable runs",
    source_type="DATAFRAME",
    dataset_name="My test dataframe name",
    dataset_spec={
        "RETRIEVAL.QUERY_TEXT": "user_query_field",
        "RECORD_ROOT.INPUT": "user_query_field",
        "RECORD_ROOT.GROUND_TRUTH_OUTPUT": "golden_answer_field",
    },
    llm_judge_name: "mistral-large2"
)

• run_name: str : nom du cycle, qui doit être unique sous la même TruApp

• description: str (facultatif) : description de la chaîne du cycle

• label: str (facultatif) : étiquette utilisée pour regrouper les cycles

• source_type: str : spécifie la source du jeu de données. Il peut s’agir de DATAFRAME pour une base de données Python ou de TABLE pour une table d’utilisateurs dans le compte Snowflake.

• dataset_name: str : tout nom arbitraire spécifié par l’utilisateur si source_type est DATAFRAME. Ou, un nom de table Snowflake valide sous le compte de l’utilisateur dans le contexte actuel (base de données et schéma) ou un nom entièrement qualifié Snowflake sous la forme « database.schema.table_name ».

• dataset_spec: Dict[str, str] : un dictionnaire mappant les attributs de span pris en charge aux noms des colonnes de l’utilisateur dans l’image de données ou la table. Les clés autorisées sont les attributs de span tels qu’ils sont spécifiés dans la page Dataset et les valeurs autorisées sont les noms des colonnes de la table ou de l’image de données spécifiée par l’utilisateur. Par exemple, « golden_answer_field » dans l’exemple de configuration de cycle ci-dessus doit être un nom de colonne valide

• llm_judge_name: str (Facultatif) : nom à utiliser en tant que juge LLM lors du calcul de la métrique basé sur LLM. Veuillez consulter la page des modèles pour connaître les juges pris en charge. Si elle n’est pas spécifiée, la valeur par défaut est llama3.1-70b

run = tru_app.add_run(run_config=run_config)

Paramètres de la requête :

• run_config: RunConfig : contient la configuration du cycle.

Récupérer le cycle¶

Récupère le cycle.

run = tru_app.get_run(run_name=run_name)

Paramètres de la requête :

• run_name: str : nom du cycle

Consulter les métadonnées du cycle¶

Décrit les détails du cycle.

run.describe()

Invoquer le cycle¶

Vous pouvez invoquer le cycle à l’aide de la fonction run.start(). Elle lit les entrées à partir du jeu de données spécifié dans la configuration du cycle, invoque l’application pour chaque entrée, génère les traçages et ingère les informations pour les stocker dans votre compte Snowflake. run.start() est un appel bloquant jusqu’à ce que l’application soit invoquée pour toutes les entrées de votre jeu de données et que l’ingestion soit terminée ou expire.

run.start()  # if source_type is "TABLE"

run.start(input_df=user_input_df)  # if source_type is "DATAFRAME"

Paramètres de la requête :

• input_df: DataFrame (Facultatif) : est un dataframe pandas provenant du SDK. Si, dans la configuration du cycle, le source_type est spécifié comme étant DATAFRAME, ce champ est obligatoire. Si le source_type est TABLE, ce champ n’est pas requis.

Calculer les métriques¶

Vous pouvez commencer les calculs des métriques en utilisant run.compute_metrics() après que l’application a été invoquée et que tous les traçages ont été ingérés. Tant que le statut du cycle est INVOCATION_IN_PROGRESS, le calcul ne peut pas être lancé. Lorsque le statut est INVOCATION_COMPLETED ou INVOCATION_PARTIALLY_COMPLETED, run.compute_metrics() peut être lancé. run.compute_metrics() est une fonction asynchrone non bloquante. Vous pouvez appeler compute_metrics plusieurs fois au cours du même cycle avec un ensemble de paramètres différent, et chaque appel déclenchera un nouveau travail de calcul. Notez que les métriques calculées une fois ne peuvent pas être recalculées pour le même cycle.

run.compute_metrics(metrics=[
    "coherence",
    "answer_relevance",
    "groundedness",
    "context_relevance",
    "correctness",
])

Paramètres de la requête :

• metrics: List[str] : liste des noms de chaînes des métriques répertoriées dans Metrics. Le nom des métriques doit être spécifié dans les snake cases. Par exemple, Context Relevance doit être spécifié comme context_relevance.

Vérifier le statut du cycle¶

Vous pouvez vérifier le statut du cycle une fois qu’il est en cours. La liste des statuts se trouve dans la section Statut du cycle.

run.get_status()

Annuler le cycle¶

Vous pouvez annuler un cycle en cours en utilisant run.cancel(). Cette opération empêchera toute mise à jour ultérieure du cycle, y compris des champs relatifs au statut du cycle et aux métadonnées.

run.cancel()

Supprimer le cycle¶

Vous pouvez supprimer un cycle existant en utilisant run.delete(). Cette opération supprime les métadonnées associées au cycle et les résultats de l’évaluation ne sont pas accessibles. Toutefois, les traçages et les évaluations générés dans le cadre des cycles ne sont pas supprimés et restent stockés. Veuillez vous référer à la section sur les données d’observabilité pour plus d’informations sur le stockage et la suppression de l’évaluation et des traçages.

run.delete()

Répertorier les cycles pour une application¶

Vous pouvez consulter la liste de tous les cycles disponibles correspondant à un objet d’application TruApp spécifique à l’aide de la fonction list_runs().

tru_app.list_runs()

Réponse :

Retourne une liste de tous les cycles créés sous tru_app.