Creación de un origen de conocimiento de archivos (versión preliminar)

Note

Búsqueda de Azure AI está disponible a través del portal de Azure, las API REST y los SDK de Azure. También respalda Foundry IQ, la capa de conocimiento administrada que transforma el contenido empresarial en bases de conocimiento reutilizables y compatibles con permisos para agentes en el portal de Microsoft Foundry.

Importante

Las características, funcionalidades o propiedades marcadas (versión preliminar) no están cubiertas por un contrato de nivel de servicio, no se recomiendan para cargas de trabajo de producción y pueden cambiar o restringirse antes de que estén disponibles con carácter general. Los términos de la versión preliminar Búsqueda de Azure AI se aplican a todas las funciones de vista previa, ya sea independiente o parte de una característica disponible con carácter general.

Un origen de conocimiento de archivos (versión preliminar) carga conjuntos de archivos pequeños a medianos directamente en Búsqueda de Azure AI para la recuperación agente. Los orígenes de conocimiento se crean de forma independiente, se hace referencia en una base de conocimiento y se usan como datos de base cuando se consulta la base de conocimiento en tiempo de ejecución.

Las fuentes de conocimientos de archivos son útiles cuando se desea una experiencia de carga administrada en lugar de aprovisionar Azure Storage, configurar el acceso y crear una canalización del indexador sobre un contenedor externo. Búsqueda de Azure AI procesa los archivos cargados para que su contenido extraído se pueda recuperar de una base de conocimiento.

Utilice una fuente de conocimiento de blobs en su lugar cuando sus archivos ya se encuentren en Azure Blob Storage o Azure Data Lake Storage Gen2, cuando su conjunto de archivos supere o sea probable que supere los límites de la fuente de conocimiento de archivos, o cuando necesite una ingesta programada. Use también un origen de conocimiento de blobs cuando quiera administrar blobs de origen con directivas de administración del ciclo de vida de Azure Blob Storage o cuando necesite permisos de nivel de documento (versión preliminar) en función de los permisos de Azure Storage.

Soporte para el uso

Azure Portal Portal de Microsoft Foundry SDK de .NET SDK de Python SDK de Java SDK de JavaScript REST API
❌ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️

Prerrequisitos

  • Un servicio de Búsqueda de Azure AI en cualquier región que proporcione recuperación mediante agentes. Las fuentes de conocimiento de archivo son compatibles con ambos modelos de precios, Dedicated y Serverless. Para obtener información sobre el modelo y el nivel, consulte Elegir un modelo de precios y un nivel de servicio.

  • Consulte los costes de Búsqueda de Azure AI. Las llamadas al modelo, la vectorización y otro procesamiento de IA pueden conllevar cargos independientes.

  • En Serverless, las operaciones de ingesta de archivos realizadas correctamente consumen capacidad de cómputo facturable. Las subidas fallidas no generan cargos de computación sin servidor.

  • Si necesita recuperación agéntica de pago más allá de la cuota mensual gratuita, habilite el plan estándar de recuperación agéntica. La knowledgeRetrieval=standard configuración es independiente de los cargos de proceso y almacenamiento sin servidor y no selecciona un modelo de precios.

  • Archivos en un formato compatible.

  • Permiso para crear orígenes de conocimiento. Configure la autenticación sin clave con el rol Colaborador del servicio de búsqueda asignado a su cuenta de usuario (recomendado) o use una clave de API de administrador.

  • Si el origen de conocimiento especifica un modelo de Azure OpenAI para inserciones, el servicio de búsqueda debe tener una identidad administrada con permisos de Usuario de Cognitive Services en el recurso de Microsoft Foundry.

    • Si el recurso Foundry tiene deshabilitado el acceso a la red pública, cree un foundry_accountvínculo privado compartido desde el servicio de búsqueda al recurso Foundry y mantenga habilitados los servicios Allow Azure del recurso en la configuración de lista de servicios de confianza.

  • Si la fuente de conocimiento especifica el modo de extracción de contenido standard, revise los requisitos de la habilidad Azure Content Understanding.

    • El uso se factura según los precios de Azure Content Understanding en Foundry Tools al recurso de Foundry configurado a través de aiServices.

    • La cuota diaria gratuita de 20 documentos disponible para algunas habilidades integradas no se aplica.

    • Para el ejemplo de este artículo, necesita el punto de conexión y la clave del recurso de Foundry, además de la información del modelo de incrustación y del modelo de finalización de chat de Azure OpenAI.

  • El paquete de versión preliminar Azure.Search.Documents más reciente: dotnet add package Azure.Search.Documents --prerelease

  • Para la autenticación sin claves, el Azure.Identity paquete: dotnet add package Azure.Identity

  • El paquete de versión preliminar azure-search-documents más reciente: pip install --pre azure-search-documents

  • Para la autenticación sin claves, el azure-identity paquete: pip install azure-identity

Compatibilidad con archivos y límites

Antes de crear un origen de conocimiento de archivos, revise los requisitos y los límites que afectan a la carga, extracción y administración de archivos.

Tipos de contenido compatibles

Los orígenes de conocimiento de archivos aceptan archivos basados en el tipo de contenido detectado. Un tipo de contenido proporcionado por el autor de la llamada no invalida la detección.

Los tipos de contenido admitidos incluyen:

  • PDF
  • Word (.doc, .docx)
  • PowerPoint (.ppt, .pptx)
  • Excel (.xls, .xlsx)
  • JSON
  • Scripts de shell
  • Contenido detectado como text/*, como .txt, .md, y .html.csv

Modos de extracción admitidos

  • Para los tipos de contenido enumerados, tanto 2026-05-01-preview como 2026-08-01-preview admiten minimal. standard solo está disponible en 2026-08-01-preview.

  • El contenido detectado como image/* no se admite en 2026-05-01-preview. En 2026-08-01-preview, utilice extracción standard. minimal la extracción devuelve el estado HTTP 415 en ambas versiones.

Límites y operaciones con archivos

Los límites y las operaciones de archivo admitidas difieren en función de la versión de API.

Capacidad 2026-05-01-preview 2026-08-01-preview
Número máximo de archivos por origen de conocimiento 100 200
Tamaño de archivo máximo 50 MB en todos los planes de tarifa admitidos 50 MB en Gratis y Básico; 100 MB en otros niveles dedicados admitidos y sin servidor
Duración del procesamiento La carga puede durar hasta 180 segundos La carga y la actualización se pueden ejecutar hasta 180 segundos.
Carga de contenido y metadatos Contenido sin procesar del archivo Contenido de archivo sin formato o contenido de varias partes con metadatos
Enumerar archivos cargados Enumerar archivos Filtre por ruta de acceso o nombre de archivo y devuelva detalles de archivo más enriquecidos.
Reemplazar el contenido del archivo existente Eliminar y volver a cargar Uso de la operación de actualización
Acceso del explorador a las operaciones de archivos CORS no está disponible Configuración de CORS

Note

  • El índice de búsqueda generado almacena el contenido cargado. Para conocer los límites de almacenamiento totales por plan de tarifa, consulte Límites de servicio.
  • Si configura la fuente de conocimiento de archivos para fragmentar o vectorizar el contenido cargado, también se aplican los límites del modelo y del procesamiento posterior.

Comprobación de orígenes de conocimiento existentes

Un origen de conocimiento es un objeto reutilizable de nivel superior. Conocer los orígenes de conocimiento existentes resulta útil para reutilizar o asignar nombres a nuevos objetos.

Ejecute el código siguiente para enumerar los orígenes de conocimiento por nombre y tipo.

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

Reference:Knowledge Sources - List

También puede devolver un único origen de conocimiento por nombre para revisar la definición JSON de este.

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

Referencia:Orígenes de conocimiento - Obtener

El siguiente json es una respuesta de ejemplo para un origen de conocimiento de archivos.

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

Creación de un origen de conocimiento

Cree un origen de conocimiento de archivo que especifique el modelo de inserción que se usa para vectorizar el contenido cargado.

Cada origen de conocimiento de archivo crea un índice, pero no un indexador ni una programación. Debe incluir el objeto fileParameters.ingestionParameters. El servicio rechaza las solicitudes que especifican 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"
    }
  }
}

Referencia:Orígenes de conocimiento: crear o actualizar

Configuración de la extracción estándar

A partir de la versión de la API 2026-08-01-preview, la extracción con standard usa Content Understanding para extraer, dividir en fragmentos semánticos y enriquecer los archivos cargados. Búsqueda de Azure AI administra este procesamiento como parte del origen de conocimiento y los cargos de Content Understanding se aplican por separado.

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

Referencia:Orígenes de conocimiento: crear o actualizar

CORS para operaciones de archivos

Para permitir operaciones con archivos basadas en el navegador, configure corsOptions en la fuente de conocimiento de archivos con los orígenes de confianza y la duración máxima de la caché de comprobación previa para su aplicación.

Importante

En la versión de la API 2026-08-01-preview, corsOptions se aplica a los extremos de carga de archivos, listado, actualización y eliminación, independientemente del modo de extracción. Si omite corsOptions, la fuente de conocimiento de archivos no tendrá ninguna directiva de origen cruzado del navegador. CORS no autoriza las solicitudes. Habilitar orígenes puede exponer operaciones del servicio y datos en un contexto de navegador e introducir riesgos de seguridad. Especifique solo orígenes de confianza y no use un origen comodín en producción. Para las solicitudes del navegador, use la autenticación mediante token de Microsoft Entra con el rol mínimo requerido. Nunca exponga tokens de acceso ni claves de servicio en el código del explorador.

Cargar archivos

Después de crear el origen de conocimiento, cargue los archivos directamente en él. Cada carga es una llamada sincrónica: Búsqueda de Azure AI extrae contenido, lo fragmenta, crea inserciones cuando es necesario, indexa los fragmentos y conserva los metadatos de archivo antes de que se devuelva la llamada. No es necesario configurar ni ejecutar una canalización de ingesta independiente.

Para obtener ayuda con errores relacionados con la carga y administración de archivos, consulte Solución de problemas de operaciones de archivos.

Sube un archivo RAW

Para una carga en bruto, el fileName indicado procede del encabezado Content-Disposition: attachment; filename="...". Las llamadas REST y el SDK de .NET establecen este encabezado directamente, mientras que el SDK de Python acepta un parámetro filename y compila automáticamente el encabezado. Si no proporciona un nombre de archivo, el servicio asigna un generado automáticamente fileName.

Los nombres de archivo pueden incluir una ruta de acceso relativa, como manuals/installation-guide.pdf. El servicio normaliza las barras invertidas a barras diagonales. Rechaza rutas absolutas, segmentos de ruta vacíos, segmentos . o .., segmentos que contienen dos puntos y caracteres no válidos en nombres de archivo con el estado 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}")

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

Referencia:Orígenes de conocimiento- Cargar archivo

Carga de un archivo con metadatos opcionales

A partir de la versión de la 2026-08-01-preview API, use una solicitud de varias partes para cargar un archivo binario con metadatos personalizados opcionales. La solicitud incluye exactamente una content parte y una parte JSON metadata opcional.

Si se especifican ambos nombres, metadata.fileName tiene prioridad sobre el nombre de archivo de la content parte. Si no se especifica ninguno, el servicio asigna un nombre de archivo generado automáticamente.

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

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

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

Referencia:Orígenes de conocimiento- Cargar archivo

Note

La carga de un archivo no reemplaza un archivo existente, aunque reutilice el mismo fileName. Cada carga correcta crea un nuevo archivo con su propio fileId, por lo que la lista de archivos cargados puede contener varias entradas que comparten un fileName.

Con 2026-05-01-preview, reemplace el contenido eliminando el archivo anterior y cargando el reemplazo. Con 2026-08-01-preview, use la operación de actualización.

Enumerar archivos cargados

Enumera los archivos del origen de conocimiento para inspeccionar el conjunto de archivos cargados.

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

Referencia:SearchIndexClient.list_knowledge_source_files

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

Referencia:Orígenes de conocimiento: Enumerar archivos

La respuesta incluye metadatos para cada archivo cargado. Los archivos incluidos correctamente en la lista tienen un valor errorMessage de 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 se produce un error en una nueva carga, la solicitud devuelve un error y no crea un registro de metadatos de archivo. La carga fallida no aparece en resultados de listas posteriores y no se cobra.

Si se produce un error al acceder al modelo y el recurso de Foundry que hospeda el modelo de incrustación usa redes privadas, confirme que el foundry_account enlace privado compartido está aprobado y que la omisión para servicios de confianza está habilitada. Una omisión deshabilitada devuelve 403 Public access is disabled. Para obtener más información sobre la configuración, consulte Requisitos previos.

Enumerar y filtrar archivos

A partir de la versión de la 2026-08-01-preview API, use prefix para filtrar los archivos por ruta de acceso relativa o search para filtrar por prefijo de nombre de archivo. Configure pageSize para controlar el número de resultados.

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

Referencia: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}}

Referencia:Orígenes de conocimiento: Enumerar archivos

La respuesta incluye modos de análisis y extracción seleccionados por el servicio, así como metadatos de usuario para la administración de archivos. Los metadatos del usuario no se pueden buscar ni filtrar.

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

Para obtener todos los resultados, siga @odata.nextLink hasta que no aparezca. Envíe la dirección URL completa exactamente como se devuelve, sin cambiar los parámetros de consulta.

Actualización de un archivo cargado

A partir de la versión 2026-08-01-preview de la API, actualice un archivo mediante su fileId. La solicitud de varias partes requiere la parte binaria content . El elemento JSON de metadatos es opcional, por lo que se admite una actualización solo de contenido. No se admite una actualización de solo metadatos.

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

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

Referencia:Orígenes de conocimiento: Actualizar archivo

Si se produce un error en una actualización, el registro de metadatos anterior permanece. No suponga que una actualización cambia el contenido indexado transaccionalmente.

Eliminación de archivos cargados

Elimine los archivos del origen de conocimiento cuando ya no desee que estén disponibles para su recuperación.

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

Referencia: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}}

Referencia:Orígenes de conocimiento: Eliminar archivo

Asignar a una base de conocimiento

Si está satisfecho con el origen de conocimiento, agréguelo a una base de conocimiento.

Consulta de una base de conocimiento

Una vez configurada la base de conocimiento, llame a la acción de recuperación o al punto de conexión de MCP para consultar el origen de conocimiento.

Eliminación de un origen de conocimiento

Para poder eliminar un origen de conocimiento, debe eliminar cualquier base de conocimiento que haga referencia a ella o actualizar la definición de la base de conocimiento para quitar la referencia. En el caso de los orígenes de conocimiento que generan una canalización de índice e indexador, también se eliminan todos los objetos generados . Sin embargo, si usó un índice existente para crear un origen de conocimiento, el índice no se eliminará.

Si intenta eliminar un origen de conocimiento que está en uso, se produce un error en la acción y devuelve una lista de bases de conocimiento afectadas.

Para eliminar un origen de conocimiento:

  1. Obtenga una lista de todas las bases de conocimiento del servicio de búsqueda.

    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

    Una respuesta de ejemplo podría ser similar a la siguiente:

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

  2. Obtenga una definición de base de conocimiento individual para comprobar si hay referencias de origen de conocimiento.

    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

    Una respuesta de ejemplo podría ser similar a la siguiente:

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

  3. Elimine la base de conocimiento o, si tiene varios orígenes de conocimiento, actualice la base de conocimiento para quitar el origen. En este ejemplo se muestra la eliminación.

    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. Elimine el origen de conocimiento.

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

    Reference:SearchIndexClient

  1. Obtenga una lista de todas las bases de conocimiento del servicio de búsqueda.

    # 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

    Una respuesta de ejemplo podría ser similar a la siguiente:

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

  2. Obtenga una definición de base de conocimiento individual para comprobar si hay referencias de origen de conocimiento.

    # 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

    Una respuesta de ejemplo podría ser similar a la siguiente:

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

  3. Elimine la base de conocimiento o, si tiene varios orígenes de conocimiento, actualice la base de conocimiento para quitar el origen. En este ejemplo se muestra la eliminación.

    # 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. Elimine el origen de conocimiento.

    # 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. Obtenga una lista de todas las bases de conocimiento del servicio de búsqueda.

    ### Get knowledge bases
GET {{search-url}}/knowledgebases?api-version={{api-version}}&$select=name
Authorization: Bearer {{token}}

    Reference:Knowledge Bases - List

    Una respuesta de ejemplo podría ser similar a la siguiente:

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

  2. Obtenga una definición de base de conocimiento individual para comprobar si hay referencias de origen de conocimiento.

    ### Get a knowledge base definition
GET {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version={{api-version}}
Authorization: Bearer {{token}}

    Reference:Bases de Conocimiento - Obtener

    Una respuesta de ejemplo podría ser similar a la siguiente:

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

  3. Elimine la base de conocimiento o, si tiene varios orígenes de conocimiento, actualice la base de conocimiento para quitar el origen. En este ejemplo se muestra la eliminación.

    ### Delete a knowledge base
DELETE {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version={{api-version}}
Authorization: Bearer {{token}}

    Referencia:Bases de Conocimiento - Eliminar

  4. Elimine el origen de conocimiento.

    ### Delete a knowledge source
DELETE {{search-url}}/knowledgesources/{{knowledge-source-name}}?api-version={{api-version}}
Authorization: Bearer {{token}}

    Referencia:Orígenes de conocimiento: Eliminar

Solucionar problemas de operaciones de archivos

Los siguientes códigos de estado son específicos de las operaciones de origen de conocimiento de archivos.

Código de estado Causa y acción
400 El archivo está vacío, no contiene texto que se pueda extraer, tiene una ruta de acceso relativa no segura o tiene una solicitud de continuación no válida. Compruebe que el archivo tiene contenido compatible, legible y un nombre de archivo válido. Para las operaciones de listado, siga @odata.nextLink exactamente tal y como se devuelve. No se combine $skiptoken con search ni pageSize.
409 La fuente de conocimiento de archivos ha alcanzado el límite de archivos para la versión de la API. Elimine los archivos antes de cargar más.
415 El servicio ha detectado un tipo MIME no compatible, o ha detectado una imagen mientras que la fuente de conocimiento utiliza extracción mínima. Use un formato compatible. En el caso de las imágenes, use la extracción estándar. Cambiar solo el tipo de contenido proporcionado por el autor de la llamada no invalida la detección.
429 La cola de procesamiento está llena. Utilice paralelismo acotado y vuelva a intentarlo con retroceso exponencial. El servicio no garantiza un Retry-After encabezado.
504 El procesamiento superó los 180 segundos durante la carga o actualización de archivos. Reduzca el tamaño o la complejidad del archivo e inténtelo de nuevo.

Contenido relacionado

  • Last updated on