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
Recherche Azure AI est disponible via le portail Azure, les API REST et les SDK Azure. Il sous-tend également Foundry IQ, la couche de connaissances managée qui transforme le contenu d’entreprise en bases de connaissances réutilisables et prenant en charge les autorisations pour les agents dans le portail Microsoft Foundry.
Important
Ces fonctionnalités font partie de l’API REST 2026-08-01-preview. La préversion 2026-08-01 vous est concédée sous licence dans le cadre de votre abonnement Azure et est soumise aux conditions applicables aux « préversions » dans les Microsoft Conditions d’utilisation du produit, l’addenda sur la protection des données des produits et des services Microsoft (« DPA ») et les conditions d’utilisation supplémentaires pour les préversions Microsoft Azure.
Les API en préversion prennent en charge les connexions à d’autres services Microsoft et à des services tiers. L’utilisation de ces services est soumise à leurs conditions respectives et peut entraîner le traitement ou le stockage des données en dehors de la limite de conformité Azure, ainsi que des données entrant dans la limite de conformité Azure.
Il est de votre responsabilité de gérer si vos données circulent en dehors des limites géographiques et de conformité de votre organisation, ainsi que des implications connexes, et que les autorisations, les limites et les approbations appropriées sont provisionnés.
Vous êtes responsable de l’examen et du test des applications que vous créez dans le contexte de vos cas d’usage spécifiques et de prendre toutes les décisions et personnalisations appropriées. Cela inclut l’implémentation de vos propres atténuations d’IA responsables, telles que les métaprompts, les filtres de contenu ou d’autres systèmes de sécurité, et la garantie que vos applications répondent aux normes de qualité, de fiabilité, de sécurité et de fiabilité appropriées. Pour plus d’informations, consultez la note de transparence Recherche Azure AI.
Une source de connaissances basée sur des fichiers (version préliminaire) télécharge directement des ensembles de fichiers de petite à moyenne taille dans Recherche Azure AI pour la récupération pour les agents. 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.
Les sources de connaissances de fichiers sont utiles lorsque vous souhaitez une expérience de chargement managée au lieu de provisionner des stockage Azure, de configurer l’accès et de créer un pipeline d’indexeur sur un conteneur externe. Recherche Azure AI traite les fichiers chargés afin que leur contenu extrait puisse être récupéré à partir d’une base de connaissances.
Utilisez plutôt une source de connaissances d’objet blob lorsque vos fichiers sont déjà dans Stockage Blob Azure ou Azure Data Lake Storage Gen2, lorsque votre jeu de fichiers dépasse ou est susceptible de dépasser les limites de la source de connaissances du fichier, ou lorsque vous avez besoin d’une ingestion planifiée. Utilisez également une source de connaissances Blob lorsque vous souhaitez gérer des blobs source à l’aide de stratégies de gestion du cycle de vie d’Stockage Blob Azure ou lorsque vous avez besoin de autorisations au niveau du document (préversion) en vous appuyant sur les autorisations définies dans stockage Azure.
Assistance à l'utilisation
| portail Azure | portail Microsoft Foundry | Kit de développement logiciel (SDK) .NET | Kit de développement logiciel (SDK) Python | SDK Java | SDK JavaScript | REST API |
|---|---|---|---|---|---|---|
| ❌ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
Prerequisites
Un service Recherche Azure AI dans n’importe quelle région qui fournit une recherche agentique. Les sources de connaissances basées sur des fichiers prennent en charge à la fois les modèles tarifaires Dédié et Sans serveur. Pour plus d’informations sur le modèle et le niveau de niveau, consultez Choisir un modèle tarifaire et un niveau de service.
Passez en revue les coûts Recherche Azure AI. Les appels de modèle, la vectorisation et d’autres traitements d’IA peuvent entraîner des frais distincts.
Sur Serverless, les opérations d’ingestion de fichiers réussies consomment un calcul facturable. Les téléversements qui échouent n’entraînent pas de frais de calcul sans serveur.
Si vous avez besoin d’une récupération agentique payante au-delà de l’allocation gratuite mensuelle, activez le plan de récupération agentique standard. Le
knowledgeRetrieval=standardparamètre est distinct des frais de calcul et de stockage serverless et ne sélectionne pas de modèle tarifaire.Fichiers dans un format pris en charge.
Autorisation de créer des sources de connaissances. Configurez l’authentification sans clé avec le rôle Contributeur de service de recherche affecté à votre compte d’utilisateur (recommandé) ou utilisez une clé API d’administration.
Si la source de connaissances spécifie un modèle OpenAI Azure pour les incorporations, le service de recherche doit disposer d’autorisations managed identity avec Cognitive Services User sur la ressource Microsoft Foundry.
- Si la ressource Foundry a un accès réseau public désactivé, créez une
foundry_accountliaison privée partagée à partir du service de recherche vers la ressource Foundry et conservez les services Autoriser Azure de la ressource sur le paramètre de liste des services approuvés activé.
- Si la ressource Foundry a un accès réseau public désactivé, créez une
Si la source de connaissances spécifie le
standardmode d’extraction de contenu, passez en revue les conditions requises pour la compétence Azure Content Understanding.L’utilisation est facturée selon la tarification d’Azure Content Understanding dans Foundry Tools à la ressource Foundry configurée via
aiServices.Le quota gratuit quotidien de 20 documents disponible pour certaines compétences intégrées ne s’applique pas.
Pour l’exemple de cet article, vous avez besoin du point de terminaison et de la clé de la ressource Foundry, ainsi que des informations sur les modèles d’incorporation et de complétion de conversation d’Azure OpenAI.
Le dernier paquet
Azure.Search.Documents(préversion) :dotnet add package Azure.Search.Documents --prereleasePour l’authentification sans clé, le
Azure.Identitypackage :dotnet add package Azure.Identity
Le dernier paquet
azure-search-documents(préversion) :pip install --pre azure-search-documentsPour l’authentification sans clé, le
azure-identitypackage :pip install azure-identity
La version 2026-08-01-preview de l’API REST du service de recherche.
Pour l’authentification sans clé, incluez un jeton de Microsoft Entra ID dans l’en-tête
Authorizationde chaque requête HTTP.
Prise en charge et limites des fichiers
Avant de créer une source de connaissances de fichier, passez en revue les exigences et limites qui affectent le chargement, l’extraction et la gestion des fichiers.
Types de contenu pris en charge
Les sources de connaissances de fichiers acceptent les fichiers en fonction du type de contenu détecté. Un type de contenu fourni par l’appelant ne remplace pas la détection.
Les types de contenu pris en charge sont les suivants :
- Word (
.doc,.docx) - PowerPoint (
.ppt,.pptx) - Excel (
.xls,.xlsx) - JSON
- Scripts d’interpréteur de commandes
- Contenu détecté comme
text/*, tel que.txt,.md,.html, et.csv
Modes d’extraction pris en charge
Pour les types de contenu répertoriés,
2026-05-01-previewet2026-08-01-previewprennent en chargeminimal.standardest disponible uniquement dans2026-08-01-preview.Le contenu détecté comme
image/*n’est pas pris en charge dans2026-05-01-preview. Dans2026-08-01-preview, utilisez l’extractionstandard.minimall’extraction renvoie le code d’état HTTP415dans les deux versions.
Limites et opérations de fichier
Les limites et les opérations de fichier prises en charge diffèrent par version de l’API.
| Capacité | 2026-05-01-preview |
2026-08-01-preview |
|---|---|---|
| Nombre maximal de fichiers par source de connaissances | 100 | 200 |
| Taille maximale du fichier | 50 Mo sur tous les niveaux tarifaires pris en charge | 50 Mo pour Free et Basic ; 100 Mo pour les autres niveaux Dedicated pris en charge et Serverless |
| Durée de traitement | Le chargement peut s’exécuter pendant jusqu’à 180 secondes | Le chargement et la mise à jour peuvent s’exécuter jusqu’à 180 secondes |
| Charger du contenu et des métadonnées | Contenu du fichier brut | Contenu de fichier brut ou contenu multipart avec des métadonnées |
| Répertorier les fichiers chargés | Lister les fichiers | Filtrer par chemin d’accès ou nom de fichier et retourner des détails de fichier plus riches |
| Remplacer le contenu de fichier existant | Supprimer et téléverser à nouveau | Utiliser l’opération de mise à jour |
| Accès via le navigateur aux opérations sur les fichiers | CORS n’est pas disponible | Configuration de CORS |
Note
- L’index de recherche généré stocke le contenu chargé. Pour connaître les limites de stockage totales par niveau tarifaire, consultez les limites du service.
- Si vous configurez la source de connaissances de fichier pour segmenter ou vectoriser le contenu chargé, les limites de traitement en aval et de modèle s’appliquent également.
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
Le code JSON suivant est un exemple de réponse pour une source de connaissances de fichier.
{
"name": "my-file-ks",
"kind": "file",
"description": "A sample file knowledge source.",
"encryptionKey": null,
"fileParameters": {
"ingestionParameters": {
"contentExtractionMode": "minimal",
"embeddingModel": {
"kind": "azureOpenAI",
"azureOpenAIParameters": {
"resourceUri": "<REDACTED>",
"deploymentId": "text-embedding-3-large",
"modelName": "text-embedding-3-large"
}
}
}
}
}
Créer une source de connaissances
Créez une source de connaissances de fichier qui spécifie le modèle d’incorporation utilisé pour vectoriser le contenu chargé.
Chaque source de connaissances de fichier crée un index, mais pas un indexeur ou une planification. Vous devez inclure l’objet fileParameters.ingestionParameters . Le service rejette les demandes qui spécifient networkAccessMode.
using Azure.Identity;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new DefaultAzureCredential());
var embeddingParams = new AzureOpenAIVectorizerParameters
{
ResourceUri = new Uri(aoaiEndpoint),
DeploymentName = aoaiEmbeddingDeployment,
ModelName = aoaiEmbeddingModel
};
var ingestionParams = new KnowledgeSourceIngestionParameters
{
ContentExtractionMode = "minimal",
EmbeddingModel = new KnowledgeSourceAzureOpenAIVectorizer
{
AzureOpenAIParameters = embeddingParams
}
};
var fileParams = new FileKnowledgeSourceParameters
{
IngestionParameters = ingestionParams
};
var knowledgeSource = new FileKnowledgeSource(
name: "my-file-ks",
fileParameters: fileParams
)
{
Description = "This knowledge source uses directly uploaded product manuals."
};
await indexClient.CreateOrUpdateKnowledgeSourceAsync(knowledgeSource);
Console.WriteLine($"Knowledge source '{knowledgeSource.Name}' created or updated successfully.");
Reference :SearchIndexClient
from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
AzureOpenAIVectorizerParameters,
FileKnowledgeSource,
FileKnowledgeSourceParameters,
)
from azure.search.documents.knowledgebases.models import (
KnowledgeSourceAzureOpenAIVectorizer,
KnowledgeSourceIngestionParameters,
)
index_client = SearchIndexClient(endpoint="<search-endpoint>", credential=DefaultAzureCredential())
embedding_params = AzureOpenAIVectorizerParameters(
resource_url="<aoai-endpoint>",
deployment_name="<aoai-embedding-deployment>",
model_name="<aoai-embedding-model>",
)
ingestion_params = KnowledgeSourceIngestionParameters(
content_extraction_mode="minimal",
embedding_model=KnowledgeSourceAzureOpenAIVectorizer(
azure_open_ai_parameters=embedding_params
),
)
knowledge_source = FileKnowledgeSource(
name="my-file-ks",
description="This knowledge source uses directly uploaded product manuals.",
file_parameters=FileKnowledgeSourceParameters(ingestion_parameters=ingestion_params),
)
index_client.create_or_update_knowledge_source(knowledge_source=knowledge_source)
print(f"Knowledge source '{knowledge_source.name}' created or updated successfully.")
Reference :SearchIndexClient
PUT {{search-endpoint}}/knowledgesources/my-file-ks?api-version=2026-08-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/json
Prefer: return=representation
{
"name": "my-file-ks",
"kind": "file",
"description": "This knowledge source uses directly uploaded product manuals.",
"encryptionKey": null,
"fileParameters": {
"ingestionParameters": {
"embeddingModel": {
"kind": "azureOpenAI",
"azureOpenAIParameters": {
"resourceUri": "{{aoai-endpoint}}",
"deploymentId": "{{aoai-embedding-deployment}}",
"modelName": "{{aoai-embedding-model}}"
}
},
"contentExtractionMode": "minimal"
}
}
}
Référence :Sources de connaissances - Créer ou mettre à jour
Configurer l’extraction standard
À partir de la version de l’API 2026-08-01-preview, standard l’extraction utilise Content Understanding pour extraire, segmenter en blocs sémantiques et enrichir les fichiers téléversés. Recherche Azure AI gère ce traitement dans le cadre de la source de connaissances et les frais Content Understanding s’appliquent séparément.
using Azure.Identity;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.KnowledgeBases.Models;
var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new DefaultAzureCredential());
var embeddingParameters = new AzureOpenAIVectorizerParameters
{
ResourceUri = new Uri(aoaiEndpoint),
DeploymentName = aoaiEmbeddingDeployment,
ModelName = aoaiEmbeddingModel
};
var ingestionParameters = new KnowledgeSourceIngestionParameters
{
ContentExtractionMode = KnowledgeSourceContentExtractionMode.Standard,
AiServices = new AIServices(new Uri(foundryEndpoint)) { ApiKey = foundryKey },
EmbeddingModel = new KnowledgeSourceAzureOpenAIVectorizer
{
AzureOpenAIParameters = embeddingParameters
},
ChatCompletionModel = new KnowledgeBaseAzureOpenAIModel(
new AzureOpenAIVectorizerParameters
{
ResourceUri = new Uri(aoaiEndpoint),
DeploymentName = aoaiChatDeployment,
ModelName = aoaiChatModel
})
};
var knowledgeSource = new FileKnowledgeSource(
"my-file-ks",
new FileKnowledgeSourceParameters { IngestionParameters = ingestionParameters });
await indexClient.CreateOrUpdateKnowledgeSourceAsync(knowledgeSource);
Console.WriteLine($"Configured standard extraction for '{knowledgeSource.Name}'.");
Reference :SearchIndexClient
from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
AzureOpenAIVectorizerParameters,
FileKnowledgeSource,
FileKnowledgeSourceParameters,
KnowledgeBaseAzureOpenAIModel,
)
from azure.search.documents.knowledgebases.models import (
AIServices,
KnowledgeSourceAzureOpenAIVectorizer,
KnowledgeSourceIngestionParameters,
)
index_client = SearchIndexClient(endpoint="<search-endpoint>", credential=DefaultAzureCredential())
embedding_parameters = AzureOpenAIVectorizerParameters(
resource_url="<aoai-endpoint>",
deployment_name="<aoai-embedding-deployment>",
model_name="<aoai-embedding-model>",
)
ingestion_parameters = KnowledgeSourceIngestionParameters(
content_extraction_mode="standard",
ai_services=AIServices(
uri="<foundry-resource-endpoint>",
api_key="<foundry-resource-key>",
),
embedding_model=KnowledgeSourceAzureOpenAIVectorizer(
azure_open_ai_parameters=embedding_parameters
),
chat_completion_model=KnowledgeBaseAzureOpenAIModel(
azure_open_ai_parameters=AzureOpenAIVectorizerParameters(
resource_url="<aoai-endpoint>",
deployment_name="<aoai-gpt-deployment>",
model_name="<aoai-gpt-model>",
)
),
)
knowledge_source = FileKnowledgeSource(
name="my-file-ks",
file_parameters=FileKnowledgeSourceParameters(
ingestion_parameters=ingestion_parameters
),
)
index_client.create_or_update_knowledge_source(knowledge_source)
print(f"Configured standard extraction for '{knowledge_source.name}'.")
Reference :SearchIndexClient
PUT {{search-endpoint}}/knowledgesources/my-file-ks?api-version=2026-08-01-preview
Content-Type: application/json
Authorization: Bearer {{search-access-token}}
Prefer: return=representation
{
"name": "my-file-ks",
"kind": "file",
"description": "This knowledge source uses standard extraction.",
"fileParameters": {
"ingestionParameters": {
"embeddingModel": {
"kind": "azureOpenAI",
"azureOpenAIParameters": {
"resourceUri": "{{aoai-endpoint}}",
"deploymentId": "{{aoai-embedding-deployment}}",
"modelName": "{{aoai-embedding-model}}"
}
},
"chatCompletionModel": {
"kind": "azureOpenAI",
"azureOpenAIParameters": {
"resourceUri": "{{aoai-endpoint}}",
"deploymentId": "{{aoai-gpt-deployment}}",
"modelName": "{{aoai-gpt-model}}"
}
},
"contentExtractionMode": "standard",
"aiServices": {
"uri": "{{foundry-resource-endpoint}}",
"apiKey": "{{foundry-resource-key}}"
}
}
}
}
Référence :Sources de connaissances - Créer ou mettre à jour
CORS pour les opérations de fichier
Pour autoriser les opérations de fichier basées sur le navigateur, définissez corsOptions sur la source de connaissances de fichier avec les origines approuvées et la durée maximale du cache de préversion pour votre application.
Important
Dans la version de l’API corsOptions, 2026-08-01-preview s’applique aux points de terminaison de téléversement de fichiers, de liste, de mise à jour et de suppression, quel que soit le mode d’extraction. Si vous omettez corsOptions, la source de connaissances du fichier n’a pas de stratégie d’origine croisée du navigateur. CORS n’autorise pas les demandes. L’activation des origines peut exposer les opérations de service et les données dans un contexte de navigateur et introduire des risques de sécurité. Spécifiez uniquement les origines approuvées et n’utilisez pas d’origine générique en production. Pour les demandes de navigateur, utilisez l’authentification par jeton Microsoft Entra avec le rôle minimal requis. N’exposez jamais de jetons d’accès ou de clés de service dans le code du navigateur.
Télécharger des fichiers
Après avoir créé la source de connaissances, chargez les fichiers directement vers celui-ci. Chaque chargement est un appel synchrone : Recherche Azure AI extrait du contenu, le segment, crée des incorporations si nécessaire, indexe les blocs et conserve les métadonnées de fichier avant que l’appel ne retourne. Vous n’avez pas besoin de configurer ou d’exécuter un pipeline d’ingestion distinct.
Pour obtenir de l’aide sur les erreurs liées au chargement et à la gestion des fichiers, consultez Résoudre les problèmes liés aux opérations de fichier.
Charger un fichier brut
Pour un téléversement brut, le fileName indiqué provient de l’en-tête Content-Disposition: attachment; filename="...". Les appels REST et le KIT de développement logiciel (SDK) .NET définissent directement cet en-tête, tandis que le SDK Python accepte un paramètre filename et génère automatiquement l’en-tête. Si vous ne fournissez pas de nom de fichier, le service affecte un fichier généré fileNameautomatiquement.
Les noms de fichiers peuvent inclure un chemin d’accès relatif, tel que manuals/installation-guide.pdf. Le service convertit les antislashs en slashs. Il rejette les chemins absolus, les segments de chemin vides, les segments . ou .., les segments contenant des deux-points et les caractères non valides dans les noms de fichier avec le code d’état HTTP 400.
using Azure.Identity;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new DefaultAzureCredential());
string fileName = "installation-guide.pdf";
byte[] fileBytes = await File.ReadAllBytesAsync(fileName);
string contentDisposition = $"attachment; filename=\"{fileName}\"";
KnowledgeSourceFile uploadedFile = (await indexClient.UploadKnowledgeSourceFileAsync(
"my-file-ks",
contentDisposition,
BinaryData.FromBytes(fileBytes))).Value;
Console.WriteLine($"Uploaded file ID: {uploadedFile.FileId}");
from pathlib import Path
from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
index_client = SearchIndexClient(endpoint="<search-endpoint>", credential=DefaultAzureCredential())
file_path = Path("installation-guide.pdf")
uploaded_file = index_client.upload_knowledge_source_file(
"my-file-ks",
file_path.read_bytes(),
filename=file_path.name,
)
print(f"Uploaded file ID: {uploaded_file.file_id}")
POST {{search-endpoint}}/knowledgesources/my-file-ks/files?api-version=2026-08-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/octet-stream
Content-Disposition: attachment; filename="installation-guide.pdf"
<binary file content>
Charger un fichier avec des métadonnées facultatives
À compter de la version de l’API 2026-08-01-preview , utilisez une requête multipart pour charger un fichier binaire avec des métadonnées personnalisées facultatives. La requête inclut exactement une content partie et une partie JSON metadata facultative.
Si les deux noms sont spécifiés, metadata.fileName prend le pas sur le nom de fichier dans la partie content. Si aucun des deux n’est spécifié, le service affecte un nom de fichier généré automatiquement.
using Azure.Identity;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new DefaultAzureCredential());
var metadata = new FileUploadMetadata
{
FileName = "installation-guide.pdf",
Metadata =
{
["department"] = "support",
["product"] = "contoso-100"
}
};
#pragma warning disable SCME0004
var request = new UploadKnowledgeSourceFileMultipartRequest(
metadata,
"installation-guide.pdf");
KnowledgeSourceFile uploadedFile = (await indexClient
.UploadKnowledgeSourceFileMultipartAsync("my-file-ks", request)).Value;
#pragma warning restore SCME0004
Console.WriteLine($"Uploaded file ID: {uploadedFile.FileId}");
Reference :SearchIndexClient.UploadKnowledgeSourceFileMultipartAsync
from pathlib import Path
from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
FileUploadMetadata,
UploadKnowledgeSourceFileMultipartRequest,
)
index_client = SearchIndexClient(endpoint="<search-endpoint>", credential=DefaultAzureCredential())
file_path = Path("installation-guide.pdf")
request = UploadKnowledgeSourceFileMultipartRequest(
metadata=FileUploadMetadata(
file_name=file_path.name,
metadata={"department": "support", "product": "contoso-100"},
),
content=(file_path.name, file_path.read_bytes(), "application/pdf"),
)
uploaded_file = index_client.upload_knowledge_source_file_multipart(
name="my-file-ks",
body=request,
)
print(f"Uploaded file ID: {uploaded_file.file_id}")
Référence :SearchIndexClient.upload_knowledge_source_file_multipart
POST {{search-endpoint}}/knowledgesources('my-file-ks')/files?api-version=2026-08-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: multipart/form-data; boundary=file-boundary
--file-boundary
Content-Disposition: form-data; name="metadata"
Content-Type: application/json
{
"fileName": "installation-guide.pdf",
"metadata": {
"department": "support",
"product": "contoso-100"
}
}
--file-boundary
Content-Disposition: form-data; name="content"; filename="installation-guide.pdf"
Content-Type: application/octet-stream
< ./installation-guide.pdf
--file-boundary--
Note
Le chargement d’un fichier ne remplace pas un fichier existant, même si vous réutilisez le même fileNamefichier . Chaque téléversement réussi crée un nouveau fichier avec son propre fileId, de sorte que la liste des fichiers téléversés peut contenir plusieurs entrées ayant le même fileName.
Avec 2026-05-01-preview, remplacez le contenu en supprimant le fichier précédent et en chargeant le remplacement. Avec 2026-08-01-preview, utilisez l’opération de mise à jour.
Répertorier les fichiers chargés
Lister les fichiers sur la source de connaissances pour examiner l’ensemble des fichiers téléchargés.
using Azure.Identity;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new DefaultAzureCredential());
await foreach (KnowledgeSourceFile file in indexClient.GetKnowledgeSourceFilesAsync("my-file-ks"))
{
Console.WriteLine($"{file.FileName} ({file.FileSizeBytes} bytes) error={file.ErrorMessage}");
}
from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
index_client = SearchIndexClient(endpoint="<search-endpoint>", credential=DefaultAzureCredential())
for file in index_client.list_knowledge_source_files("my-file-ks"):
print(f"{file.file_name} ({file.file_size_bytes} bytes) error={file.error_message}")
GET {{search-endpoint}}/knowledgesources/my-file-ks/files?api-version=2026-08-01-preview
Authorization: Bearer {{search-access-token}}
Référence :Sources de connaissances - Répertorier les fichiers
La réponse inclut des métadonnées pour chaque fichier chargé. Les fichiers répertoriés avec succès ont la errorMessage valeur null.
{
"value": [
{
"fileId": "file-abc123",
"fileName": "installation-guide.pdf",
"fileSizeBytes": 1048576,
"createdAt": "2026-05-07T18:10:00Z",
"lastUpdatedAt": "2026-05-07T18:14:00.803Z",
"errorMessage": null
}
]
}
Si un nouveau chargement échoue, la requête retourne une erreur et ne crée pas d’enregistrement de métadonnées de fichier. Le chargement ayant échoué n’apparaît pas dans les résultats de liste ultérieurs et n’est pas facturé.
Si un échec d’accès au modèle se produit et que la ressource Foundry qui héberge le modèle d’incorporation utilise la mise en réseau privée, vérifiez que la foundry_account liaison privée partagée est approuvée et que le contournement des services approuvés est activé. Un bypass désactivé renvoie 403 Public access is disabled. Pour plus d’informations sur l’installation, consultez Conditions préalables.
Répertorier et filtrer des fichiers
À compter de la version de l’API 2026-08-01-preview , utilisez prefix pour filtrer les fichiers par chemin d’accès relatif ou search pour filtrer par préfixe de nom de fichier. Définissez pageSize pour contrôler le nombre de résultats.
using Azure.Identity;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new DefaultAzureCredential());
await foreach (KnowledgeSourceFile file in indexClient.GetKnowledgeSourceFilesAsync(
"my-file-ks",
prefix: "manuals/",
pageSize: 100))
{
Console.WriteLine($"{file.FileName} ({file.FileId})");
}
from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
index_client = SearchIndexClient(endpoint="<search-endpoint>", credential=DefaultAzureCredential())
files = index_client.list_knowledge_source_files(
"my-file-ks",
prefix="manuals/",
page_size=100,
)
for file in files:
print(f"{file.file_name} ({file.file_id})")
GET {{search-endpoint}}/knowledgesources('my-file-ks')/files?api-version=2026-08-01-preview&prefix=manuals/&pageSize=100
Authorization: Bearer {{search-access-token}}
Référence :Sources de connaissances - Répertorier les fichiers
La réponse inclut les modes d’analyse et d’extraction sélectionnés par le service, ainsi que les métadonnées utilisateur pour la gestion des fichiers. Les métadonnées utilisateur ne peuvent pas faire l’objet d’une recherche ni d’un filtre.
{
"value": [
{
"fileId": "file-abc123",
"fileName": "manuals/installation-guide.md",
"prefix": "manuals/",
"metadata": {
"department": "support",
"product": "contoso-100"
},
"parsingMode": "markdown",
"extractionMode": "minimal",
"fileSizeBytes": 1048576,
"createdAt": "2026-08-03T18:10:00Z",
"lastUpdatedAt": "2026-08-03T18:14:00Z",
"errorMessage": null
}
],
"@odata.nextLink": "<service-generated continuation URL>"
}
Pour récupérer tous les résultats, suivez @odata.nextLink jusqu’à ce qu’il soit absent. Envoyez l’URL complète exactement comme retourné, sans modifier les paramètres de requête.
Mettre à jour un fichier chargé
À partir de la version de l’API 2026-08-01-preview, mettez à jour un fichier à l’aide de son fileId. La requête multipart nécessite la partie binaire content . La partie JSON de métadonnées est facultative. Par conséquent, une mise à jour de contenu uniquement est prise en charge. Une mise à jour de métadonnées uniquement n’est pas prise en charge.
using Azure.Identity;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new DefaultAzureCredential());
var metadata = new FileUploadMetadata
{
FileName = "installation-guide.pdf",
Metadata =
{
["department"] = "support",
["product"] = "contoso-200"
}
};
#pragma warning disable SCME0004
var request = new UpdateKnowledgeSourceFileRequest(
metadata,
"installation-guide.pdf");
KnowledgeSourceFile updatedFile = (await indexClient.UpdateKnowledgeSourceFileAsync(
fileId,
"my-file-ks",
request)).Value;
#pragma warning restore SCME0004
Console.WriteLine($"Updated file ID: {updatedFile.FileId}");
from pathlib import Path
from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
FileUploadMetadata,
UpdateKnowledgeSourceFileRequest,
)
index_client = SearchIndexClient(endpoint="<search-endpoint>", credential=DefaultAzureCredential())
file_path = Path("installation-guide.pdf")
request = UpdateKnowledgeSourceFileRequest(
metadata=FileUploadMetadata(
file_name=file_path.name,
metadata={"department": "support", "product": "contoso-200"},
),
content=(file_path.name, file_path.read_bytes(), "application/pdf"),
)
updated_file = index_client.update_knowledge_source_file(
name="my-file-ks",
file_id=file_id,
body=request,
)
print(f"Updated file ID: {updated_file.file_id}")
PUT {{search-endpoint}}/knowledgesources('my-file-ks')/files('{{file-id}}')?api-version=2026-08-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: multipart/form-data; boundary=file-boundary
--file-boundary
Content-Disposition: form-data; name="metadata"
Content-Type: application/json
{
"fileName": "installation-guide.pdf",
"metadata": {
"department": "support",
"product": "contoso-200"
}
}
--file-boundary
Content-Disposition: form-data; name="content"; filename="installation-guide.pdf"
Content-Type: application/octet-stream
< ./installation-guide.pdf
--file-boundary--
Référence :Sources de connaissances - Fichier de mise à jour
En cas d’échec d’une mise à jour, l’enregistrement de métadonnées précédent reste. Ne supposez pas qu’une mise à jour modifie le contenu indexé de façon transactionnelle.
Supprimer les fichiers chargés
Supprimez les fichiers de la source de connaissances lorsque vous ne souhaitez plus qu’ils soient disponibles pour la récupération.
using Azure.Identity;
using Azure.Search.Documents.Indexes;
var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new DefaultAzureCredential());
await indexClient.DeleteKnowledgeSourceFileAsync("my-file-ks", "file-abc123");
from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
index_client = SearchIndexClient(endpoint="<search-endpoint>", credential=DefaultAzureCredential())
index_client.delete_knowledge_source_file("my-file-ks", "file-abc123")
DELETE {{search-endpoint}}/knowledgesources/my-file-ks/files/file-abc123?api-version=2026-08-01-preview
Authorization: Bearer {{search-access-token}}
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
Une fois la base de connaissances configurée, appelez l’action de récupération ou le point de terminaison MCP 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 :
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}"); }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 de recherche.
# 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 de recherche.
### 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 :Sources de connaissances - Supprimer
Résoudre les problèmes liés aux opérations sur les fichiers
Les codes d’état suivants sont spécifiques aux opérations de source de connaissances de fichier.
| Code de statut | Cause et action |
|---|---|
400 |
Le fichier est vide, ne contient aucun texte extractible, a un chemin relatif non sécurisé ou a une demande de continuation non valide. Vérifiez que le fichier contient un contenu pris en charge et lisible, et qu’il possède un nom de fichier valide. Pour les opérations de liste, suivez @odata.nextLink exactement tel que renvoyé. Ne pas combiner $skiptoken avec search ou pageSize. |
409 |
La source de connaissances de fichier a atteint la limite de fichiers pour la version de l’API. Supprimez les fichiers avant de charger davantage. |
415 |
Le service a détecté un type MIME non pris en charge ou a détecté une image alors que la source de connaissances utilise une extraction minimale. Utilisez un format pris en charge. Pour les images, utilisez l’extraction standard. La modification du type de contenu fourni par l’appelant ne remplace pas la détection. |
429 |
La file d’attente de traitement est complète. Utilisez le parallélisme borné et réessayez avec un délai d’attente exponentiel. Le service ne garantit pas un en-tête Retry-After. |
504 |
Le traitement a dépassé 180 secondes pendant le chargement ou la mise à jour du fichier. Réduisez la taille ou la complexité du fichier et réessayez. |