Citation des sources v2

Introduction

Lorsqu'une APP Wikit Semantics répond à une question, elle peut citer ses sources sous forme de références numérotées (ex: [1], [2], [10]) - option à activer dans le prompt. Cette API vous permet de récupérer les métadonnées complètes de ces sources pour les afficher dans votre interface utilisateur.

Utilité :

• Tracer l'origine des informations fournies
• Garantir la transparence auprès des utilisateurs
• Permettre la vérification en accédant aux documents sources

Prérequis

Cette documentation suppose que vous ayez déjà :

• Exécuté une query via l'endpoint /query-executions
• Récupéré le queryId depuis la réponse

Pour plus d'informations sur l'exécution de queries, consultez la section dédiée.

Récupérer les sources d'une query

Endpoint

GET /semantics/apps/{llm_app_id}/query-execution-sources/{query_id}/get-quoted-sources

Exemple de requête

curl -X GET "https://apis.wikit.ai/semantics/apps/$APP_ID/query-execution-sources/$QUERY_ID/get-quoted-sources" \
  -H "accept: application/json" \
  -H "Wikit-Semantics-API-Key: $API_KEY" \
  -H "X-Wikit-Organization-Id: $ORG_ID"

ℹ️ le Wikit-Semantics-API-Key est nécessaire uniquement pour les Apps privées

Le point de terminaison renvoie une liste de passages identifiés dans les fragments de documents.

Exemple de réponse

[
  {
    "quoted_as": "1",
    "document": {
      "id": "686e90dd2ff687c57806d107",
      "name": "Charte_Teletravail_01_08_2023.pdf",
      "title": null,
      "url": null,
      "public_link": false,
      "storage_name": "lien_du_stockage",
      "data_source_id": "686d402ce52bbbf7116f55f8",
      "organization_id": "686d3ceb18a3087351f0fa35"
    },
    "chunk": {
      "id": "686e90e725e88b90bdd50eb2",
      "data": "## le contenu du chunk...",
      "document_id": "686e90dd2ff687c57806d107",
      "data_source_id": "686d402ce52bbbf7116f55f8",
      "llm_app_id": null,
      "user_id": null,
      "flags": null,
      "position": 29,
      "page_start": null,
      "page_end": null
    },
    "data_source": {
      "id": "686d402ce52bbbf7116f55f8",
      "name": "Ressources Humaines"
    },
    "score": 0.88380575,
    "retriever_type": "SEMANTIC_SEARCH"
  }
]

Structure de la réponse

La réponse est un tableau d'objets source, chaque objet contenant :

Champs principaux

Champ	Type	Description
quoted_as	string	Numéro de la citation dans la réponse (ex : "1", "2", "10")
document	object	Métadonnées du document source
chunk	object	Extrait du document utilisé comme source
data_source	object	Informations sur la source de données
score	float	Score de pertinence sémantique (entre 0 et 1)
retriever_type	string	Type de recherche utilisé (ex : "SEMANTIC_SEARCH")

Objet document

Champ	Type	Description
id	string	Identifiant unique du document
name	string	Nom du fichier source
title	string/null	Titre du document (si disponible)
url	string/null	URL du document (si disponible)
public_link	boolean	Indique si le document a un lien public
storage_name	string	Chemin de stockage interne
data_source_id	string	Identifiant de la source de données
organization_id	string	Identifiant de l'organisation

Objet chunk

Champ	Type	Description
id	string	Identifiant unique du chunk
data	string	Extrait du texte source (contenu markdown)
document_id	string	Référence au document parent
position	integer	Position du chunk dans le document
page_start	integer/null	Page de début (si applicable)
page_end	integer/null	Page de fin (si applicable)

Objet data_source

Champ	Type	Description
id	string	Identifiant de la source de données
name	string	Nom de la source de données (ex: "Ressources Humaines")

Bonnes pratiques

1. Timing de l'appel

Appelez l'API des sources après la fin du streaming de la réponse

2. Affichage conditionnel

N'affichez la section sources que si elles existent

3. Gestion des URLs

Certaines sources n'ont pas d'URL. Gérez ce cas dans votre UI

4. Affichage conditionnel

L’API peut retourner plusieurs fois le même document, gérez bien le cas en fonction de votre besoin

5. Affichage conditionnel

Si vous le souhaitez, vous pouvez cacher/transformer les [1],[2], … lors de l’affichage de la réponse

6. Codes d'erreur courants

Code	Signification	Solution
401	API Key invalide	Vérifier la clé API et l'Organization ID
404	Query non trouvée	Vérifier le queryId ou attendre quelques secondes
500	Erreur serveur	Réessayer après un délai

Citation des sources v1 (dépréciée)

Récupération des citations des sources d’une requête

Après l’exécution d’une requête, il est possible d’extraire les citations identifiées dans les sources (i.e. les fragments des documents) utilisées par l’App.

POST /semantics/apps/{llm_app_id}/query-executions/{query_execution_id}/citations

curl -X POST "https://apis.wikit.ai/semantics/apps/$SEMANTICS_APP_ID/query-executions/$SEMANTICS_QUERY_EXECUTION_ID/citations" \
  -H "Authorization: Bearer $SEMANTICS_TOKEN" \
  -H "X-Wikit-Organization-Id: $SEMANTICS_ORG_ID" \
  -H "X-Wikit-Response-Format: json" \
  -H "Content-Type: application/json" \
  -d "{}"

Le point de terminaison renvoie une liste de passage identifiée dans les fragments de document.

Exemple :

[
    {
        "_id": "668e9bf39bd4493d2557a6ea",
        "created_at": "2024-07-10T14:34:26Z",
        "query_execution_id": "668e9bf09bd4493d2557a6e6",
        "total_count": 1,
        "reply_sentence": "Les couleurs de la charte graphique de Wikit sont : Bleu ciel, Bleu nuit et Violet.",
        "source_sentence": "Les couleurs de la charte graphique de Wikit sont : - Bleu ciel ; - Bleu nuit ; - Violet.",
        "chunk_data_snapshot": " [...]  {{source_sentence}}  [...] ",
        "start_char_idx": 0,
        "end_char_idx": 89,
        "chunk_id": "668e9b94ca8d43490c14ede3",
        "chunk_page_start": 2,
        "chunk_page_end": 2,
        "chunk_position": null,
        "document_id": "668e9b94ca8d43490c14ede0",
        "document_name": "wikit-visual-identity.pdf",
        "document_title": null,
        "document_url": "https://semantics-files.wikit.ai/v1/viewer/NjVkNWIzNDRhMDUxZWEyOGI3ZjU0ZDc2LzY2OGU5YjgzY2E4ZDQzNDkwYzE0ZWRkZi8xNzIwNjIxOTcxLjkwNzU3N193aWtpdF9kb2N1bWVudF9zYW1wbGUucGRm",
        "organization_id": "65d5b344a051ea28b7f54d76",
        "threshold": 50
    }
]

Dans cet exemple, le fragment associé à la page 3 (cf. les indexchunk_page_start et chunk_page_endqui démarrent à 0) du document “wikit-visual-identity.pdf” (cf. le champ document_name) a été identifié par Wikit Semantics en tant que source.