Recherche RAG - UBIK Public API

L’outil rag_search est la pierre angulaire de la récupération d’information au sein de la plateforme UBIK. Il permet aux agents d’effectuer des recherches en Génération Augmentée par Récupération (RAG) à travers vos documents téléchargés. Contrairement à une recherche par mot-clé standard, cet outil utilise la compréhension sémantique pour trouver les “morceaux” (chunks) de texte les plus pertinents de votre base de connaissances et utilise un Grand Modèle de Langage (LLM) pour synthétiser une réponse précise basée sur ces faits.

Quand Utiliser Cet Outil

Utilisez rag_search lorsque vous avez besoin de :

Répondre à des questions spécifiques basées sur vos données privées (par ex., “Quelle est la politique de congés ?”).
Trouver des faits précis enfouis dans de grands documents.
Vérifier des informations par rapport à une source fiable.
Récupérer du contexte pour soutenir une conversation.

Cet outil est optimisé pour la précision de récupération et la génération ancrée. Il n’est pas destiné au traitement de documents entiers ou à la génération de résumés longs (utilisez information_analysis pour cela).

Paramètres d’Entrée

L’outil accepte les paramètres suivants :

Paramètre	Type	Requis	Description
`query`	`string`	Oui	La question en langage naturel ou la requête de recherche. Soyez aussi précis que possible pour de meilleurs résultats.
`document_ids`	`array<uuid>`	Non	Une liste d’UUIDs de documents spécifiques dans lesquels chercher. Si omis, la recherche s’exécute sur tous les documents accessibles à l’utilisateur/session.

Portée & Permissions

L’outil rag_search respecte automatiquement le contexte de sécurité de l’exécution :

Accès Utilisateur : Recherche les documents appartenant à l’utilisateur ou partagés avec lui via des espaces de travail.
Contexte de Session : Si exécuté au sein d’une session de chat, il inclut les documents attachés à cette session spécifique.
ID Externe : Pour les applications multi-tenants, il applique strictement les frontières external_user_id, garantissant que les utilisateurs ne voient jamais les données d’autres sous-utilisateurs.

Structure de Sortie

L’outil renvoie un objet structuré contenant la réponse, les preuves utilisées pour la générer et des métadonnées sur l’exécution.

{
  "response": "**Réflexion :**\n*L'utilisateur pose une question sur la politique de télétravail. Je dois vérifier le manuel de l'employé pour l'éligibilité et les processus d'approbation...*\n\n# Directives de Télétravail\n\nSelon le manuel de l'entreprise, le télétravail est autorisé sous certaines conditions :\n\n- Les employés doivent avoir terminé leur période d'essai <citation id=\"9bdef571-ed43-4cb7-a4a1-1011edce8a62\">[1]</citation>\n- L'approbation est requise de la part du manager direct au moins 48 heures à l'avance <citation id=\"af572b1c-cb3a-49dc-a062-17860219b8ef\">[2]</citation>\n\nDes exceptions peuvent être faites pour raisons médicales.",
  "contexts": [
    {
      "rank": 1,
      "chunk_id": "9bdef571-ed43-4cb7-a4a1-1011edce8a62",
      "document_id": "7f15f1ff-d15e-4894-8fb3-155392ab8972",
      "text_preview": "Éligibilité au télétravail : Les employés à temps plein ayant terminé avec succès leur période d'essai de 3 mois sont éligibles...",
      "used_in_response": true
    },
    {
      "rank": 2,
      "chunk_id": "af572b1c-cb3a-49dc-a062-17860219b8ef",
      "document_id": "7f15f1ff-d15e-4894-8fb3-155392ab8972",
      "text_preview": "Processus de demande : Soumettez une demande via le portail RH. L'approbation du manager est requise 48 heures avant la date demandée...",
      "used_in_response": true
    }
  ],
  "sources_used": [1, 2],
  "model": "claude-3-7-sonnet-20250219-thinking",
  "execution_id": "call_HB55iUMZE3dZ3QKCHGKE6qYF"
}

Champ	Description
`response`	La réponse en langage naturel. Peut inclure un bloc “Réflexion” (processus de pensée), du formatage Markdown et des citations en ligne pointant vers des morceaux spécifiques.
`contexts`	Une liste des morceaux de texte récupérés passés au LLM. Inclut `chunk_id`, `document_id` et `text_preview`.
`sources_used`	Une liste d’indices (rangs) correspondant aux `contexts` qui ont été explicitement utilisés pour former la réponse. Ces indices sont dérivés des citations (ex: `<source_1>`) générées par le modèle.
`model`	Le LLM spécifique utilisé pour la génération.
`execution_id`	L’identifiant unique pour cette exécution d’outil.

Récupération des Détails des Chunks

La réponse de rag_search fournit des chunk_ids dans le tableau contexts. Vous pouvez utiliser ces identifiants pour récupérer des données de localisation précises pour le surlignage ou la navigation dans le document original via l’endpoint GET /chunks/{chunk_id}.

Obtenir les détails d’un chunk : GET /chunks/{chunk_id}
Obtenir le document d’un chunk : GET /chunks/{chunk_id}/document

La structure de la réponse s’adapte à la modalité du contenu (Texte/PDF vs Audio/Vidéo) :

{
  "id": "9bdef571-ed43-4cb7-a4a1-1011edce8a62",
  "document_id": "7f15f1ff-d15e-4894-8fb3-155392ab8972",
  "text": "Contenu complet du chunk...",
  
  // Pour les PDF et Images
  "page_number": 3,
  "bbox": [
    {
      "bbox": [100.5, 200.0, 300.5, 250.0], // [x1, y1, x2, y2]
      "page_number": 3
    },
    {
      "bbox": [50.0, 100.0, 200.0, 150.0], // Suite sur la page suivante
      "page_number": 4
    }
  ],

  // Pour Audio et Vidéo
  "start_time": 120.5, // Secondes
  "end_time": 135.0,   // Secondes

  "metadata": {
    "filename": "manuel.pdf",
    "languages": ["fra"],
    "modality": "text"
  }
}

Champ	Description
`bbox`	Une liste de boîtes englobantes pour le surlignage visuel. Chaque entrée contient les coordonnées `[x1, y1, x2, y2]` et le `page_number` spécifique. Note : Certains types de documents (ex: fichiers texte brut, markdown) peuvent ne pas fournir de coordonnées.
`page_number`	Le numéro de page principal du chunk (indexé à partir de 1). Null pour les médias temporels.
`start_time` / `end_time`	Horodatages en secondes, utilisés pour la navigation dans les lecteurs audio ou vidéo.

Événements de Streaming

Lorsqu’il est utilisé en mode streaming, l’outil rag_search émet des événements en temps réel via SSE (Server-Sent Events). Cela permet de suivre la progression du pipeline RAG et d’afficher la réponse au fur et à mesure de sa génération.

Types d’Événements

Événement	Description
`tool_update`	Indique une mise à jour de progression (changement de phase).
`tool_partial_update`	Contient un nouveau fragment de texte de la réponse générée (streaming).
`error`	Signale qu’une erreur critique s’est produite pendant l’exécution.
`tool_end`	Signale la fin de l’exécution de l’outil et fournit le résultat final complet.

Phases du Pipeline (`tool_update`)

L’événement tool_update contient un champ data avec une phase et un status. Voici les phases possibles :

SEARCH_PREPARATION
- status: started
- Indique que le pipeline a commencé et prépare la recherche.
RETRIEVAL (Récupération)
- status: completed
- data: { "retrieved_count": <int> }
- Indique que la recherche vectorielle initiale est terminée et combien de documents ont été trouvés.
RERANKING (Réordonnancement)
- status: completed
- data: { "initial_count": <int>, "reranked_count": <int>, "kept_count": <int> }
- Indique que les résultats ont été réordonnés par pertinence. kept_count est le nombre de documents retenus pour la génération.
COMPILING_RESULTS (Génération)
- status: started
- Indique que la génération de la réponse par le LLM commence.

Streaming de Contenu (`tool_partial_update`)

Pendant la phase de génération, des événements tool_partial_update sont émis pour chaque fragment de texte généré.

content: <string> (Le fragment de texte)
output_key: "response"

Ces fragments doivent être concaténés pour former la réponse complète.

Gestion des Événements Volumineux (Chunking)Si la charge utile d’un événement dépasse la limite de taille SSE, elle sera divisée en plusieurs événements _delta_sse. Pour des instructions détaillées et des exemples de code sur la façon de mettre en mémoire tampon et de reconstruire ces événements fragmentés, veuillez consulter le Guide des Résultats en Streaming ou le Guide des Événements de Session d’Agent.

Exemple de Flux d’Événements

// Début
{ "event": "tool_update", "data": { "phase": "SEARCH_PREPARATION", "status": "started" } }

// Récupération terminée
{ "event": "tool_update", "data": { "phase": "RETRIEVAL", "status": "completed", "data": { "retrieved_count": 15 } } }

// Réordonnancement terminé
{ "event": "tool_update", "data": { "phase": "RERANKING", "status": "completed", "data": { "initial_count": 15, "reranked_count": 15, "kept_count": 5 } } }

// Début de la génération
{ "event": "tool_update", "data": { "phase": "COMPILING_RESULTS", "status": "started" } }

// Streaming de la réponse (tool_partial_update)
{ "event": "tool_partial_update", "data": { "content": "Selon", "output_key": "response" } }
{ "event": "tool_partial_update", "data": { "content": " le", "output_key": "response" } }
{ "event": "tool_partial_update", "data": { "content": " document...", "output_key": "response" } }

// Fin
{ "event": "tool_end", "data": { ...résultat final complet... } }

Exemple d’Utilisation

1. Recherche Large

Recherche à travers toutes les connaissances disponibles. Entrée :

{
  "query": "Comment réinitialiser mon jeton 2FA ?"
}

2. Recherche Ciblée

Recherche uniquement au sein d’un manuel technique spécifique. Entrée :

{
  "query": "Quel est le code d'erreur E-505 ?",
  "document_ids": ["550e8400-e29b-41d4-a716-446655440000"]
}

Capacités Multimodales

Le pipeline rag_search est entièrement compatible avec le multimodal. Si vous avez indexé des documents contenant des images (comme des PDF avec des graphiques ou des diapositives), la recherche peut récupérer le contexte visuel pertinent.

Récupération Texte-vers-Image : Votre requête textuelle peut correspondre à des descriptions d’images.
Compréhension d’Image : Le modèle de génération peut “voir” les images récupérées pour répondre à des questions sur des graphiques, des diagrammes ou des photos.

Activation RequiseLe RAG multimodal n’est pas activé par défaut. Pour activer cette fonctionnalité pour votre espace de travail, veuillez contacter l’équipe UBIK à contact@ubik-agent.com.

Pour une plongée plus profonde dans la façon dont le pipeline gère les embeddings, le re-ranking et la recherche hybride, voir l’Approfondissement du Pipeline RAG.

Documentation Index

​Quand Utiliser Cet Outil

​Paramètres d’Entrée

​Portée & Permissions

​Structure de Sortie

​Récupération des Détails des Chunks

​Événements de Streaming

​Types d’Événements

​Phases du Pipeline (tool_update)

​Streaming de Contenu (tool_partial_update)

​Exemple de Flux d’Événements

​Exemple d’Utilisation

​1. Recherche Large

​2. Recherche Ciblée

​Capacités Multimodales

Quand Utiliser Cet Outil

Paramètres d’Entrée

Portée & Permissions

Structure de Sortie

Récupération des Détails des Chunks

Événements de Streaming

Types d’Événements

Phases du Pipeline (`tool_update`)

Streaming de Contenu (`tool_partial_update`)

Exemple de Flux d’Événements

Exemple d’Utilisation

1. Recherche Large

2. Recherche Ciblée

Capacités Multimodales