Configurer la vectorisation intégrée dans Recherche Azure AI à l’aide de REST

Dans cet article, vous allez apprendre à utiliser un ensemble de compétences pour segmenter et vectoriser du contenu à partir d’une source de données prise en charge. L’ensemble de compétences appelle la compétence Fractionnement de texte ou la compétence Disposition de document pour la segmentation et une compétence d’incorporation attachée à un modèle d’incorporation pris en charge pour la vectorisation de segment. Vous allez également apprendre à stocker le contenu segmenté et vectorisé dans un index vectoriel.

Cet article décrit le flux de travail de bout en bout pour la vectorisation intégrée à l’aide de REST. Pour obtenir des instructions basées sur le portail, consultez Quickstart : Vectoriser du texte et des images dans le portail Azure.

Conditions préalables

• Un compte Azure avec un abonnement actif. Créez gratuitement un compte.

• Un service Recherche Azure AI. Nous vous recommandons le niveau De base ou supérieur.

• Source de données prise en charge.

• Modèle d’intégration pris en charge.

• Achèvement de Démarrage rapide : Se connecter sans clés et Configurer une identité managée affectée par le système. Bien que vous puissiez utiliser l’authentification basée sur des clés pour les opérations de plan de données, cet article part du principe que les rôles et les identités managées sont plus sécurisés.

• Visual Studio Code avec l’extension client REST.

Sources de données prises en charge

La vectorisation intégrée fonctionne avec toutes les sources de données prises en charge. Toutefois, cet article se concentre sur les sources de données les plus couramment utilisées, qui sont décrites dans le tableau suivant.

Source de données	Description
Stockage Blob Azure	Cette source de données fonctionne avec des objets blob et des tables. Vous devez utiliser un compte de performances standard (v2 universel). Les niveaux d’accès peuvent être chauds, tempérés ou froids.
Azure Data Lake Storage (ADLS) Gen2	Il s’agit d’un compte stockage Azure avec un espace de noms hiérarchique activé. Pour confirmer que vous avez Data Lake Storage, cochez l’onglet Properties de la page Overview.
Microsoft OneLake	Cette source de données se connecte aux fichiers et raccourcis OneLake.

Modèles d’incorporation pris en charge

Utilisez l’un des modèles d’incorporation suivants pour la vectorisation intégrée. Les instructions de déploiement sont fournies dans une section ultérieure.

¹ Le point de terminaison de votre ressource OpenAI Azure doit avoir un sous-domaine custome, tel que https://my-unique-name.openai.azure.com. Si vous avez créé votre ressource dans le portail Azure, ce sous-domaine a été généré automatiquement lors de l’installation de la ressource.

² Azure ressources OpenAI (avec accès aux modèles incorporés) créées dans le portail Microsoft Foundry ne sont pas prises en charge. Vous devez créer une ressource OpenAI Azure dans le portail Azure.

³ À des fins de facturation, vous devez tachez votre ressource Microsoft Foundry à votre ensemble de compétences Recherche Azure AI. Sauf si vous utilisez une connexion sans clé pour créer l’ensemble de compétences, les deux ressources doivent se trouver dans la même région.

⁴ Le modèle d’incorporation modal Azure Vision est disponible dans certaines régions.

Accès en fonction du rôle

Vous pouvez utiliser Microsoft Entra ID avec des attributions de rôles ou une authentification basée sur des clés avec des chaînes de connexion à accès total. Pour les connexions d'Recherche Azure AI à d’autres ressources, nous vous recommandons d’attribuer des rôles.

Pour configurer l’accès en fonction du rôle pour la vectorisation intégrée :

1. Sur votre service de recherche, activez les rôles et configurez une identité managée affectée par le système.

2. Sur votre plateforme de source de données et votre fournisseur de modèles d’incorporation, créez des attributions de rôles qui permettent à votre service de recherche d’accéder aux données et aux modèles. Consultez Préparer vos données et préparer votre modèle d’incorporation.

Obtenir des informations de connexion pour Recherche Azure AI

Dans cette section, vous récupérez le point de terminaison et le jeton Microsoft Entra pour votre service Recherche Azure AI. Les deux valeurs sont nécessaires pour établir des connexions pour les demandes REST.

1. Accédez à votre service de recherche dans le portail Azure.

2. Pour obtenir votre point de terminaison de recherche, copiez l’URL dans la page Vue d’ensemble . Un exemple de point de terminaison de recherche est https://my-service.search.windows.net.

3. Pour obtenir votre jeton Microsoft Entra, exécutez la commande suivante sur votre système local. Cette étape nécessite l’achèvement du démarrage rapide : Se connecter sans clés.

   az account get-access-token --scope https://search.azure.com/.default --query accessToken --output tsv
   

Préparer vos données

Dans cette section, vous préparez vos données pour la vectorisation intégrée en chargeant des fichiers dans une source de données prise en charge, en affectant des rôles et en obtenant des informations de connexion.

Préparer votre modèle d’incorporation

Dans cette section, vous préparez votre ressource IA Azure pour la vectorisation intégrée en affectant des rôles, en obtenant un point de terminaison et en déployant un modèle d’incorporation pris en charge.

Définir des variables

Dans cette section, vous spécifiez les informations de connexion de votre service Recherche Azure AI, votre source de données prise en charge et votre modèle d’incorporation supporté.

1. Dans Visual Studio Code, collez les marqueurs de position suivants dans votre fichier .rest ou .http.

   @baseUrl = PUT-YOUR-SEARCH-SERVICE-URL-HERE
   @token = PUT-YOUR-MICROSOFT-ENTRA-TOKEN-HERE
   

2. Remplacez @baseUrl par le point de terminaison de recherche et @token par le jeton Microsoft Entra que vous avez obtenu dans Get des informations de connexion pour Recherche Azure AI.

3. Selon votre source de données, ajoutez les variables suivantes.

   Source de données	Variables	Entrez ces informations
   Service de stockage Blob Azure	@storageConnectionString et @blobContainer	Les chaîne de connexion et le nom du conteneur que vous avez créé dans Preparez vos données.
   ADLS Gen2	@storageConnectionString et @blobContainer	Les chaîne de connexion et le nom du conteneur que vous avez créé dans Preparez vos données.
   OneLake	@workspaceId et @lakehouseId	Espace de travail et identifiants de lakehouse que vous avez obtenus dans Préparer vos données.

4. En fonction de votre fournisseur de modèles d’incorporation, ajoutez les variables suivantes.

   Fournisseur de modèle d’incorporation	Variables	Entrez ces informations
   Azure OpenAI	@aoaiEndpoint, @aoaiDeploymentNameet @aoaiModelName	Le point de terminaison, le nom du déploiement et le nom du modèle que vous avez obtenus dans Préparer votre modèle d’incorporation.
   Azure Vision	@AiFoundryEndpoint	Point de terminaison que vous avez obtenu dans Préparer votre modèle d’incorporation.

5. Pour vérifier les variables, envoyez la requête suivante.

   ### List existing indexes by name
   GET {{baseUrl}}/indexes?api-version=2026-04-01  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{token}}
   

   Une réponse doit apparaître dans un volet adjacent. Si vous avez des index existants, ils sont répertoriés. Sinon, la liste est vide. Si le code HTTP est 200 OK, vous êtes prêt à continuer.

Se connecter à vos données

Dans cette section, vous vous connectez à une source de données prise en charge pour l’indexation basée sur l’indexeur. Un indexer dans Recherche Azure AI nécessite une source de données qui spécifie le type, les informations d’identification et le conteneur.

1. Utilisez Créer une source de données pour définir une source de données qui fournit des informations de connexion pendant l’indexation.

   ### Create a data source
   POST {{baseUrl}}/datasources?api-version=2026-04-01  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{token}}
   
     {
       "name": "my-data-source",
       "type": "azureblob",
       "subtype": null,
       "credentials": {
           "connectionString": "{{storageConnectionString}}"
       },
       "container": {
           "name": "{{blobContainer}}",
           "query": null
       },
       "dataChangeDetectionPolicy": null,
       "dataDeletionDetectionPolicy": null
     }
   

2. Défini type sur votre source de données : azureblob ou adlsgen2.

3. Pour créer la source de données, sélectionnez Envoyer une demande.

4. Si vous utilisez OneLake, définissez credentials.connectionString sur ResourceId={{workspaceId}} et container.name sur {{lakehouseId}}.

Créer un ensemble de compétences

Dans cette section, vous allez créer un ensemble de compétences qui appelle une compétence intégrée pour segmenter votre contenu et une compétence d’incorporation pour créer des représentations vectorielles des blocs. Les compétences sont utilisées pendant l’indexation dans une section ultérieure.

Appeler une compétence intégrée pour segmenter votre contenu

Le partitionnement de votre contenu en blocs vous permet de répondre aux exigences de votre modèle d’incorporation et d’empêcher la perte de données en raison de la troncation. Pour plus d’informations sur la segmentation, consultez Les documents volumineux segments pour les solutions de recherche vectorielle.

Pour la segmentation de données intégrée, Recherche Azure AI offre la compétence Text Split et Azure Compétence Content Understanding. La compétence Division de texte divise le texte en phrases ou en pages d’une longueur donnée, tandis que la compétence Azure Content Understanding effectue un découpage sémantique tenant compte de la mise en page et respectant les limites des paragraphes.

1. Utilisez Create Skillset pour définir un ensemble de compétences.

   ### Create a skillset
   POST {{baseUrl}}/skillsets?api-version=2026-04-01  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{token}}
   
     {
       "name": "my-skillset",
       "skills": []
     }
   

2. Dans le tableau skills, appelez la compétence Text Split ou la compétence Azure Content Understanding. Vous pouvez coller l’une des définitions suivantes.

       "skills": [
        {
          "@odata.type": "#Microsoft.Skills.Text.SplitSkill",
          "name": "my-text-split-skill",
          "textSplitMode": "pages",
          "maximumPageLength": 2000,
          "pageOverlapLength": 500,
          "maximumPagesToTake": 0,
          "unit": "characters",
          "defaultLanguageCode": "en",
          "inputs": [
           {
             "name": "text",
             "source": "/document/text",
             "inputs": []
           }
          ],
          "outputs": [
           {
             "name": "textItems"
           }
          ]
        },
        {
          "@odata.type": "#Microsoft.Skills.Util.ContentUnderstandingSkill",
          "name": "my-content-understanding-skill",
          "context": "/document",
          "chunkingProperties": {
            "method": "semantic",
            "unit": "tokens",
            "maximumLength": 500
          },
          "inputs": [
           {
             "name": "file_data",
             "source": "/document/file_data"
           }
          ],
          "outputs": [
           {
             "name": "text_sections",
             "targetName": "text_sections"
           }
          ]
        }
       ]
   

Appeler une compétence d’incorporation pour vectoriser les blocs

Pour vectoriser votre contenu segmenté, l’ensemble de compétences a besoin d’une compétence d’incorporation qui pointe vers un modèle d’incorporation pris en charge.

1. Après la compétence de fractionnement intégrée dans le tableau skills, appelez ensuite la compétence Azure OpenAI Embedding ou la compétence Azure Vision multimodal embeddings (préversion). Vous pouvez coller l’une des définitions suivantes.

        {
          "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
          "resourceUri": "{{aoaiEndpoint}}",
          "deploymentId": "{{aoaiDeploymentName}}",
          "modelName": "{{aoaiModelName}}",
          "dimensions": 1536,
          "inputs": [
            {
              "name": "text",
              "source": "/document/text"
            }
          ],
          "outputs": [
            {
              "name": "embedding"
            }
          ]
        },
        {
          "@odata.type": "#Microsoft.Skills.Vision.VectorizeSkill",
          "context": "/document",
          "modelVersion": "2023-04-15",
          "inputs": [
            {
              "name": "url",
              "source": "/document/metadata_storage_path"
            },
            {
              "name": "queryString",
              "source": "/document/metadata_storage_sas_token"
            }
          ],
          "outputs": [
            {
              "name": "vector"
            }
          ]
        }
   

   Note

   La compétence d'incorporation multimodale Azure Vision est en préversion. Si vous souhaitez appeler cette compétence, utilisez la dernière version de l’API en préversion.

2. Si vous utilisez la compétence d'Embedding Azure OpenAI, définissez dimensions sur le nombre d'intégrations générées par votre modèle d'intégration.

3. Si vous utilisez la compétence d’intégration multimodale Azure Vision, attachez votre ressource Microsoft Foundry après le tableau skills. Cette pièce jointe est à des fins de facturation.

       "skills": [ ... ],
       "cognitiveServices": {
         "@odata.type": "#Microsoft.Azure.Search.AIServicesByIdentity",
         "subdomainUrl": "{{AiFoundryEndpoint}}"
        }
   

4. Pour créer les compétences, sélectionnez Envoyer une demande.

Créer un index vectoriel

Dans cette section, vous allez configurer des structures de données physiques sur votre service Recherche Azure AI en créant un index vectoriel. Le schéma d’un index vectoriel nécessite les éléments suivants :

• Nom
• Champ clé (chaîne)
• Un ou plusieurs champs vectoriels
• Configuration vectorielle

Les champs vectoriels stockent des représentations numériques de vos données segmentées. Ils doivent être pouvant faire l’objet d’une recherche et être récupérables, mais ils ne peuvent pas être filtrables, facetables ou triables. Ils ne peuvent pas non plus avoir d’analyseurs, de normaliseurs ou d’affectations de mappage de synonymes.

En plus des champs vectoriels, l’exemple d’index des étapes suivantes contient des champs non vecteurs pour le contenu lisible par l’homme. Il est courant d’inclure des équivalents en texte brut du contenu que vous souhaitez vectoriser. Pour plus d’informations, consultez Créer un index vectoriel.

1. Utilisez Create Index pour définir le schéma d’un index vectoriel.

   ### Create a vector index
   POST {{baseUrl}}/indexes?api-version=2026-04-01  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{token}}
   
     {
       "name": "my-vector-index",
       "fields": [],
       "vectorSearch": []
     }
   

2. Ajoutez une configuration de recherche vectorielle à la vectorSearch section.

       "vectorSearch": {
         "algorithms": [
           {
             "name": "hnsw-algorithm",
             "kind": "hnsw",
             "hnswParameters": {
               "m": 4,
               "efConstruction": 400,
               "efSearch": 100,
               "metric": "cosine"
             }
           }
         ],
         "profiles": [
           {
             "name": "vector-profile-hnsw",
             "algorithm": "hnsw-algorithm",
           }
         ]
       }
   

   vectorSearch.algorithms spécifie l’algorithme utilisé pour l’indexation et l’interrogation des champs vectoriels, tandis que vectorSearch.profiles les liens entre la configuration de l’algorithme et un profil que vous pouvez affecter aux champs vectoriels.

3. Selon votre modèle d’incorporation, mettez à jour vectorSearch.algorithms.metric. Les valeurs valides pour les métriques de distance sont cosine, dotproduct, euclideanet hamming.

4. Ajoutez des champs aux fields tableaux. Incluez un champ clé pour l’identification de document, les champs non-vecteurs pour le contenu lisible par l’homme et les champs vectoriels pour les incorporations.

       "fields": [
         {
           "name": "id",
           "type": "Edm.String",
           "key": true,
           "filterable": true
         },
         {
           "name": "title",
           "type": "Edm.String",
            "searchable": true,
            "filterable": true,
            "sortable": true,
            "retrievable": true
         },
         {
           "name": "titleVector",
           "type": "Collection(Edm.Single)",
            "searchable": true,
            "retrievable": false,
            "stored": true,
            "dimensions": 1536,
            "vectorSearchProfile": "vector-profile-hnsw"
         },
         {
           "name": "content",
           "type": "Edm.String",
            "searchable": true,
            "retrievable": true
         },
         {
           "name": "contentVector",
           "type": "Collection(Edm.Single)",
            "searchable": true,
            "retrievable": false,
            "stored": false,
            "dimensions": 1536,
            "vectorSearchProfile": "vector-profile-hnsw"
         }
       ]
   

5. Selon votre compétence en intégration, définissez dimensions pour chaque champ vectoriel à la valeur suivante.

   Compétence d'intégration	Entrez cette valeur
   Azure OpenAI	Nombre d’incorporations générées par votre modèle d’incorporation.
   Azure Vision	1024

Ajouter un vectoriseur à l’index

Dans cette section, vous activez la vectorisation au moment de la requête en définissant un vectoriseur dans votre index. Le vectoriseur utilise le modèle d’incorporation qui indexe vos données pour décoder une chaîne de recherche ou une image dans un vecteur de recherche vectorielle.

1. Ajoutez le vectoriseur Azure OpenAI ou Azure Vectoriseur Vision (préversion) après vectorSearch.profiles. Vous pouvez coller l’une des définitions suivantes.

         "profiles": [ ... ],
         "vectorizers": [
           {
             "name": "my-openai-vectorizer",
             "kind": "azureOpenAI",
             "azureOpenAIParameters": {
               "resourceUri": "{{aoaiEndpoint}}",
               "deploymentId": "{{aoaiDeploymentName}}",
               "modelName": "{{aoaiModelName}}"
             }
           },
           {
             "name": "my-ai-services-vision-vectorizer",
             "kind": "aiServicesVision",
             "aiServicesVisionParameters": {
               "resourceUri": "{{AiFoundryEndpoint}}",
               "modelVersion": "2023-04-15"
             }
           }
         ]
   

   Note

   Le vectoriseur Azure Vision est en préversion. Si vous souhaitez appeler ce vectoriseur, utilisez la dernière version de l’API en préversion.

2. Spécifiez votre vectoriseur dans vectorSearch.profiles.

         "profiles": [
           {
             "name": "vector-profile-hnsw",
             "algorithm": "hnsw-algorithm",
             "vectorizer": "my-openai-vectorizer"
           }
         ]
   

3. Pour créer l’index vectoriel, sélectionnez Envoyer une requête.

Créer un indexeur

Dans cette section, vous créez un indexeur pour piloter l’intégralité du pipeline de vectorisation, de la récupération de données à l’exécution de l’ensemble de compétences à l’indexation. Nous vous recommandons de planifier l'exécution de l'indexeur pour traiter les modifications ou les documents qui ont été manqués en raison de la limitation de débit.

1. Utilisez Create Indexer pour définir un indexeur qui exécute le pipeline de vectorisation.

   ### Create an indexer
   POST {{baseUrl}}/indexers?api-version=2026-04-01  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{token}}
   
     {
       "name": "my-indexer",
       "dataSourceName": "my-data-source",
       "targetIndexName": "my-vector-index",
       "skillsetName": "my-skillset",
       "schedule": {
         "interval": "PT2H"
       },
       "parameters": {
         "batchSize": null,
         "maxFailedItems": null,
         "maxFailedItemsPerBatch": null
       }
     }
   

2. Pour créer l’indexeur, sélectionnez Envoyer une requête.

Exécuter une requête vectorielle pour confirmer l’indexation

Dans cette section, vous vérifiez que votre contenu a été correctement indexé en créant une requête vectorielle. Étant donné que vous avez configuré un vectoriseur dans une section précédente, le moteur de recherche peut décoder du texte brut ou une image dans un vecteur pour l’exécution des requêtes.

1. Utilisez documents - Recherche post pour définir une requête vectorisée au moment de la requête.

   ### Run a vector query
   POST {{baseUrl}}/indexes('my-vector-index')/docs/search.post.search?api-version=2026-04-01  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{token}}
   
     {
       "count": true,
       "select": "title, content",
       "vectorQueries": [
           {
             "kind": "text",
             "text": "a sample text string for integrated vectorization",
             "fields": "titleVector, contentVector",
             "k": "3"
           }
       ]
     }
   

   Note

   Le vectoriseur Azure Vision est en préversion. Si vous souhaitez appeler ce vectoriseur, utilisez la dernière version de l’API en préversion.

   Pour les requêtes qui appellent la vectorisation intégrée, kind doit être défini sur text, et text doit spécifier une chaîne de texte. Cette chaîne est transmise au vectoriseur affecté au champ vectoriel. Pour plus d’informations, consultez Requête avec vectorisation intégrée.

2. Pour exécuter la requête vectorielle, sélectionnez Envoyer une requête.

Contenu connexe

• Incorporation de vecteurs intégrées dans Recherche Azure AI
• Quickstart : Recherche vectorielle dans le portail Azure
• exemple Python pour la vectorisation intégrée