建立檔案知識來源（預覽）

Note

Azure AI 搜尋服務可透過 Azure 入口網站、REST API 及 Azure SDK 取得。它同時也是 Foundry IQ 的基礎，這是一個管理式知識層，能將企業內容轉化為可重複使用、權限感知的知識庫，供 Microsoft Foundry 入口網站中的代理使用。

Important

標記（預覽）的功能、能力或屬性不受服務等級協議涵蓋，也不建議用於生產工作負載，且在正式上架前可能會有所變動或受限。 Azure AI 搜尋服務預覽條款適用於所有預覽功能，無論是獨立功能還是正式推出功能的一部分。

檔案知識來源（預覽）會直接將小型到中型檔案集上傳到 Azure AI 搜尋服務進行代理檢索。知識來源獨立建立，並在知識庫中被引用，並在執行時查詢知識庫時作為基礎資料。

當你想要有受管式上傳體驗，而不是用 Azure 儲存體配置、設定存取權限，或在外部容器建立索引器管線時，檔案知識來源很有用。 Azure AI 搜尋服務會處理上傳的檔案，使其擷取的內容能從知識庫中取得。

當您的檔案已經位於 Azure Blob 儲存體或 Azure Data Lake Storage Gen2 中、當您的檔案集超過或可能超過檔案知識來源限制，或當您需要排程擷取時，請改用 Blob 知識來源。另外，當您想要使用 Azure Blob 儲存體生命週期管理原則來管理來源 Blob，或需要根據 Azure 儲存體中的權限提供文件層級權限（預覽）時，也請使用 Blob 知識來源。

使用支援

Azure portal	Microsoft Foundry 入口網站	.NET SDK	Python SDK	Java 開發套件	JavaScript SDK	REST API
❌	✔️	✔️	✔️	✔️	✔️	✔️

先決條件

任何區域內提供主動檢索的 Azure AI 搜尋服務服務。檔案知識來源支援專用與無伺服器定價模式。關於型號與層級的詳細資訊，請參見「選擇定價模式與服務層級」。
檢視 Azure AI 搜尋服務費用。模型呼叫、向量化及其他 AI 處理可能會產生獨立費用。
在無伺服器模式下，成功的檔案擷取操作會消耗可計費的運算。上傳失敗不會產生無伺服器運算費用。
如果你需要付費的代理檢索，超出每月免費津貼，請啟用標準代理檢索方案。這個 knowledgeRetrieval=standard 設定與無伺服器的運算和儲存費用是分開的，也不會選擇定價模式。
支援格式的檔案。
允許建立知識來源。設定無金鑰驗證，並將搜尋服務參與者角色指派給您的使用者帳戶（建議），或使用管理員 API 金鑰。
若知識來源指定Azure OpenAI 模型用於嵌入，搜尋服務必須擁有管理身份，且 Microsoft Foundry 資源擁有 Cognitive Services User 權限。
- 如果 Foundry 資源被關閉了公共網路存取，請建立foundry_account一條從搜尋服務到 Foundry 資源的共用私有連結，並保持資源的「允許 Azure 服務在可信服務清單」設定中啟用。
如果知識來源指定 standard內容擷取模式，請檢閱 Azure 內容理解技能的需求。
- 使用量會依照 Foundry Tools 中 Azure Content Understanding 的定價，向透過 aiServices 設定的 Foundry 資源收費。
- 適用於某些內建技能的每日 20 份文件免費額度不適用。
- 本文範例中，你需要 Foundry 資源端點與金鑰，以及 Azure OpenAI 的嵌入與聊天完成模型資訊。

最新的 Azure.Search.Documents 預覽套件：dotnet add package Azure.Search.Documents --prerelease
對於無鑰匙認證，套件如下 Azure.Identity ： dotnet add package Azure.Identity

最新的 azure-search-documents 預覽套件：pip install --pre azure-search-documents
對於無鑰匙認證，套件如下 azure-identity ： pip install azure-identity

搜尋服務 REST API 的 2026-08-01 預覽版。
對於無金鑰認證，請在Authorization每個 HTTP 請求的標頭中加入 Microsoft Entra ID 令牌。

檔案支援與限制

在建立檔案知識來源前，請先檢視影響檔案上傳、擷取與管理的需求與限制。

支援的內容類型

檔案知識來源會根據偵測到的內容類型接受檔案。來電者提供的內容類型不會覆蓋偵測。

支援的內容類型包括：

PDF
Word （.doc， .docx）
PowerPoint （.ppt， .pptx）
Excel （.xls， .xlsx）
JSON
Shell 指令稿
偵測到的內容為 text/*，例如 .txt、 .md.html.csv

支援的擷取模式

對於所列的內容類型，2026-05-01-preview和2026-08-01-preview都支援minimal。 standard 僅在 2026-08-01-preview中提供。
偵測為image/*的內容不受2026-05-01-preview支援。在 2026-08-01-preview 中，使用 standard 擷取。 minimal 擷取在兩個版本中都會回傳 HTTP 狀態 415 。

限制與檔案操作

限制與支援的檔案操作會依 API 版本而異。

Capability	`2026-05-01-preview`	`2026-08-01-preview`
每個知識來源的最大檔案數	100	200
檔案大小上限	所有支援的定價層級均為 50 MB	免費及基礎版為 50 MB;其他支援的專用層級和無伺服器層級則有 100 MB
處理時間	上傳時間可長達 180 秒	上傳與更新可持續長達180秒
上傳內容與元資料	原始檔案內容	原始檔案內容或含元資料的多部分內容
列出已上傳的檔案	列出檔案	依路徑或檔名篩選，並回傳更豐富的檔案細節
替換現有檔案內容	刪除並重新上傳	使用更新作業
瀏覽器對檔案作業的存取	CORS 目前無法取得	設定 CORS

Note

產生的搜尋索引會儲存已上傳的內容。依價格層級劃分的總儲存限制，請參見服務限制。
如果你將檔案知識來源設定為將上傳內容分割或向量化，模型和下游處理限制也會適用。

檢查現有的知識來源

知識來源是一個頂層且可重複使用的物件。了解現有的知識來源對於重用或命名新物件都很有幫助。

執行以下程式碼，依名稱和類型列出知識來源。

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

參考資料：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})")

參考資料：SearchIndexClient

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

參考資料：知識來源列表

你也可以以名稱回傳單一知識來源，以檢視其 JSON 定義。

using Azure.Search.Documents.Indexes;
using System.Text.Json;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);

// Specify the knowledge source name to retrieve
string ksNameToGet = "earth-knowledge-source";

// Get its definition
var knowledgeSourceResponse = await indexClient.GetKnowledgeSourceAsync(ksNameToGet);
var ks = knowledgeSourceResponse.Value;

// Serialize to JSON for display
var jsonOptions = new JsonSerializerOptions 
{ 
    WriteIndented = true,
    DefaultIgnoreCondition = System.Text.Json.Serialization.JsonIgnoreCondition.Never
};
Console.WriteLine(JsonSerializer.Serialize(ks, ks.GetType(), jsonOptions));

參考資料：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))

參考資料：SearchIndexClient

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

參考資料：知識來源 - 取得

以下 JSON 是一個檔案知識來源的範例回應。

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

建立知識來源

建立一個檔案知識來源，指定用於向量化上傳內容的嵌入模型。

每個檔案知識來源都會建立索引，但不會建立索引器或排程器。你必須包含 fileParameters.ingestionParameters 物件。服務會拒絕指定 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.");

參考資料：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.")

參考資料：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"
    }
  }
}

參考資料：知識來源 - 建立或更新

設定標準擷取

自 2026-08-01-preview API 版本起，standard 擷取會使用內容理解，從上傳的檔案中擷取內容、進行語意分塊，並加以豐富化。 Azure AI 搜尋服務將此處理視為知識來源的一部分，內容理解費用則另行計算。

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

參考資料：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}'.")

參考資料：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}}"
      }
    }
  }
}

參考資料：知識來源 - 建立或更新

檔案作業的 CORS

若要允許以瀏覽器為基礎的檔案操作，請在檔案知識來源上將 corsOptions 設定為應用程式的可信任來源和預檢快取最長持續時間。

Important

在 2026-08-01-preview API 版本中，corsOptions 適用於檔案上傳、列出、更新及刪除端點，且與擷取模式無關。如果你省略 corsOptions了，檔案知識來源就沒有瀏覽器的跨來源政策。 CORS 不會授權申請。啟用來源可能會在瀏覽器環境中暴露服務作業與資料，並帶來安全風險。僅指定受信任的來源，且不要在生產環境中使用萬用字元來源。對於瀏覽器請求，請使用 Microsoft Entra 令牌認證，並設定最低必要角色。切勿在瀏覽器程式碼中暴露存取權杖或服務金鑰。

上傳檔案

建立知識來源後，直接上傳檔案到那裡。每次上傳都是同步呼叫：Azure AI 搜尋服務會擷取內容、區塊化、必要時建立嵌入、索引區塊，並在呼叫返回前持續保存檔案元資料。你不需要設定或執行獨立的擷取流程。

如需協助處理與上傳及管理檔案相關的錯誤，請參閱「檔案操作故障排除」。

上傳原始檔案

對於原始上傳，所列的 fileName 來自 Content-Disposition: attachment; filename="..." 標頭。 REST 呼叫和 .NET SDK 直接設定標頭，而 Python SDK 則接受 filename 參數並自動建立標頭。如果你沒有提供檔名，服務會指派一個自動產生的 fileName。

檔案名稱可以包含相對路徑，例如 manuals/installation-guide.pdf。該服務會將反斜線標準化為正斜線。它會拒絕絕對路徑、空路徑段（ . 或稱 .. 段）、含冒號的段子，以及具有 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}");

參考資料：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}")

參考資料：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>

參考資料：知識來源 - 上傳檔案

上傳帶有可選元資料的檔案

從 2026-08-01-preview API 版本開始，請使用 multipart 要求上傳一個二進位檔案，並可附帶選用的自訂中繼資料。請求中只包含一個 content 部分及一個可選的 JSON metadata 部分。

若兩個名稱皆指定，則 metadata.fileName 優先於該零件的 content 檔名。若兩者皆未指定，服務會自動指派一個自動產生的檔案名稱。

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

參考資料：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}")

參考資料：SearchIndexClient.upload_knowledge_source_file_multipart

POST {{search-endpoint}}/knowledgesources('my-file-ks')/files?api-version=2026-08-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: multipart/form-data; boundary=file-boundary

--file-boundary
Content-Disposition: form-data; name="metadata"
Content-Type: application/json

{
  "fileName": "installation-guide.pdf",
  "metadata": {
    "department": "support",
    "product": "contoso-100"
  }
}
--file-boundary
Content-Disposition: form-data; name="content"; filename="installation-guide.pdf"
Content-Type: application/octet-stream

< ./installation-guide.pdf
--file-boundary--

參考資料：知識來源 - 上傳檔案

Note

上傳檔案並不會取代現有檔案，即使你重複使用了同 fileName一個檔案。每次成功上傳都會產生一個新檔案，包含自己的 fileId，因此上傳檔案清單中可能包含多個共享 fileName的條目。

用 2026-05-01-preview來替換內容，方法是刪除先前的檔案並上傳替換檔案。使用 2026-08-01-preview 來進行更新操作。

列出已上傳的檔案

在知識來源上列出檔案，以便檢查已上傳的檔案集。

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

參考：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}")

參考資料：SearchIndexClient.list_knowledge_source_files

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

參考資料：知識來源 - 清單檔案

回應包含每個上傳檔案的元資料。成功列出的檔案其 errorMessage 值為 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
    }
  ]
}

如果新的上傳失敗，請求會回傳錯誤，且不會建立檔案的元資料記錄。上傳失敗的結果不會出現在後續的清單結果中，也不會被計費。

若模型存取失敗，且承載嵌入模型的 Foundry 資源使用私有網路，請確認 foundry_account 共享私有連結已核准且可信服務繞過已啟用。停用的略過會傳回 403 Public access is disabled。關於設定細節，請參見前置條件。

清單與篩選檔案

從 2026-08-01-preview API 版本開始，使用 prefix 依相對路徑篩選檔案，或使用 search 依檔名前綴篩選檔案。設定 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})");
}

參考：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})")

參考資料：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}}

參考資料：知識來源 - 清單檔案

回應包含服務選擇的解析與擷取模式，以及用於檔案管理的使用者元資料。使用者的元資料無法搜尋或篩選。

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

要取得所有結果，請持續追蹤 @odata.nextLink 直到它消失為止。請依照回傳的原樣傳送完整 URL，且不要更改查詢參數。

更新已上傳的檔案

從 2026-08-01-preview API 版本開始，依其 fileId 更新檔案。多部分請求需要二進位 content 部分。中繼資料 JSON 部分是可選的，因此只支援內容更新。不支援僅包含元資料的更新。

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

參考：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}")

參考資料：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--

參考資料：知識來源 - 更新檔

若更新失敗，先前的元資料記錄會保留。不要假設更新會以交易方式改變已索引的內容。

刪除已上傳的檔案

當你不想再讓知識來源被檢索時，請刪除檔案。

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

參考：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")

參考資料：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}}

參考資料：知識來源 - 刪除檔案

指派至知識庫

如果你對知識來源感到滿意，就把它加入知識庫。

查詢知識庫

知識庫設定完成後，呼叫擷取動作或 MCP 端點查詢知識來源。

刪除知識來源

在刪除知識來源之前，必須刪除所有引用該來源的知識庫，或更新知識庫定義以移除該參考。對於產生索引與索引管線的知識來源，所有 產生的物件 也會被刪除。不過，如果你用現有的索引建立知識來源，你的索引不會被刪除。

如果你嘗試刪除正在使用的知識來源，該動作會失敗，並回傳一份受影響的知識庫清單。

刪除知識來源：

取得你搜尋服務中所有知識庫的清單。

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

參考資料：SearchIndexClient

範例回應可能如下所示：

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

取得一個獨立的知識庫定義，以檢查是否有知識來源的參考。

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

參考資料：SearchIndexClient

範例回應可能如下所示：

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

要麼刪除知識庫，要麼如果你有多個知識來源，就更新知識庫來移除該來源。這個例子顯示刪除。

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

參考資料：SearchIndexClient

刪除知識來源。

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

參考資料：SearchIndexClient

取得你搜尋服務中所有知識庫的清單。

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

參考資料：SearchIndexClient

範例回應可能如下所示：

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

取得一個獨立的知識庫定義，以檢查是否有知識來源的參考。

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

參考資料：SearchIndexClient

範例回應可能如下所示：

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

要麼刪除知識庫，要麼如果你有多個知識來源，就更新知識庫來移除該來源。這個例子顯示刪除。

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

參考資料：SearchIndexClient

刪除知識來源。

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

參考資料：SearchIndexClient

取得你搜尋服務中所有知識庫的清單。

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

參考資料：知識庫列表

範例回應可能如下所示：

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

取得一個獨立的知識庫定義，以檢查是否有知識來源的參考。

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

參考資料：知識庫 - 取得

範例回應可能如下所示：

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

要麼刪除知識庫，要麼如果你有多個知識來源，就更新知識庫來移除該來源。這個例子顯示刪除。
```
### Delete a knowledge base
DELETE {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version={{api-version}}
Authorization: Bearer {{token}}
```
參考資料：知識庫 - 刪除

刪除知識來源。

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

參考資料：知識來源 - 刪除

檔案操作故障排除

以下狀態碼專為檔案知識來源操作而設。

狀態代碼	因果關係
`400`	該檔案為空、無可擷取文字、有不安全的相對路徑，或有無效的續讀請求。確認檔案內容是否支援、可讀且檔名有效。對於清單操作，請完全依照 `@odata.nextLink` 的回傳結果。不要將 `search` 與 `pageSize` 或 `$skiptoken` 組合使用。
`409`	檔案知識來源已達到此 API 版本的檔案數量上限。在上傳更多檔案前先刪除檔案。
`415`	服務偵測到不支援的 MIME 類型，或偵測到影像，而知識來源僅使用最小的擷取。使用支援格式。影像方面，請使用標準擷取。只更改來電者提供的內容類型並不會覆蓋偵測。
`429`	處理佇列已滿。使用受限平行處理，並以指數退避機制重試。此服務不保證會有 `Retry-After` 標頭。
`504`	檔案上傳或更新時處理時間超過180秒。縮小檔案大小或複雜度，再試一次。

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-09-17

建立檔案知識來源（預覽）

使用支援

先決條件

檔案支援與限制

支援的內容類型

支援的擷取模式

限制與檔案操作

檢查現有的知識來源

建立知識來源

設定標準擷取

檔案作業的 CORS

上傳檔案

上傳原始檔案

上傳帶有可選元資料的檔案

列出已上傳的檔案

清單與篩選檔案

更新已上傳的檔案

刪除已上傳的檔案

指派至知識庫

查詢知識庫

刪除知識來源

檔案操作故障排除

相關內容

意見反應

其他資源