Dans la Recherche Azure AI, un magasin de vecteurs a un schéma d’index qui définit des champs vectoriels et non vectoriels, une configuration vectorielle pour les algorithmes qui créent l’espace d’incorporation et les paramètres sur les définitions de champ vectoriel utilisées dans les requêtes de requête. L’API Créer ou mettre à jour un index crée le magasin de vecteurs.
Procédez comme suit pour indexer les données vectorielles :
Définir un schéma avec des algorithmes vectoriels pour l’indexation et la recherche
Cet article explique le flux de travail et utilise REST pour illustrer chaque étape. Chaque version récente de l’API REST ajoute de nouvelles fonctionnalités. Une fois que vous avez compris le flux de travail de base et ce que chaque version de l’API fournit, poursuivez avec les exemples de code du kit de développement logiciel (SDK) Azure dans le référentiel azure-search-vector-samples pour obtenir des conseils sur l’utilisation de ces fonctionnalités dans le code de test et de production.
La Recherche Azure AI, dans n’importe quelle région et sur n’importe quel niveau. La plupart des services existants prennent en charge la recherche vectorielle. Pour les services créés avant janvier 2019, il existe un petit sous-ensemble qui ne peut pas créer d’index vectoriel. Dans ce cas, un nouveau service doit être créé.
Les incorporations de vecteurs préexistantes dans vos documents sources si vous utilisez la version en disponibilité générale des kits SDK Azure et des API REST. Pour plus d’informations, consultez Générer une implémentation. Une alternative est la vectorisation intégrée (préversion).
Vous devez connaître la limite des dimensions du modèle utilisé pour créer les incorporations et la façon dont la similarité est calculée. Dans Azure OpenAI, pour text-embedding-ada-002, la longueur du vecteur numérique est 1536. La similarité est calculée en utilisant cosine. Les valeurs valides sont comprises entre 2 et 3 072 dimensions.
Vous devez être familiarisé avec la création d'un index. Le schéma doit inclure un champ pour la clé de document, d’autres champs que vous souhaitez rechercher ou filtrer, ainsi que d’autres configurations pour les comportements nécessaires lors de l’indexation et des requêtes.
Préparer des documents pour l’indexation
Avant l’indexation, vous devez assembler un document qui comprend des champs de données vectorielles et non vectorielles. La structure du document doit être conforme au schéma de l'index.
Vérifiez que vos documents sont les suivants :
Fournissez un champ ou une propriété de métadonnées qui identifie de manière unique chaque document. Tous les index de recherche nécessitent une clé de document. Pour répondre aux exigences de clé de document, un document source doit avoir un champ ou une propriété qui peut l’identifier de manière unique dans l’index. Ce champ source doit être mappé à un champ d’index de type Edm.String et key=true dans l’index de recherche.
Fournir des données vectorielles (un tableau de nombres à virgule flottante en simple précision) dans les champs source.
Les champs vectoriels contiennent des données numériques générées par des modèles incorporés, une incorporation par champ. Nous recommandons les modèles d'intégration dans Azure OpenAI, tels que text-embedding-ada-002 pour les documents textuels ou l’API REST Recherche d'images pour les images. Seuls les champs vectoriels de niveau supérieur d’index sont pris en charge : les sous-champs vectoriels ne sont actuellement pas pris en charge.
Fournissez d’autres champs avec du contenu alphanumérique lisible par l’homme pour la réponse à la requête et pour les scénarios de requête hybrides qui incluent la recherche en texte intégral ou le classement sémantique dans la même requête.
Votre index de recherche doit inclure des champs et du contenu pour tous les scénarios de requête que vous souhaitez prendre en charge. Supposons que vous souhaitez rechercher ou filtrer les noms de produits, les versions, les métadonnées ou les adresses. Dans ce cas, la recherche de similarité n’est pas particulièrement utile. La recherche par mot clé, la recherche géographique ou les filtres seraient un meilleur choix. Un index de recherche qui comprend une collection complète de données vectorielles et non vectorielles offre une flexibilité maximale pour la construction des requêtes et la composition de la réponse.
Un bref exemple d’une charge utile de documents qui comprend des champs vectoriels et non vectoriels est présenté dans la section charge des données vectorielles de cet article.
Ajouter une configuration de recherche vectorielle
Une configuration vectorielle spécifie l'algorithme de recherche vectorielle et les paramètres utilisés lors de l'indexation pour créer les informations sur les "voisins les plus proches" parmi les nœuds du vecteur :
Hierarchical Navigable Small Worlds (HNSW)
Exhaustive KNN
Si vous choisissez HNSW sur un champ, vous pouvez opter pour un KNN exhaustif au moment de la requête. Mais l’autre direction ne fonctionne pas : si vous choisissez exhaustive, vous ne pouvez pas demander ultérieurement la recherche HNSW, car les structures de données supplémentaires qui activent la recherche approximative n’existent pas.
Vous cherchez de l’aide pour migrer de la préversion vers la version stable ? Pour les étapes à suivre, consultez Mettre à niveau les API REST.
Nom de la configuration. Le nom doit être unique dans l'index.
profiles ajouter une couche d’abstraction pour accueillir des définitions plus riches. Un profil est défini dans vectorSearch, puis référencé par nom sur chaque champ vectoriel.
"hnsw" et "exhaustiveKnn" sont les algorithmes de voisins les plus proches (ANN) approximatifs utilisés pour organiser le contenu vectoriel pendant l’indexation.
"m" (nombre de liens bidirectionnels) par défaut est 4. La fourchette est comprise entre 4 et 10. Les valeurs inférieures doivent retourner moins de bruit dans les résultats.
"efConstruction" la valeur par défaut est 400. La plage est comprise entre 100 et 1,000. Il s’agit du nombre de voisins les plus proches utilisés lors de l’indexation.
"efSearch" la valeur par défaut est 500. La plage est comprise entre 100 et 1,000. C'est le nombre de voisins les plus proches utilisés lors de la recherche.
"metric" doit être « cosinus » si vous utilisez Azure OpenAI, sinon utilisez la métrique de similarité associée au modèle d’incorporation que vous utilisez. Les valeurs prises en charge sont les suivantes : cosine, dotProduct, euclidean.
2024-05-01-Preview est la version la plus récente. Elle ajoute d’autres options d’encodage, mais la configuration de recherche vectorielle (structure vectorSearch) est quasiment identique à la version 2024-03-01-preview.
Développe la vectorisation intégrée avec des choix de modèle d’incorporation supplémentaires. Pour tirer parti de cette fonctionnalité, vous devez opter pour une dépendance sur un indexeur et un ensemble de compétences. Pour obtenir la liste des nouvelles compétences d’incorporation, consultez Charger des données vectorielles et la section API de tirage (pull).
Ajoutez une section vectorSearch dans l’index pour spécifie les paramètres de compression et les algorithmes de recherche utilisés pour créer l’espace d’incorporation. Pour plus d’informations, consultez Configurer la quantification vectorielle et le stockage réduit.
vectorSearch.compressions.kind doit être scalarQuantization.
rerankWithOriginalVectors utilise les vecteurs originaux non compressés pour recalculer la similarité et reclasser les meilleurs résultats renvoyés par la requête de recherche initiale. Les vecteurs non compressés existent dans l'index de recherche même si stored sont faux. Cette propriété est facultative. La valeur par défaut est true.
defaultOversampling considère un ensemble plus large de résultats potentiels pour compenser la réduction des informations résultant de la quantification. La formule des résultats potentiels consiste en le k dans la requête, avec un multiplicateur de suréchantillonnage. Par exemple, si la requête spécifie un k de 5 et que le suréchantillonnage est de 20, alors la requête demande effectivement 100 documents à utiliser dans le reclassement, en utilisant le vecteur non compressé d'origine à cette fin. Seuls les résultats k les mieux classés sont renvoyés. Cette propriété est facultative. La valeur par défaut est 4.
quantizedDataType doit être défini sur int8. Il s’agit du seul type de données primitif pris en charge pour le moment. Cette propriété est facultative. La valeur par défaut est int8.
2023-10-01-Preview ajoute la vectorisation interne, mais la configuration de recherche vectorielle (structure vectorSearch) est quasiment identique à la version 2023-11-01.
Nom de la configuration. Le nom doit être unique dans l'index.
profiles sont nouveaux dans cette préversion. Ils ajoutent une couche d'abstraction permettant d'intégrer des définitions plus riches. Un profil est défini dans vectorSearch, puis comme une propriété de chaque champ de vecteurs.
hnsw et "exhaustiveKnn" sont les algorithmes de voisins les plus proches (ANN) approximatifs utilisés pour organiser le contenu vectoriel pendant l’indexation.
m (nombre de liens bidirectionnels) par défaut est 4. La fourchette est comprise entre 4 et 10. Les valeurs inférieures doivent retourner moins de bruit dans les résultats.
efConstruction la valeur par défaut est 400. La plage est comprise entre 100 et 1,000. Il s’agit du nombre de voisins les plus proches utilisés lors de l’indexation.
efSearch la valeur par défaut est 500. La plage est comprise entre 100 et 1,000. C'est le nombre de voisins les plus proches utilisés lors de la recherche.
metric doit être « cosinus » si vous utilisez Azure OpenAI, sinon utilisez la métrique de similarité associée au modèle d’incorporation que vous utilisez. Les valeurs prises en charge sont les suivantes : cosine, dotProduct, euclidean.
Important
2023-07-01-Preview était la première version de l’API REST à prendre en charge les vecteurs. Elle utilise des structures obsolètes qui ont été remplacées dans des préversions plus récentes. Nous vous recommandons de migrer vers une API REST plus récente.
Cette préversion a ajouté :
vectorSearch.algorithmConfigurations pour spécifier l’algorithme HNSW.
L’algorithme du plus proche voisin hnsw pour l’indexation du contenu vectoriel.
Nom de la configuration. Le nom doit être unique dans l'index.
hnsw est l’algorithme de proximité des voisins les plus proches (ANN) utilisé pour créer le graphique de proximité pendant l’indexation. Seul l’HNSW (Hierarchical Navigable Small World) est pris en charge dans cette version de l’API.
m (nombre de liens bidirectionnels) par défaut est 4. La fourchette est comprise entre 4 et 10. Les valeurs inférieures doivent retourner moins de bruit dans les résultats.
efConstruction la valeur par défaut est 400. La plage est comprise entre 100 et 1,000. Il s’agit du nombre de voisins les plus proches utilisés lors de l’indexation.
efSearch la valeur par défaut est 500. La plage est comprise entre 100 et 1,000. C'est le nombre de voisins les plus proches utilisés lors de la recherche.
metric doit être « cosinus » si vous utilisez Azure OpenAI, sinon utilisez la métrique de similarité associée au modèle d’incorporation que vous utilisez. Les valeurs prises en charge sont les suivantes : cosine, dotProduct, euclidean.
Ajouter un champ vectoriel à la collection de champs
La collection de champs doit inclure un champ pour la clé de document, les champs vectoriels et tous les autres champs dont vous avez besoin pour les scénarios de recherche hybride.
Les champs vectoriels sont caractérisés par leur type de données, une propriété dimensions basée sur le modèle d’incorporation utilisé pour générer les vecteurs et un profil vectoriel.
Définissez un champ vectoriel avec les attributs suivants. Vous pouvez stocker un incorporation généré par champ. Pour chaque champ vectoriel :
type doit être Collection(Edm.Single) dans cette version de l’API.
dimensions retourne le nombre de dimensions dans le modèle d’incorporation. Pour text-embedding-ada-002, c'est 1536.
vectorSearchProfile est le nom d’un profil défini ailleurs dans l’index.
searchable doit être true.
retrievable peut avoir la valeur « true » ou « false ». True retourne les vecteurs bruts (1536 d’entre eux) sous forme de texte brut et consomme de l’espace de stockage. Définissez la valeur true si vous transmettez un résultat vectoriel à une application en aval.
Ajoutez d’autres champs qui définissent la substance et la structure du contenu textuel que vous indexez. Au minimum, vous avez besoin d'une clé de document.
Vous devez également ajouter des champs utiles à la requête ou à la réponse. L’exemple suivant montre des champs vectoriels pour le titre et le contenu (« titleVector », « contentVector ») équivalents aux vecteurs. Il fournit également des champs pour le contenu textuel équivalent (« titre », « contenu ») utile pour le tri, le filtrage et la lecture dans un résultat de recherche.
L'exemple suivant montre la collection de champs :
Ajouter des champs vectoriels à la collection de champs. Vous pouvez enregistrer un encart généré par champ de document. Pour chaque champ vectoriel :
type peut être Collection(Edm.Single), Collection(Edm.Half), Collection(Edm.Int16), Collection(Edm.SByte)
dimensions retourne le nombre de dimensions dans le modèle d’incorporation. Pour text-embedding-ada-002, c'est 1536.
vectorSearchProfile est le nom d’un profil défini ailleurs dans l’index.
searchable doit être true.
retrievable peut avoir la valeur « true » ou « false ». True retourne les vecteurs bruts (1536 d’entre eux) sous forme de texte brut et consomme de l’espace de stockage. Définissez la valeur true si vous transmettez un résultat vectoriel à une application en aval. False est obligatoire si stored est false.
stored est une nouvelle propriété booléenne qui s’applique uniquement aux champs vectoriels. La valeur True indique qu’une copie de vecteurs retournés dans les résultats de recherche est stockée. La valeur False indique que cette copie est ignorée pendant l’indexation. Vous pouvez rechercher sur des vecteurs, mais ne pouvez pas retourner de vecteurs dans les résultats.
filterable, facetable, sortable doit être false.
L'exemple suivant montre la collection de champs :
Dans l’exemple d’API REST suivant, « titre » et « contenu » contiennent du contenu textuel utilisé dans la recherche en texte intégral et le classement sémantique, tandis que « titleVector » et « contentVector » contiennent des données vectorielles. Dans cette version de l’API, vous pouvez utiliser des indexeurs et un ensemble de compétences pour remplir le champ vectoriel à l’aide de la vectorisation intégrée. La définition d’index ne change pas, mais vous pouvez ajouter des indexeurs et des compétences à votre solution pour remplir les champs.
Ajouter des champs vectoriels à la collection de champs. Vous pouvez enregistrer un encart généré par champ de document. Pour chaque champ vectoriel :
type doit être Collection(Edm.Single).
dimensions retourne le nombre de dimensions dans le modèle d’incorporation. Pour text-embedding-ada-002, c'est 1536.
vectorSearchProfile est le nom d’un profil défini ailleurs dans l’index.
searchable doit être true.
retrievable peut avoir la valeur « true » ou « false ». True retourne les vecteurs bruts (1536 d’entre eux) sous forme de texte brut et consomme de l’espace de stockage. Définissez la valeur true si vous transmettez un résultat vectoriel à une application en aval.
filterable, facetable, sortable doit être false.
Si vous souhaitez appeler le préfiltrage ou le postfiltrage sur [vector query](vector-search-how-to-query.md), ajoutez des champs non vectoriels filtrables à la collection, tels que "« titre » avec filterable défini sur true
Ajoutez d’autres champs qui définissent la substance et la structure du contenu textuel que vous indexez. Au minimum, vous avez besoin d'une clé de document.
Vous devez également ajouter des champs utiles à la requête ou à la réponse. L’exemple suivant montre des champs vectoriels pour le titre et le contenu (« titleVector », « contentVector ») équivalents aux vecteurs. Il fournit également des champs pour le contenu textuel équivalent (« titre », « contenu ») utile pour le tri, le filtrage et la lecture dans un résultat de recherche.
L'exemple suivant montre la collection de champs :
Les définitions de champ vectoriel pour cette version sont obsolètes dans les versions ultérieures. Nous vous recommandons de migrer vers une API REST plus récente.
2023-07-01-Preview était la première version de l’API REST à prendre en charge les scénarios vectoriels.
Dans l’exemple d’API REST suivant, « title » et « content » contiennent du contenu textuel utilisé dans la recherche en texte intégral et le classement sémantique, tandis que « titleVector » et « contentVector » contiennent des données vectorielles générées en externe.
Ajouter des champs vectoriels à la collection de champs. Vous pouvez enregistrer un encart généré par champ de document. Pour chaque champ vectoriel :
Attribuer le type de données Collection(Edm.Single).
Indiquez le nom de la configuration de l’algorithme de recherche vectorielle.
Indiquer le nombre de dimensions générées par le modèle d'intégration.
Définir des attributs :
« pouvant faire l’objet d’une recherche » doit être « true ».
« récupérable » défini sur « true » vous permet d’afficher les vecteurs bruts (par exemple, en tant qu’étape de vérification), mais cela augmente le stockage. Définissez la valeur « false » si vous n’avez pas besoin de retourner des vecteurs bruts. Vous n'avez pas besoin de renvoyer des vecteurs pour une requête, mais si vous transmettez un résultat vectoriel à une application en aval, mettez « pouvant faire l’objet d’une recherche » sur « true ».
Les attributs « filtrable », « table à facettes » et « triable » doivent être « false ». Ne définissez pas ces comportements sur « true », car ces comportements ne s’appliquent pas dans le contexte des champs vectoriels et la requête échoue.
Ajoutez d’autres champs qui définissent la substance et la structure du contenu textuel que vous indexez. Au minimum, vous avez besoin d'une clé de document.
Vous devez également ajouter des champs utiles à la requête ou à la réponse. L’exemple suivant montre des champs vectoriels pour le titre et le contenu (« titleVector », « contentVector ») équivalents aux vecteurs. Il fournit également des champs pour le contenu textuel équivalent (« titre », « contenu ») utile pour le tri, le filtrage et la lecture dans un résultat de recherche.
Une définition d’index avec les éléments décrits ressemble à ceci :
Charger des données vectorielles pour l’indexation
Le contenu que vous fournissez pour l'indexation doit être conforme au schéma de l'index et inclure une chaîne de valeur unique pour la clé du document. Les données prévectorisées sont chargées dans un ou plusieurs champs vectoriels, qui peuvent coexister avec d’autres champs contenant du contenu alphanumérique.
Utilisez Documents – Index pour charger des données vectorielles et non vectorielles dans un index. Les API d’envoi (push) pour l’indexation sont identiques dans toutes les versions stables et préliminaires. Utilisez l’une des API suivantes pour charger des documents :
POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/index?api-version=2023-11-01
Content-Type: application/json
api-key: {{admin-api-key}}
{
"value": [
{
"id": "1",
"title": "Azure App Service",
"content": "Azure App Service is a fully managed platform for building, deploying, and scaling web apps. You can host web apps, mobile app backends, and RESTful APIs. It supports a variety of programming languages and frameworks, such as .NET, Java, Node.js, Python, and PHP. The service offers built-in auto-scaling and load balancing capabilities. It also provides integration with other Azure services, such as Azure DevOps, GitHub, and Bitbucket.",
"category": "Web",
"titleVector": [
-0.02250031754374504,
. . .
],
"contentVector": [
-0.024740582332015038,
. . .
],
"@search.action": "upload"
},
{
"id": "2",
"title": "Azure Functions",
"content": "Azure Functions is a serverless compute service that enables you to run code on-demand without having to manage infrastructure. It allows you to build and deploy event-driven applications that automatically scale with your workload. Functions support various languages, including C#, F#, Node.js, Python, and Java. It offers a variety of triggers and bindings to integrate with other Azure services and external services. You only pay for the compute time you consume.",
"category": "Compute",
"titleVector": [
-0.020159931853413582,
. . .
],
"contentVector": [
-0.02780858241021633,
. . .
],
"@search.action": "upload"
}
. . .
]
}
Toutes les versions préliminaires les plus récentes utilisent des API de tirage (pull) (indexeurs et ensembles de compétences) pour la vectorisation intégrée pendant l’indexation et au moment de la requête.
Les indexeurs peuvent récupérer et indexer des champs vectoriels dans des documents sources, en supposant qu’un schéma d’index répond aux exigences de champ vectoriel et à l’API REST en préversion. Les sources de données fournissent les vecteurs au format pris en charge par la source de données (comme les chaînes au format JSON). L’indexeur suppose que les champs tapés comme Collection(Edm.Single) contiennent des vecteurs et indexent ce contenu en tant qu’index vectoriels.
Aucune modification du comportement de mappage de champ ou de la détection des modifications pour les vecteurs. Les comportements d’indexation de texte s’appliquent également aux vecteurs.
Si les données vectorielles sont sources dans des fichiers, nous recommandons une parsingMode non définie comme json, jsonLinesou csv en fonction de la forme des données.
Azure SQL ne permet pas de stocker une collection en mode natif en tant que colonne SQL unique. Une solution de contournement n’a pas été identifiée pour l’instant.
Les dimensions de tous les vecteurs de la source de données doivent être identiques et correspondre à leur définition d’index pour le champ auquel ils sont mappés. L’indexeur lève une erreur sur tous les documents qui ne correspondent pas.
Les compétences et les vectoriseurs sont utilisés pour générer des incorporations. Pour la vectorisation pendant l’indexation, choisissez parmi les compétences suivantes :
À des fins de validation, vous pouvez interroger l’index à l’aide de l’Explorateur de recherche dans le Portail Azure ou d’un appel d’API REST. Étant donné qu’Azure AI Search ne peut pas convertir un vecteur en texte lisible par l’homme, essayez de renvoyer des champs du même document qui fournissent des preuves de la correspondance. Par exemple, si la requête vectorielle cible le champ « titleVector », vous pouvez sélectionner « titre » pour les résultats de la recherche.
Les champs doivent être attribués comme « récupérables » pour être inclus dans les résultats.
Utilisez la vue Requête par défaut pour une confirmation rapide que l’index contient des vecteurs. L’affichage de requête est destiné à la recherche en texte intégral. Bien que vous ne puissiez pas l’utiliser pour les requêtes vectorielles, vous pouvez envoyer une recherche vide (search=*) pour rechercher du contenu. Le contenu de tous les champs, y compris les champs vectoriels, est retourné sous forme de texte brut.
L’exemple d’API REST suivant est une requête vectorielle, mais il ne renvoie que des champs non vectoriels (titre, contenu, catégorie). Seuls les champs marqués comme « récupérables » peuvent être renvoyés dans les résultats de la recherche.
Pour mettre à jour un magasin vectoriel, modifiez le schéma et, si nécessaire, rechargez les documents pour remplir de nouveaux champs. Les API pour les mises à jour de schéma incluent Create or Update Index (REST), CreateOrUpdateIndex dans le SDK Azure pour .NET, create_or_update_index dans le SDK Azure pour Python et des méthodes similaires dans d’autres SDK Azure.
La suppression et la régénération sont souvent requises pour les mises à jour et la suppression de champs existants.
Toutefois, vous pouvez mettre à jour un schéma existant avec les modifications suivantes, sans aucune régénération requise :
Ajouter de nouveaux champs à une collection de champs.
Ajouter de nouvelles configurations vectorielles (affectées à de nouveaux champs, mais pas à des champs existants déjà vectorisés).
Modifier « retrievable » (les valeurs sont true ou false) sur un champ existant. Les champs vectoriels doivent pouvoir faire l’objet d’une recherche et être récupérables. Toutefois, si vous souhaitez désactiver l’accès à un champ vectoriel dans des situations où la suppression et la régénération ne sont pas réalisables, vous pouvez définir retrievable sur false.
Les exemples de code du dépôt azure-search-vector illustrent des workflows de bout en bout qui incluent la définition de schéma, la vectorisation, l’indexation et les requêtes.
Prochainement : Tout au long de l'année 2024, nous supprimerons progressivement les GitHub Issues en tant que mécanisme de retour d'information pour le contenu et nous les remplacerons par un nouveau système de retour d'information. Pour plus d’informations, voir: https://aka.ms/ContentUserFeedback.