Buat sumber pengetahuan berkas (pratinjau)

Note

Pencarian Azure AI tersedia melalui portal Azure, REST API, dan Azure SDK. Ini juga mendukung Foundry IQ, lapisan pengetahuan terkelola yang mengubah konten perusahaan menjadi pangkalan pengetahuan yang dapat digunakan kembali dan sadar izin untuk agen di portal Microsoft Foundry.

Important

Fitur, kemampuan, atau properti yang ditandai (pratinjau) tidak tercakup dalam perjanjian tingkat layanan, tidak disarankan untuk beban kerja produksi, dan mungkin berubah atau dibatasi sebelum tersedia secara umum. Ketentuan pratinjau Pencarian Azure AI berlaku untuk semua fungsionalitas pratinjau, baik itu mandiri atau bagian dari fitur yang tersedia secara umum.

Sumber pengetahuan berkas (pratinjau) mengunggah sekumpulan berkas berukuran kecil hingga menengah langsung ke Pencarian Azure AI untuk pengambilan untuk agen. Sumber pengetahuan dibuat secara independen, direferensikan dalam pangkalan pengetahuan, dan digunakan sebagai data dasar ketika pangkalan pengetahuan dikueri saat runtime.

Sumber pengetahuan file berguna ketika Anda menginginkan pengalaman pengunggahan terkelola alih-alih menyediakan Azure Storage, mengonfigurasi akses, dan membuat alur pengindeks melalui kontainer eksternal. Pencarian Azure AI memproses file yang diunggah sehingga konten yang diekstrak dapat diambil dari pangkalan pengetahuan.

Sebaiknya gunakan sumber pengetahuan blob jika file Anda sudah berada di Azure Blob Storage atau Azure Data Lake Storage Gen2, jika kumpulan file Anda melebihi atau kemungkinan akan melebihi batas sumber pengetahuan file, atau jika Anda memerlukan proses penyerapan terjadwal. Gunakan juga sumber pengetahuan blob saat Anda ingin mengelola blob sumber dengan kebijakan manajemen siklus hidup Azure Blob Storage atau saat Anda memerlukan izin tingkat dokumen (pratinjau) berdasarkan izin di Azure Storage.

Dukungan penggunaan

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

Prerequisites

  • Layanan Pencarian Azure AI dalam wilayah mana pun yang menyediakan agentic retrieval. Sumber pengetahuan berbasis file mendukung model penetapan harga Dedicated dan Serverless. Untuk detail model dan tingkatan, lihat Memilih model harga dan tingkat layanan.

  • Tinjau biaya Pencarian Azure AI. Panggilan model, vektorisasi, dan pemrosesan AI lainnya dapat dikenakan biaya terpisah.

  • Pada Serverless, operasi penyerapan file yang berhasil menggunakan sumber daya komputasi yang ditagihkan. Unggahan yang gagal tidak dikenakan biaya komputasi Tanpa Server.

  • Jika Anda memerlukan agentic retrieval berbayar di luar kuota gratis bulanan, aktifkan paket agentic retrieval standar. Pengaturan knowledgeRetrieval=standard ini terpisah dari biaya komputasi dan penyimpanan tanpa server dan tidak memilih model harga.

  • File dalam format yang didukung.

  • Izin untuk membuat sumber pengetahuan. Konfigurasikan autentikasi tanpa kunci dengan peran Kontributor Layanan Pencarian yang ditetapkan ke akun pengguna Anda (disarankan) atau gunakan kunci API admin.

  • Jika sumber pengetahuan menentukan model Azure OpenAI untuk embedding, layanan pencarian harus memiliki managed identity dengan izin Cognitive Services User pada sumber daya Microsoft Foundry.

    • Jika akses jaringan publik untuk sumber daya Foundry dinonaktifkan, buat foundry_accounttautan privat bersama dari layanan pencarian ke sumber daya Foundry dan biarkan pengaturan Izinkan layanan Azure pada daftar layanan tepercaya tetap aktif.

  • Jika sumber pengetahuan menentukan standard mode ekstraksi konten, tinjau persyaratan untuk keterampilan Azure Content Understanding.

    • Penggunaan dikenakan biaya sesuai harga Azure Content Understanding di Foundry Tools pada sumber daya Foundry yang dikonfigurasi melalui aiServices.

    • Tunjangan gratis harian 20 dokumen yang tersedia untuk beberapa keterampilan bawaan tidak berlaku.

    • Untuk contoh dalam artikel ini, Anda memerlukan endpoint dan kunci sumber daya Foundry, serta informasi model embedding dan model penyelesaian chat Azure OpenAI.

  • Paket pratinjau terbaru Azure.Search.Documents: dotnet add package Azure.Search.Documents --prerelease

  • Untuk autentikasi tanpa kunci, Azure.Identity paket: dotnet add package Azure.Identity

Dukungan dan batasan file

Sebelum Anda membuat sumber pengetahuan file, tinjau persyaratan dan batasan yang memengaruhi pengunggahan, ekstraksi, dan manajemen file.

Jenis konten yang didukung

Sumber pengetahuan file menerima file berdasarkan jenis konten yang terdeteksi. Tipe konten yang diberikan oleh pemanggil tidak menggantikan pendeteksian.

Jenis konten yang didukung meliputi:

  • PDF
  • Word (.doc, .docx)
  • PowerPoint (.ppt, .pptx)
  • Excel (.xls, .xlsx)
  • JSON
  • Skrip shell
  • Konten yang terdeteksi seperti text/*, .txt, .md, .htmldan .csv

Mode ekstraksi yang didukung

  • Untuk jenis konten yang tercantum, baik 2026-05-01-preview maupun 2026-08-01-preview mendukung minimal. standard hanya tersedia di 2026-08-01-preview.

  • Konten yang terdeteksi sebagai image/* tidak didukung di 2026-05-01-preview. Dalam 2026-08-01-preview, gunakan ekstraksi standard. minimal ekstraksi mengembalikan status 415 HTTP di kedua versi.

Batasan dan operasi berkas

Batas dan operasi file yang didukung berbeda menurut versi API.

Kemampuan 2026-05-01-preview 2026-08-01-preview
File maksimum per sumber pengetahuan 100 200
Ukuran file maksimal 50 MB pada semua tingkat harga yang didukung 50 MB gratis dan dasar; 100 MB pada tingkat Khusus lain yang didukung dan Tanpa Server
Durasi pemrosesan Unggahan dapat berjalan hingga 180 detik Unggah dan perbarui dapat berjalan hingga 180 detik
Mengunggah konten dan metadata Konten file asli Konten file mentah atau konten multipihak dengan metadata
Mencantumkan file yang diunggah Mencantumkan file Filter menurut jalur atau nama file, dan kembalikan detail file yang lebih kaya
Ganti konten file yang sudah ada Menghapus dan mengunggah ulang Gunakan operasi pembaruan
Akses melalui browser ke operasi berkas CORS tidak tersedia Konfigurasikan CORS

Note

  • Indeks pencarian yang dihasilkan menyimpan konten yang diunggah. Untuk batas penyimpanan total berdasarkan tingkat harga, lihat Batas layanan.
  • Jika Anda mengonfigurasi sumber pengetahuan file untuk memotong atau mem-vektorisasi konten yang diunggah, batas pemrosesan model dan hilir juga berlaku.

Periksa sumber pengetahuan yang ada

Sumber pengetahuan adalah objek tingkat atas yang dapat digunakan kembali. Mengetahui tentang sumber pengetahuan yang ada sangat membantu untuk menggunakan kembali atau memberi nama objek baru.

Jalankan kode berikut untuk mencantumkan sumber pengetahuan menurut nama dan jenis.

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

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

Referensi:SearchIndexClient

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

Referensi:Sumber Pengetahuan - Daftar

Anda juga dapat mengembalikan satu sumber pengetahuan berdasarkan nama untuk meninjau definisi JSON-nya.

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

Referensi: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))

Referensi:SearchIndexClient

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

Referensi:Sumber Pengetahuan - Dapatkan

JSON berikut adalah contoh respons untuk sumber pengetahuan file.

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

Membuat sumber pengetahuan

Buat sumber pengetahuan file yang menentukan model penyematan yang digunakan untuk mem-vektorisasi konten yang diunggah.

Setiap sumber pengetahuan file membuat indeks, tetapi bukan pengindeks atau jadwal. Anda harus menyertakan fileParameters.ingestionParameters objek . Layanan menolak permintaan yang mencantumkan 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.");

Referensi: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.")

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

Referensi:Sumber Pengetahuan - Buat atau Perbarui

Konfigurasikan ekstraksi standar

Dimulai dengan 2026-08-01-preview versi API, standard ekstraksi menggunakan Pemahaman Konten untuk mengekstrak, memotong secara semantik, dan memperkaya file yang diunggah. Pencarian Azure AI mengelola pemrosesan ini sebagai bagian dari sumber pengetahuan, dan biaya Pemahaman Konten berlaku secara terpisah.

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

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

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

Referensi:Sumber Pengetahuan - Buat atau Perbarui

CORS untuk operasi file

Untuk mengizinkan operasi file berbasis browser, atur corsOptions pada sumber pengetahuan file dengan asal tepercaya dan durasi cache preflight maksimum untuk aplikasi Anda.

Important

Dalam versi API 2026-08-01-preview, corsOptions berlaku untuk endpoint pengunggahan berkas, daftar, pembaruan, dan penghapusan, terlepas dari mode ekstraksi. Jika Anda menghilangkan corsOptions, sumber pengetahuan file tidak memiliki kebijakan lintas asal browser. CORS tidak mengotorisasi permintaan. Mengaktifkan origin dapat membuka akses terhadap operasi layanan dan data dalam konteks peramban serta menimbulkan risiko keamanan. Tentukan hanya asal tepercaya, dan jangan gunakan asal kartubebas dalam produksi. Untuk permintaan browser, gunakan autentikasi token Microsoft Entra dengan peran minimum yang diperlukan. Jangan pernah mengekspos token akses atau kunci layanan dalam kode browser.

Unggah berkas

Setelah Anda membuat sumber pengetahuan, unggah file langsung ke sumber pengetahuan tersebut. Setiap unggahan adalah panggilan sinkron: Pencarian Azure AI mengekstrak konten, memotongnya, membuat penyematan saat diperlukan, mengindeks gugus, dan mempertahankan metadata file sebelum panggilan kembali. Anda tidak perlu mengonfigurasi atau menjalankan alur penyerapan terpisah.

Untuk bantuan terkait kesalahan terkait pengunggahan dan pengelolaan file, lihat Memecahkan masalah operasi file.

Mengunggah file mentah

Untuk unggahan mentah, yang tercantum fileName berasal dari Content-Disposition: attachment; filename="..." header. Panggilan REST dan SDK .NET mengatur header ini secara langsung, sementara Python SDK menerima parameter filename dan membangun header secara otomatis. Jika Anda tidak memberikan nama file, layanan akan memberikan fileName yang dibuat secara otomatis.

Nama file dapat menyertakan jalur relatif, seperti manuals/installation-guide.pdf. Layanan ini menormalkan backslash menjadi slash. Sistem ini menolak jalur absolut, segmen jalur kosong, segmen . atau .., segmen yang mengandung titik dua, dan karakter nama berkas yang tidak valid dengan status 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}");

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

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

Referensi:Sumber Pengetahuan - Unggah File

Mengunggah file dengan metadata opsional

Dimulai dengan 2026-08-01-preview versi API, gunakan permintaan multipart untuk mengunggah satu file biner dengan metadata kustom opsional. Permintaan ini mencakup tepat satu content bagian dan bagian JSON metadata opsional.

Jika kedua nama ditentukan, metadata.fileName lebih diutamakan daripada nama file pada content bagian tersebut. Jika tidak ditentukan, layanan menetapkan nama file yang dibuat secara otomatis.

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

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

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

Referensi:Sumber Pengetahuan - Unggah File

Note

Mengunggah file tidak menggantikan file yang ada, bahkan jika Anda menggunakan kembali file yang sama fileName. Setiap unggahan yang berhasil membuat file baru dengan filenya sendiri fileId, sehingga daftar file yang diunggah dapat berisi beberapa entri yang berbagi fileName.

Dengan 2026-05-01-preview, ganti konten dengan menghapus file sebelumnya dan mengunggah penggantinya. Dengan 2026-08-01-preview, gunakan operasi pembaruan.

Mencantumkan file yang diunggah

Cantumkan file pada sumber pengetahuan untuk memeriksa kumpulan file yang diunggah.

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

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

Referensi:SearchIndexClient.list_knowledge_source_files

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

Referensi:Sumber Pengetahuan - Mencantumkan File

Respons mencakup metadata untuk setiap file yang diunggah. File yang berhasil terdaftar memiliki nilai errorMessage sebesar 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
    }
  ]
}

Jika unggahan baru gagal, permintaan mengembalikan kesalahan dan tidak membuat catatan metadata file. Unggahan yang gagal tidak akan muncul dalam hasil daftar berikutnya dan tidak akan dikenakan biaya.

Jika terjadi kegagalan akses model dan sumber daya Foundry yang menampung model penyematan menggunakan jaringan privat, pastikan bahwa tautan privat bersama foundry_account telah disetujui dan pengecualian layanan tepercaya telah diaktifkan. Bypass yang dinonaktifkan mengembalikan 403 Public access is disabled. Untuk detail penyiapan, lihat Prasyarat.

Mencantumkan dan memfilter file

Dimulai dengan 2026-08-01-preview versi API, gunakan prefix untuk memfilter file menurut jalur relatif atau search untuk memfilter berdasarkan awalan nama file. Atur pageSize untuk mengontrol jumlah hasil.

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

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

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

Referensi:Sumber Pengetahuan - Mencantumkan File

Respons mencakup mode penguraian dan ekstraksi yang dipilih layanan, serta metadata pengguna untuk manajemen file. Metadata pengguna tidak dapat dicari atau dapat difilter.

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

Untuk mengambil semua hasil, ikuti @odata.nextLink hingga tidak lagi tersedia. Kirim URL lengkap persis seperti yang dikembalikan, tanpa mengubah parameter kueri.

Memperbarui file yang diunggah

Mulai dari versi API 2026-08-01-preview, perbarui file berdasarkan fileId-nya. Permintaan multipihak memerlukan bagian biner content . Bagian JSON metadata bersifat opsional, sehingga pembaruan khusus konten didukung. Pembaruan khusus metadata tidak didukung.

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

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

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

Referensi:Sumber Pengetahuan - Perbarui File

Jika pembaruan gagal, catatan metadata sebelumnya tetap ada. Jangan berasumsi bahwa pembaruan mengubah konten terindeks secara transaksional.

Menghapus file yang diunggah

Hapus file dari sumber pengetahuan ketika Anda tidak lagi ingin file tersebut tersedia untuk diambil.

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

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

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

Referensi:Sumber Pengetahuan - Hapus File

Mengaitkan ke basis pengetahuan

Jika Anda puas dengan sumber pengetahuan, tambahkan ke pangkalan pengetahuan.

Meminta pangkalan pengetahuan

Setelah pangkalan pengetahuan dikonfigurasi, panggil tindakan ambil atau titik akhir MCP untuk mengkueri sumber pengetahuan.

Menghapus sumber pengetahuan

Sebelum dapat menghapus sumber pengetahuan, Anda harus menghapus pangkalan pengetahuan apa pun yang mereferensikannya atau memperbarui definisi pangkalan pengetahuan untuk menghapus referensi. Untuk sumber pengetahuan yang menghasilkan indeks dan alur pengindeks, semua objek yang dihasilkan juga dihapus. Namun, jika Anda menggunakan indeks yang ada untuk membuat sumber pengetahuan, indeks Anda tidak dihapus.

Jika Anda mencoba menghapus sumber pengetahuan yang sedang digunakan, tindakan gagal dan mengembalikan daftar pangkalan pengetahuan yang terpengaruh.

Untuk menghapus sumber pengetahuan:

  1. Dapatkan daftar semua pangkalan pengetahuan di layanan pencarian Anda.

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

    Referensi:SearchIndexClient

    Contoh respons mungkin terlihat seperti berikut ini:

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

  2. Dapatkan definisi pangkalan pengetahuan individual untuk memeriksa referensi sumber pengetahuan.

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

    Referensi:SearchIndexClient

    Contoh respons mungkin terlihat seperti berikut ini:

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

  3. Hapus pangkalan pengetahuan atau, jika Anda memiliki beberapa sumber pengetahuan, perbarui pangkalan pengetahuan untuk menghapus sumbernya. Contoh ini menunjukkan penghapusan.

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

    Referensi:SearchIndexClient

  4. Hapus sumber pengetahuan.

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

    Referensi:SearchIndexClient

  1. Dapatkan daftar semua pangkalan pengetahuan di layanan pencarian Anda.

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

    Referensi:SearchIndexClient

    Contoh respons mungkin terlihat seperti berikut ini:

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

  2. Dapatkan definisi pangkalan pengetahuan individual untuk memeriksa referensi sumber pengetahuan.

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

    Referensi:SearchIndexClient

    Contoh respons mungkin terlihat seperti berikut ini:

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

  3. Hapus pangkalan pengetahuan atau, jika Anda memiliki beberapa sumber pengetahuan, perbarui pangkalan pengetahuan untuk menghapus sumbernya. Contoh ini menunjukkan penghapusan.

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

    Referensi:SearchIndexClient

  4. Hapus sumber pengetahuan.

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

    Referensi:SearchIndexClient

  1. Dapatkan daftar semua pangkalan pengetahuan di layanan pencarian Anda.

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

    Referensi:Pangkalan Pengetahuan - Daftar

    Contoh respons mungkin terlihat seperti berikut ini:

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

  2. Dapatkan definisi pangkalan pengetahuan individual untuk memeriksa referensi sumber pengetahuan.

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

    Referensi:Pangkalan Pengetahuan - Dapatkan

    Contoh respons mungkin terlihat seperti berikut ini:

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

  3. Hapus pangkalan pengetahuan atau, jika Anda memiliki beberapa sumber pengetahuan, perbarui pangkalan pengetahuan untuk menghapus sumbernya. Contoh ini menunjukkan penghapusan.

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

    Referensi:Pangkalan Pengetahuan - Hapus

  4. Hapus sumber pengetahuan.

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

    Referensi:Sumber Pengetahuan - Hapus

Memecahkan masalah pada operasi berkas

Kode status berikut khusus untuk operasi sumber pengetahuan file.

Kode status Penyebab dan tindakan
400 File kosong, tidak berisi teks yang dapat diekstrak, memiliki jalur relatif yang tidak aman, atau memiliki permintaan kelanjutan yang tidak valid. Verifikasi bahwa file telah mendukung konten yang dapat dibaca dan nama file yang valid. Untuk operasi pada daftar, ikuti @odata.nextLink persis sebagaimana dikembalikan. Jangan gabungkan $skiptoken dengan search atau pageSize.
409 Sumber pengetahuan berbasis file telah mencapai batas jumlah file untuk versi API tersebut. Hapus file sebelum mengunggah lebih banyak.
415 Layanan mendeteksi jenis MIME yang tidak didukung, atau mendeteksi gambar sementara sumber pengetahuan menggunakan ekstraksi minimal. Gunakan format yang didukung. Untuk gambar, gunakan ekstraksi standar. Mengubah hanya jenis konten yang diberikan oleh pemanggil tidak akan mengesampingkan deteksi.
429 Antrean pemrosesan penuh. Gunakan paralelisme terbatas dan lakukan percobaan ulang dengan backoff eksponensial. Layanan tidak menjamin header Retry-After.
504 Pemrosesan melebihi 180 detik selama pengunggahan atau pembaruan file. Kurangi ukuran atau kompleksitas file, lalu coba lagi.

Konten terkait

  • Terakhir diperbarui pada