Créer une source de connaissances de type fichier (version préliminaire)

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=standard paramè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 source de connaissances spécifie le standard mode 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 --prerelease

  • Pour l’authentification sans clé, le Azure.Identity package : dotnet add package Azure.Identity

  • Le dernier paquet azure-search-documents (préversion) : pip install --pre azure-search-documents

  • Pour l’authentification sans clé, le azure-identity package : pip install azure-identity

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 :

  • PDF
  • 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-preview et 2026-08-01-preview prennent en charge minimal. standard est disponible uniquement dans 2026-08-01-preview.

  • Le contenu détecté comme image/* n’est pas pris en charge dans 2026-05-01-preview. Dans 2026-08-01-preview, utilisez l’extraction standard. minimal l’extraction renvoie le code d’état HTTP 415 dans 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}");

Reference :SearchIndexClient.UploadKnowledgeSourceFileAsync

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}")

Référence :SearchIndexClient.upload_knowledge_source_file

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>

Référence :Sources de connaissances - Charger un fichier

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--

Référence :Sources de connaissances - Charger un fichier

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}");
}

Reference :SearchIndexClient.GetKnowledgeSourceFilesAsync

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}")

Référence :SearchIndexClient.list_knowledge_source_files

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})");
}

Reference :SearchIndexClient.GetKnowledgeSourceFilesAsync

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})")

Référence :SearchIndexClient.list_knowledge_source_files

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}");

Reference :SearchIndexClient.UpdateKnowledgeSourceFileAsync

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}")

Référence :SearchIndexClient.update_knowledge_source_file

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");

Reference :SearchIndexClient.DeleteKnowledgeSourceFileAsync

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")

Référence :SearchIndexClient.delete_knowledge_source_file

DELETE {{search-endpoint}}/knowledgesources/my-file-ks/files/file-abc123?api-version=2026-08-01-preview
Authorization: Bearer {{search-access-token}}

Référence :Sources de connaissances - Supprimer un fichier

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 :

  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}");
    }
    

    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"
         }
         ]
     }
    
  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
     }
    
  3. 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

  4. Supprimez la source de connaissances.

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

    Reference :SearchIndexClient

  1. 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"
         }
         ]
     }
    
  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"
       }
     }
    
  3. 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

  4. 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

  1. 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"
         }
         ]
     }
    
  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"
       }
     }
    
  3. 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

  4. 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.