Migration vers Discovery v2

Planifiez l'adaptation de votre application

L'une des principales modifications entre les versions est que Discovery v2 introduit des projets. Un projet est constitué d'une ou plusieurs collections. L'avantage d'utiliser des projets est qu'une requête peut s'exécuter simultanément sur de nombreuses collections. Chaque collection peut contenir des documents que vous téléchargez ou que vous extrayez d'une source de données unique, telle qu'un site web, Microsoft SharePoint, et bien d'autres encore.

Points à prendre en compte lorsque vous adaptez votre application pour utiliser des projets:

• Bien que le concept d'environnement n'existe pas dans v2, les données sont toujours organisées en collections. Dans v2, les collections sont regroupées en projets. Dans la plupart des cas, vous souhaitez migrer une collection v1 unique vers une collection v2 unique.

  Si vous souhaitez conserver les informations d'entraînement à la pertinence qui sont appliquées à une collection v1, ajoutez les documents de collection à une collection unique dans votre projet v2.

• Déterminez le nombre de collections à ajouter à chaque projet v2. Tous les types de projet, à l'exception des projets Content Mining, peuvent contenir jusqu'à 5 collections. Choisissez le type de projet approprié pour vos données.

  Pour optimiser les résultats de la recherche, différents enrichissements et options de configuration sont appliqués automatiquement aux collections qui sont ajoutées à différents types de projet. pour plus d'informations, consultez les rubriques suivantes :

  • Descriptions de projet
  • Paramètres par défaut du projet
  • Paramètres de requête par défaut

• L'API Discovery v2 a été modifiée pour prendre en compte les projets et les collections, entre autres améliorations. Certains appels d'API ont été modifiés pour prendre en charge des actions au niveau du projet au lieu du niveau de la collection, comme la soumission d'une requête et l'exécution d'un entraînement à la pertinence. De nombreuses autres méthodes d'API ont été modifiées et certaines ne sont pas disponibles dans v2. Pour une comparaison détaillée des méthodes d'API v1 et v2, voir Comparaison des versions d'API.

Prélèvement d'un plan de service

Choisissez parmi les plans gérés Plus, Enterpriseet Premium ou optez pour une installation sur site en achetant la cartouche Discovery pour IBM Cloud Pak for Data. Passez en revue les avantages et les limites de chaque type de régime avant d'en choisir un.

• Pour plus d'informations sur les plans, voir Plans de tarificationDiscovery.
• Pour plus d'informations sur les limites d'artefact, voir Détails des limites.

Le tableau suivant présente les types de plan pour les déploiements gérés qui sont généralement similaires entre v1 et v2.

Pour obtenir des informations sur le stockage en cours, les documents et les collections utilisés, cliquez sur l'icône Détails de l'environnement dans l'en-tête de l'interface utilisateur du produit.

Vous ne pouvez pas effectuer une mise à niveau interne à partir d'un plan v1, tel que Lite ou Advanced, vers un plan v2. Vous devez créer un nouveau plan v2, puis déplacer vos données vers la nouvelle instance de service. Lorsque vous migrez vos données de v1 vers v2, il est probable qu'une instance v1 et v2 soient déployées simultanément. Pensez à utiliser l'essai gratuit de 30 jours qui est disponible avec votre première instance de plan Plus pendant cette période.

Données transférées

Si vous avez utilisé l'API pour télécharger des documents dans Discovery v1, une API similaire est disponible dans v2 pour télécharger des documents dans des collections. Vous devez mettre à jour les flux de travaux que vous utilisez pour automatiser le processus afin de tenir compte de la nouvelle organisation des projets et des collections.

Si les documents d'origine que vous avez ingérés dans Discovery v1 ne sont plus disponibles, vous pouvez utiliser l'API de requête pour extraire le texte du document depuis Discovery v1. Vous pouvez ensuite ajouter le texte à une collection dans Discovery v2. Pour plus d'informations, voir Récupération de documents.

Données explorées

Si vous avez exploré des données à partir d'une source de données externe dans v1, vous pouvez continuer à explorer des données à partir de la même source de données externe dans v2. Toutes les mêmes sources de données sont prises en charge.

Pour utiliser les données d'une source de données externe, vous devez recréer les collections dans un projet v2 et configurer la façon dont la source de données est explorée. Pour plus d'informations, voir Présentation des sources de données.

Le service a besoin de temps et de ressources pour explorer et ingérer des documents à partir de sources de données externes. Recréez les connecteurs un par un. Prenez en compte le temps nécessaire à la réexploration des données dans votre planification de plan de migration.

Collections de données préconfigurées

Les collections de sources de données intégrées suivantes ne sont pas disponibles dans v2:

Watson Discovery Actualités

Cette source de données pré-enrichie n'est pas disponible dans v2. Pour plus d'informations sur une autre méthode d'obtention de données de nouvelles, voir Utilisation d'un service de nouvelles avec v2.

Kit COVID-19

Cette collection prégénérée a été conçue pour vous aider à alimenter un agent conversationnel dynamique qui est généré avec IBM® watsonx™ Assistant et Discovery pour répondre aux questions de vos clients sur COVID-19. Dans v2, vous pouvez générer une solution similaire. Créez un type de projet Conversational Search avec des collections qui explorent des sites Web de confiance pour obtenir des réponses aux questions COVID-19.

Conservation des ID de document

Les ID de document sont affectés aux documents que vous ajoutez à une collection v2 lorsque vous les téléchargez à partir de l'interface utilisateur du produit ou que vous les ajoutez à l'aide de la méthode d'API Ajouter un document.

Vous pouvez conserver les ID de vos documents v1 dans v2 si vous utilisez des processus qui dépendent de ces identificateurs uniques. Par exemple, les tests de régression de l'application peuvent vérifier que des documents spécifiques sont renvoyés en vérifiant les ID de document. L'entraînement à la pertinence utilise les ID de document pour suivre les documents entre les exécutions d'entraînement. Ces processus sont plus faciles à adapter si les ID de document sont identiques entre vos instances v1 et v2. Sinon, les processus utilisés avec l'instance Discovery v1 doivent être remappés aux ID affectés aux documents une fois qu'ils ont été ajoutés à l'instance Discovery v2.

Si vous avez spécifié vos propres ID de document lorsque vous avez ajouté des documents à l'instance de service v1, vous pouvez conserver les ID à l'aide de la méthode Mettre à jour un document au lieu de la méthode Ajouter un document. Avec la méthode de mise à jour, vous pouvez affecter un ID document au document lorsque vous l'ajoutez à la collection v2. Pour plus d'informations, voir Mise à jour d'un document.

Si vos données sont stockées dans un fichier JSON, un tableau du document d'origine génère un ID de document auquel est ajouté un numéro. Par exemple, original_id_n. Pour conserver l'ID document d'origine sans le suffixe numérique, supprimez le tableau dans le fichier JSON. Remplacez [ {"name": "value"} ] par {"name": "value"}, par exemple.

Si vos documents v1 possèdent des ID générés par le système, vous pouvez soumettre une requête de recherche vide pour extraire une liste des documents et de leurs ID. Vous pouvez ensuite affecter le même ID à chaque document lorsque vous l'ajoutez à votre nouvelle collection dans v2.

Récupération de documents

Dans certains cas, les documents d'origine qui ont été ingérés dans Discovery V1 ne sont plus disponibles. Vous pouvez utiliser l'instance Discovery v1 pour extraire des informations du document. Discovery crée une copie texte de chaque document qu'il ingère. La copie est du texte uniquement, de sorte que tous les documents aux formats HTML, PDF ou non texte sont convertis en version texte uniquement.

Vous pouvez récupérer uniquement les 10 000 premiers documents d'une collection à l'aide de cette méthode. Pour plus d'informations sur la façon de récupérer plus de 10 000 documents, voir Récupération de plus de 10 000 documents à partir d'une collection.

Pour transférer des informations de document de v1 vers v2, procédez comme suit:

1. Extrayez les documents de v1 à l'aide de l'API pour soumettre une requête vide.

   Par exemple, GET {url}/v1/environments/{environment_id}/collections/{collection_id}/query?q=.

   L'API renvoie les résultats. La zone matching_results indique le nombre total de résultats. L'objet de résultats renvoie les documents correspondants. Chaque document est renvoyé en tant qu'objet JSON distinct. Elle renvoie un maximum de 10 documents par défaut.

   {
     "matching_results": 34,
     "session_token": "nnn",
     "results": [
       {"{result objects}":"{maximum of 10 by default}"}
     ]
   }
   

2. Vous pouvez utiliser les paramètres count et offset pour parcourir les résultats de la requête et sauvegarder tous les documents.

   Par exemple, pour obtenir 100 documents à la fois, vous pouvez définir count sur 100 et offset sur 0 et soumettre la requête.

   GET {url}/v1/environments/{environment_id}/collections/{collection_id}/query?q=&count=100&offset=0
   

   Ensuite, vous pouvez à nouveau définir le nombre sur 100, mais cette fois, définissez le décalage sur 100 pour obtenir les 100 documents suivants.

   GET {url}/v1/environments/{environment_id}/collections/{collection_id}/query?q=&count=100&offset=100`
   

   Répétez ce processus en incrémentant le décalage de 100 jusqu'à ce que vous extrayez tous les documents.

3. Préparez les documents exportés à ingérer dans v2.

   Chaque fichier JSON obtenu à partir de Discovery v1 contient des données extraites du document d'origine, telles que du texte, du code HTML et d'autres zones. Si des métadonnées personnalisées ont été associées au document lors de son téléchargement vers v1, elles sont également présentes dans le fichier JSON. En outre, le fichier contient plusieurs zones qui ont été générées par l'analyse v1. Conservez uniquement un sous-ensemble de ces données dans le cadre du document que vous ajoutez à Discovery v2.

   Les conseils suivants peuvent vous aider à déterminer les zones à conserver:

   • Incluez la zone text ou toute autre zone avec du contenu textuel que vous souhaitez pouvoir enrichir ou rechercher dans Discovery v2.
   • Incluez les métadonnées personnalisées stockées dans le document. Ces métadonnées sont généralement spécifiques à l'application qui utilise Discovery et qui est utilisée pour filtrer les documents dans une recherche. Par exemple, metadata.customer_id.
   • N'incluez pas les enrichissements de Discovery v1. Par exemple, enriched_text.entities. Discovery v2 génère ses propres enrichissements.
   • Excluez les zones générées par Discovery sauf si elles sont utilisées par votre application et qu'elles contiennent des informations spécifiques à la version v1 du document. Dans ce cas, renommez la zone pour qu'elle ne soit pas remplacée lorsque le document est ingéré dans Discovery v2. Par exemple, extracted_metadata.publicationdate est une zone qui est générée par Discovery lorsqu'un document est ingéré. Vous souhaitez peut-être conserver les informations metadata.parent_document_id de v1 pour comprendre comment les sous-documents ont été générés à l'origine à partir d'un seul document source.
   • Evitez les zones dont les noms sont réservés. Pour plus d'informations, voir Comment les zones sont traitées.

4. Ingérez chaque document JSON v1 édité dans l'instance Discovery v2. L'ID document Discovery v1 peut être conservé dans Discovery v2. Pour plus d'informations sur la conservation de l'ID document, voir Conservation des ID document.

Récupération de plus de 10 000 documents à partir d'une collection

Une requête ne peut renvoyer que jusqu'à 10 000 documents. Toutefois, si vous souhaitez récupérer plus de 10 000 documents à partir de votre collection, vous avez besoin d'un moyen de séparer les documents en sous-groupes qui ne se chevauchent pas. Chaque sous-groupe doit contenir moins de 10 000 documents pouvant être renvoyés par une requête. Ensuite, vous pouvez mettre en page les résultats pour extraire les documents.

La pagination des résultats est limitée à un maximum de 10 000 documents renvoyés par la requête. En particulier, l'utilisation combinée des paramètres de pagination count et offset ne peut pas dépasser 10 000 documents.

Une façon de séparer les documents en sous-groupes qui ne se chevauchent pas consiste à optimiser un champ qui existe dans chaque document et qui contient une valeur unique. Par exemple, la zone SHA-1 contient un hachage du fichier source d'origine et est formatée en tant que valeur de chaîne hexadécimale. Vous pouvez utiliser le premier caractère de la zone pour diviser la collection en sous-groupes. Etant donné que SHA-1 contient une valeur hexadécimale, le premier caractère peut avoir jusqu'à 16 valeurs possibles (0-9 ou a-f). Si vous effectuez un filtrage par first_char_of (SHA-1) == 0, il peut renvoyer environ 1/16 de l'ensemble de la collection. Vous pouvez ensuite parcourir en boucle chacune des 16 valeurs possibles pour obtenir le reste des documents. Si le nombre optimal de documents n'est pas renvoyé dans l'un des sous-groupes, vous pouvez utiliser les 2 premiers caractères de la zone SHA-1 pour diviser la collection en 256 sous-groupes à la place.

Mise à jour de la façon dont votre application gère les résultats de requête

La façon dont votre application affiche les résultats de requête peut nécessiter une mise à jour en raison des différences suivantes entre la syntaxe du document de résultats de requête entre les requêtes v1 et v2:

• Au niveau de l'enrichissement d'entité, les informations suivantes ne sont pas prises en charge dans v2:

  • Désambigüisation
  • Emotion
  • Sentiment

  L'enrichissement Part of Speech est appliqué automatiquement aux documents de la plupart des types de projet dans v2, mais les zones d'index générées par l'enrichissement ne sont pas affichées dans la représentation JSON du document.

  {: caption="

• A la place de count et relevance dans v1, v2 inclut les mentions.

  Chaque entrée de la mention correspond à une occurrence de l'entité dans le texte du document. Dans l'exemple suivant, sept occurrences sont trouvées. Pour chaque occurrence, une cote de confiance et les décalages du texte de la mention sont affichés. Vous pouvez utiliser les décalages pour mettre en évidence la mention dans le texte du document lorsque le résultat est affiché dans une interface utilisateur.

  

• La structure JSON des réponses de requête est légèrement réorganisée dans v2.

• Les informations de dédoublonnage ne sont pas incluses dans la réponse à la requête v2.

• Dans v2, enriched_text est un tableau à la place d'un objet.

• Dans Discovery v2, l'enrichissement Entities v2 est utilisé. Les noms de type d'entité dans v2 sont spécifiés en majuscules et non en majuscules. Si vous utilisez une requête ou une agrégation qui spécifie un nom d'entité, vous devez modifier la casse. Par exemple, remplacez PERSON par Person.

• Les zones des fichiers JSON qui sont ajoutés à une collection sont converties différemment lors de l'ingestion entre v1 et v2. Si votre application manipule ces résultats, vous devrez peut-être effectuer des ajustements.

  Vous pouvez spécifier les objets normalizations et conversions dans la méthode Update a collection de l'API pour déplacer ou fusionner des zones JSON.

  Comment les zones source JSON sont traitées

  Contenu de la zone JSON d'origine	Représentation v1	Représentation v2	Remarques
  "field": null	"field": null	N/A	v1 conserve la valeur null. v2 ignore complètement la zone null.
  "field": ""	"field": ""	N/A	v1 conserve la valeur de texte vide. v2 ignore complètement la zone de texte vide.
  "field": "value2"	"field": "value2"	"field": "value2"	Pas de différence.
  "field": []	"field": []	N/A	v1 conserve le tableau vide. v2 ignore la zone avec le tableau vide.
  "field": [ "value4" ]	"field": [ "value4" ]	"field": "value4"	v1 conserve le tableau de singleton. v2 convertit le tableau singleton en valeur uniquement ; il n'est pas stocké dans un tableau.
  "field": [ 1, 2, 3 ]	"field": [ 1, 2, 3 ]	"field": [ 1, 2, 3 ]	Pas de différence.
  "field": [ "v6", "v7", "v8" ]	"field": [ "v6", "v7", "v8"]	"field": [ "v6", "v7", "v8"]	Pas de différence.