註
Foundry IQ(Azure AI 搜尋服務)提供直接的索引與查詢 API,並搭配高階知識來源與知識庫 API 用於受控檢索。 使用 Azure 入口網站、REST API 或 Azure SDK 來設定這些功能,或將代理連線到 Microsoft Foundry 入口網站 中的知識庫。
Important
本文中標示為(預覽)的功能或特性目前處於公開預覽狀態,並受 Microsoft Azure 預覽版補充使用條款的約束。
有關 Foundry IQ(Azure AI 搜尋服務)專屬的預覽條款,請參閱預覽功能。
有關連接外部資料來源時適用的術語,請參閱「外部資料來源」。
索引化的 SharePoint 知識來源會將 SharePoint 內容匯入 Foundry IQ(Azure AI 搜尋服務)中的代理式擷取管線。 它已透過 2026-10-01 REST API 正式推出。
知識來源 會獨立建立,並在 知識庫中被引用,並在 執行時查詢知識庫時作為基礎資料。
當您建立索引SharePoint知識來源時,您指定SharePoint 連接字串、模型與屬性,以自動產生下列 Foundry IQ 物件:
- 指向 SharePoint 網站且使用維持不變的連接字串的資料來源。 產生的資料來源遵循 SharePoint 索引器的
TenantId規則。 - 一套技能組合,可以分割並可選擇向量化多模態內容。
- 一個儲存豐富內容且符合代理檢索標準的索引。
- 使用先前物件來驅動編製索引和擴充管線的索引子。
產生的索引器符合 Microsoft 365 索引器的 SharePoint,其先決條件、支援的文件格式及限制同樣適用於索引化的 SharePoint 知識來源。 欲了解更多資訊,請參閱 SharePoint 索引器文件及索引器限制。 若所產生的技能組呼叫外部服務,該技能的輸入與服務限制也會適用。
使用contentExtractionMode來選取或minimal內容擷取,當您standard時。 有關檔案、清單與現代頁面的差異,請參閱 SharePoint 內容表示。
使用支援
| Azure portal | Microsoft Foundry 入口網站 | .NET SDK | Python SDK | Java SDK | JavaScript SDK | REST API |
|---|---|---|---|---|---|---|
| ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
REST 範例使用穩定 2026-10-01 API。 SDK 範例保留下列套件需求;REST 可用性不會決定 SDK 套件的發行狀態。 標示為預覽的功能仍保持其獨立狀態。
先決條件
任何 提供代理檢索的區域內的 Foundry IQ 服務。
完成以下 SharePoint 索引器設定步驟:
步驟 1:為 Foundry IQ 啟用受控識別(僅在使用無密碼驗證時才需要;若使用用戶端密碼則可略過)
步驟 3:建立 Microsoft Entra 應用程式註冊(對於應用程式權限,您同時設定用戶端密鑰或無密鑰驗證)
如果
contentExtractionMode是standard,請使用位於 Foundry Tools 中 Content Understanding 支援的區域 的 Microsoft Foundry 資源,以及https://<resource-name>.services.ai.azure.com端點。 部署嵌入模型,若啟用影像語言化,則部署多模態聊天模型。允許建立知識來源。 建議使用分配給你的使用者帳號的搜尋服務貢獻者和搜尋索引資料貢獻者角色來設定無密鑰認證,或使用管理員 API 金鑰。
對於對 Azure OpenAI 嵌入或影像描述進行受控身分識別呼叫,請將 Cognitive Services OpenAI User 指派給 Azure OpenAI 或上層 Foundry 資源上與
resourceUri相符的所選身分識別。 擷取服務權限是分開的。 請參閱 「指派角色」。SharePoint Online 使用公開端點,獨立於任何 Search 的入站私有端點。 請參閱「 入站與出站網路流量」。
最新的
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-10-01 版本。
對於無金鑰認證,請在
Authorization每個 HTTP 請求的標頭中加入 Microsoft Entra ID 令牌。
對於 REST Client,請在您的 .http 檔案中設定這些變數。 本文後續的資源管理範例使用相同的端點、API 版本及知識來源名稱。
@search-url = https://<search-service-name>.search.windows.net
@api-version = 2026-10-01
@knowledge-source-name = my-indexed-sharepoint-ks
@knowledge-base-name = <your-knowledge-base-name>
@sharepoint-federated-connection-string = <your-federated-connection-string>
@aoai-endpoint = https://<resource-name>.openai.azure.com
請將 connection-string 佔位符替換為您已設定的 federated 連接字串。 設定aoai-endpoint為承載您嵌入部署的 Azure OpenAI 資源。 在建立請求中,將 deploymentId 替換為 embeddingModel.azureOpenAIParameters.resourceUri,並將範例 {{aoai-endpoint}} 替換為您的部署名稱,並設定 modelName 為已部署模型。
刪除範例也使用 knowledge-base-name。 在執行這些範例之前,先將其設定為你打算更新或刪除的所參照的知識庫。
選擇資源所有權
本文使用 knowledge-source API 來管理資料匯入並建立後備索引。 在知識來源上設定來源選擇、內容擷取及其他支援的選項。 檢視 已產生的資源,但避免直接編輯它們。
如果您需要控制索引結構或建立自訂處理管線,請設定 SharePoint 索引器,並透過搜尋索引知識來源連接其已填充的索引。 有關遠端擷取與自訂擷取的替代方案,請參閱 SharePoint 架構選項。
規劃 SharePoint 群組 權限的拓撲
如果您的應用程式需要 SharePoint 群組 權限,請在建立知識來源前評估其網站範圍。 每個產生的索引若使用標記為 sharepointSiteUrl: true 的欄位,最多支援五個不同的網站 URL 值。 對額外網站 URL 的寫入會被拒絕。 另外 100 個 URL 的查詢時彙總上限並不會增加此限制。 請參閱 SharePoint 群組 權限網站限制。
若要擴大網站範圍,請評估以下拓撲:
- 將網站範圍劃分到不同的索引 SharePoint 知識來源,確保每個產生的索引都維持在五個值限制之內。 在每個索引及衍生文件中保留所需的權限欄位與原始站點上下文。
- 將資料來源指派到知識庫,但須在 每個知識庫的最大知識來源數 範圍內。 例如,S1 支援每個知識庫最多 10 個來源。 請查看您的分級與服務建立日期,而非假設此限制適用於所有服務。
- 如果所有必要的資料來源都無法集中在同一個知識庫中,可以考慮多個知識庫。 在選擇此拓撲之前,請先檢查知識來源、知識庫、索引及索引器的每項服務限制。
- 為多個知識庫實作應用程式層級的路由或編排。 擷取要求以單一知識庫為目標,而不是該服務上的所有知識庫。 在每個請求以及合併結果與引用時,保留終端使用者的權限上下文。
檢索時也要檢查 知識來源的選擇。 知識庫中設定的來源數量與請求所選擇的數量是不同的考量。
檢查現有的知識來源
知識來源是一個頂層且可重複使用的物件。 了解現有的知識來源對於重用或命名新物件都很有幫助。
執行以下程式碼,依名稱和類型列出知識來源。
// 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}}
參考資料:知識來源 - 取得
以下回應會遮蔽敏感值。 在重新使用它來建立另一個知識來源之前,請先提供目標連線設定和認證資訊,或設定支援的無密碼驗證;已遮蔽的值不是認證資訊。
{
"name": "my-indexed-sharepoint-ks",
"kind": "indexedSharePoint",
"description": "A sample indexed SharePoint knowledge source",
"encryptionKey": null,
"indexedSharePointParameters": {
"connectionString": "<redacted>",
"containerName": "defaultSiteLibrary",
"query": null,
"ingestionParameters": {
"disableImageVerbalization": false,
"ingestionPermissionOptions": [],
"contentExtractionMode": "minimal",
"identity": null,
"embeddingModel": {
"kind": "azureOpenAI",
"azureOpenAIParameters": {
"resourceUri": "<redacted>",
"deploymentId": "text-embedding-3-large",
"modelName": "text-embedding-3-large",
"authIdentity": null
}
},
"chatCompletionModel": null,
"ingestionSchedule": null,
"aiServices": null
},
"createdResources": {
"datasource": "my-indexed-sharepoint-ks-datasource",
"indexer": "my-indexed-sharepoint-ks-indexer",
"skillset": "my-indexed-sharepoint-ks-skillset",
"index": "my-indexed-sharepoint-ks-index"
}
}
}
建立知識來源
執行以下程式碼建立一個索引化的 SharePoint 知識來源。
範例選取網站的預設文件庫。 若要選擇其他文件庫、清單、頁面或網站,請在下方indexedSharePointParameters設定containerName。query 依照 SharePoint 的內容選擇選項及跨網站選擇要求。
// Create an IndexedSharePoint knowledge source
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.KnowledgeBases.Models;
using Azure.Identity;
var foundryEndpoint = "https://<foundry-resource>.services.ai.azure.com";
var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new DefaultAzureCredential());
var chatCompletionParams = new AzureOpenAIVectorizerParameters
{
ResourceUri = new Uri(foundryEndpoint),
DeploymentName = aoaiGptDeployment,
ModelName = aoaiGptModel
};
var embeddingParams = new AzureOpenAIVectorizerParameters
{
ResourceUri = new Uri(foundryEndpoint),
DeploymentName = aoaiEmbeddingDeployment,
ModelName = aoaiEmbeddingModel
};
var ingestionParams = new KnowledgeSourceIngestionParameters
{
NetworkAccessMode = KnowledgeSourceNetworkAccessMode.Public,
DisableImageVerbalization = false,
ChatCompletionModel = new KnowledgeBaseAzureOpenAIModel(azureOpenAIParameters: chatCompletionParams),
EmbeddingModel = new KnowledgeSourceAzureOpenAIVectorizer
{
AzureOpenAIParameters = embeddingParams
}
};
var sharePointParams = new IndexedSharePointKnowledgeSourceParameters(
connectionString: sharePointConnectionString,
containerName: "defaultSiteLibrary")
{
IngestionParameters = ingestionParams
};
var knowledgeSource = new IndexedSharePointKnowledgeSource(
name: "my-indexed-sharepoint-ks",
indexedSharePointParameters: sharePointParams)
{
Description = "A sample indexed SharePoint knowledge source."
};
await indexClient.CreateOrUpdateKnowledgeSourceAsync(knowledgeSource);
Console.WriteLine($"Knowledge source '{knowledgeSource.Name}' created or updated successfully.");
# Create an indexed SharePoint knowledge source
from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import IndexedSharePointKnowledgeSource, IndexedSharePointKnowledgeSourceParameters, KnowledgeBaseAzureOpenAIModel, AzureOpenAIVectorizerParameters, KnowledgeSourceContentExtractionMode
from azure.search.documents.knowledgebases.models import KnowledgeSourceIngestionParameters, KnowledgeSourceNetworkAccessMode, KnowledgeSourceAzureOpenAIVectorizer
foundry_endpoint = "https://<foundry-resource>.services.ai.azure.com"
index_client = SearchIndexClient(endpoint = "<search-endpoint>", credential = DefaultAzureCredential())
knowledge_source = IndexedSharePointKnowledgeSource(
name = "my-indexed-sharepoint-ks",
description = "A sample indexed SharePoint knowledge source.",
encryption_key = None,
indexed_share_point_parameters = IndexedSharePointKnowledgeSourceParameters(
connection_string = "connection_string",
container_name = "defaultSiteLibrary",
query = None,
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 = foundry_endpoint,
deployment_name = "<aoai-gpt-deployment>",
model_name = "<aoai-gpt-model>",
)
),
embedding_model = KnowledgeSourceAzureOpenAIVectorizer(
azure_open_ai_parameters=AzureOpenAIVectorizerParameters(
resource_url = foundry_endpoint,
deployment_name = "<aoai-embedding-deployment>",
model_name = "<aoai-embedding-model>",
)
),
content_extraction_mode = KnowledgeSourceContentExtractionMode.MINIMAL,
ingestion_schedule = None,
ingestion_permission_options = None
)
)
)
index_client.create_or_update_knowledge_source(knowledge_source)
print(f"Knowledge source '{knowledge_source.name}' created or updated successfully.")
### Create an indexed SharePoint knowledge source
PUT {{search-url}}/knowledgesources/{{knowledge-source-name}}?api-version={{api-version}}
Authorization: Bearer {{search-access-token}}
Content-Type: application/json
{
"name": "{{knowledge-source-name}}",
"kind": "indexedSharePoint",
"description": "A sample indexed SharePoint knowledge source.",
"encryptionKey": null,
"indexedSharePointParameters": {
"connectionString": "{{sharepoint-federated-connection-string}}",
"containerName": "defaultSiteLibrary",
"query": null,
"ingestionParameters": {
"networkAccessMode": "public",
"identity": null,
"embeddingModel": {
"kind": "azureOpenAI",
"azureOpenAIParameters": {
"deploymentId": "text-embedding-3-large",
"modelName": "text-embedding-3-large",
"resourceUri": "https://<foundry-resource>.services.ai.azure.com"
}
},
"chatCompletionModel": null,
"disableImageVerbalization": false,
"ingestionSchedule": null,
"ingestionPermissionOptions": [],
"contentExtractionMode": "minimal"
}
}
}
參考:知識來源 - 建立或更新
設定標準擷取
標準擷取使用 Content Understanding 來進行版面感知解析及對支援的 SharePoint 文件進行語意分塊,並可選擇提供圖片描述。 它使用 必要條件 中所述的 Foundry 資源以及部署。
在建立或更新請求中,設定 indexedSharePointParameters.ingestionParameters:
- 設定
contentExtractionMode為standard並設定aiServices為您的 Foundry 資源端點。 - 將
ingestionPermissionOptions設為["userIds", "groupIds"],以保留 SharePoint 文件權限。 - 設定
chatCompletionModel,使其使用該 Foundry 資源中支援的模型和部署,以進行影像語音化。 將disableImageVerbalization保持設為false,或省略它。 - 在
resourceUri中使用您的 Foundry 資源端點設定embeddingModel.azureOpenAIParameters,例如https://<embedding-resource>.services.ai.azure.com。 為您的嵌入部署設定deploymentId和modelName,並保留建立範例中所需的連線設定。
生成的嵌入技能會在寫入向量至索引之前,先將內容理解的區塊內容(包括生成的圖片描述)傳送到該嵌入端點。
搜尋會產生資料來源、索引器、內容理解技能集以及安全區塊索引。 一旦成功匯入,知識來源即可 指派給知識庫。
內容理解語意區塊與圖片描述通常已在搜尋 REST API 2026-10-01中正式可用。 請在您的設定中使用同時支援 SharePoint 連接器及權限功能的 API 版本。
使用同時支援 SharePoint 索引器與內容理解技能的檔案。 請勿將檔案處理設定套用於以文字解析的清單項目或網站頁面。
標準擷取會產生內容理解費用,啟用影像語音化時,則會產生模型使用費用。 如需更多資訊,請參閱 帳單與影像描述控制項。
如需對技能、分塊處理及受保護的投影有更多控制,請參閱 設定 SharePoint 索引器和內容理解技能集。
設定匯入排程
若未設定匯入排程,已索引的 SharePoint 知識來源預設每 24 小時執行一次產生的索引器。 若要使用較短的重複更新間隔進行權限刷新,請設定 indexedSharePointParameters.ingestionParameters.ingestionSchedule 建立或更新知識來源時的間隔。 設定 interval 為 XSD 持續時間,例如 PT5M 五分鐘,這是最短支援的間隔。
有關排程屬性,請參閱 排程定義。 關於時間限制,請遵循 SharePoint 權限重新整理建議;該間隔並非完成期限或撤銷 SLA。
此知識來源的預設設定不同於直接建立、且不含 schedule 的索引器;後者是隨需執行,而非依定期排程執行。
使用各語言的自動分析器
自動按語言分類的分析工具目前處於預覽階段。 請依照下列章節中的設定與驗證步驟操作;您不需要自己在產生的索引上設定分析器。 關於管理式與直接配置語言分析的區別,請參閱自動各語言分析器。
自 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 新增的。
第一次同步完成後,檢查 lastSynchronizationState.endTime 是否有值,且 itemsUpdatesFailed 為 0。 如果項目失敗,請在查詢知識庫前檢查所報告的錯誤及已產生之索引器執行記錄。
檢視產生的物件
當您建立此知識來源時,Foundry IQ(Azure AI 搜尋服務)會自動產生資料來源、索引器與索引,並在擷取管線需要技能集時一併產生技能集。 建立回應會列出 createdResources 下的每個物件。
這些物件依據固定模板產生,名稱則取自知識來源的名稱。 你無法更改物件名稱。 避免直接編輯這些物件,因為變更可能會產生錯誤或不相容,破壞索引器管線。
僅針對符合資格的 Blob、ADLS Gen2 及 Azure SQL 來源,臨時網路覆寫允許變更產生索引器的執行環境。 此例外不適用於已索引的 SharePoint 或 OneLake,也不允許其他產生物件的變更。 後續的知識來源更新或重新產生可能會覆寫此覆寫設定。
你可以使用 Azure 入口網站來驗證物件建立。 工作流程如下:
檢查索引器上的成功或失敗訊息。 連線或配額錯誤會出現在這裡。
請檢查資料來源以確認與資料儲存的連結。 連線會依據您設定知識來源的方式,使用連接字串或受控識別。
如果某個技能組合被生成,請檢查其擴充與向量化設定。 只有在您指定
embeddingColumns時,SQL 知識來源才會產生技能集。檢查索引,了解你的內容如何被索引並展示以便檢索,包括哪些欄位可搜尋和篩選,哪些欄位儲存向量以便相似度搜尋。 使用搜尋總管對產生的索引執行查詢。
確認產生的資料來源已選取預期的 SharePoint 網站與內容。 檢查已填入索引中的已知來源項目,然後透過知識庫驗證檢索及其來源引用。 僅僅成功建立資源並不能確認內嵌已完成。
指派至知識庫
如果你對知識來源感到滿意,就 把它加入知識庫。
對於指定索引SharePoint知識來源的知識庫,請務必將 includeReferenceSourceData 設為 true。 此步驟是將原始文件網址拉入引用中所必需的。
查詢知識庫
設定知識庫後, 呼叫擷取動作或 MCP 端點 查詢知識來源。 選擇符合你情境的配置。
強制執行文件層級權限
若要匯入明確的使用者與群組指派,請設定 indexedSharePointParameters.ingestionParameters.ingestionPermissionOptions 為 ["userIds", "groupIds"]。 請在擷取請求中包含使用者的存取權杖,如「 在查詢時強制執行權限(預覽)」所述。
在支援時,使用預設的擷取選項(contentExtractionMode: "minimal")或基於內容理解的標準擷取(contentExtractionMode: "standard")。 每個產生的區塊都會保留來源項目的權限元資料與來源上下文。 文件層級權限不支援客戶選取的特殊解析模式。 請參閱 支援權限擷取的剖析和內容擷取。 在知識來源上設定這些選項;不要更改生成的解析器設定。
為您需要的群組類型選擇驗證與權限選項:
| Authentication |
groupIds 包含 |
已匯入的群組權限 |
|---|---|---|
| 同盟驗證 | Yes | Microsoft Entra 與原生 SharePoint 網站群組。 |
| 客戶端密碼 | Yes | 僅限 Microsoft Entra 群組。 |
| 任一方法 | No | 沒有群組 ACL 攝取。 針對明確的使用者指派,請另行設定 userIds 。 |
聯合群組支援需要您的 ACL 情境所需的 Microsoft Graph 和 SharePoint 權限。 在產生的索引中,會 sharePointConnectorAppRegistration.federatedCredentialId 使用所選受管理身份的應用程式 ID,而非聯邦認證物件的 ID。
在依賴權限篩選檢索前,先檢查 產生的物件 :
- 確認產生的資料來源
indexerPermissionOptions是否符合所要求的使用者及群組擷取設定。 - 確認索引已啟用
permissionFilterOption,並包含欄位註解,包含所需permissionFilter值及所需的metadata_spo_item_path來源路徑欄位。 對於沒有填入路徑的現有記錄,請遵循 回填指引;光是新增欄位並不會自動填入這些路徑。 - 對於聯邦
groupIds,請檢查sharePointConnectorAppRegistration、其應用程式識別碼,以及標記為sharepointSiteUrl: true的欄位。 確認網站對應使用每個項目的metadata_spo_site_url,包括跨網站選取項目。 - 檢查每個區塊上來源路徑、請求的使用者與群組 ACL,以及適用的網站 URL。 請將投影產生的索引鍵和父系識別保留為未對應。
- 檢查索引器的執行結果,然後使用 ACL 驗證檢查具代表性的文件與區塊。 比較擷取或權限重新整理後測試使用者被允許與被拒絕的結果。
使用 SharePoint 欄位與對應需求來區分來源路徑、網站上下文與文件庫,以及資產與項目身份。
支援的 權限模型 包含繼承指派及群組巢狀,範圍涵蓋五個層級,但須遵守站點層級巢狀解析限制。 SharePoint ACL 擷取或查詢時權限強制執行不支援組織範圍的共用連結(「組織中的人員」)。 不支援分享連結到期強制執行。 產生的資源不會加入到期日強制執行機制。 獨立支援的明確授權與連結的到期時間無關。
此知識來源會評估一組複寫的 SharePoint 權限,以及 與 SharePoint 權限模型的差異和繼承的連接器限制,包括條件存取限制。 關於遠端、索引與推送 API 的權衡,請參閱「 選擇擷取方法以保持新鮮度」。 權限更新會遵循所產生索引器的 SharePoint 同步行為。
關於索引 SharePoint 權限查詢中遺失、意外或失敗的結果,請參見故障排除 SharePoint 權限過濾。
對於現有的知識來源,您無法直接更改 連接字串 和 ingestion 權限選項。 變更這些設定:
- 建立一個替換知識來源,包含所需的驗證、網站授權與權限選項。
- 完成匯入並檢查其產生的物件,使用前述步驟中的檢查。
- 在更新知識庫以使用替代項之前,請先確認允許與拒絕的使用者結果。 重設或重新同步舊索引器不會改變其知識來源的權限選項。
呈現文件內嵌影像
影像服務目前處於預覽階段,且需要受支援的預覽 API。
要在答案綜合回應中呈現文件嵌入的影像(如圖表或掃描圖),請在此知識來源上設定 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}}參考資料:知識來源 - 刪除
已知錯誤
產生的 SharePoint 資料來源與索引器使用與直接設定的 SharePoint 索引器相同的 Microsoft Entra 租戶驗證與認證行為。 對於與租用戶相關的失敗,請檢閱所產生之索引子的狀態與執行記錄,然後依照Invalid AAD tenant補救步驟進行處理。
針對其他驗證、連線或權限失敗,請找出故障的連線。 區分對 Foundry IQ 服務的存取、SharePoint 匯入、查詢時權限解析,以及對模型或 Foundry 端點的呼叫。