Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
Note
Foundry IQ (Recherche Azure AI) fournit des API d’indexation et d’interrogation directes, ainsi que des API de source de connaissances et de base de connaissances de niveau supérieur pour une récupération gérée. Utilisez le portail Azure, les API REST ou SDK Azure pour configurer ces fonctionnalités, ou connecter des agents à des bases de connaissances dans le portail Microsoft Foundry.
Important
Les fonctionnalités ou fonctionnalités marquées (préversion) dans cet article sont en préversion publique et sont soumises aux conditions d’utilisation supplémentaires pour les préversions Microsoft Azure.
Pour connaître les conditions d’utilisation en préversion spécifiques à Foundry IQ (Recherche Azure AI), consultez Fonctionnalité en préversion.
Une source de connaissances blob ingère du contenu provenant d’Stockage Blob Azure ou d’ADLS Gen2 dans un pipeline de récupération piloté par agent dans Foundry IQ (Recherche Azure AI). 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 lorsque la base de connaissances est interrogée lors de l’exécution.
Lorsque vous créez une source de connaissances Blob, vous spécifiez une source de données externe, des modèles et des propriétés afin de générer automatiquement les objets Foundry IQ suivants :
- Source de données qui représente un conteneur d’objets 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.
L’indexeur généré est conforme à l’indexeur d’objets blob, dont les prérequis, les formats de documents pris en charge et les limitations s’appliquent également aux sources de connaissances blob. Pour plus d’informations, consultez la documentation de l’indexeur d’objets BLOB et les limites de l’indexeur. Si l’ensemble de compétences généré appelle un service externe, les limites d’entrée et de service de cette compétence s’appliquent également.
Support d'utilisation
| portail Azure | portail Microsoft Foundry | Kit de développement logiciel (SDK) .NET | SDK Python | Java SDK | Kit de développement logiciel (SDK) JavaScript | REST API |
|---|---|---|---|---|---|---|
| ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
Conditions préalables
Service Foundry IQ dans n’importe quelle région qui fournit une recherche agentique.
Un compte Stockage Blob Azure ou Azure Data Lake Storage (ADLS) Gen2.
Conteneur de blobs avec des types de contenu pris en charge pour le contenu textuel. Pour une verbalisation d’image facultative, le type de contenu pris en charge dépend de la capacité de votre modèle de complétion de chat à analyser et décrire le fichier image.
Si
contentExtractionModecorrespond àstandard, utilisez une ressource Microsoft Foundry dans une région prise en charge par Content Understanding dans Foundry Tools avec un point de terminaisonhttps://<resource-name>.services.ai.azure.com. La ressource doit disposer d’un modèle de déploiement d’incorporation et, si vous activez la verbalisation d’image, d’un modèle de déploiement de conversation multimodale.Autorisation de créer des sources de connaissances. Configurez l’authentification sans clé avec les rôles Contributeur du service de recherche et Contributeur de données d’index de recherche affectés à votre compte d’utilisateur (recommandé) ou utilisez une clé API d’administration.
Identité managée pour le service Foundry IQ avec Storage Blob Data Reader au niveau de l’étendue du compte de stockage source et Cognitive Services User sur la ressource Microsoft Foundry. Si vous configurez un magasin d’artefacts dans un autre compte de stockage, attribuez également le rôle Contributeur de données blob de stockage au niveau de ce compte de stockage. Si les conteneurs source et d’éléments multimédias partagent un compte, Storage Blob Data Contributor accorde à la fois un accès en lecture à la source et un accès en lecture/écriture au stockage des éléments multimédias.
- Pour les appels avec identité managée vers des déploiements d’incorporation ou de conversation Azure OpenAI, affectez Cognitive Services OpenAI User à l’identité sélectionnée sur la ressource Azure OpenAI ou la ressource Foundry parente qui correspond à
resourceUri. Les autorisations de service d’extraction sont distinctes. Voir Attribuer un rôle.
- Pour les appels avec identité managée vers des déploiements d’incorporation ou de conversation Azure OpenAI, affectez Cognitive Services OpenAI User à l’identité sélectionnée sur la ressource Azure OpenAI ou la ressource Foundry parente qui correspond à
Si vous définissez
networkAccessModesurprivate, remplissez les conditions suivantes :Utilisez un service S2, S3, L1 ou L2 Foundry IQ. Vérifiez la matrice de prise en charge des liaisons privées partagées canoniques pour connaître les qualifications de configuration et de niveau.
Activez une identité managée affectée par le système ou affectée par l’utilisateur sur le service Foundry IQ, accordez-lui le rôle Lecteur de données blob de stockage sur le compte de stockage et utilisez un
ResourceId=/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Storage/storageAccounts/<storage-account>chaîne de connexion. Pour une identité attribuée par l’utilisateur, définissez égalementingestionParameters.identity.Créez et approuvez les liens de stockage répertoriés sous les types de ressources pris en charge. Pour ADLS Gen2, les liens
dfsetblobsont obligatoires.Créez et approuvez un lien pour chaque dépendance protégée de modèle, d’extraction, d’enrichissement ou de stockage de ressources que votre configuration utilise. Respectez les types de ressources pris en charge pour chaque ID de cible et de groupe.
Package
Azure.Search.Documentsrequis :Pour les fonctionnalités
2026-08-01-preview, le dernier package de préversion :dotnet add package Azure.Search.Documents --prereleasePour
2026-10-01, le dernier package stable :dotnet add package Azure.Search.Documents
Pour l’authentification sans clé, le
Azure.Identitypackage :dotnet add package Azure.Identity
Package
azure-search-documentsrequis :Pour les fonctionnalités
2026-08-01-preview, le dernier package de préversion :pip install --pre azure-search-documentsPour
2026-10-01, le dernier package stable :pip install azure-search-documents
Pour l’authentification sans clé, le
azure-identitypackage :pip install azure-identity
Version de l’API REST du service de recherche obligatoire :
Pour les fonctionnalités en préversion : 2026-11-01-preview
Pour les fonctionnalités en disponibilité générale, notamment l’ingestion privée : 2026-10-01
Pour l’authentification sans clé, incluez un jeton de Microsoft Entra ID dans l’en-tête
Authorizationde chaque requête HTTP.
Pour l’ingestion des autorisations, utilisez REST 2026-10-01 comme indiqué dans Appliquer des autorisations au niveau du document. Les exemples de SDK stables 2026-04-01 ne configurent pas l’ingestion d’autorisations. Vérifiez le journal des modifications du package pour obtenir la prise en charge de la version de l’API et des propriétés requises.
Les exemples REST utilisent la dernière API en préversion, 2026-11-01-preview. Les exemples de SDK en préversion conservent leur contrat documenté 2026-08-01-preview . Vérifiez le journal des modifications du package avant de cibler une version plus récente de l’API.
Rechercher les sources de connaissances existantes
Une source de connaissances est 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}");
}
Reference :SearchIndexClient
# List knowledge sources by name and type
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
for ks in index_client.list_knowledge_sources():
print(f" - {ks.name} ({ks.kind})")
Reference :SearchIndexClient
### List knowledge sources by name and type
GET {{search-url}}/knowledgesources?api-version={{api-version}}&$select=name,kind
Authorization: Bearer {{token}}
Référence :Sources de connaissances - Liste
Vous pouvez également retourner une source de connaissances unique 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));
Reference :SearchIndexClient
# Get a knowledge source definition
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
import json
index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
ks = index_client.get_knowledge_source("knowledge_source_name")
print(json.dumps(ks.as_dict(), indent = 2))
Reference :SearchIndexClient
### Get a knowledge source definition
GET {{search-url}}/knowledgesources('{{knowledge-source-name}}')?api-version={{api-version}}
Authorization: Bearer {{token}}
Référence :Sources de connaissances - Obtenir
La réponse suivante réactualise les valeurs sensibles et répertorie les objets générés sous createdResources. Avant de le réutiliser pour créer une autre source de connaissances, fournissez des informations d’identification cibles ou configurez l’identité managée prise en charge ; Les valeurs régérées ne sont pas des informations d’identification.
{
"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",
"modelName": "text-embedding-3-large",
"authIdentity": null
}
},
"chatCompletionModel": {
"kind": "azureOpenAI",
"azureOpenAIParameters": {
"resourceUri": "<aoai-endpoint>",
"deploymentId": "gpt-5-mini",
"modelName": "gpt-5-mini",
"authIdentity": null
}
},
"ingestionSchedule": null,
"assetStore": null,
"aiServices": {
"uri": "<aoai-endpoint>"
}
},
"createdResources": {
"datasource": "my-blob-ks-datasource",
"indexer": "my-blob-ks-indexer",
"skillset": "my-blob-ks-skillset",
"index": "my-blob-ks-index"
}
}
}
Créer une source de connaissances
Exécutez le code suivant pour créer une source d'informations 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.Search.Documents.Models;
using Azure.Identity;
var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new DefaultAzureCredential());
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
{
NetworkAccessMode = KnowledgeSourceNetworkAccessMode.Public,
DisableImageVerbalization = false,
ChatCompletionModel = new KnowledgeBaseAzureOpenAIModel(azureOpenAIParameters: chatCompletionParams),
EmbeddingModel = new KnowledgeSourceAzureOpenAIVectorizer
{
AzureOpenAIParameters = embeddingParams
},
IngestionPermissionOptions = new List<KnowledgeSourceIngestionPermissionOption>
{
KnowledgeSourceIngestionPermissionOption.RbacScope
}
};
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.");
Reference :SearchIndexClient, AzureBlobKnowledgeSource
# Create a blob knowledge source
from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import AzureBlobKnowledgeSource, AzureBlobKnowledgeSourceParameters, KnowledgeBaseAzureOpenAIModel, AzureOpenAIVectorizerParameters, KnowledgeSourceAzureOpenAIVectorizer, KnowledgeSourceContentExtractionMode, KnowledgeSourceIngestionParameters
from azure.search.documents.knowledgebases.models import KnowledgeSourceNetworkAccessMode
index_client = SearchIndexClient(endpoint = "<search-endpoint>", credential = DefaultAzureCredential())
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(
network_access_mode = KnowledgeSourceNetworkAccessMode.PUBLIC,
identity = None,
disable_image_verbalization = False,
chat_completion_model = KnowledgeBaseAzureOpenAIModel(
azure_open_ai_parameters = AzureOpenAIVectorizerParameters(
resource_url = "<aoai-endpoint>",
deployment_name = "<aoai-gpt-deployment>",
model_name = "<aoai-gpt-model>",
)
),
embedding_model = KnowledgeSourceAzureOpenAIVectorizer(
azure_open_ai_parameters=AzureOpenAIVectorizerParameters(
resource_url = "<aoai-endpoint>",
deployment_name = "<aoai-embedding-deployment>",
model_name = "<aoai-embedding-model>",
)
),
content_extraction_mode = KnowledgeSourceContentExtractionMode.MINIMAL,
ingestion_schedule = None,
ingestion_permission_options = ["rbacScope"]
)
)
)
index_client.create_or_update_knowledge_source(knowledge_source)
print(f"Knowledge source '{knowledge_source.name}' created or updated successfully.")
Reference :SearchIndexClient
### Create a blob knowledge source
PUT {{search-endpoint}}/knowledgesources/my-blob-ks?api-version=2026-11-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/json
{
"name": "my-blob-ks",
"kind": "azureBlob",
"description": "This knowledge source pulls from a blob storage container.",
"encryptionKey": null,
"azureBlobParameters": {
"connectionString": "ResourceId=<storage-resource-id>",
"containerName": "<blob-container-name>",
"folderPath": null,
"isADLSGen2": false,
"ingestionParameters": {
"networkAccessMode": "public",
"identity": null,
"disableImageVerbalization": null,
"chatCompletionModel": {
"kind": "azureOpenAI",
"azureOpenAIParameters": {
"resourceUri": "{{aoai-endpoint}}",
"deploymentId": "{{aoai-gpt-deployment}}",
"modelName": "{{aoai-gpt-model}}"
}
},
"embeddingModel": {
"kind": "azureOpenAI",
"azureOpenAIParameters": {
"resourceUri": "{{aoai-endpoint}}",
"deploymentId": "{{aoai-embedding-deployment}}",
"modelName": "{{aoai-embedding-model}}"
}
},
"contentExtractionMode": "minimal",
"ingestionSchedule": null,
"ingestionPermissionOptions": ["rbacScope"]
}
}
}
Référence :Sources de connaissances - Créer ou mettre à jour
Configurer la planification de l’ingestion
Définissez ingestionParameters.ingestionSchedule pour contrôler la fréquence à laquelle l’indexeur généré vérifie les changements dans la source. L’ingestion inachevée admissible peut se poursuivre automatiquement après un arrêt survenant pendant l’exécution sans attendre la prochaine interrogation.
Configurer l’extraction standard
Pour utiliser Content Understanding pour l’extraction de la mise en page et la segmentation sémantique au lieu de l’extraction minimal dans les exemples précédents, définissez contentExtractionMode sur standard et configurez aiServices avec le point de terminaison de votre ressource Foundry. Utilisez la ressource et les déploiements décrits dans Prérequis.
L’extraction standard entraîne des frais de Content Understanding et, lorsque la verbalisation d’image est activée, les frais d’utilisation du modèle. Pour plus d’informations, consultez les contrôles de facturation et de description d’image.
Restreindre l’ingestion à un réseau privé
Dans l’API stable 2026-10-01, networkAccessMode contrôle l’environnement réseau dans lequel l’indexeur généré pour une source de connaissances Blob s’exécute. Ce paramètre affecte uniquement l’ingestion et ne modifie pas la base de connaissances pour récupérer les demandes ou les réponses. Vérifiez la matrice de prise en charge des liaisons privées partagées pour connaître les configurations éligibles. Les fonctionnalités d’évaluation indépendantes, telles que les analyseurs automatiques par langage et le service d’images, conservent leurs propres exigences d’API.
networkAccessMode
publicla valeur par défaut est , qui conserve le comportement existant du réseau public. Lorsque networkAccessMode est private, l’indexeur généré s’exécute dans l’environnement d’exécution privé. Il utilise des liens privés partagés approuvés pour accéder à la connexion source Stockage Blob Azure ou ADLS Gen2 et aux dépendances Azure prises en charge, telles que les modèles OpenAI Azure et les ressources Foundry Microsoft.
Pour configurer et vérifier l’accès au réseau privé :
Remplissez les conditions préalables au réseau privé.
Définissez
networkAccessModesurprivatedans la demande de création de la source de connaissances. Vous ne pouvez définir cette propriété que lors de la création, y compris dans l’API stable2026-10-01. Pour modifier le mode stocké ultérieurement, supprimez et recréez la source de connaissances. Les sources d’objets blob éligibles, ADLS Gen2 et Azure SQL peuvent utiliser à la place la dérogation réseau provisoire de l’indexeur généré. Cette exception ne s'applique pas aux SharePoint indexés ou à d'autres types sources.La création peut échouer si le niveau de service ou le runtime ne prend pas en charge l’exécution privée ou si une liaison privée partagée requise n’existe pas. Serverless et S3 HD ne prennent pas en charge l’exécution privée. La configuration du périmètre de sécurité réseau contrôle l’accès au point de terminaison public pris en charge, et non l’exécution privée.
Vérifiez que l’indexeur
parameters.configuration.executionEnvironmentgénéré estprivate.Vérifiez que chaque liaison privée partagée requise est approuvée, provisionnée et cible la dépendance correcte. La création réussie ne confirme pas l’approbation ou le ciblage du lien. Si une vérification du portail ne peut pas résoudre une ressource entre abonnements, vérifiez manuellement l’approbation et la préparation sur la ressource cible et le service Foundry IQ.
Interrogez régulièrement l’état de la source de connaissances jusqu’à ce que
lastSynchronizationState.endTimeait une valeur. Confirmez queitemsUpdatesFailedest0, puis vérifiez le contenu source spécifique au connecteur. La synchronisation échoue si une dépendance n’est pas accessible.
Utiliser des analyseurs automatiques pour chaque langue (préversion)
À compter de la version de l’API2026-08-01-preview, les analyseurs automatiques par langage sont disponibles pour les objets blob, OneLake indexés et les sources de connaissances SharePoint indexées. Lorsqu'il est activé, Foundry IQ (Recherche Azure AI) détecte la langue de chaque document source et applique automatiquement un analyseur de langage Microsoft correspondant. Vous ne spécifiez pas d’analyseur dans la définition de la source de connaissances ou dans une requête.
Pour activer les analyseurs automatiques par langage, définissez et configurez contentExtractionModeminimalingestionParameters.aiServices dans la définition de la source de connaissances.
Pour l’authentification sans clé, omettez aiServices.apiKey et affectez le rôle d’utilisateur Cognitive Services sur votre ressource Microsoft Foundry à l’identité managée de votre service Foundry IQ. Pour l’authentification basée sur des clés, définissez aiServices.apiKey sur une clé valide pour votre ressource Foundry.
Les langues suivantes sont prises en charge :
- Anglais
- Japonais
- Français
- espagnol
- Allemand
- Néerlandais
- Italian
- Portugais brésilien
- Portugais européen
- Chinois simplifié
- Chinois traditionnel
- Coréen
Pour le contenu multilingue, Foundry IQ sélectionne un analyseur en fonction de la langue détectée prédominante. Il utilise l’analyseur standard lorsque la langue n’est pas prise en charge ou n’est pas connue avec certitude.
Lorsque vous activez des analyseurs automatiques par langue, Foundry IQ ajoute des champs de contenu spécifiques à la langue pour chaque langue prise en charge au schéma d’index généré, que vos données contiennent ou non des documents dans ces langues. Pendant l’ingestion, les documents sont routés vers le champ propre à la langue appropriée en fonction de leur langue détectée.
Les champs de langue inutilisés ne contiennent pas de contenu indexé et ont un impact minimal sur le stockage, mais ils restent dans le schéma d’index et comptent vers la limite de champ d’index. Tenez compte des champs supplémentaires lorsque vous planifiez la conception de votre index, le nombre de champs et les exigences de stockage. Pour plus d’informations, consultez Les limitesd’index et Estimer et gérer la capacité d’un service Foundry IQ.
La détection de langue est facturable après l’allocation gratuite d’enrichissement par IA. Pour plus d’informations, consultez Enrichissements gratuits.
Après l’ingestion, vérifiez le routage du langage sans modifier les objets générés :
- Inspectez le schéma d’index généré. Vérifiez que les champs spécifiques à la langue ont leurs analyseurs correspondants, comme
snippet_enavecen.microsoft, et quisnippet_defaultfournissent le secours de l’analyseur standard. - Vérifiez que la configuration sémantique générée répertorie les champs de contenu propres au langage et
snippet_default. - Inspectez les blocs indexés d’un document détecté comme étant rédigé dans une langue prise en charge. Le texte de chaque bloc appartient au champ de langue correspondant. Le texte issu d’une détection non prise en charge ou incertaine est acheminé vers
snippet_default. - Lire le contenu à partir du champ de langue renseigné ou du champ de secours. Dans ce mode, le schéma généré n’inclut pas de champ distinct
snippet.
Si le schéma ou les résultats ne correspondent pas, passez en revue les paramètres d’activation ci-dessus et les erreurs d’indexeur. Ces vérifications ne définissent pas de procédure de mise à jour ou de migration pour un index généré existant.
Vérifier l’état d’ingestion
Exécutez le code suivant pour surveiller la progression et l’intégrité de l’ingestion, notamment le type de source de connaissances et les erreurs d’indexation détaillées pour les sources de connaissances qui génèrent un pipeline d’indexeur et remplissent un index de recherche.
using Azure.Search.Documents.Indexes;
using System.Text.Json;
var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new AzureKeyCredential(apiKey));
// Get knowledge source ingestion 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);
Reference :SearchIndexClient
# Check knowledge source ingestion status
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
import json
index_client = SearchIndexClient(endpoint="search_url", credential=AzureKeyCredential("api_key"))
status = index_client.get_knowledge_source_status("knowledge_source_name")
print(json.dumps(status.as_dict(), indent=2))
Reference :SearchIndexClient
### Check knowledge source ingestion status
GET {{search-url}}/knowledgesources/{{knowledge-source-name}}/status?api-version={{api-version}}
Authorization: Bearer {{token}}
Content-Type: application/json
Référence :Knowledge Sources - Get Status
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.
{
"kind": "azureBlob",
"synchronizationStatus": "active",
"synchronizationInterval": "1d",
"currentSynchronizationState": {
"startTime": "2026-04-10T19:30:00Z",
"itemUpdatesProcessed": 1100,
"itemsUpdatesFailed": 100,
"itemsSkipped": 1100,
"errors": [
{
"key": "Item id 1",
"docURL": "https://contoso.blob.core.windows.net/contracts/2024/Q4/doc-00023.csv",
"statusCode": 400,
"componentName": "DocumentExtraction.AzureBlob.MyDataSource",
"errorMessage": "Could not read the value of column 'foo' at index '0'.",
"details": "The file could not be parsed.",
"documentationLink": "https://go.microsoft.com/fwlink/?linkid=2049388"
}
]
},
"lastSynchronizationState": {
"status": "partialSuccess",
"startTime": "2026-04-09T19:30:00Z",
"endTime": "2026-04-09T19:40:01Z",
"itemUpdatesProcessed": 1100,
"itemsUpdatesFailed": 100,
"itemsSkipped": 1100,
"errors": null
},
"statistics": {
"totalSynchronizations": 25,
"averageSynchronizationDuration": "00:15:20",
"averageItemsProcessedPerSynchronization": 500
}
}
Note
La kind propriété et currentSynchronizationState.errors[] le tableau avec les détails d’erreur au niveau du document sont disponibles à partir de la version de l’API 2026-04-01. Pour les versions antérieures de l’API, ces champs ne sont pas retournés. Le lastSynchronizationState.status champ est également nouveau en 2026-04-01.
Passer en revue les objets générés
Lorsque vous créez cette source de connaissances, Foundry IQ (Recherche Azure AI) génère automatiquement une source de données, un indexeur et un index, ainsi qu’un ensemble de compétences lorsque le pipeline d’ingestion en nécessite un. La réponse de création répertorie chaque objet sous createdResources.
Ces objets sont généré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 d’objets. Évitez de modifier ces objets directement, car les modifications peuvent introduire des erreurs ou des incompatibilités qui interrompent le pipeline d’indexeur.
Pour les sources Blob éligibles, ADLS Gen2 et Azure SQL uniquement, le remplacement de mise en réseau intermédiaire permet de modifier l'environnement d'exécution de l'indexeur généré. Cette exception ne s'applique pas aux SharePoint indexés ou OneLake et n'autorise pas d'autres modifications d'objet générées. Les mises à jour ultérieures ou la régénération de la source de connaissances peuvent écraser la dérogation.
Vous pouvez utiliser le portail Azure pour valider la création d’objets. Le flux de travail est le suivant :
Vérifiez les messages de réussite ou d’échec de l'indexeur. Les erreurs de connexion ou de quota s’affichent ici.
Vérifiez la source de données pour vérifier la connexion à votre magasin de données. La connexion utilise une chaîne de connexion ou une identité managée, selon la façon dont vous avez configuré la source de connaissances.
Si un ensemble de compétences est généré, vérifiez ses paramètres d’enrichissement et de vectorisation. Les sources de connaissances SQL génèrent un ensemble de compétences uniquement lorsque vous spécifiez
embeddingColumns.Vérifiez l’index pour voir comment votre contenu est indexé et exposé pour la récupération, y compris les champs pouvant faire l’objet d’une recherche et filtrables et quels champs stockent des vecteurs pour la recherche de similarité. Utilisez l’Explorateur de recherche pour exécuter des requêtes sur l’index généré.
Traitez la source de données générée, l’indexeur, l’index et l’ensemble de compétences, le cas échéant, comme une configuration d’ingestion. Restreindre les personnes autorisées à modifier cette configuration ou publier des documents vers cet index. Les identificateurs générés et les noms de champs d’autorisation n’établissent pas la propriété d’un document et ne font pas du contenu ordinaire une source autorisée d’octrois. Suivez les instructions d’ingestion préventive et les limites de personnalisation documentées ; n’utilisez pas de modifications directes arbitraires des clés ou des mappages générés comme mécanisme de contrôle de la propriété.
Attribuer à une base de connaissances
Si vous êtes satisfait de la source de connaissances, ajoutez-la à une base de connaissances.
Interroger une base de connaissances
Après avoir configuré la base de connaissances, appelez l’action de récupération ou le point de terminaison MCP pour interroger la source de connaissances. Choisissez la configuration qui correspond à votre scénario.
Imposer des permissions au niveau du document
Utilisez l’option d’extraction par défaut (contentExtractionMode: "minimal") ou l’extraction standard basée sur Content Understanding (contentExtractionMode: "standard") où elle est prise en charge. Chaque bloc généré conserve les métadonnées d’autorisation et le contexte source de l’élément source. Les autorisations au niveau du document ne prennent pas en charge les modes d’analyse spécialisés sélectionnés par le client. Consultez l’analyse syntaxique prise en charge et l’extraction de contenu pour l’ingestion des autorisations. Configurez ces options sur la source de connaissances ; ne modifiez pas les paramètres d’analyseur générés.
Définissez ingestionPermissionOptions lorsque vous créez la source de connaissances avec l’API REST 2026-10-01 :
- Pour les Stockage Blob standard, définissez
isADLSGen2surfalseet demandezrbacScope. Consultez la configuration Blob REST complète. - Pour ADLS Gen2, définissez
isADLSGen2surtrueet demandezuserIds,groupIdsetrbacScope. Commencez par la configuration REST ADLS et ajoutezrbacScopeà son tableauingestionPermissionOptionspour ingérer à la fois les ACL et les étendues RBAC de conteneur.
L’index généré inclut metadata_storage_path et les champs d’autorisation configurés, avec des mappages sur des blocs projetés. Le chemin d’accès est requis pour l’ingestion d’autorisations ADLS, y compris l’ingestion RBAC uniquement. Sa présence dans un schéma d’objet blob standard généré ne rend pas nécessaire le calcul de l’étendue de conteneur d’un indexeur d’objets blob direct.
Passez en revue l’index généré, les projections d’ensemble de compétences et l’indexeur ensemble. Conservez le contexte du chemin source et les mappages d’autorisations faisant autorité sur chaque bloc protégé. Pour les enregistrements existants avec des valeurs manquantes, la correction du schéma seul ne reremplit pas les métadonnées ; suivez la correction du schéma et de la projection.
Les indexeurs ADLS générés suivent les paramètres et la cadence d’actualisation automatiques de la liste de contrôle d’accès. Configurez parameters.configuration.refreshAllAcls dans l’indexeur généré. Pour une actualisation à la demande, utilisez le nom de cet indexeur dans la procédure de resynchronisation des autorisations.
Incluez le jeton d’accès de l’utilisateur délégué dans la requête de récupération. Pour les en-têtes de requête, consultez Appliquer les autorisations au moment de la requête.
Afficher les images intégrées aux documents (version préliminaire)
Pour afficher des images intégrées aux documents (telles que des diagrammes ou des documents numérisés) dans les réponses générées par la synthèse de réponses, configurez assetStore sur cette source de connaissances, puis activez la diffusion d’images sur la base de connaissances. La diffusion d’images n’est pas prise en charge lorsque ingestionPermissionOptions est configuré. Pour plus d’informations, consultez Afficher les images intégrées au document dans la récupération agentique (préversion).
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 :
Obtenez la liste de toutes les bases de connaissances sur votre service Foundry IQ.
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}"); }Reference :SearchIndexClient
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" } ] }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);Reference :SearchIndexClient
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 }Supprimez la base de connaissances ou, si vous avez plusieurs sources de connaissances, mettez à jour la base de connaissances pour supprimer la source. 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.");Reference :SearchIndexClient
Supprimez la source de connaissances.
await indexClient.DeleteKnowledgeSourceAsync(knowledgeSourceName); System.Console.WriteLine($"Knowledge source '{knowledgeSourceName}' deleted successfully.");Reference :SearchIndexClient
Obtenez la liste de toutes les bases de connaissances sur votre service Foundry IQ.
# Get knowledge bases from azure.core.credentials import AzureKeyCredential from azure.search.documents.indexes import SearchIndexClient index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key")) print("Knowledge Bases:") for kb in index_client.list_knowledge_bases(): print(f" - {kb.name}")Reference :SearchIndexClient
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" } ] }Obtenez une définition de base de connaissances individuelle pour rechercher des références à la source de connaissances.
# Get a knowledge base definition from azure.core.credentials import AzureKeyCredential from azure.search.documents.indexes import SearchIndexClient index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key")) kb = index_client.get_knowledge_base("knowledge_base_name") print(kb)Reference :SearchIndexClient
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" } }Supprimez la base de connaissances ou, si vous avez plusieurs sources de connaissances, mettez à jour la base de connaissances pour supprimer la source. 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.")Reference :SearchIndexClient
Supprimez 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.")Reference :SearchIndexClient
Obtenez la liste de toutes les bases de connaissances sur votre service Foundry IQ.
### Get knowledge bases GET {{search-url}}/knowledgebases?api-version={{api-version}}&$select=name Authorization: Bearer {{token}}Référence :Bases de connaissances - Liste
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" } ] }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-url}}/knowledgebases('{{knowledge-base-name}}')?api-version={{api-version}} Authorization: Bearer {{token}}Référence :Bases de connaissances - Obtenir
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" } }Supprimez la base de connaissances ou, si vous avez plusieurs sources de connaissances, mettez à jour la base de connaissances pour supprimer la source. Cet exemple montre la suppression.
### Delete a knowledge base DELETE {{search-url}}/knowledgebases('{{knowledge-base-name}}')?api-version={{api-version}} Authorization: Bearer {{token}}Référence :Bases de connaissances - Supprimer
Supprimez la source de connaissances.
### Delete a knowledge source DELETE {{search-url}}/knowledgesources('{{knowledge-source-name}}')?api-version={{api-version}} Authorization: Bearer {{token}}Référence :Supprimer les sources de connaissances