Partager via

Créer une source de connaissances de blobs à partir du Stockage Blob Azure et d'ADLS Gen2

Note

Cette fonctionnalité est actuellement disponible en préversion publique. Cette préversion est fournie sans contrat de niveau de service et n’est pas recommandée pour les charges de travail de production. Certaines fonctionnalités peuvent être limitées ou non prises en charge. Pour plus d’informations, consultez Conditions d’utilisation supplémentaires pour les préversions de Microsoft Azure.

Utilisez une source de connaissances blob pour indexer et interroger le contenu blob d’Azure dans un pipeline de récupération autonome. Les sources de connaissances sont créées indépendamment, référencées dans une base de connaissances et utilisées comme données de base lorsqu’un agent ou un chatbot appelle une action de récupération au moment de la requête.

Contrairement à une source de connaissances d’index de recherche, qui spécifie un index existant et qualifié, une source de connaissances d’objet blob spécifie une source de données externe, des modèles et des propriétés pour générer automatiquement les objets Recherche Azure AI suivants :

  • Source de données qui représente un conteneur blob.
  • Ensemble de compétences qui segmente et vectorise éventuellement le contenu modal du conteneur.
  • Index qui stocke du contenu enrichi et répond aux critères de récupération agentique.
  • Indexeur qui utilise les objets précédents pour piloter l’indexation et le pipeline d’enrichissement.

Note

Si l’accès utilisateur est spécifié au niveau du document (blob) dans stockage Azure, une source de connaissances peut transférer les métadonnées d’autorisation vers le contenu indexé dans Recherche AZURE AI. Pour plus d’informations, consultez les métadonnées d’autorisation ADLS Gen2 ou les étendues RBAC Blob.

Prerequisites

Rechercher des sources de connaissances existantes

Une source de connaissances constitue un objet réutilisable de niveau supérieur. Connaître les sources de connaissances existantes est utile pour réutiliser ou nommer de nouveaux objets.

Exécutez le code suivant pour répertorier les sources de connaissances par nom et par type.

// List knowledge sources by name and type
using Azure.Search.Documents.Indexes;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);
var knowledgeSources = indexClient.GetKnowledgeSourcesAsync();

Console.WriteLine("Knowledge Sources:");

await foreach (var ks in knowledgeSources)
{
    Console.WriteLine($"  Name: {ks.Name}, Type: {ks.GetType().Name}");
}

Vous pouvez également renvoyer une seule source de connaissances par nom pour passer en revue sa définition JSON.

using Azure.Search.Documents.Indexes;
using System.Text.Json;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);

// Specify the knowledge source name to retrieve
string ksNameToGet = "earth-knowledge-source";

// Get its definition
var knowledgeSourceResponse = await indexClient.GetKnowledgeSourceAsync(ksNameToGet);
var ks = knowledgeSourceResponse.Value;

// Serialize to JSON for display
var jsonOptions = new JsonSerializerOptions 
{ 
    WriteIndented = true,
    DefaultIgnoreCondition = System.Text.Json.Serialization.JsonIgnoreCondition.Never
};
Console.WriteLine(JsonSerializer.Serialize(ks, ks.GetType(), jsonOptions));

Le JSON suivant est un exemple de réponse pour une source de connaissances en blob.

{
  "name": "my-blob-ks",
  "kind": "azureBlob",
  "description": "A sample blob knowledge source.",
  "encryptionKey": null,
  "azureBlobParameters": {
    "connectionString": "<REDACTED>",
    "containerName": "blobcontainer",
    "folderPath": null,
    "isADLSGen2": false,
    "ingestionParameters": {
      "disableImageVerbalization": false,
      "ingestionPermissionOptions": [],
      "contentExtractionMode": "standard",
      "identity": null,
      "embeddingModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "<REDACTED>",
          "deploymentId": "text-embedding-3-large",
          "apiKey": "<REDACTED>",
          "modelName": "text-embedding-3-large",
          "authIdentity": null
        }
      },
      "chatCompletionModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "<REDACTED>",
          "deploymentId": "gpt-5-mini",
          "apiKey": "<REDACTED>",
          "modelName": "gpt-5-mini",
          "authIdentity": null
        }
      },
      "ingestionSchedule": null,
      "assetStore": null,
      "aiServices": {
        "uri": "<REDACTED>",
        "apiKey": "<REDACTED>"
      }
    },
    "createdResources": {
      "datasource": "my-blob-ks-datasource",
      "indexer": "my-blob-ks-indexer",
      "skillset": "my-blob-ks-skillset",
      "index": "my-blob-ks-index"
    }
  }
}

Note

Les informations sensibles sont expurgées. Les ressources générées s’affichent à la fin de la réponse.

Créer une source de connaissances

Exécutez le code suivant pour créer une source de données blob.

// Create a blob knowledge source
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.KnowledgeBases.Models;
using Azure;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new AzureKeyCredential(apiKey));

var chatCompletionParams = new AzureOpenAIVectorizerParameters
{
    ResourceUri = new Uri(aoaiEndpoint),
    DeploymentName = aoaiGptDeployment,
    ModelName = aoaiGptModel
};

var embeddingParams = new AzureOpenAIVectorizerParameters
{
    ResourceUri = new Uri(aoaiEndpoint),
    DeploymentName = aoaiEmbeddingDeployment,
    ModelName = aoaiEmbeddingModel
};

var ingestionParams = new KnowledgeSourceIngestionParameters
{
    DisableImageVerbalization = false,
    ChatCompletionModel = new KnowledgeBaseAzureOpenAIModel(azureOpenAIParameters: chatCompletionParams),
    EmbeddingModel = new KnowledgeSourceAzureOpenAIVectorizer
    {
        AzureOpenAIParameters = embeddingParams
    }
};

var blobParams = new AzureBlobKnowledgeSourceParameters(
    connectionString: connectionString,
    containerName: containerName
)
{
    IsAdlsGen2 = false,
    IngestionParameters = ingestionParams
};

var knowledgeSource = new AzureBlobKnowledgeSource(
    name: "my-blob-ks",
    azureBlobParameters: blobParams
)
{
    Description = "This knowledge source pulls from a blob storage container."
};

await indexClient.CreateOrUpdateKnowledgeSourceAsync(knowledgeSource);
Console.WriteLine($"Knowledge source '{knowledgeSource.Name}' created or updated successfully.");

Propriétés spécifiques à la source

Vous pouvez passer les propriétés suivantes pour créer une source de connaissances de blobs.

Nom Descriptif Type Modifiable Obligatoire
name Nom de la source de connaissances, qui doit être unique dans la collection de sources de connaissances et suivre les instructions d’affectation de noms pour les objets dans Recherche IA Azure. Chaîne Non Oui
Description Description de la source de connaissances. Chaîne Oui Non
encryptionKey Clé gérée par le client pour chiffrer les informations sensibles dans la source de connaissances et les objets générés. Objet Oui Non
chatCompletionParams Paramètres spécifiques aux modèles d’achèvement de conversation utilisés pour la planification des requêtes et la synthèse des réponses facultatives lorsque l’effort de raisonnement de récupération est faible ou moyen. Objet Non
embeddingParams Paramètres spécifiques à l’incorporation de modèles utilisés si vous souhaitez vectoriser des blocs de contenu. Objet Non
azureBlobParameters Paramètres spécifiques aux sources de connaissances blob : connectionString, containerName, folderPath, et isAdlsGen2. Objet Non
connectionString Chaîne de connexion basée sur une clé ou, si vous utilisez une identité managée, l’ID de ressource. Chaîne Non Oui
containerName Nom du conteneur de stockage de blobs. Chaîne Non Oui
folderPath Dossier dans le conteneur. Chaîne Non Non
isAdlsGen2 La valeur par défaut est False. Définissez sur True si vous utilisez un compte de stockage ADLS Gen2. Booléen Non Non

propriétés ingestionParameters

Pour les sources de connaissances indexées uniquement, vous pouvez transmettre les propriétés suivantes ingestionParameters pour contrôler la façon dont le contenu est ingéré et traité.

Nom Descriptif Type Modifiable Obligatoire
Identity Identité managée à utiliser dans l’indexeur généré. Objet Oui Non
DisableImageVerbalization Active ou désactive l’utilisation de la verbalisation d’image. La valeur par défaut est False, qui active la verbalisation d’image. Réglez sur True pour désactiver la verbalisation d’image. Booléen Non Non
ChatCompletionModel Modèle d’achèvement de conversation qui verbalise des images ou extrait du contenu. Les modèles pris en charge sont gpt-4o, , gpt-4o-minigpt-4.1, gpt-4.1-minigpt-4.1-nanogpt-5gpt-5-mini, et .gpt-5-nano La compétence "GenAI Prompt" sera incluse dans les compétences générées. La définition de ce paramètre nécessite également que disable_image_verbalization soit défini sur False. Objet Uniquement api_key et deployment_name sont modifiables Non
EmbeddingModel Modèle d’incorporation de texte qui vectorise le contenu du texte et de l’image pendant l’indexation et au moment de la requête. Les modèles pris en charge sont text-embedding-ada-002, text-embedding-3-smallet text-embedding-3-large. La compétence d’incorporation Azure OpenAI sera incluse dans l’ensemble de compétences généré, et le vectoriseur Azure OpenAI sera inclus dans l’index généré. Objet Uniquement api_key et deployment_name sont modifiables Non
ContentExtractionMode Contrôle la façon dont le contenu est extrait des fichiers. La valeur par défaut est minimal, qui utilise l’extraction de contenu standard pour le texte et les images. Définissez sur standardpour le craquage et la segmentation de documents avancés à l’aide de la compétence Azure Content Understanding, qui sera incluse dans l’ensemble de compétences généré. Pour standard seulement, les paramètres AiServices et AssetStore sont spécifiables. Chaîne Non Non
AiServices Ressource Microsoft Foundry permettant d’accéder à Azure Content Understanding dans Foundry Tools. La définition de ce paramètre nécessite que ContentExtractionMode soit défini à standard. Objet Il n’est modifiable que api_key Oui
IngestionSchedule Ajoute des informations de planification à l’indexeur généré. Vous pouvez également ajouter une planification ultérieurement pour automatiser l’actualisation des données. Objet Oui Non
IngestionPermissionOptions Autorisations au niveau du document à ingérer à partir de sources de connaissances sélectionnées : ADLS Gen2 ou SharePoint indexé. Si vous spécifiez user_ids, group_idsou rbac_scope, l’indexeur ADLS Gen2 généré ou l’indexeur SharePoint inclut les autorisations ingérées. Array Non Non

Vérifier l’état d’ingestion

Exécutez le code suivant pour surveiller la progression et l'état de l’ingestion, y compris l’état de l’indexeur pour les sources de connaissance qui génèrent un pipeline d’indexeur et remplissent un index de recherche.

// Get knowledge source ingestion status
using Azure.Search.Documents.Indexes;
using System.Text.Json;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new AzureKeyCredential(apiKey));

// Get the knowledge source status
var statusResponse = await indexClient.GetKnowledgeSourceStatusAsync(knowledgeSourceName);
var status = statusResponse.Value;

// Serialize to JSON for display
var json = JsonSerializer.Serialize(status, new JsonSerializerOptions { WriteIndented = true });
Console.WriteLine(json);

Une réponse pour une demande qui inclut des paramètres d’ingestion et qui ingère activement du contenu peut ressembler à l’exemple suivant.

{ 
  "synchronizationStatus": "active", // creating, active, deleting 
  "synchronizationInterval" : "1d", // null if no schedule 
  "currentSynchronizationState" : { // spans multiple indexer "runs" 
    "startTime": "2025-10-27T19:30:00Z", 
    "itemUpdatesProcessed": 1100, 
    "itemsUpdatesFailed": 100, 
    "itemsSkipped": 1100, 
  }, 
  "lastSynchronizationState" : {  // null on first sync 
    "startTime": "2025-10-27T19:30:00Z", 
    "endTime": "2025-10-27T19:40:01Z", // this value appears on the activity record on each /retrieve 
    "itemUpdatesProcessed": 1100, 
    "itemsUpdatesFailed": 100, 
    "itemsSkipped": 1100, 
  }, 
  "statistics": {  // null on first sync 
    "totalSynchronization": 25, 
    "averageSynchronizationDuration": "00:15:20", 
    "averageItemsProcessedPerSynchronization" : 500 
  } 
}

Passer en revue les objets créés

Lorsque vous créez une source de connaissances blob, votre service de recherche crée également un indexeur, un index, un ensemble de compétences et une source de données. Nous vous déconseillons de modifier ces objets, car l’introduction d’une erreur ou d’une incompatibilité peut interrompre le pipeline.

Après avoir créé une source de connaissances, la réponse répertorie les objets créés. Ces objets sont créés en fonction d’un modèle fixe et leurs noms sont basés sur le nom de la source de connaissances. Vous ne pouvez pas modifier les noms des objets.

Nous vous recommandons d’utiliser le Portail Azure pour valider la création de la sortie. Le flux de travail est le suivant :

  1. Vérifiez les messages de réussite ou d’échec de l’indexeur. Les erreurs de connexion ou de quota s’affichent ici.
  2. Vérifiez l’index pour rechercher du contenu interrogeable. Utilisez l’Explorateur de recherche pour exécuter des requêtes.
  3. Vérifiez l’ensemble de compétences pour savoir comment votre contenu est segmenté et éventuellement vectorisé.
  4. Vérifiez la source de données pour obtenir les détails de connexion. Notre exemple utilise des clés API par souci de simplicité, mais vous pouvez utiliser l’ID Microsoft Entra pour l’authentification et le contrôle d’accès en fonction du rôle pour l’autorisation.

Attribuer à une base de connaissances

Si vous êtes satisfait de la source de connaissances, passez à l’étape suivante : spécifiez la source de connaissances dans une base de connaissances.

Une fois la base de connaissances configurée, utilisez l’action de récupération pour interroger la source de connaissances.

Supprimer une source de connaissances

Avant de pouvoir supprimer une source de connaissances, vous devez supprimer toute base de connaissances qui la référence ou mettre à jour la définition de la base de connaissances pour supprimer la référence. Pour les sources de connaissances qui génèrent un pipeline d’index et d’indexeur, tous les objets générés sont également supprimés . Toutefois, si vous avez utilisé un index existant pour créer une source de connaissances, votre index n’est pas supprimé.

Si vous essayez de supprimer une source de connaissances en cours d’utilisation, l’action échoue et retourne une liste de bases de connaissances affectées.

Pour supprimer une source de connaissances :

  1. Obtenez la liste de toutes les bases de connaissances sur votre service de recherche.

    using Azure.Search.Documents.Indexes;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);
var knowledgeBases = indexClient.GetKnowledgeBasesAsync();

Console.WriteLine("Knowledge Bases:");

await foreach (var kb in knowledgeBases)
{
    Console.WriteLine($"  - {kb.Name}");
}

    Un exemple de réponse peut ressembler à ce qui suit :

     Knowledge Bases:
   - earth-knowledge-base
   - hotels-sample-knowledge-base
   - my-demo-knowledge-base

  2. Obtenez une définition de base de connaissances individuelle pour rechercher des références à la source de connaissances.

    using Azure.Search.Documents.Indexes;
using System.Text.Json;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);

// Specify the knowledge base name to retrieve
string kbNameToGet = "earth-knowledge-base";

// Get a specific knowledge base definition
var knowledgeBaseResponse = await indexClient.GetKnowledgeBaseAsync(kbNameToGet);
var kb = knowledgeBaseResponse.Value;

// Serialize to JSON for display
string json = JsonSerializer.Serialize(kb, new JsonSerializerOptions { WriteIndented = true });
Console.WriteLine(json);

    Un exemple de réponse peut ressembler à ce qui suit :

     {
   "Name": "earth-knowledge-base",
   "KnowledgeSources": [
     {
       "Name": "earth-knowledge-source"
     }
   ],
   "Models": [
     {}
   ],
   "RetrievalReasoningEffort": {},
   "OutputMode": {},
   "ETag": "\u00220x8DE278629D782B3\u0022",
   "EncryptionKey": null,
   "Description": null,
   "RetrievalInstructions": null,
   "AnswerInstructions": null
 }

  3. Supprimez la base de connaissances ou mettez à jour la base de connaissances pour supprimer la source de connaissances si vous avez plusieurs sources. Cet exemple montre la suppression.

    using Azure.Search.Documents.Indexes;
var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);

await indexClient.DeleteKnowledgeBaseAsync(knowledgeBaseName);
System.Console.WriteLine($"Knowledge base '{knowledgeBaseName}' deleted successfully.");

  4. Supprimer la source de connaissances.

    await indexClient.DeleteKnowledgeSourceAsync(knowledgeSourceName);
System.Console.WriteLine($"Knowledge source '{knowledgeSourceName}' deleted successfully.");

Note

Cette fonctionnalité est actuellement disponible en préversion publique. Cette préversion est fournie sans contrat de niveau de service et n’est pas recommandée pour les charges de travail de production. Certaines fonctionnalités peuvent être limitées ou non prises en charge. Pour plus d’informations, consultez Conditions d’utilisation supplémentaires pour les préversions de Microsoft Azure.

Utilisez une source de connaissances blob pour indexer et interroger le contenu blob d’Azure dans un pipeline de récupération autonome. Les sources de connaissances sont créées indépendamment, référencées dans une base de connaissances et utilisées comme données de base lorsqu’un agent ou un chatbot appelle une action de récupération au moment de la requête.

Contrairement à une source de connaissances d’index de recherche, qui spécifie un index existant et qualifié, une source de connaissances d’objet blob spécifie une source de données externe, des modèles et des propriétés pour générer automatiquement les objets Recherche Azure AI suivants :

  • Source de données qui représente un conteneur blob.
  • Ensemble de compétences qui segmente et vectorise éventuellement le contenu modal du conteneur.
  • Index qui stocke du contenu enrichi et répond aux critères de récupération agentique.
  • Indexeur qui utilise les objets précédents pour piloter l’indexation et le pipeline d’enrichissement.

Note

Si l’accès utilisateur est spécifié au niveau du document (blob) dans stockage Azure, une source de connaissances peut transférer les métadonnées d’autorisation vers le contenu indexé dans Recherche AZURE AI. Pour plus d’informations, consultez les métadonnées d’autorisation ADLS Gen2 ou les étendues RBAC Blob.

Prerequisites

Rechercher des sources de connaissances existantes

Une source de connaissances constitue un objet réutilisable de niveau supérieur. Connaître les sources de connaissances existantes est utile pour réutiliser ou nommer de nouveaux objets.

Exécutez le code suivant pour répertorier les sources de connaissances par nom et par type.

# List knowledge sources by name and type
import requests
import json

endpoint = "{search_url}/knowledgesources"
params = {"api-version": "2025-11-01-preview", "$select": "name, kind"}
headers = {"api-key": "{api_key}"}

response = requests.get(endpoint, params = params, headers = headers)
print(json.dumps(response.json(), indent = 2))

Vous pouvez également renvoyer une seule source de connaissances par nom pour passer en revue sa définition JSON.

# Get a knowledge source definition
import requests
import json

endpoint = "{search_url}/knowledgesources/{knowledge_source_name}"
params = {"api-version": "2025-11-01-preview"}
headers = {"api-key": "{api_key}"}

response = requests.get(endpoint, params = params, headers = headers)
print(json.dumps(response.json(), indent = 2))

Le JSON suivant est un exemple de réponse pour une source de connaissances en blob.

{
  "name": "my-blob-ks",
  "kind": "azureBlob",
  "description": "A sample blob knowledge source.",
  "encryptionKey": null,
  "azureBlobParameters": {
    "connectionString": "<REDACTED>",
    "containerName": "blobcontainer",
    "folderPath": null,
    "isADLSGen2": false,
    "ingestionParameters": {
      "disableImageVerbalization": false,
      "ingestionPermissionOptions": [],
      "contentExtractionMode": "standard",
      "identity": null,
      "embeddingModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "<REDACTED>",
          "deploymentId": "text-embedding-3-large",
          "apiKey": "<REDACTED>",
          "modelName": "text-embedding-3-large",
          "authIdentity": null
        }
      },
      "chatCompletionModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "<REDACTED>",
          "deploymentId": "gpt-5-mini",
          "apiKey": "<REDACTED>",
          "modelName": "gpt-5-mini",
          "authIdentity": null
        }
      },
      "ingestionSchedule": null,
      "assetStore": null,
      "aiServices": {
        "uri": "<REDACTED>",
        "apiKey": "<REDACTED>"
      }
    },
    "createdResources": {
      "datasource": "my-blob-ks-datasource",
      "indexer": "my-blob-ks-indexer",
      "skillset": "my-blob-ks-skillset",
      "index": "my-blob-ks-index"
    }
  }
}

Note

Les informations sensibles sont expurgées. Les ressources générées s’affichent à la fin de la réponse.

Créer une source de connaissances

Exécutez le code suivant pour créer une base de connaissances blob.

# Create a blob knowledge source
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import AzureBlobKnowledgeSource, AzureBlobKnowledgeSourceParameters, KnowledgeBaseAzureOpenAIModel, AzureOpenAIVectorizerParameters, KnowledgeSourceAzureOpenAIVectorizer, KnowledgeSourceContentExtractionMode, KnowledgeSourceIngestionParameters

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))

knowledge_source = AzureBlobKnowledgeSource(
    name = "my-blob-ks",
    description = "This knowledge source pulls from a blob storage container.",
    encryption_key = None,
    azure_blob_parameters = AzureBlobKnowledgeSourceParameters(
        connection_string = "blob_connection_string",
        container_name = "blob_container_name",
        folder_path = None,
        is_adls_gen2 = False,
        ingestion_parameters = KnowledgeSourceIngestionParameters(
            identity = None,
            disable_image_verbalization = False,
            chat_completion_model = KnowledgeBaseAzureOpenAIModel(
                azure_open_ai_parameters = AzureOpenAIVectorizerParameters(
                    # TRIMMED FOR BREVITY
                )
            ),
            embedding_model = KnowledgeSourceAzureOpenAIVectorizer(
                azure_open_ai_parameters=AzureOpenAIVectorizerParameters(
                    # TRIMMED FOR BREVITY
                )
            ),
            content_extraction_mode = KnowledgeSourceContentExtractionMode.MINIMAL,
            ingestion_schedule = None,
            ingestion_permission_options = None
        )
    )
)

index_client.create_or_update_knowledge_source(knowledge_source)
print(f"Knowledge source '{knowledge_source.name}' created or updated successfully.")

Propriétés spécifiques à la source

Vous pouvez passer les propriétés suivantes pour créer une source de connaissances de blobs.

Nom Descriptif Type Modifiable Obligatoire
name Nom de la source de connaissances, qui doit être unique dans la collection de sources de connaissances et suivre les instructions d’affectation de noms pour les objets dans Recherche IA Azure. Chaîne Non Oui
description Description de la source de connaissances. Chaîne Oui Non
encryption_key Clé gérée par le client pour chiffrer les informations sensibles dans la source de connaissances et les objets générés. Objet Oui Non
azure_blob_parameters Paramètres spécifiques aux sources de connaissances blob : connection_string, container_name, folder_path, et is_adls_gen2. Objet Non
connection_string Chaîne de connexion basée sur une clé ou, si vous utilisez une identité managée, l’ID de ressource. Chaîne Non Oui
container_name Nom du conteneur de stockage de blobs. Chaîne Non Oui
folder_path Dossier dans le conteneur. Chaîne Non Non
is_adls_gen2 La valeur par défaut est False. Définissez sur True si vous utilisez un compte de stockage ADLS Gen2. Booléen Non Non

propriétés ingestionParameters

Pour les sources de connaissances indexées uniquement, vous pouvez transmettre les propriétés suivantes ingestionParameters pour contrôler la façon dont le contenu est ingéré et traité.

Nom Descriptif Type Modifiable Obligatoire
identity Identité managée à utiliser dans l’indexeur généré. Objet Oui Non
disable_image_verbalization Active ou désactive l’utilisation de la verbalisation d’image. La valeur par défaut est False, qui active la verbalisation d’image. Réglez sur True pour désactiver la verbalisation d’image. Booléen Non Non
chat_completion_model Modèle d’achèvement de conversation qui verbalise des images ou extrait du contenu. Les modèles pris en charge sont gpt-4o, , gpt-4o-minigpt-4.1, gpt-4.1-minigpt-4.1-nanogpt-5gpt-5-mini, et .gpt-5-nano La compétence "GenAI Prompt" sera incluse dans les compétences générées. La définition de ce paramètre nécessite également que disable_image_verbalization soit défini sur False. Objet Uniquement api_key et deployment_name sont modifiables Non
embedding_model Modèle d’incorporation de texte qui vectorise le contenu du texte et de l’image pendant l’indexation et au moment de la requête. Les modèles pris en charge sont text-embedding-ada-002, text-embedding-3-smallet text-embedding-3-large. La compétence d’incorporation Azure OpenAI sera incluse dans l’ensemble de compétences généré, et le vectoriseur Azure OpenAI sera inclus dans l’index généré. Objet Uniquement api_key et deployment_name sont modifiables Non
content_extraction_mode Contrôle la façon dont le contenu est extrait des fichiers. La valeur par défaut est minimal, qui utilise l’extraction de contenu standard pour le texte et les images. Définissez sur standardpour le craquage et la segmentation de documents avancés à l’aide de la compétence Azure Content Understanding, qui sera incluse dans l’ensemble de compétences généré. Pour standard seulement, les paramètres ai_services et asset_store sont spécifiables. Chaîne Non Non
ai_services Ressource Microsoft Foundry permettant d’accéder à Azure Content Understanding dans Foundry Tools. La définition de ce paramètre nécessite que content_extraction_mode soit défini à standard. Objet Il n’est modifiable que api_key Oui
asset_store Conteneur d’objets blob destiné à stocker des images extraites. La définition de ce paramètre nécessite que content_extraction_mode soit défini à standard. Objet Non Non
ingestion_schedule Ajoute des informations de planification à l’indexeur généré. Vous pouvez également ajouter une planification ultérieurement pour automatiser l’actualisation des données. Objet Oui Non
ingestion_permission_options Autorisations au niveau du document à ingérer à partir de sources de connaissances sélectionnées : ADLS Gen2 ou SharePoint indexé. Si vous spécifiez user_ids, group_idsou rbac_scope, l’indexeur ADLS Gen2 généré ou l’indexeur SharePoint inclut les autorisations ingérées. Array Non Non

Vérifier l’état d’ingestion

Exécutez le code suivant pour surveiller la progression et l’état de l’ingestion, y compris l’état de l’indexeur pour les sources de connaissances générant un pipeline d’indexeur et alimentant un index de recherche.

# Check knowledge source ingestion status
import requests
import json

endpoint = "{search_url}/knowledgesources/{knowledge_source_name}/status"
params = {"api-version": "2025-11-01-preview"}
headers = {"api-key": "{api_key}"}

response = requests.get(endpoint, params = params, headers = headers)
print(json.dumps(response.json(), indent = 2))

Une réponse pour une demande qui inclut des paramètres d’ingestion et qui ingère activement du contenu peut ressembler à l’exemple suivant.

{ 
  "synchronizationStatus": "active", // creating, active, deleting 
  "synchronizationInterval" : "1d", // null if no schedule 
  "currentSynchronizationState" : { // spans multiple indexer "runs" 
    "startTime": "2025-10-27T19:30:00Z", 
    "itemUpdatesProcessed": 1100, 
    "itemsUpdatesFailed": 100, 
    "itemsSkipped": 1100, 
  }, 
  "lastSynchronizationState" : {  // null on first sync 
    "startTime": "2025-10-27T19:30:00Z", 
    "endTime": "2025-10-27T19:40:01Z", // this value appears on the activity record on each /retrieve 
    "itemUpdatesProcessed": 1100, 
    "itemsUpdatesFailed": 100, 
    "itemsSkipped": 1100, 
  }, 
  "statistics": {  // null on first sync 
    "totalSynchronization": 25, 
    "averageSynchronizationDuration": "00:15:20", 
    "averageItemsProcessedPerSynchronization" : 500 
  } 
}

Passer en revue les objets créés

Lorsque vous créez une source de connaissances blob, votre service de recherche crée également un indexeur, un index, un ensemble de compétences et une source de données. Nous vous déconseillons de modifier ces objets, car l’introduction d’une erreur ou d’une incompatibilité peut interrompre le pipeline.

Après avoir créé une source de connaissances, la réponse répertorie les objets créés. Ces objets sont créés en fonction d’un modèle fixe et leurs noms sont basés sur le nom de la source de connaissances. Vous ne pouvez pas modifier les noms des objets.

Nous vous recommandons d’utiliser le Portail Azure pour valider la création de la sortie. Le flux de travail est le suivant :

  1. Vérifiez les messages de réussite ou d’échec de l’indexeur. Les erreurs de connexion ou de quota s’affichent ici.
  2. Vérifiez l’index pour rechercher du contenu interrogeable. Utilisez l’Explorateur de recherche pour exécuter des requêtes.
  3. Vérifiez l’ensemble de compétences pour savoir comment votre contenu est segmenté et éventuellement vectorisé.
  4. Vérifiez la source de données pour obtenir les détails de connexion. Notre exemple utilise des clés API par souci de simplicité, mais vous pouvez utiliser l’ID Microsoft Entra pour l’authentification et le contrôle d’accès en fonction du rôle pour l’autorisation.

Attribuer à une base de connaissances

Si vous êtes satisfait de la source de connaissances, passez à l’étape suivante : spécifiez la source de connaissances dans une base de connaissances.

Une fois la base de connaissances configurée, utilisez l’action de récupération pour interroger la source de connaissances.

Supprimer une source de connaissances

Avant de pouvoir supprimer une source de connaissances, vous devez supprimer toute base de connaissances qui la référence ou mettre à jour la définition de la base de connaissances pour supprimer la référence. Pour les sources de connaissances qui génèrent un pipeline d’index et d’indexeur, tous les objets générés sont également supprimés . Toutefois, si vous avez utilisé un index existant pour créer une source de connaissances, votre index n’est pas supprimé.

Si vous essayez de supprimer une source de connaissances en cours d’utilisation, l’action échoue et retourne une liste de bases de connaissances affectées.

Pour supprimer une source de connaissances :

  1. Obtenez la liste de toutes les bases de connaissances sur votre service de recherche.

    # Get knowledge bases
import requests
import json

endpoint = "{search_url}/knowledgebases"
params = {"api-version": "2025-11-01-preview", "$select": "name"}
headers = {"api-key": "{api_key}"}

response = requests.get(endpoint, params = params, headers = headers)
print(json.dumps(response.json(), indent = 2))

    Un exemple de réponse peut ressembler à ce qui suit :

     {
     "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
     "value": [
     {
         "name": "my-kb"
     },
     {
         "name": "my-kb-2"
     }
     ]
 }

  2. Obtenez une définition de base de connaissances individuelle pour rechercher des références à la source de connaissances.

    # Get a knowledge base definition
import requests
import json

endpoint = "{search_url}/knowledgebases/{knowledge_base_name}"
params = {"api-version": "2025-11-01-preview"}
headers = {"api-key": "{api_key}"}

response = requests.get(endpoint, params = params, headers = headers)
print(json.dumps(response.json(), indent = 2))

    Un exemple de réponse peut ressembler à ce qui suit :

     {
   "name": "my-kb",
   "description": null,
   "retrievalInstructions": null,
   "answerInstructions": null,
   "outputMode": null,
   "knowledgeSources": [
     {
       "name": "my-blob-ks",
     }
   ],
   "models": [],
   "encryptionKey": null,
   "retrievalReasoningEffort": {
     "kind": "low"
   }
 }

  3. Supprimez la base de connaissances ou mettez à jour la base de connaissances pour supprimer la source de connaissances si vous avez plusieurs sources. Cet exemple montre la suppression.

    # Delete a knowledge base
from azure.core.credentials import AzureKeyCredential 
from azure.search.documents.indexes import SearchIndexClient

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
index_client.delete_knowledge_base("knowledge_base_name")
print(f"Knowledge base deleted successfully.")

  4. Supprimer la source de connaissances.

    # Delete a knowledge source
from azure.core.credentials import AzureKeyCredential 
from azure.search.documents.indexes import SearchIndexClient

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
index_client.delete_knowledge_source("knowledge_source_name")
print(f"Knowledge source deleted successfully.")

Note

Cette fonctionnalité est actuellement disponible en préversion publique. Cette préversion est fournie sans contrat de niveau de service et n’est pas recommandée pour les charges de travail de production. Certaines fonctionnalités peuvent être limitées ou non prises en charge. Pour plus d’informations, consultez Conditions d’utilisation supplémentaires pour les préversions de Microsoft Azure.

Utilisez une source de connaissances blob pour indexer et interroger le contenu blob d’Azure dans un pipeline de récupération autonome. Les sources de connaissances sont créées indépendamment, référencées dans une base de connaissances et utilisées comme données de base lorsqu’un agent ou un chatbot appelle une action de récupération au moment de la requête.

Contrairement à une source de connaissances d’index de recherche, qui spécifie un index existant et qualifié, une source de connaissances d’objet blob spécifie une source de données externe, des modèles et des propriétés pour générer automatiquement les objets Recherche Azure AI suivants :

  • Source de données qui représente un conteneur blob.
  • Ensemble de compétences qui segmente et vectorise éventuellement le contenu modal du conteneur.
  • Index qui stocke du contenu enrichi et répond aux critères de récupération agentique.
  • Indexeur qui utilise les objets précédents pour piloter l’indexation et le pipeline d’enrichissement.

Note

Si l’accès utilisateur est spécifié au niveau du document (blob) dans stockage Azure, une source de connaissances peut transférer les métadonnées d’autorisation vers le contenu indexé dans Recherche AZURE AI. Pour plus d’informations, consultez les métadonnées d’autorisation ADLS Gen2 ou les étendues RBAC Blob.

Prerequisites

Rechercher des sources de connaissances existantes

Une source de connaissances constitue un objet réutilisable de niveau supérieur. Connaître les sources de connaissances existantes est utile pour réutiliser ou nommer de nouveaux objets.

Utilisez les sources de connaissances - Obtenir (API REST) pour répertorier les sources de connaissances par nom et par type.

### List knowledge sources by name and type
GET {{search-url}}/knowledgesources?api-version=2025-11-01-preview&$select=name,kind
api-key: {{api-key}}

Vous pouvez également renvoyer une seule source de connaissances par nom pour passer en revue sa définition JSON.

### Get a knowledge source definition
GET {{search-url}}/knowledgesources/{{knowledge-source-name}}?api-version=2025-11-01-preview
api-key: {{api-key}}

Le JSON suivant est un exemple de réponse pour une source de connaissances en blob.

{
  "name": "my-blob-ks",
  "kind": "azureBlob",
  "description": "A sample blob knowledge source.",
  "encryptionKey": null,
  "azureBlobParameters": {
    "connectionString": "<REDACTED>",
    "containerName": "blobcontainer",
    "folderPath": null,
    "isADLSGen2": false,
    "ingestionParameters": {
      "disableImageVerbalization": false,
      "ingestionPermissionOptions": [],
      "contentExtractionMode": "standard",
      "identity": null,
      "embeddingModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "<REDACTED>",
          "deploymentId": "text-embedding-3-large",
          "apiKey": "<REDACTED>",
          "modelName": "text-embedding-3-large",
          "authIdentity": null
        }
      },
      "chatCompletionModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "<REDACTED>",
          "deploymentId": "gpt-5-mini",
          "apiKey": "<REDACTED>",
          "modelName": "gpt-5-mini",
          "authIdentity": null
        }
      },
      "ingestionSchedule": null,
      "assetStore": null,
      "aiServices": {
        "uri": "<REDACTED>",
        "apiKey": "<REDACTED>"
      }
    },
    "createdResources": {
      "datasource": "my-blob-ks-datasource",
      "indexer": "my-blob-ks-indexer",
      "skillset": "my-blob-ks-skillset",
      "index": "my-blob-ks-index"
    }
  }
}

Note

Les informations sensibles sont expurgées. Les ressources générées s’affichent à la fin de la réponse.

Créer une source de connaissances

Utilisez Sources de connaissances - Créer ou mettre à jour (API REST) pour créer une source de connaissances Blob.

PUT {{search-url}}/knowledgesources/my-blob-ks?api-version=2025-11-01-preview
api-key: {{api-key}}
Content-Type: application/json

{
  "name": "my-blob-ks",
  "kind": "azureBlob",
  "description": "This knowledge source pulls from a blob storage container.",
  "encryptionKey": null,
  "azureBlobParameters": {
    "connectionString": "<YOUR AZURE STORAGE CONNECTION STRING>",
    "containerName": "<YOUR BLOB CONTAINER NAME>",
    "folderPath": null,
    "isADLSGen2": false,
    "ingestionParameters": {
        "identity": null,
        "disableImageVerbalization": null,
        "chatCompletionModel": { TRIMMED FOR BREVITY },
        "embeddingModel": { TRIMMED FOR BREVITY },
        "contentExtractionMode": "minimal",
        "ingestionSchedule": null,
        "ingestionPermissionOptions": []
    }
  }
}

Propriétés spécifiques à la source

Vous pouvez passer les propriétés suivantes pour créer une source de connaissances de blobs.

Nom Descriptif Type Modifiable Obligatoire
name Nom de la source de connaissances, qui doit être unique dans la collection de sources de connaissances et suivre les instructions d’affectation de noms pour les objets dans Recherche IA Azure. Chaîne Non Oui
kind Type de source de connaissances, qui est azureBlob dans ce cas. Chaîne Non Oui
description Description de la source de connaissances. Chaîne Oui Non
encryptionKey Clé gérée par le client pour chiffrer les informations sensibles dans la source de connaissances et les objets générés. Objet Oui Non
azureBlobParameters Paramètres spécifiques aux sources de connaissances blob : connectionString, containerName, folderPath, et isADLSGen2. Objet Non
connectionString Chaîne de connexion basée sur une clé ou, si vous utilisez une identité managée, l’ID de ressource. Chaîne Non Oui
containerName Nom du conteneur de stockage de blobs. Chaîne Non Oui
folderPath Dossier dans le conteneur. Chaîne Non Non
isADLSGen2 La valeur par défaut est false. Définissez sur true si vous utilisez un compte de stockage ADLS Gen2. Booléen Non Non

propriétés ingestionParameters

Pour les sources de connaissances indexées uniquement, vous pouvez transmettre les propriétés suivantes ingestionParameters pour contrôler la façon dont le contenu est ingéré et traité.

Nom Descriptif Type Modifiable Obligatoire
identity Identité managée à utiliser dans l’indexeur généré. Objet Oui Non
disableImageVerbalization Active ou désactive l’utilisation de la verbalisation d’image. La valeur par défaut est false, qui active la verbalisation d’image. Réglez sur true pour désactiver la verbalisation d’image. Booléen Non Non
chatCompletionModel Modèle d’achèvement de conversation qui verbalise des images ou extrait du contenu. Les modèles pris en charge sont gpt-4o, , gpt-4o-minigpt-4.1, gpt-4.1-minigpt-4.1-nanogpt-5gpt-5-mini, et .gpt-5-nano La compétence "GenAI Prompt" sera incluse dans les compétences générées. La définition de ce paramètre nécessite également que disableImageVerbalization soit défini sur false. Objet Uniquement apiKey et deploymentId sont modifiables Non
embeddingModel Modèle d’incorporation de texte qui vectorise le contenu du texte et de l’image pendant l’indexation et au moment de la requête. Les modèles pris en charge sont text-embedding-ada-002, text-embedding-3-smallet text-embedding-3-large. La compétence d’incorporation Azure OpenAI sera incluse dans l’ensemble de compétences généré, et le vectoriseur Azure OpenAI sera inclus dans l’index généré. Objet Uniquement apiKey et deploymentId sont modifiables Non
contentExtractionMode Contrôle la façon dont le contenu est extrait des fichiers. La valeur par défaut est minimal, qui utilise l’extraction de contenu standard pour le texte et les images. Définissez sur standardpour le craquage et la segmentation de documents avancés à l’aide de la compétence Azure Content Understanding, qui sera incluse dans l’ensemble de compétences généré. Pour standard seulement, les paramètres aiServices et assetStore sont spécifiables. Chaîne Non Non
aiServices Ressource Microsoft Foundry permettant d’accéder à Azure Content Understanding dans Foundry Tools. La définition de ce paramètre nécessite que contentExtractionMode soit défini à standard. Objet Il n’est modifiable que apiKey Oui
assetStore Conteneur d’objets blob destiné à stocker des images extraites. La définition de ce paramètre nécessite que contentExtractionMode soit défini à standard. Objet Non Non
ingestionSchedule Ajoute des informations de planification à l’indexeur généré. Vous pouvez également ajouter une planification ultérieurement pour automatiser l’actualisation des données. Objet Oui Non
ingestionPermissionOptions Autorisations au niveau du document à ingérer à partir de sources de connaissances sélectionnées : ADLS Gen2 ou SharePoint indexé. Si vous spécifiez userIds, groupIdsou rbacScope, l’indexeur ADLS Gen2 généré ou l’indexeur SharePoint inclut les autorisations ingérées. Array Non Non

Vérifier l’état d’ingestion

Utilisez les sources de connaissances - État (API REST) pour surveiller la progression et l’intégrité de l’ingestion, y compris l’état de l’indexeur pour les sources de connaissances qui génèrent un pipeline d’indexeur et remplissent un index de recherche.

### Check knowledge source ingestion status
GET {{search-url}}/knowledgesources/{{knowledge-source-name}}/status?api-version=2025-11-01-preview
api-key: {{api-key}}
Content-Type: application/json

Une réponse pour une demande qui inclut des paramètres d’ingestion et qui ingère activement du contenu peut ressembler à l’exemple suivant.

{ 
  "synchronizationStatus": "active", // creating, active, deleting 
  "synchronizationInterval" : "1d", // null if no schedule 
  "currentSynchronizationState" : { // spans multiple indexer "runs" 
    "startTime": "2025-10-27T19:30:00Z", 
    "itemUpdatesProcessed": 1100, 
    "itemsUpdatesFailed": 100, 
    "itemsSkipped": 1100, 
  }, 
  "lastSynchronizationState" : {  // null on first sync 
    "startTime": "2025-10-27T19:30:00Z", 
    "endTime": "2025-10-27T19:40:01Z", // this value appears on the activity record on each /retrieve 
    "itemUpdatesProcessed": 1100, 
    "itemsUpdatesFailed": 100, 
    "itemsSkipped": 1100, 
  }, 
  "statistics": {  // null on first sync 
    "totalSynchronization": 25, 
    "averageSynchronizationDuration": "00:15:20", 
    "averageItemsProcessedPerSynchronization" : 500 
  } 
}

Passer en revue les objets créés

Lorsque vous créez une source de connaissances blob, votre service de recherche crée également un indexeur, un index, un ensemble de compétences et une source de données. Nous vous déconseillons de modifier ces objets, car l’introduction d’une erreur ou d’une incompatibilité peut interrompre le pipeline.

Après avoir créé une source de connaissances, la réponse répertorie les objets créés. Ces objets sont créés en fonction d’un modèle fixe et leurs noms sont basés sur le nom de la source de connaissances. Vous ne pouvez pas modifier les noms des objets.

Nous vous recommandons d’utiliser le Portail Azure pour valider la création de la sortie. Le flux de travail est le suivant :

  1. Vérifiez les messages de réussite ou d’échec de l’indexeur. Les erreurs de connexion ou de quota s’affichent ici.
  2. Vérifiez l’index pour rechercher du contenu interrogeable. Utilisez l’Explorateur de recherche pour exécuter des requêtes.
  3. Vérifiez l’ensemble de compétences pour savoir comment votre contenu est segmenté et éventuellement vectorisé.
  4. Vérifiez la source de données pour obtenir les détails de connexion. Notre exemple utilise des clés API par souci de simplicité, mais vous pouvez utiliser l’ID Microsoft Entra pour l’authentification et le contrôle d’accès en fonction du rôle pour l’autorisation.

Attribuer à une base de connaissances

Si vous êtes satisfait de la source de connaissances, passez à l’étape suivante : spécifiez la source de connaissances dans une base de connaissances.

Une fois la base de connaissances configurée, utilisez l’action de récupération pour interroger la source de connaissances.

Supprimer une source de connaissances

Avant de pouvoir supprimer une source de connaissances, vous devez supprimer toute base de connaissances qui la référence ou mettre à jour la définition de la base de connaissances pour supprimer la référence. Pour les sources de connaissances qui génèrent un pipeline d’index et d’indexeur, tous les objets générés sont également supprimés . Toutefois, si vous avez utilisé un index existant pour créer une source de connaissances, votre index n’est pas supprimé.

Si vous essayez de supprimer une source de connaissances en cours d’utilisation, l’action échoue et retourne une liste de bases de connaissances affectées.

Pour supprimer une source de connaissances :

  1. Obtenez la liste de toutes les bases de connaissances sur votre service de recherche.

    ### Get knowledge bases
GET {{search-endpoint}}/knowledgebases?api-version=2025-11-01-preview&$select=name
api-key: {{api-key}}

    Un exemple de réponse peut ressembler à ce qui suit :

     {
     "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
     "value": [
     {
         "name": "my-kb"
     },
     {
         "name": "my-kb-2"
     }
     ]
 }

  2. Obtenez une définition de base de connaissances individuelle pour rechercher des références à la source de connaissances.

    ### Get a knowledge base definition
GET {{search-endpoint}}/knowledgebases/{{knowledge-base-name}}?api-version=2025-11-01-preview
api-key: {{api-key}}

    Un exemple de réponse peut ressembler à ce qui suit :

     {
   "name": "my-kb",
   "description": null,
   "retrievalInstructions": null,
   "answerInstructions": null,
   "outputMode": null,
   "knowledgeSources": [
     {
       "name": "my-blob-ks",
     }
   ],
   "models": [],
   "encryptionKey": null,
   "retrievalReasoningEffort": {
     "kind": "low"
   }
 }

  3. Supprimez la base de connaissances ou mettez à jour la base de connaissances en supprimant la source de connaissances si vous avez plusieurs sources. Cet exemple montre la suppression.

    ### Delete a knowledge base
DELETE {{search-endpoint}}/knowledgebases/{{knowledge-base-name}}?api-version=2025-11-01-preview
api-key: {{api-key}}

  4. Supprimer la source de connaissances.

    ### Delete a knowledge source
DELETE {{search-endpoint}}/knowledgesources/{{knowledge-source-name}}?api-version=2025-11-01-preview
api-key: {{api-key}}

Contenu connexe

  • Last updated on