Dosya bilgi kaynağı oluşturma (önizleme)

Note

Azure Yapay Zeka Arama Azure portalı, REST API'leri ve Azure SDK’ları aracılığıyla kullanılabilir. Ayrıca kuruluş içeriğini Microsoft Foundry portalındaki aracılar için yeniden kullanılabilir, izin kullanan bilgi bankalarına dönüştüren yönetilen bilgi katmanı Foundry IQ'yu temel alır.

Important

(önizleme) olarak işaretlenen özellikler, özellikler veya özellikler hizmet düzeyi sözleşmesi kapsamında değildir, üretim iş yükleri için önerilmez ve genel kullanıma sunulmadan önce değişebilir veya kısıtlanabilir. Azure Yapay Zeka Arama önizleme terimleri, tek başına veya genel kullanıma sunulan bir özelliğin parçası olsun, tüm önizleme işlevleri için geçerlidir.

Dosya bilgi kaynağı (önizleme), küçük ve orta boyutlu dosya kümelerini aracı tabanlı alma için doğrudan Azure Yapay Zeka Arama’e yükler. Bilgi kaynakları bağımsız olarak oluşturulur, bilgi bankasında başvurulur ve çalışma zamanında bilgi bankası sorgulandığında temel veri olarak kullanılır.

Dosya bilgi kaynakları, Azure Depolama’ı kullanıma alma, erişimi yapılandırma ve harici bir kapsayıcı üzerinde bir dizin oluşturucu işlem hattı oluşturma yerine yönetilen bir yükleme deneyimi istediğiniz durumlarda kullanışlıdır. Azure Yapay Zeka Arama, ayıklanan içeriklerin bir bilgi bankasından alınabilmesi için karşıya yüklenen dosyaları işler.

Dosyalarınız zaten Azure Blob Depolama veya Azure Data Lake Storage 2. Nesil olduğunda, dosya kümeniz dosya bilgi kaynağı sınırlarını aştığında veya aşma olasılığı yüksek olduğunda ya da zamanlanmış alıma ihtiyacınız olduğunda bunun yerine bir blob bilgi kaynağı kullanın. Ayrıca, Azure Blob Depolama yaşam döngüsü yönetim ilkeleriyle kaynak blobları yönetmek istediğinizde veya Azure Depolama izinlerine göre belge düzeyi izinlere (önizleme) ihtiyacınız olduğunda blob bilgi kaynağı kullanın.

Kullanım desteği

Azure portalı	Microsoft Foundry portalı	.NET SDK	Python SDK'sı	Java SDK	JavaScript SDK'sı	REST API
❌	✔️	✔️	✔️	✔️	✔️	✔️

Prerequisites

• Azure Yapay Zeka Arama hizmetinin her hangi bir bölgesinde özerk bilgi edinimini sağlayan. Dosya bilgi kaynakları hem Ayrılmış hem de Sunucusuz fiyatlandırma modellerini destekler. Model ve katman ayrıntıları için bkz. Fiyatlandırma modeli ve hizmet katmanı seçme.

• Azure Yapay Zeka Arama maliyetlerini gözden geçirin. Model çağrıları, vektörleştirme ve diğer yapay zeka işlemleri ayrı ücretlendirilebilir.

• Serverless'ta başarılı dosya içe aktarma işlemleri, faturalandırılabilir işlem kaynağı tüketir. Başarısız yüklemeler, Serverless işlem ücretleri oluşturmaz.

• Aylık ücretsiz kullanım hakkının ötesinde ücretli agentic retrieval'e ihtiyacınız varsa, standart agentic retrieval planını etkinleştirin. Bu knowledgeRetrieval=standard ayar Sunucusuz işlem ve depolama ücretlerinden ayrıdır ve bir fiyatlandırma modeli seçmez.

• Desteklenen biçimlerde dosyalar.

• Bilgi kaynakları oluşturma izni. Kullanıcı hesabınıza atanan Arama Hizmeti Katkıda Bulunanı rolüyle anahtarsız kimlik doğrulamasını yapılandırın (önerilir) veya bir yönetici API anahtarı kullanın.

• Bilgi kaynağı, gömmeler için bir Azure OpenAI modeli belirtiyorsa, arama hizmetinin Microsoft Foundry kaynağı üzerinde Cognitive Services User izinlerine sahip bir managed identity'si olmalıdır.

  • Foundry kaynağında genel ağ erişimi devre dışı bırakılmışsa, arama hizmetinden Dökümhane kaynağına paylaşılan bir foundry_accountözel bağlantı oluşturun ve kaynağın Güvenilen hizmetler listesinde Azure hizmetlerine izin ver ayarını etkin tutun.

• Bilgi kaynağı içerik ayıklama modunu belirtiyorsa standard, Azure Content Understanding becerisinin gereksinimlerini gözden geçirin.

  • Kullanım, aracılığıyla yapılandırılan Foundry kaynağı için aiServices üzerinden ücretlendirilir.

  • Bazı yerleşik beceriler için sağlanan 20 belgelik günlük ücretsiz izin geçerli değildir.

  • Bu makaledeki örnek için, Foundry kaynak uç noktası ve anahtarına ek olarak Azure OpenAI gömme ve sohbet tamamlama modeli bilgilerine ihtiyacınız vardır.

• En son Azure.Search.Documents önizleme paketi: dotnet add package Azure.Search.Documents --prerelease

• Anahtarsız kimlik doğrulaması için Azure.Identity paket: dotnet add package Azure.Identity

• En son azure-search-documents önizleme paketi: pip install --pre azure-search-documents

• Anahtarsız kimlik doğrulaması için azure-identity paket: pip install azure-identity

• Arama Hizmeti REST API'sinin 2026-08-01-preview sürümü.

• Anahtarsız kimlik doğrulaması için her HTTP isteğinin üst bilgisine Authorization bir Microsoft Entra ID belirteci ekleyin.

Dosya desteği ve sınırları

Dosya bilgi kaynağı oluşturmadan önce dosya yükleme, ayıklama ve yönetimi etkileyen gereksinimleri ve sınırları gözden geçirin.

Desteklenen içerik türleri

Dosya bilgi kaynakları algılanan içerik türüne göre dosyaları kabul eder. Arayan tarafından sağlanan içerik türü algılamayı geçersiz kılmaz.

Desteklenen içerik türleri şunlardır:

• PDF
• Word (.doc, .docx)
• PowerPoint (.ppt, .pptx)
• Excel (.xls, .xlsx)
• JSON
• Kabuk komut dosyaları
• .txt olarak algılanan içerik; örneğin .md, .html, text/* ve .csv

Desteklenen ayıklama modları

• Listelenen içerik türleri için hem 2026-05-01-preview hem de 2026-08-01-preview, minimal destekler. standard yalnızca 2026-08-01-preview içinde kullanılabilir.

• image/* olarak algılanan içerik, 2026-05-01-preview içinde desteklenmiyor. 2026-08-01-preview'da standard ayıklamasını kullanın. minimal ayıklama, her iki sürümde de HTTP durumunu 415 döndürür.

Sınırlar ve dosya işlemleri

Sınırlar ve desteklenen dosya işlemleri API sürümüne göre farklılık gösterir.

Capability	2026-05-01-preview	2026-08-01-preview
Bilgi kaynağı başına en fazla dosya sayısı	100	200
En büyük dosya boyutu	Desteklenen tüm fiyatlandırma katmanlarında 50 MB	Ücretsiz ve Temel sürümlerde 50 MB; Desteklenen diğer Ayrılmış katmanlarda ve Sunucusuz katmanlarda 100 MB
İşleme süresi	Yükleme 180 saniyeye kadar sürebilir	Yükleme ve güncelleme 180 saniyeye kadar sürebilir
İçeriği ve meta verileri yükleyin	Ham dosya içeriği	Meta verilerle ham dosya içeriği veya çok bölümlü içerik
Yüklenen dosyaları listele	Dosyaları listeleme	Yola veya dosya adına göre filtreleyin ve daha zengin dosya ayrıntıları döndürin
Mevcut dosya içeriğini değiştirme	Silme ve yeniden yükleme	Güncelleştirme işlemini kullanma
Dosya işlemlerine tarayıcı erişimi	CORS kullanılamıyor	CORS'u yapılandır

Note

• Oluşturulan arama dizini karşıya yüklenen içeriği depolar. Fiyatlandırma katmanına göre toplam depolama sınırları için bkz. Hizmet sınırları.
• Yüklenen içeriği parçalara ayıracak veya vektörleştirecek şekilde dosya bilgi kaynağını yapılandırırsanız, model ve sonraki işleme sınırları da geçerlidir.

Mevcut bilgi kaynaklarını denetleme

Bilgi kaynağı üst düzey, yeniden kullanılabilir bir nesnedir. Mevcut bilgi kaynakları hakkında bilgi edinmek, yeni nesneleri yeniden kullanmak veya adlandırmak için yararlıdır.

Bilgi kaynaklarını ada ve türe göre listelemek için aşağıdaki kodu çalıştırın.

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

Başvuru: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})")

Başvuru:SearchIndexClient

### List knowledge sources by name and type
GET {{search-url}}/knowledgesources?api-version={{api-version}}&$select=name,kind
Authorization: Bearer {{token}}

Başvuru:Bilgi Kaynakları - Liste

JSON tanımını gözden geçirmek için, ismiyle tek bir bilgi kaynağını da döndürebilirsiniz.

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

Başvuru: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))

Başvuru:SearchIndexClient

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

Başvuru:Bilgi Kaynakları - Get

Aşağıdaki JSON, bir dosya bilgi kaynağı için örnek bir yanıttır.

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

Bilgi kaynağı oluşturma

Karşıya yüklenen içeriği vektörleştirmek için kullanılan ekleme modelini belirten bir dosya bilgi kaynağı oluşturun.

Her dosya bilgi kaynağı bir dizin oluşturur, ancak dizin oluşturucu veya zamanlama oluşturmaz. fileParameters.ingestionParameters nesnesini eklemeniz gerekir. Hizmet, networkAccessMode belirten istekleri reddeder.

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

Başvuru: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.")

Başvuru: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"
    }
  }
}

Başvuru:Bilgi Kaynakları - Oluşturma veya Güncelleştirme

Standart ayıklamayı yapılandırma

2026-08-01-preview API sürümünden itibaren, standard ayıklama işleminde karşıya yüklenen dosyaları ayıklamak, anlamsal parçalara ayırmak ve zenginleştirmek için Content Understanding kullanılır. Azure Yapay Zeka Arama bu işlemeyi bilgi kaynağının bir parçası olarak yönetir ve Content Understanding ücretleri ayrıca uygulanır.

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

Başvuru: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}'.")

Başvuru: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}}"
      }
    }
  }
}

Başvuru:Bilgi Kaynakları - Oluşturma veya Güncelleştirme

Dosya işlemleri için CORS

Tarayıcı tabanlı dosya işlemlerine izin vermek için, dosya bilgi kaynağında uygulamanız için güvenilir kaynaklar ve maksimum preflight önbellek süresiyle corsOptions ayarını yapın.

Important

API sürümünde, corsOptions ayıklama modundan 2026-08-01-preview bağımsız olarak dosya yükleme, listeleme, güncelleştirme ve silme uç noktaları için geçerlidir. corsOptions öğesini atlarsanız, dosya bilgi kaynağı için tarayıcının kaynaklar arası ilkesi uygulanmaz. CORS istekleri yetkilendirmez. Kaynakların etkinleştirilmesi, hizmet işlemlerini ve verileri tarayıcı ortamında açığa çıkarabilir ve güvenlik riskleri ortaya çıkarabilir. Yalnızca güvenilir kaynakları belirtin ve üretimde joker karakterli kaynak kullanmayın. Tarayıcı istekleri için gerekli en düşük rolle Microsoft Entra belirteç kimlik doğrulamasını kullanın. Tarayıcı kodunda erişim belirteçlerini veya hizmet anahtarlarını hiçbir zaman kullanıma sunma.

Dosyaları yükleyin

Bilgi kaynağını oluşturduktan sonra dosyaları doğrudan bu kaynağa yükleyin. Her karşıya yükleme eşzamanlı bir çağrıdır: Azure Yapay Zeka Arama içeriği ayıklar, öbeklere ayırır, gerektiğinde gömüler oluşturur, öbekleri dizine ekler ve çağrı tamamlanmadan önce dosya meta verilerini kalıcı olarak kaydeder. Ayrı bir alım işlem hattı yapılandırmanız veya çalıştırmanız gerekmez.

Dosyaları karşıya yükleme ve yönetmeyle ilgili hatalarla ilgili yardım için bkz. Dosya işlemleriyle ilgili sorunları giderme.

Ham dosya yükle

Ham yüklemede, listelenen fileName, Content-Disposition: attachment; filename="..." üst bilgisinden gelir. REST çağrıları ve .NET SDK'sı bu üst bilgiyi doğrudan ayarlarken, Python SDK bir filename parametresi kabul eder ve üst bilgiyi otomatik olarak oluşturur. Dosya adı belirtmezseniz, hizmet otomatik olarak oluşturulmuş bir fileName atar.

Dosya adları, manuals/installation-guide.pdf gibi göreli bir yol içerebilir. Hizmet, ters eğik çizgileri eğik çizgilere dönüştürür. Mutlak yolları, boş yol bölümlerini, .. veya . bölümlerini, iki nokta üst üste karakteri içeren bölümleri ve geçersiz dosya adı karakterlerini HTTP durum kodu 400 ile reddeder.

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

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

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

Başvuru:Bilgi Kaynakları - Dosyayı Karşıya Yükle

İsteğe bağlı meta verilerle bir dosya yükleyin

API sürümünden 2026-08-01-preview başlayarak, isteğe bağlı özel meta veriler içeren bir ikili dosyayı karşıya yüklemek için çok parçalı bir istek kullanın. İstekte tam olarak bir content bölüm ve isteğe bağlı bir JSON metadata bölümü bulunur.

Her iki ad da belirtilmişse, metadata.fileName, content bölümündeki dosya adına göre öncelikli olur. Hiçbiri belirtilmezse, hizmet otomatik olarak oluşturulan bir dosya adı atar.

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

Başvuru: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}")

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

Başvuru:Bilgi Kaynakları - Dosyayı Karşıya Yükle

Note

Bir dosyayı karşıya yüklemek, aynı fileNamedosyayı yeniden kullansanız bile var olan bir dosyanın yerini almaz. Başarılı her yükleme, kendine ait fileId ile yeni bir dosya oluşturur; bu nedenle yüklenen dosyalar listesi, aynı fileName değerini paylaşan birden fazla girdi içerebilir.

2026-05-01-preview ile, önceki dosyayı silip yerine yenisini yükleyerek içeriği değiştirin. ile 2026-08-01-previewgüncelleştirme işlemini kullanın.

Yüklenen dosyaları listele

Yüklenen dosya kümesini incelemek için bilgi kaynağındaki dosyaları listeleyin.

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

Başvuru: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}")

Başvuru:SearchIndexClient.list_knowledge_source_files

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

Başvuru:Bilgi Kaynakları - Liste Dosyaları

Yanıt, karşıya yüklenen her dosyanın meta verilerini içerir. Başarıyla listelenen dosyalar için errorMessage değeri null şeklindedir.

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

Yeni karşıya yükleme başarısız olursa istek bir hata döndürür ve dosya meta veri kaydı oluşturmaz. Başarısız yükleme, daha sonraki listeleme sonuçlarında görünmez ve faturalandırılmaz.

Modele erişim hatası oluşursa ve gömme modelini barındıran Foundry kaynağı özel ağ kullanıyorsa, foundry_account paylaşılan özel bağlantının onaylandığını ve güvenilir hizmetler için atlamanın etkinleştirildiğini doğrulayın. Devre dışı bırakılmış bypass, 403 Public access is disabled döndürür. Kurulum ayrıntıları için bkz . Önkoşullar.

Dosyaları listeleme ve filtreleme

2026-08-01-preview API sürümünden itibaren, dosyaları göreli yola göre filtrelemek için search veya dosya adı ön ekine göre filtrelemek için prefix kullanın. Sonuç sayısını denetlemek için ayarlayın pageSize .

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

Başvuru: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})")

Başvuru: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}}

Başvuru:Bilgi Kaynakları - Liste Dosyaları

Yanıt, hizmet tarafından seçilen ayrıştırma ve ayıklama modlarının yanı sıra dosya yönetimi için kullanıcı meta verilerini içerir. Kullanıcı meta verileri aranabilir veya filtrelenebilir değildir.

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

Tüm sonuçları almak için, @odata.nextLink artık görünmeyene kadar takip edin. Sorgu parametrelerini değiştirmeden url'nin tamamını tam olarak döndürülen şekilde gönderin.

Yüklenen dosyayı güncelle

2026-08-01-preview API sürümünden itibaren, bir dosyayı fileId ile güncelleştirin. Çok bölümlü istek, ikili content bölümü gerektirir. Meta veri JSON bölümü isteğe bağlıdır, bu nedenle yalnızca içerikle ilgili bir güncelleştirme desteklenir. Yalnızca meta veri güncelleştirmesi desteklenmez.

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

Başvuru: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}")

Başvuru bilgileri: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--

Başvuru:Bilgi Kaynakları - Dosyayı Güncelleştir

Bir güncelleştirme başarısız olursa, önceki meta veri kaydı kalır. Güncelleştirmenin dizine alınan içeriği işlemsel olarak değiştirdiğini varsaymayın.

Yüklenen dosyaları sil

Artık alma için kullanılabilir olmasını istemediğiniz dosyaları bilgi kaynağından silin.

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

Başvuru: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")

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

Başvuru:Bilgi Kaynakları - Dosyayı Sil

Bilgi bankasına atama

Bilgi kaynağından memnunsanız bunu bir bilgi bankasına ekleyin.

Bilgi bankasına sorgu yapma

Bilgi bankası yapılandırıldıktan sonra, bilgi kaynağını sorgulamak için alma eylemini veya MCP uç noktasını çağırın .

Bilgi kaynağını silme

Bilgi kaynağını silebilmeniz için önce, buna başvuran bilgi bankalarını silmeniz veya başvuruyu kaldırmak için bilgi bankası tanımını güncelleştirmeniz gerekir. Dizin ve dizin oluşturucu işlem hattı oluşturan bilgi kaynakları için , oluşturulan tüm nesneler de silinir. Ancak, bilgi kaynağı oluşturmak için mevcut bir dizini kullandıysanız dizininiz silinmez.

Kullanımda olan bir bilgi kaynağını silmeye çalışırsanız, eylem başarısız olur ve etkilenen bilgi bankalarının listesini döndürür.

Bilgi kaynağını silmek için:

1. Arama hizmetinizdeki tüm bilgi bankalarının listesini alın.

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

   Başvuru:SearchIndexClient

   Örnek bir yanıt aşağıdaki gibi görünebilir:

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

2. Bilgi kaynağı başvurularını denetlemek için tek bir bilgi bankası tanımı alın.

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

   Başvuru:SearchIndexClient

   Örnek bir yanıt aşağıdaki gibi görünebilir:

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

3. Bilgi bankasını silin veya birden çok bilgi kaynağınız varsa, kaynağı kaldırmak için bilgi bankasını güncelleştirin. Bu örnekte silme işlemi gösterilmektedir.

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

   Başvuru:SearchIndexClient

4. Bilgi kaynağını silin.

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

   Başvuru:SearchIndexClient

1. Arama hizmetinizdeki tüm bilgi bankalarının listesini alın.

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

   Başvuru:SearchIndexClient

   Örnek bir yanıt aşağıdaki gibi görünebilir:

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

2. Bilgi kaynağı başvurularını denetlemek için tek bir bilgi bankası tanımı alın.

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

   Başvuru:SearchIndexClient

   Örnek bir yanıt aşağıdaki gibi görünebilir:

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

3. Bilgi bankasını silin veya birden çok bilgi kaynağınız varsa, kaynağı kaldırmak için bilgi bankasını güncelleştirin. Bu örnekte silme işlemi gösterilmektedir.

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

   Başvuru:SearchIndexClient

4. Bilgi kaynağını silin.

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

   Başvuru:SearchIndexClient

1. Arama hizmetinizdeki tüm bilgi bankalarının listesini alın.

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

   Başvuru:Bilgi Bankaları - Liste

   Örnek bir yanıt aşağıdaki gibi görünebilir:

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

2. Bilgi kaynağı başvurularını denetlemek için tek bir bilgi bankası tanımı alın.

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

   Başvuru:Bilgi Bankaları - Get

   Örnek bir yanıt aşağıdaki gibi görünebilir:

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

3. Bilgi bankasını silin veya birden çok bilgi kaynağınız varsa, kaynağı kaldırmak için bilgi bankasını güncelleştirin. Bu örnekte silme işlemi gösterilmektedir.

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

   Başvuru:Bilgi Tabanları - Sil

4. Bilgi kaynağını silin.

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

   Başvuru:Bilgi Kaynakları - Sil

Dosya işlemleriyle ilgili sorunları giderme

Aşağıdaki durum kodları dosya bilgi kaynağı işlemlerine özeldir.

Durum kodu	Neden ve eylem
400	Dosya boş, ayıklanabilir metin içermiyor, güvenli olmayan bir göreli yolu var veya geçersiz bir devamlılık isteği var. Dosyanın desteklenen, okunabilir içeriğe ve geçerli bir dosya adına sahip olduğunu doğrulayın. Liste işlemleri için, @odata.nextLink döndürüldüğü şekliyle tam olarak uyun. pageSize öğesini search veya $skiptoken ile birleştirmeyin.
409	Dosya bilgi kaynağı API sürümü için dosya sınırına ulaştı. Daha fazla dosya yüklemeden önce dosyaları silin.
415	Hizmet, desteklenmeyen bir MIME türü veya bilgi kaynağı en düşük düzeyde ayıklama kullanırken bir görüntü tespit etti. Desteklenen bir biçim kullanın. Görüntüler için standart ayıklamayı kullanın. Yalnızca arayan tarafından sağlanan içerik türünün değiştirilmesi algılamayı geçersiz kılmaz.
429	İşlem kuyruğu dolu. Sınırlandırılmış paralellik kullanın ve üstel geri çekilme ile yeniden deneyin. Hizmet, bir Retry-After üst bilgisi garanti etmez.
504	Dosya yükleme veya güncelleştirme sırasında işlem 180 saniyeyi aştı. Dosya boyutunu veya karmaşıklığını azaltın ve yeniden deneyin.

İlgili içerik

• Bilgi kaynağı nedir?
• Bilgi bankası oluşturma
• Bilgi bankasını sorgulama