註
Foundry IQ(Azure AI 搜尋服務)提供直接的索引與查詢 API,並搭配高階知識來源與知識庫 API 用於受控檢索。 使用 Azure 入口網站、REST API 或 Azure SDK 來設定這些功能,或將代理連線到 Microsoft Foundry 入口網站 中的知識庫。
Important
本文中標示為(預覽)的功能或特性目前處於公開預覽狀態,並受 Microsoft Azure 預覽版補充使用條款的約束。
如需了解 Foundry IQ(Azure AI 搜尋服務)特定的預覽條款,請參閱 預覽功能。
Blob 知識來源會將 Azure Blob 儲存體 或 ADLS Gen2 的內容匯入 Foundry IQ(Azure AI 搜尋服務)中的代理式擷取管線。 知識來源會個別建立,並在 知識庫中加以引用,且在於執行階段查詢知識庫時作為依據資料使用。
當您建立 blob 知識來源時,會指定外部資料來源、模型和屬性,以自動產生下列 Foundry IQ 物件:
- 一個代表 Blob 容器的資料來源。
- 一套技能組可以從容器中切塊並可選擇向量化多模態內容。
- 一個儲存豐富內容且符合代理檢索標準的索引。
- 使用先前物件來驅動編製索引和擴充管線的索引子。
產生的索引器符合 blob 索引器,其前提條件、支援的文件格式及限制同樣適用於 blob 知識來源。 欲了解更多資訊,請參閱 blob 索引器文件 與 索引器限制。 若所產生的技能組呼叫外部服務,該技能的輸入與服務限制也會適用。
使用支援
| Azure portal | Microsoft Foundry 入口網站 | .NET SDK | Python SDK | Java SDK | JavaScript SDK | REST API |
|---|---|---|---|---|---|---|
| ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
先決條件
位於任何提供代理式擷取的區域的 Foundry IQ 服務。
支援文字內容類型的 blob 容器。 對於可選的圖片語言化,支援的內容類型取決於你的聊天完成模型是否能分析並描述圖片檔案。
如果 為
https://<resource-name>.services.ai.azure.com,請使用位於standard的 Microsoft Foundry 資源,並使用contentExtractionMode端點。 該資源必須有嵌入模型部署,若啟用影像語言化,則需部署多模態聊天模型。允許建立知識來源。 建議使用分配給你的使用者帳號的搜尋服務貢獻者和搜尋索引資料貢獻者角色來設定無密鑰認證,或使用管理員 API 金鑰。
Foundry IQ 服務的受控識別,在來源儲存體帳戶範圍具有 Storage Blob Data Reader,並在 Microsoft Foundry 資源上具有 Cognitive Services User。 如果你在不同的儲存帳號設定資產儲存,也要在該儲存帳號範圍內指定 Storage Blob 資料貢獻者 。 如果原始碼與資產容器共用一個帳號, Storage Blob Data Contributor 同時提供原始碼讀取權限及資產儲存的讀寫權限。
- 對 Azure OpenAI 嵌入或聊天部署進行受控識別呼叫時,請將 認知服務 OpenAI 使用者 指派給所選身分,並在符合
resourceUri的 Azure OpenAI 或上層 Foundry 資源上進行指派。 擷取服務權限是分開的。 請參閱「指派角色」。
- 對 Azure OpenAI 嵌入或聊天部署進行受控識別呼叫時,請將 認知服務 OpenAI 使用者 指派給所選身分,並在符合
如果你設定
networkAccessMode為private,請完成以下要求:使用 S2、S3、L1 或 L2 Foundry IQ 服務。 請查看正式的 共享私人連結支援矩陣,以了解設定與層級需求。
在 Foundry IQ 服務上啟用系統指派或使用者指派的管理識別,並在儲存帳戶上授予其 Storage Blob Data Reader 角色,並使用
ResourceId=/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Storage/storageAccounts/<storage-account>連接字串。 對於使用者指派的身分識別,也請設定ingestionParameters.identity。建立並核准列於 支援資源類型下的儲存連結。 對於 ADLS Gen2,
blob和dfs這兩個連結皆為必填條件。為您的配置所使用的每個受保護模型、擷取、豐富化或資產儲存相依性建立並核准連結。 請針對每個目標和群組 ID,遵循 支援的資源類型。
必備的
Azure.Search.Documents套件:關於
2026-08-01-preview功能,最新預覽包:dotnet add package Azure.Search.Documents --prerelease對於
2026-10-01,最新的穩定套件:dotnet add package Azure.Search.Documents
對於無鑰匙認證,套件如下
Azure.Identity:dotnet add package Azure.Identity
必備的
azure-search-documents套件:關於
2026-08-01-preview功能,最新預覽包:pip install --pre azure-search-documents對於
2026-10-01,最新的穩定套件:pip install azure-search-documents
對於無鑰匙認證,套件如下
azure-identity:pip install azure-identity
必要的搜尋服務 REST API 版本:
預覽功能請見: 2026-11-01-preview
針對一般可用的功能,包括私人擷取功能: 2026-10-01
對於無金鑰認證,請在
Authorization每個 HTTP 請求的標頭中加入 Microsoft Entra ID 令牌。
若要擷取權限資訊,請如 2026-10-01 所示使用 REST 。 穩定 2026-04-01 版 SDK 範例並未設定權限擷取。 請查看套件變更記錄,確認是否支援所需 API 版本及屬性。
REST 範例使用最新的預覽 API,2026-11-01-preview。 預覽版 SDK 範例會維持文件中記載的 2026-08-01-preview 合約。 在鎖定較新的 API 版本之前,請先檢查套件變更日誌。
檢查現有的知識來源
知識來源是一個頂層且可重複使用的物件。 了解現有的知識來源對於重用或命名新物件都很有幫助。
執行以下程式碼,依名稱和類型列出知識來源。
// 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}");
}
# 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})")
### 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));
# 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))
### Get a knowledge source definition
GET {{search-url}}/knowledgesources('{{knowledge-source-name}}')?api-version={{api-version}}
Authorization: Bearer {{token}}
參考資料:知識來源 - 取得
以下回應會遮蔽敏感值,並在 createdResources 下方列出產生的物件。 在重新使用它以建立另一個知識來源之前,請 提供目標憑證或設定支援的受控識別;被刪減的值不是憑證。
{
"name": "my-blob-ks",
"kind": "azureBlob",
"description": "A sample blob knowledge source.",
"encryptionKey": null,
"azureBlobParameters": {
"connectionString": "<REDACTED>",
"containerName": "blobcontainer",
"folderPath": null,
"isADLSGen2": false,
"ingestionParameters": {
"disableImageVerbalization": false,
"ingestionPermissionOptions": [],
"contentExtractionMode": "standard",
"identity": null,
"embeddingModel": {
"kind": "azureOpenAI",
"azureOpenAIParameters": {
"resourceUri": "<REDACTED>",
"deploymentId": "text-embedding-3-large",
"modelName": "text-embedding-3-large",
"authIdentity": null
}
},
"chatCompletionModel": {
"kind": "azureOpenAI",
"azureOpenAIParameters": {
"resourceUri": "<aoai-endpoint>",
"deploymentId": "gpt-5-mini",
"modelName": "gpt-5-mini",
"authIdentity": null
}
},
"ingestionSchedule": null,
"assetStore": null,
"aiServices": {
"uri": "<aoai-endpoint>"
}
},
"createdResources": {
"datasource": "my-blob-ks-datasource",
"indexer": "my-blob-ks-indexer",
"skillset": "my-blob-ks-skillset",
"index": "my-blob-ks-index"
}
}
}
建立知識來源
執行以下程式碼來建立一個 blob 知識來源。
// Create a blob knowledge source
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.KnowledgeBases.Models;
using Azure.Search.Documents.Models;
using Azure.Identity;
var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new DefaultAzureCredential());
var chatCompletionParams = new AzureOpenAIVectorizerParameters
{
ResourceUri = new Uri(aoaiEndpoint),
DeploymentName = aoaiGptDeployment,
ModelName = aoaiGptModel
};
var embeddingParams = new AzureOpenAIVectorizerParameters
{
ResourceUri = new Uri(aoaiEndpoint),
DeploymentName = aoaiEmbeddingDeployment,
ModelName = aoaiEmbeddingModel
};
var ingestionParams = new KnowledgeSourceIngestionParameters
{
NetworkAccessMode = KnowledgeSourceNetworkAccessMode.Public,
DisableImageVerbalization = false,
ChatCompletionModel = new KnowledgeBaseAzureOpenAIModel(azureOpenAIParameters: chatCompletionParams),
EmbeddingModel = new KnowledgeSourceAzureOpenAIVectorizer
{
AzureOpenAIParameters = embeddingParams
},
IngestionPermissionOptions = new List<KnowledgeSourceIngestionPermissionOption>
{
KnowledgeSourceIngestionPermissionOption.RbacScope
}
};
var blobParams = new AzureBlobKnowledgeSourceParameters(
connectionString: connectionString,
containerName: containerName
)
{
IsAdlsGen2 = false,
IngestionParameters = ingestionParams
};
var knowledgeSource = new AzureBlobKnowledgeSource(
name: "my-blob-ks",
azureBlobParameters: blobParams
)
{
Description = "This knowledge source pulls from a blob storage container."
};
await indexClient.CreateOrUpdateKnowledgeSourceAsync(knowledgeSource);
Console.WriteLine($"Knowledge source '{knowledgeSource.Name}' created or updated successfully.");
Reference:SearchIndexClient, AzureBlobKnowledgeSource
# Create a blob knowledge source
from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import AzureBlobKnowledgeSource, AzureBlobKnowledgeSourceParameters, KnowledgeBaseAzureOpenAIModel, AzureOpenAIVectorizerParameters, KnowledgeSourceAzureOpenAIVectorizer, KnowledgeSourceContentExtractionMode, KnowledgeSourceIngestionParameters
from azure.search.documents.knowledgebases.models import KnowledgeSourceNetworkAccessMode
index_client = SearchIndexClient(endpoint = "<search-endpoint>", credential = DefaultAzureCredential())
knowledge_source = AzureBlobKnowledgeSource(
name = "my-blob-ks",
description = "This knowledge source pulls from a blob storage container.",
encryption_key = None,
azure_blob_parameters = AzureBlobKnowledgeSourceParameters(
connection_string = "blob_connection_string",
container_name = "blob_container_name",
folder_path = None,
is_adls_gen2 = False,
ingestion_parameters = KnowledgeSourceIngestionParameters(
network_access_mode = KnowledgeSourceNetworkAccessMode.PUBLIC,
identity = None,
disable_image_verbalization = False,
chat_completion_model = KnowledgeBaseAzureOpenAIModel(
azure_open_ai_parameters = AzureOpenAIVectorizerParameters(
resource_url = "<aoai-endpoint>",
deployment_name = "<aoai-gpt-deployment>",
model_name = "<aoai-gpt-model>",
)
),
embedding_model = KnowledgeSourceAzureOpenAIVectorizer(
azure_open_ai_parameters=AzureOpenAIVectorizerParameters(
resource_url = "<aoai-endpoint>",
deployment_name = "<aoai-embedding-deployment>",
model_name = "<aoai-embedding-model>",
)
),
content_extraction_mode = KnowledgeSourceContentExtractionMode.MINIMAL,
ingestion_schedule = None,
ingestion_permission_options = ["rbacScope"]
)
)
)
index_client.create_or_update_knowledge_source(knowledge_source)
print(f"Knowledge source '{knowledge_source.name}' created or updated successfully.")
### Create a blob knowledge source
PUT {{search-endpoint}}/knowledgesources/my-blob-ks?api-version=2026-11-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/json
{
"name": "my-blob-ks",
"kind": "azureBlob",
"description": "This knowledge source pulls from a blob storage container.",
"encryptionKey": null,
"azureBlobParameters": {
"connectionString": "ResourceId=<storage-resource-id>",
"containerName": "<blob-container-name>",
"folderPath": null,
"isADLSGen2": false,
"ingestionParameters": {
"networkAccessMode": "public",
"identity": null,
"disableImageVerbalization": null,
"chatCompletionModel": {
"kind": "azureOpenAI",
"azureOpenAIParameters": {
"resourceUri": "{{aoai-endpoint}}",
"deploymentId": "{{aoai-gpt-deployment}}",
"modelName": "{{aoai-gpt-model}}"
}
},
"embeddingModel": {
"kind": "azureOpenAI",
"azureOpenAIParameters": {
"resourceUri": "{{aoai-endpoint}}",
"deploymentId": "{{aoai-embedding-deployment}}",
"modelName": "{{aoai-embedding-model}}"
}
},
"contentExtractionMode": "minimal",
"ingestionSchedule": null,
"ingestionPermissionOptions": ["rbacScope"]
}
}
}
參考:知識來源 - 建立或更新
設定匯入排程
設定 ingestionParameters.ingestionSchedule,以控制所產生的索引器輪詢來源變更的頻率。 符合條件且尚未完成的擷取作業可在因執行時間限制而停止後自動繼續,無需等待下一次輪詢。
設定標準擷取
若要使用 Content Understanding 來進行版面擷取與語意分塊,而非前述範例中的 minimal 擷取,請將 contentExtractionMode 設為 standard,並使用您的 Foundry 資源端點設定 aiServices。 使用 先決條件 中所述的資源和部署。
標準擷取會產生 Content Understanding 費用;啟用影像描述時,還會產生模型使用費用。 如需更多資訊,請參閱 計費與影像描述控制項。
限制擷取權限僅限於私人網路
在穩定 2026-10-01 API 中,networkAccessMode 控制 blob 知識來源所產生索引器執行時的網路環境。 此設定只會影響資料擷取,不會變更知識庫擷取請求或回應。 請檢查 共用私有連結支援矩陣 中符合資格的配置。 獨立預覽功能,如自動的各語言分析器與影像提供,仍保留其自身的 API 需求。
networkAccessMode 預設為 public,以保留現有的公共網路行為。 當 networkAccessMode 為 private 時,產生的索引器會在 私有執行環境中執行。 它使用核准的共享私有連結來存取 Azure Blob 儲存體 或 ADLS Gen2 原始碼連線,以及支援的 Azure 相依關係,例如 Azure OpenAI 模型和 Microsoft Foundry 資源。
要配置並驗證私人網路存取:
完成 私人網路的必要條件。
在建立知識來源的請求中,將
networkAccessMode設為private。 您只能在建立過程中設定此屬性,包括在穩定版2026-10-01API 中。 若要稍後變更儲存模式,請刪除並重新建立知識來源。 符合資格的 Blob、ADLS Gen2 和 Azure SQL 來源則可改用臨時生成索引器的網路覆寫。 此例外不適用於已建立索引的 SharePoint 或其他來源類型。如果服務層級或執行時不支援私有執行,或沒有所需的共享私有連結,建立可能會失敗。 Serverless 和 S3 HD 不支援私人執行。 網路安全邊界設定 控制支援的公用端點存取,而非私人執行。
確認產生的索引器
parameters.configuration.executionEnvironment為private。確認每個所需的共用私有連結都已核准、配置完成,且指向正確的相依資源。 僅成功建立並不代表連結已獲核准或已設定目標對象。 如果入口網站檢查無法解決跨訂閱資源,請手動驗證目標資源及 Foundry IQ 服務的核准與準備狀態。
輪詢知識來源狀態直到
lastSynchronizationState.endTime有值為止。 確認itemsUpdatesFailed為0,然後驗證連接器專屬的來源內容。 如果相依項目無法存取,同步就會失敗。
使用自動語言分析器(預覽)
自 2026-08-01-preview API 版本起,Blob、已建立索引的 OneLake,以及已建立索引的 SharePoint 知識來源可使用每種語言的自動分析器。 啟用後,Foundry IQ(Azure AI 搜尋服務)會偵測每個來源文件的語言,並自動套用匹配的 Microsoft 語言分析器。 你不會在知識來源定義或查詢中指定分析器。
若要啟用各語言的自動分析器,請將 contentExtractionMode 設為 minimal,並在知識來源定義中設定 ingestionParameters.aiServices。
對於無金鑰驗證,請省略 aiServices.apiKey,並在您的 Microsoft Foundry 資源上,將 Cognitive Services User 角色指派給 Foundry IQ 服務的受控識別。 對於基於金鑰的認證,請設定 aiServices.apiKey 為 Foundry 資源的有效金鑰。
支援下列語言:
- English
- 日本
- 法語
- 西班牙語
- 德語
- 荷蘭語
- 義大利語
- 巴西葡萄牙文
- 歐洲葡萄牙語
- 簡體中文
- 繁體中文
- 韓語
對於多語言內容,Foundry IQ 會根據主要偵測語言選擇分析器。 當語言不支援或不確定時,它會使用標準分析器。
啟用自動各語言分析器時,Foundry IQ 會在產生的索引結構中為每種支援語言新增語言專屬內容欄位,無論您的資料是否包含這些語言的文件。 在擷取過程中,文件會根據偵測到的語言被導向到相應的語言專屬欄位。
未使用的語言欄位不包含索引內容,且對儲存的影響極小,但仍屬於索引結構,並計入索引欄位的限制。 規劃索引設計、欄位數量及儲存需求時,請考慮額外的欄位。 如需更多資訊,請參閱 索引限制 與 估算與管理 Foundry IQ 服務的容量。
語言偵測 超過免費 AI 擴充配額後即須付費。 欲了解更多資訊,請參閱 免費豐富活動。
導入後,請在不編輯產生物件的情況下驗證語言路由:
- 檢查產生的索引結構。 確認語言專屬欄位有其匹配的分析器,例如
snippet_en,en.microsoft且該snippet_default欄位提供標準分析器的備援。 - 確認產生的語意設定列出了語言專屬的內容欄位和
snippet_default。 - 檢查被偵測為支援語言的文件的索引區塊。 每個區塊的文字都屬於對應的語言欄位。 不支援或不確定的偵測路徑會將文字導向
snippet_default。 - 從填入的語言或備援欄位讀取內容。 在此模式下,產生的結構不包含獨立
snippet欄位。
如果結構或結果不符,請檢視上方啟用設定及 索引器錯誤。 這些檢查並不定義現有產生索引的更新或遷移程序。
檢查吞食狀態
執行下列程式碼以監視擷取進度和健康情況,包括知識來源種類,以及產生索引子管線並填入搜尋索引之知識來源的詳細索引錯誤。
using Azure.Search.Documents.Indexes;
using System.Text.Json;
var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new AzureKeyCredential(apiKey));
// Get knowledge source ingestion status
var statusResponse = await indexClient.GetKnowledgeSourceStatusAsync(knowledgeSourceName);
var status = statusResponse.Value;
// Serialize to JSON for display
var json = JsonSerializer.Serialize(status, new JsonSerializerOptions { WriteIndented = true });
Console.WriteLine(json);
# Check knowledge source ingestion status
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"))
status = index_client.get_knowledge_source_status("knowledge_source_name")
print(json.dumps(status.as_dict(), indent=2))
### Check knowledge source ingestion status
GET {{search-url}}/knowledgesources/{{knowledge-source-name}}/status?api-version={{api-version}}
Authorization: Bearer {{token}}
Content-Type: application/json
參考資料:知識來源 - 取得狀態
包含輸入參數並且正在積極匯入內容的請求回應,其格式可能如以下範例。
{
"kind": "azureBlob",
"synchronizationStatus": "active",
"synchronizationInterval": "1d",
"currentSynchronizationState": {
"startTime": "2026-04-10T19:30:00Z",
"itemUpdatesProcessed": 1100,
"itemsUpdatesFailed": 100,
"itemsSkipped": 1100,
"errors": [
{
"key": "Item id 1",
"docURL": "https://contoso.blob.core.windows.net/contracts/2024/Q4/doc-00023.csv",
"statusCode": 400,
"componentName": "DocumentExtraction.AzureBlob.MyDataSource",
"errorMessage": "Could not read the value of column 'foo' at index '0'.",
"details": "The file could not be parsed.",
"documentationLink": "https://go.microsoft.com/fwlink/?linkid=2049388"
}
]
},
"lastSynchronizationState": {
"status": "partialSuccess",
"startTime": "2026-04-09T19:30:00Z",
"endTime": "2026-04-09T19:40:01Z",
"itemUpdatesProcessed": 1100,
"itemsUpdatesFailed": 100,
"itemsSkipped": 1100,
"errors": null
},
"statistics": {
"totalSynchronizations": 25,
"averageSynchronizationDuration": "00:15:20",
"averageItemsProcessedPerSynchronization": 500
}
}
註
kind屬性和currentSynchronizationState.errors[]陣列提供文件層級錯誤細節,並自 2026-04-01 起於 API 版本中提供。 對於較早期的 API 版本,這些欄位不會回傳。
lastSynchronizationState.status這個欄位也是在 2026-04-01 新增的。
檢視產生的物件
當您建立此知識來源時,Foundry IQ(Azure AI 搜尋服務)會自動產生資料來源、索引器與索引,並在擷取管線需要技能集時一併產生技能集。 建立回應會列出 createdResources 下的每個物件。
這些物件依據固定模板產生,名稱則取自知識來源的名稱。 你無法更改物件名稱。 避免直接編輯這些物件,因為變更可能會產生錯誤或不相容,破壞索引器管線。
僅針對符合資格的 Blob、ADLS Gen2 及 Azure SQL 來源,臨時網路覆寫允許變更產生索引器的執行環境。 此例外不適用於已索引的 SharePoint 或 OneLake,也不允許其他產生物件的變更。 後續的知識來源更新或重新產生可能會覆寫此覆寫設定。
你可以使用 Azure 入口網站來驗證物件建立。 工作流程如下:
檢查索引器上的成功或失敗訊息。 連線或配額錯誤會出現在這裡。
請檢查資料來源以確認與資料儲存的連結。 連線會依據您設定知識來源的方式,使用連接字串或受控識別。
如果某個技能組合被生成,請檢查其擴充與向量化設定。 只有在您指定
embeddingColumns時,SQL 知識來源才會產生技能集。檢查索引,了解你的內容如何被索引並展示以便檢索,包括哪些欄位可搜尋和篩選,哪些欄位儲存向量以便相似度搜尋。 使用搜尋總管對產生的索引執行查詢。
將產生的資料來源、索引器、索引及技能集(如存在)視為單一匯入配置。 限制誰可以變更該設定或將文件發佈到其索引。 產生的識別碼與權限欄位名稱不會建立文件所有權,也不會讓一般內容成為授權來源。 遵循 預防性攝取指引 及文件中的自訂邊界;不要用任意直接編輯產生的金鑰或對應作為所有權控制。
指派至知識庫
如果你對知識來源感到滿意,就 把它加入知識庫。
查詢知識庫
設定知識庫後, 呼叫擷取動作或 MCP 端點 查詢知識來源。 選擇符合你情境的配置。
強制執行文件層級權限
在支援時,使用預設的擷取選項(contentExtractionMode: "minimal")或基於內容理解的標準擷取(contentExtractionMode: "standard")。 每個產生的區塊都會保留來源項目的權限元資料與來源上下文。 文件層級權限不支援客戶選取的特殊解析模式。 請參閱 支援權限擷取的剖析和內容擷取。 在知識來源中設定這些選項;不要變更已產生的剖析器設定。
使用 REST API ingestionPermissionOptions 建立知識來源時,設定 2026-10-01:
- 對於標準 Blob 儲存體,請設定
isADLSGen2為false並請求rbacScope。 請參閱 完整 Blob REST 設定。 - 針對 ADLS Gen2,請將
isADLSGen2設為true,並要求userIds、groupIds和rbacScope。 先使用 ADLS REST 設定,並將rbacScope新增至其ingestionPermissionOptions陣列,以匯入 ACL 和容器 RBAC 範圍。
產生的索引包含 metadata_storage_path 及已設定的權限欄位,並在投影區塊上設定映射。 此路徑是 ADLS 權限匯入(包括僅 RBAC 擷取)所必需的。 它出現在生成的標準 Blob 架構中,並不代表它是計算直接 Blob 索引器的容器範圍的必要條件。
一起檢閱已產生的索引、技能集投影和索引器。 在每個受保護區塊上保留來源路徑上下文與權威權限映射。 對於有缺失值的現有記錄,僅修正結構並不會回填中繼資料;請遵循 結構與投影修復。
產生的 ADLS 索引器會遵循 自動 ACL 刷新設定與節奏。 在產生的索引器上進行設定 parameters.configuration.refreshAllAcls 。 對於隨需重新整理,請在 權限重新同步程序中使用該索引器的名稱。
在擷取要求中包含委派使用者的存取權杖。 關於請求標頭,請參閱「 在查詢時強制執行權限」。
Surface 文件內嵌影像(預覽)
要在答案綜合回應中呈現文件嵌入的影像(如圖表或掃描圖),請在此知識來源上設定 assetStore ,然後在知識庫啟用影像服務。 設定時 ingestionPermissionOptions 不支援影像服務。 如需詳細資訊,請參閱 在 agentic retrieval 中呈現文件內嵌影像(預覽)。
刪除知識來源
在刪除知識來源之前,必須刪除所有引用該來源的知識庫,或更新知識庫定義以移除該參考。 對於產生索引與索引管線的知識來源,所有 產生的物件 也會被刪除。 不過,如果你用現有的索引建立知識來源,你的索引不會被刪除。
如果你嘗試刪除正在使用的知識來源,該動作會失敗,並回傳一份受影響的知識庫清單。
刪除知識來源:
取得您 Foundry IQ 服務中所有知識庫的清單。
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}"); }一個範例回應可能如下:
{ "@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);一個範例回應可能如下:
{ "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.");刪除知識來源。
await indexClient.DeleteKnowledgeSourceAsync(knowledgeSourceName); System.Console.WriteLine($"Knowledge source '{knowledgeSourceName}' deleted successfully.");
取得您 Foundry IQ 服務中所有知識庫的清單。
# 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}")一個範例回應可能如下:
{ "@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)一個範例回應可能如下:
{ "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.")刪除知識來源。
# 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.")
取得您 Foundry IQ 服務中所有知識庫的清單。
### 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}}參考資料:知識來源 - 刪除