> ## Documentation Index
> Fetch the complete documentation index at: https://wb-21fd5541-docs-hivemind-launch.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Collecter les retours et utiliser les annotations

> Recueillir et analyser les retours pour les applications LLM via l’UI et le SDK

Pour évaluer efficacement des applications LLM, vous avez besoin d’outils robustes pour recueillir et analyser les retours. W\&B Weave fournit un système de retours intégré, qui permet aux utilisateurs de donner leur avis sur les Appels directement dans l’UI ou par programmation via le SDK. Différents types de retours sont pris en charge, notamment les réactions par emoji, les commentaires textuels et les données structurées, ce qui permet aux équipes de :

* Créer des jeux de données d’évaluation pour le suivi des performances.
* Identifier et résoudre efficacement les problèmes de contenu des LLM.
* Recueillir des exemples pour des tâches avancées comme le fine-tuning.

Ce guide explique comment utiliser la fonctionnalité de retours de Weave dans l’UI et le SDK, interroger et gérer les retours, et utiliser des annotations humaines pour des évaluations détaillées.

* [Donner un retour dans l’UI](#provide-feedback-in-the-ui)
* [Donner un retour via le SDK](#provide-feedback-through-the-sdk)
* [Ajouter des annotations humaines](#add-human-annotations)

<div id="provide-feedback-in-the-ui">
  ## Fournir des retours dans l’UI
</div>

Dans Weave UI, vous pouvez ajouter et consulter des retours [depuis le panneau des détails de l’appel](#from-the-call-details-panel) ou [à l’aide des icônes](#use-the-icons).

<div id="from-the-call-details-panel">
  ### Depuis le panneau des détails de l’appel
</div>

1. Dans la barre latérale du projet Weave, accédez à **Traces**.
2. Repérez la ligne correspondant à l’Appel auquel vous souhaitez ajouter un feedback.
3. Cliquez sur le nom de la trace associé pour ouvrir l’arborescence de trace et le panneau des détails de l’appel.
4. Dans la barre d’onglets des détails de l’appel, sélectionnez **Feedback**.
5. Ajoutez, affichez ou supprimez des feedbacks :
   * *Ajoutez et affichez des feedbacks à l’aide des icônes* situées dans l’angle supérieur droit de la vue Feedback des détails de l’appel.
   * *Affichez et supprimez des feedbacks depuis le tableau Feedback des détails de l’appel.* Supprimez un feedback en cliquant sur l’icône de corbeille dans la colonne la plus à droite de la ligne de feedback concernée.

<Frame>
  <img src="https://mintcdn.com/wb-21fd5541-docs-hivemind-launch/IJ5wvwHtTZtWc35M/weave/guides/tracking/imgs/feedback_tab.png?fit=max&auto=format&n=IJ5wvwHtTZtWc35M&q=85&s=49554ca5e7e2d2ad476ac5537db7de75" alt="Capture d’écran de l’onglet Feedback dans les détails de l’appel" width="1266" height="548" data-path="weave/guides/tracking/imgs/feedback_tab.png" />
</Frame>

<div id="use-the-feedback-icons">
  ### Utilisez les icônes de feedback
</div>

Vous pouvez ajouter ou supprimer une réaction, et ajouter une note à l’aide des icônes situées à la fois dans le tableau **Traces** et dans chaque panneau des détails de l’appel.

* *Tableau Traces* : dans la colonne **Feedback** de la ligne correspondante du tableau **Traces**.
* *Panneau des détails de l’appel* : dans le coin supérieur droit de chaque panneau des détails de l’appel.

Pour ajouter une réaction :

1. Cliquez sur l’icône emoji.
2. Ajoutez un pouce levé, un pouce baissé ou cliquez sur l’icône **+** pour afficher plus d’emojis.

Pour supprimer une réaction :

1. Survolez la réaction emoji que vous souhaitez supprimer.
2. Cliquez sur la réaction pour la supprimer.

> Vous pouvez également supprimer un feedback depuis la [colonne **Feedback** du panneau des détails de l’appel](#from-the-call-details-panel).

Pour ajouter un commentaire :

1. Cliquez sur l’icône de bulle de commentaire.
2. Dans la zone de texte, ajoutez votre note. Le nombre maximal de caractères dans une note de feedback est de 1024.
3. Pour enregistrer la note, appuyez sur la touche **Entrée**. Vous pouvez ajouter des notes supplémentaires.

<Warning>
  Le nombre maximal de caractères dans une note de feedback est de 1024. Si une note dépasse cette limite, elle ne sera pas créée.
</Warning>

<Frame>
  <img src="https://mintcdn.com/wb-21fd5541-docs-hivemind-launch/IJ5wvwHtTZtWc35M/weave/guides/tracking/imgs/feedback_calls.png?fit=max&auto=format&n=IJ5wvwHtTZtWc35M&q=85&s=8c42c705d075fbad79a6a5b5cb1de321" alt="Capture d’écran de la grille des appels avec la colonne Feedback" width="3170" height="1589" data-path="weave/guides/tracking/imgs/feedback_calls.png" />
</Frame>

<div id="provide-feedback-through-the-sdk">
  ## Fournir des retours via le SDK
</div>

Vous trouverez des exemples d'utilisation du SDK pour les retours dans l'UI, sous l'onglet **Use** du panneau des détails de l’appel.

Vous pouvez utiliser le SDK Python de Weave pour [ajouter](/fr/weave/reference/python-sdk/trace/feedback#method-add), [supprimer](/fr/weave/reference/python-sdk/trace/feedback#method-purge) et [interroger les retours](/fr/weave/reference/python-sdk/trace/weave_client#method-get_feedback) sur les appels par programmation. Le SDK TypeScript ne prend actuellement pas en charge les retours.

<div id="query-a-projects-feedback">
  ### Consulter les feedbacks d'un projet
</div>

Vous pouvez interroger les feedbacks de votre projet Weave à l'aide du SDK. Le SDK prend en charge les opérations de requête de feedback suivantes :

* `client.get_feedback()` : Renvoie tous les feedbacks d'un projet.
* `client.get_feedback("<feedback_uuid>")` : Renvoie, sous forme de collection, un objet de feedback spécifique désigné par `<feedback_uuid>`.
* `client.get_feedback(reaction="<reaction_type>")` : Renvoie tous les objets de feedback pour un type de réaction donné.

Vous pouvez également obtenir des informations supplémentaires pour chaque objet de feedback dans `client.get_feedback()` :

* `id` : l'ID de l'objet de feedback.
* `created_at` : la date et l'heure de création de l'objet de feedback.
* `feedback_type` : le type de feedback (`reaction`, `note`, `custom`).
* `payload` : le payload du feedback.

<Tabs>
  <Tab title="Python">
    ```python lines theme={null}
    import weave
    client = weave.init('intro-example')

    # Obtenir tous les feedbacks d'un projet
    all_feedback = client.get_feedback()

    # Récupérer un objet de feedback spécifique par ID.
    # L'API renvoie une collection, qui ne doit contenir au plus qu'un seul élément.
    one_feedback = client.get_feedback("<feedback_uuid>")[0]

    # Trouver tous les objets de feedback avec une réaction spécifique. Vous pouvez spécifier offset et limit.
    thumbs_up = client.get_feedback(reaction="👍", limit=10)

    # Après récupération, afficher les détails de chaque objet de feedback.
    for f in client.get_feedback():
        print(f.id)
        print(f.created_at)
        print(f.feedback_type)
        print(f.payload)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```plaintext theme={null}
    Cette fonctionnalité n'est pas encore disponible en TypeScript.
    ```
  </Tab>
</Tabs>

<div id="add-feedback-to-a-call">
  ### Ajouter du feedback à un Appel
</div>

Vous pouvez ajouter du feedback à un Appel à l’aide de l’UUID de l’Appel. Pour utiliser l’UUID afin d’obtenir un Appel précis, [récupérez-le pendant ou après l’exécution de l’Appel](#retrieve-the-call-uuid). Le SDK prend en charge les opérations suivantes pour ajouter du feedback à un Appel :

* `call.feedback.add_reaction("<reaction_type>")` : ajoute l’un des `<reaction_types>` pris en charge (émojis), par exemple 👍.
* `call.feedback.add_note("<note>")` : ajoute une note.
* `call.feedback.add("<label>", <object>)` : ajoute un `<object>` de feedback personnalisé spécifié par `<label>`.

<Warning>
  Le nombre maximal de caractères dans une note de feedback est de 1024. Si une note dépasse cette limite, elle ne sera pas créée.
</Warning>

<Tabs>
  <Tab title="Python">
    ```python lines theme={null}
    import weave
    client = weave.init('intro-example')

    call = client.get_call("<call_uuid>")

    # Ajout d’une réaction emoji
    call.feedback.add_reaction("👍")

    # Ajout d’une note
    call.feedback.add_note("this is a note")

    # Ajout de paires clé/valeur personnalisées.
    # Le premier argument est une chaîne de "type" définie par l’utilisateur.
    # Le feedback doit être sérialisable en JSON et faire moins de 1 Ko une fois sérialisé.
    call.feedback.add("correctness", { "value": 5 })
    ```
  </Tab>

  <Tab title="TypeScript">
    ```plaintext theme={null}
    Cette fonctionnalité n’est pas encore disponible en TypeScript.
    ```
  </Tab>
</Tabs>

<div id="retrieve-the-call-uuid">
  #### Récupérer l’UUID de l’Appel
</div>

Si vous devez ajouter un feedback immédiatement après un Appel, vous pouvez récupérer l’UUID de l’Appel par code pendant son exécution ou une fois l’Appel terminé.

<div id="during-call-execution">
  ##### Lors de l’exécution de l’Appel
</div>

Pour récupérer l’UUID lors de l’exécution de l’Appel, récupérez l’Appel en cours et renvoyez son ID.

<Tabs>
  <Tab title="Python">
    ```python lines theme={null}

    import weave
    weave.init("uuid")

    @weave.op()
    def simple_operation(input_value):
        # Effectuer une opération simple
        output = f"Processed {input_value}"
        # Obtenir l'ID de l'appel en cours
        current_call = weave.require_current_call()
        call_id = current_call.id
        return output, call_id
    ```
  </Tab>

  <Tab title="TypeScript">
    ```plaintext theme={null}
    Cette fonctionnalité n’est pas encore disponible en TypeScript.
    ```
  </Tab>
</Tabs>

<div id="after-call-execution">
  ##### Après l’exécution d’un Appel
</div>

Vous pouvez également utiliser la méthode `call()` pour exécuter l’opération et récupérer l’ID après l’exécution de l’Appel :

<Tabs>
  <Tab title="Python">
    ```python lines theme={null}
    import weave
    weave.init("uuid")

    @weave.op()
    def simple_operation(input_value):
        return f"Processed {input_value}"

    # Exécute l’opération et récupère le résultat ainsi que l’ID de l’appel
    result, call = simple_operation.call("example input")
    call_id = call.id
    ```
  </Tab>

  <Tab title="TypeScript">
    ```plaintext theme={null}
    Cette fonctionnalité n’est pas encore disponible en TypeScript.
    ```
  </Tab>
</Tabs>

<div id="delete-feedback-from-a-call">
  ### Supprimer le feedback d’un Appel
</div>

Vous pouvez supprimer le feedback d’un Appel donné en spécifiant un UUID.

<Tabs>
  <Tab title="Python">
    ```python lines theme={null}
    call.feedback.purge("<feedback_uuid>")
    ```
  </Tab>

  <Tab title="TypeScript">
    ```plaintext theme={null}
    Cette fonctionnalité n’est pas encore disponible en TypeScript.
    ```
  </Tab>
</Tabs>

<div id="add-human-annotations">
  ## Ajouter des annotations humaines
</div>

Les annotations humaines sont prises en charge dans Weave UI. Cette fonctionnalité vous permet de créer des champs personnalisés pour ajouter à vos traces des données supplémentaires saisies manuellement sous forme de retours. Pour créer des annotations humaines, vous devez d’abord créer un évaluateur d’annotation humaine à l’aide de la [UI](#create-a-human-annotation-scorer-in-the-ui) ou de l’[API](#create-a-human-annotation-scorer-using-the-api). Vous pouvez ensuite [utiliser le scorer dans la UI pour créer des annotations](#use-the-human-annotation-scorer-in-the-ui), puis [modifier vos évaluateurs d’annotation à l’aide de l’API](#modify-a-human-annotation-scorer-using-the-api).

<div id="create-a-human-annotation-scorer-in-the-ui">
  ### Créez un évaluateur d’annotation humaine dans l’interface utilisateur
</div>

Pour créer un évaluateur d’annotation humaine dans l’interface utilisateur, procédez comme suit :

1. Dans la barre latérale du projet, accédez à **Assets**.
2. Dans le panneau de navigation d’**Assets**, cliquez sur **Scorers**.
3. Dans l’en-tête du panneau **Scorers**, cliquez sur **New scorer**.
4. Dans la boîte de dialogue modale **Create Scorer**, définissez :
   * `Scorer type` sur `Human annotation`
   * `Name`
   * `Description`
   * `Type`, qui détermine le type de retour collecté, par exemple `boolean` ou `integer`.
5. Cliquez sur **Create scorer**. Vous pouvez maintenant utiliser votre évaluateur pour ajouter des annotations.

Dans l’exemple suivant, il est demandé à un annotateur humain de sélectionner le type de document traité par le LLM. Ainsi, le `Type` sélectionné pour la configuration du score est un `enum` contenant les types de documents possibles.

<Frame>
  <img src="https://mintcdn.com/wb-21fd5541-docs-hivemind-launch/IJ5wvwHtTZtWc35M/weave/guides/tracking/imgs/human-annotation-scorer-form.png?fit=max&auto=format&n=IJ5wvwHtTZtWc35M&q=85&s=7e9dc934d3690d8347bc6d554ebfaf90" alt="Boîte de dialogue modale Create Scorer" width="3454" height="1862" data-path="weave/guides/tracking/imgs/human-annotation-scorer-form.png" />
</Frame>

<div id="use-the-human-annotation-scorer-in-the-ui">
  ### Utiliser l’évaluateur d’annotation humaine dans l’interface utilisateur
</div>

Une fois que vous avez créé un évaluateur d’annotation humaine, vous pouvez l’utiliser sur la page Traces.

Pour utiliser l’évaluateur, procédez comme suit :

1. Dans la barre latérale du projet, accédez à **Traces**.

2. Repérez la ligne de l’Appel auquel vous souhaitez ajouter une annotation humaine.

3. Cliquez sur le nom de la trace pour ouvrir l’arborescence de trace et le panneau des détails de l’appel.

4. Dans l’angle supérieur droit de la barre d’onglets des détails de l’Appel, cliquez sur le bouton **Show feedback**.

   <img src="https://mintcdn.com/wb-21fd5541-docs-hivemind-launch/IJ5wvwHtTZtWc35M/weave/guides/tracking/imgs/marker-icon.png?fit=max&auto=format&n=IJ5wvwHtTZtWc35M&q=85&s=5c07617fa8509b6f690d83e05b321e0f" alt="Icône de marqueur dans l’en-tête de l’Appel" width="306" height="84" data-path="weave/guides/tracking/imgs/marker-icon.png" />

   Vos évaluateurs d’annotation humaine disponibles s’affichent dans un panneau **Annotate** supplémentaire.

   <img src="https://mintcdn.com/wb-21fd5541-docs-hivemind-launch/IJ5wvwHtTZtWc35M/weave/guides/tracking/imgs/full-feedback-sidebar.png?fit=max&auto=format&n=IJ5wvwHtTZtWc35M&q=85&s=1ab04225479083b7a0f23f99acae8e59" alt="Panneau de feedback de l’évaluateur d’annotation humaine" width="3454" height="1862" data-path="weave/guides/tracking/imgs/full-feedback-sidebar.png" />

5. Ajoutez une annotation.

6. Cliquez sur **Save**.

7. Dans la barre d’onglets du panneau des détails de l’Appel, cliquez sur l’onglet **Feedback** pour afficher le tableau Feedback. La nouvelle annotation apparaît dans le tableau. Vous pouvez également voir les annotations dans la colonne **Annotations** du tableau principal Traces.

   > Actualisez le tableau Traces pour afficher les informations les plus récentes.

<Frame>
  <img src="https://mintcdn.com/wb-21fd5541-docs-hivemind-launch/IJ5wvwHtTZtWc35M/weave/guides/tracking/imgs/feedback-in-the-table.png?fit=max&auto=format&n=IJ5wvwHtTZtWc35M&q=85&s=ad77b9b864bc8d5978b4da2f98aa067b" alt="Feedback de l’évaluateur d’annotation humaine dans le tableau Traces" width="3456" height="1569" data-path="weave/guides/tracking/imgs/feedback-in-the-table.png" />
</Frame>

<div id="create-a-human-annotation-scorer-using-the-api">
  ### Créer un évaluateur d’annotation humaine à l’aide de l’API
</div>

Vous pouvez également créer des évaluateurs d’annotation humaine via l’API. Chaque évaluateur est un objet distinct, que vous créez et mettez à jour indépendamment. Pour créer un évaluateur d’annotation humaine par programmation, procédez comme suit :

1. Importez la classe `AnnotationSpec` depuis `weave.flow.annotation_spec`.
2. Utilisez la méthode `publish` de `weave` pour créer l’évaluateur.

Dans l’exemple suivant, deux évaluateurs sont créés. Le premier, `Temperature`, sert à attribuer un score à la température perçue de l’Appel LLM. Le second, `Tone`, sert à attribuer un score au ton de la Réponse du LLM. Chaque évaluateur est créé à l’aide de `save` avec un ID d’objet associé (`temperature-scorer` et `tone-scorer`).

<Tabs>
  <Tab title="Python">
    ```python lines theme={null}
    import weave
    from weave.flow.annotation_spec import AnnotationSpec

    client = weave.init("feedback-example")

    spec1 = AnnotationSpec(
      name="Temperature",
      description="The perceived temperature of the llm call",
      field_schema={
        "type": "number",
        "minimum": -1,
        "maximum": 1,
      }
    )
    spec2 = AnnotationSpec(
      name="Tone",
      description="The tone of the llm response",
      field_schema={
        "type": "string",
        "enum": ["Aggressive", "Neutral", "Polite", "N/A"],
      },
    )
    weave.publish(spec1, "temperature-scorer")
    weave.publish(spec2, "tone-scorer")
    ```
  </Tab>

  <Tab title="TypeScript">
    ```plaintext theme={null}
    Cette fonctionnalité n’est pas encore disponible en TypeScript.
    ```
  </Tab>
</Tabs>

<div id="modify-a-human-annotation-scorer-using-the-api">
  ### Modifier un évaluateur d’annotation humaine via l’API
</div>

Dans la continuité de [la création d’un évaluateur d’annotation humaine via l’API](#create-a-human-annotation-scorer-using-the-api), l’exemple suivant crée une version mise à jour de l’évaluateur `Temperature` en utilisant l’ID d’objet original (`temperature-scorer`) lors de `publish`. Le résultat est un objet mis à jour, avec un historique de toutes les versions.

> Vous pouvez consulter l’historique des objets d’évaluateur d’annotation humaine dans l’onglet **Évaluateurs**, sous **Annotations humaines**.

<Tabs>
  <Tab title="Python">
    ```python lines theme={null}
    import weave
    from weave.flow.annotation_spec import AnnotationSpec

    client = weave.init("feedback-example")

    # créer une nouvelle version de l’évaluateur
    spec1 = AnnotationSpec(
      name="Temperature",
      description="The perceived temperature of the llm call",
      field_schema={
        "type": "integer",  # <<- remplacer le type par integer
        "minimum": -1,
        "maximum": 1,
      }
    )
    weave.publish(spec1, "temperature-scorer")
    ```
  </Tab>

  <Tab title="TypeScript">
    ```plaintext theme={null}
    Cette fonctionnalité n’est pas encore disponible en TypeScript.
    ```
  </Tab>
</Tabs>

<Frame>
  <img src="https://mintcdn.com/wb-21fd5541-docs-hivemind-launch/IJ5wvwHtTZtWc35M/weave/guides/tracking/imgs/human-annotation-scorer-history.png?fit=max&auto=format&n=IJ5wvwHtTZtWc35M&q=85&s=b440c54573c619f63db4626f6a99a0e6" alt="Historique de l’évaluateur d’annotation humaine" width="2686" height="1434" data-path="weave/guides/tracking/imgs/human-annotation-scorer-history.png" />
</Frame>

<div id="use-a-human-annotation-scorer-using-the-api">
  ### Utiliser un évaluateur d’annotation humaine avec l’API
</div>

L’API de feedback vous permet d’utiliser un évaluateur d’annotation humaine en indiquant un nom au format spécifique et un champ `annotation_ref`. Vous pouvez obtenir l’`annotation_spec_ref` dans l’UI en sélectionnant l’onglet approprié, ou lors de la création de l’`AnnotationSpec`.

<Tabs>
  <Tab title="Python">
    ```python lines theme={null}
    import weave

    client = weave.init("feedback-example")

    call = client.get_call("<call_id>")
    annotation_spec = weave.ref("<annotation_spec_ref_uri>")

    call.feedback.add(
      feedback_type="wandb.annotation." + annotation_spec.name,
      payload={"value": 1},
      annotation_ref=annotation_spec.uri(),
    )
    ```
  </Tab>
</Tabs>