Note
Foundry IQ(Azure AI 搜尋服務)提供直接的索引與查詢 API,並搭配高階知識來源與知識庫 API 用於受控檢索。 使用 Azure 入口網站、REST API 或 Azure SDK 來設定這些功能,或將代理連線到 Microsoft Foundry 入口網站 中的知識庫。
建立索引後,您可以使用 Azure 入口網站存取其統計資料與定義,或將其從 Foundry IQ 服務中移除。
建立索引後,您可以使用 Foundry IQ REST API 存取其統計資料與定義,或將其從 Foundry IQ 服務中移除。
建立索引後,您可以使用 .NET、Java、JavaScript 或 Python 的 Azure SDK,存取索引的統計資料與定義,或從您的 Foundry IQ 服務中移除索引。
本文說明如何管理索引,而不會影響其內容。 如需修改索引定義的指引,請參閱在 Foundry IQ 中更新或重建索引。
局限性
您的 Foundry IQ 服務的定價層級決定了索引、欄位與文件的最大數量與大小。 更多資訊請參閱 Foundry IQ 中的服務限制。
否則,下列限制適用於索引管理:
您無法將索引離線以進行維護。 索引一律可供搜尋作業使用。
您無法直接在 Foundry IQ 服務內或跨 Foundry IQ 服務複製或建立索引副本。 .NET 與 Python 的備份與還原範例說明匯出定義與文件。 在還原包含祕密資訊的定義之前,請先執行「備份、還原或複製索引」。 範例匯出並非認證資訊備份。
處理索引定義中的密鑰
GET 和 LIST 回傳的是資源定義,而非憑證備份。 回應可以遮蔽或省略建立其他資源所需的祕密:
| Configuration | 讀取呈現方式 | 建立或複製需求 |
|---|---|---|
Azure OpenAI vectorizerazureOpenAIParameters.apiKey |
儲存的金鑰會以 <redacted> 傳回。 |
提供目標模型資源的金鑰,或設定支援的管理式身份驗證與授權。 |
自訂 Web API 向量器 customWebApiParameters.httpHeaders |
每個標頭值會以 <redacted> 傳回。 |
提供目標端點的標頭值。 |
自訂 Web API 向量器 customWebApiParameters.uri |
敏感的 code 和 sig 查詢值會被遮蔽。 |
如有需要,請提供實際的目標查詢憑證。 |
<redacted> 和 <unchanged> 不是憑證。 只有對同一既有資源及含有秘密的屬性進行受支援的更新,才能保留已儲存的值。 新索引、重新命名的複本或其他服務中的索引,沒有可保留的來源密鑰。 不要假設每個向量器或 API 都支援相同的保存行為。
對於 Azure OpenAI 向量器,省略 apiKey 會根據向量器的驗證合約選擇管理式身分識別驗證。 省略並不是中立的「之後再設定」狀態。 在使用此模式之前,先設定所選的搜尋身份及其模型資源角色指派。
建立帶有模型鍵的索引
以下完整的 REST 主體會使用 text-embedding-3-small 部署建立索引。 首先,將資源值與部署值替換為您的模型配置。 在發送請求前,請先以您用戶端中的金鑰取代 ${AZURE_OPENAI_API_KEY} 。 此表示法為用戶端替換,而非服務端插值。 不要傳送字面變數,也不要把替換後的主體存進版本控制或日誌。
使用您現有的搜尋驗證傳送Content-Type: application/json與POST https://<search-service>.search.windows.net/indexes?api-version=2026-10-01:
{
"name": "model-index",
"fields": [
{ "name": "id", "type": "Edm.String", "key": true },
{
"name": "contentVector", "type": "Collection(Edm.Single)",
"searchable": true, "dimensions": 1536, "vectorSearchProfile": "model-profile"
}
],
"vectorSearch": {
"algorithms": [{ "name": "hnsw", "kind": "hnsw" }],
"profiles": [{
"name": "model-profile", "algorithm": "hnsw", "vectorizer": "model-vectorizer"
}],
"vectorizers": [{
"name": "model-vectorizer", "kind": "azureOpenAI",
"azureOpenAIParameters": {
"resourceUri": "https://contoso.openai.azure.com",
"deploymentId": "text-embedding-3-small",
"modelName": "text-embedding-3-small",
"apiKey": "${AZURE_OPENAI_API_KEY}"
}
}]
}
}
參考資料: 索引 - 建立。
在同一索引更新時保留鍵值
在前一個建立成功取得真實金鑰後,這個完整主體會更新該索引的描述,同時保留其儲存的金鑰。 使用相同的搜尋驗證與 JSON 內容類型傳送 PUT https://<search-service>.search.windows.net/indexes/model-index?api-version=2026-10-01 。
此範例保持向量化器名稱、類型、資源 URI、部署、模型及驗證模式不變。 當 Azure OpenAI 向量器能依名稱、類型及資源 URI 比對現有向量器時,其現有的 apiKey 可接受 <redacted> 或 <unchanged>。 不要把遺漏當作金鑰保留。 對於不同模型設定或驗證模式,請提供預期的認證,或明確設定支援的受控識別。
{
"name": "model-index", "description": "Updated description",
"fields": [
{ "name": "id", "type": "Edm.String", "key": true },
{
"name": "contentVector", "type": "Collection(Edm.Single)",
"searchable": true, "dimensions": 1536, "vectorSearchProfile": "model-profile"
}
],
"vectorSearch": {
"algorithms": [{ "name": "hnsw", "kind": "hnsw" }],
"profiles": [{
"name": "model-profile", "algorithm": "hnsw", "vectorizer": "model-vectorizer"
}],
"vectorizers": [{
"name": "model-vectorizer", "kind": "azureOpenAI",
"azureOpenAIParameters": {
"resourceUri": "https://contoso.openai.azure.com",
"deploymentId": "text-embedding-3-small",
"modelName": "text-embedding-3-small",
"apiKey": "<redacted>"
}
}]
}
}
參考資料: 索引 - 建立或更新。
自訂的 Web API 向量器具有不同的 URI 與標頭保留規則。 這些規則並不支援保留另一個向量器的屬性。
解決憑證驗證錯誤
建立與更新請求會在佈建或套用定義前驗證設定。 不要建立一個帶有遮蔽佔位符的無效資源,然後打算事後再修正。
如果請求無法將保留預留位置符與現有密鑰相符,請提供實際的目標認證。 檢查索引名稱、向量器名稱與類型、端點及屬性。 針對自訂 Web API 查詢或標頭匹配失敗,請依照 屬性專屬規則操作。
對於缺少或空的 Azure OpenAI 金鑰,請確認您是否打算選擇受管理身份。 請驗證所選身份的授權,而非假設金鑰已被保留。 不要將不相容的驗證設定(例如金鑰與 authIdentity)合併。 若變更端點、模型或驗證,請取得目標憑證或設定目標身分後再重新提交。
備份、還原或複製索引
將定義和可擷取的文件與憑證分開匯出。 由 GET 或 LIST 回傳的定義可以包含遮蔽佔位符,或省略唯寫屬性。 檢視每種資源類型的合約;光搜尋 <redacted> 是不夠的。
如果備份工具複製 GET 回應,只更改索引名稱,且未更改提交,請調整還原步驟以先提供目標驗證。 不要將該工作流程原樣用於包含敏感資訊的索引。
- 匯出非機密定義及還原所需的文件。 將機密資料排除在結構備份、儲存庫和日誌之外。
- 檢查含有秘密值的屬性是否有已刪節的值與僅寫遺漏。 記錄所需的憑證來源,但不記錄憑證本身。
- 將來源相依性對應至目標:模型部署、外部連線、閘道設定、端點原則、受管理身分、角色指派、私人連線及客戶管理的金鑰存取。
- 重建目標相依關係與授權。 新的 Foundry IQ 服務的身份不會繼承舊身份的角色或網路存取權。
- 從安全儲存中取得目標金鑰、OAuth 秘密或其他認證,並在提交每個完整定義前將這些認證注入到用戶端。 或者,設定明確支援的受控識別模式。 不要在建立請求中攜帶來源保留的佔位符。
- 依相依順序建立有效的目標資源。 成功的建立或 GET 並不代表外寄模型或自訂 API 呼叫成功。
- 以受控請求驗證目標驗證、連線性,以及模型或自訂 API 行為。 接著載入文件或執行索引器並驗證搜尋結果,再切換應用程式。
關於區域移動,請參閱將您的 Foundry IQ 服務移至另一個 Azure 區域。
檢視所有索引
若要檢視所有索引:
前往 Azure 入口網站中的 Foundry IQ 服務。
從左窗格中,選取 [搜尋管理>索引]。
根據預設,索引會以遞增順序依名稱排序。 您可以選取對應的數據行標頭,依 [名稱]、 [文件計數]、[ 向量索引配額使用量] 或 [ 記憶體大小總計 ] 排序。
使用 索引 - 清單(REST API) 來擷取您 Foundry IQ 服務上的所有索引。
### List all indexes
GET https://[service name].search.windows.net/indexes?api-version=[api version]
Content-Type: application/json
api-key: [admin key]
在 2026-11-01-preview 和 2026-10-01 REST API 中,列出作業使用伺服器端分頁。 當有更多結果可用時,回應會包含接續 URL。 追蹤每個續接網址,直到回應遺漏該網址為止。 完整模式與範例請參閱 「逐頁瀏覽 Foundry IQ 清單結果」。
使用您偏好的 Azure SDK 來擷取 Foundry IQ 服務上的所有索引。
Azure SDK for .NET 提供用於此任務的 GetIndexesAsync。
// Create a SearchIndexClient
var endpoint = new Uri("[service endpoint]");
var credential = new AzureKeyCredential("[admin key]");
var indexClient = new SearchIndexClient(endpoint, credential);
// List all indexes
await foreach (var index in indexClient.GetIndexesAsync())
{
Console.WriteLine(index.Name);
}
使用伺服器端分頁的清單操作,當有更多結果可用時,會回傳一個續頁 URL。 有關支援的用戶端函式庫版本與範例,請參閱「逐頁瀏覽 Foundry IQ 清單結果」。
檢視索引的統計數據
在索引頁面上,入口網站提供下列統計數據:
- 索引中的文件數目。
- 索引所使用的儲存空間。
- 索引所使用的向量儲存空間。
- Foundry IQ 服務中每個索引的最大儲存空間, 視您的定價等級而定。 此值不代表索引目前可用的總記憶體。
使用 索引 - 取得統計數據 (REST API) 來擷取索引的檔計數、記憶體使用量和向量記憶體使用量。
### Get index statistics
GET https://[service name].search.windows.net/indexes/[index name]/stats?api-version=[api version]
Content-Type: application/json
api-key: [admin key]
使用你偏好的 Azure SDK 來取得索引的文件數量、儲存使用量和向量儲存使用量。
.NET 的Azure SDK提供了此任務的 GetIndexStatisticsAsync。
// Create a SearchIndexClient
var endpoint = new Uri("[service endpoint]");
var credential = new AzureKeyCredential("[admin key]");
var indexClient = new SearchIndexClient(endpoint, credential);
// Get index statistics
var statsResponse = await indexClient.GetIndexStatisticsAsync("[index name]");
var stats = statsResponse.Value;
Console.WriteLine($"Number of documents: {stats.DocumentCount:N0}");
Console.WriteLine($"Storage consumed by index: {stats.StorageSize:N0} bytes");
Console.WriteLine($"Storage consumed by vectors: {stats.VectorIndexSize:N0} bytes");
檢視索引的定義
每個索引都是由增強搜尋功能的欄位和可選元件所定義,例如分析器、正規化程式、語詞分隔程序和同義字詞映射。 此定義會決定索引在編製索引和查詢期間的結構和行為。
使用 索引 - 取得 (REST API) 來擷取索引的 JSON 定義。
### Get index definition
GET https://[service name].search.windows.net/indexes/[index name]?api-version=[api version]
Content-Type: application/json
api-key: [admin key]
使用你偏好的 Azure SDK 來取得索引的 JSON 定義。
.NET 的Azure SDK提供 GetIndexAsync 用於此任務。
// Create a SearchIndexClient
var endpoint = new Uri("[service endpoint]");
var credential = new AzureKeyCredential("[admin key]");
var indexClient = new SearchIndexClient(endpoint, credential);
// Get index definition
var index = await indexClient.GetIndexAsync("[index name]");
string indexJson = JsonSerializer.Serialize(index.Value, new JsonSerializerOptions { WriteIndented = true });
Console.WriteLine(indexJson);
刪除索引
警告
您無法復原索引刪除。 在繼續之前,請確定您希望永久從 Foundry IQ 服務中移除該索引及其文件。
使用 索引 - 刪除 (REST API) 永久刪除索引。
### Delete an index
DELETE https://[service name].search.windows.net/indexes/[index name]?api-version=[api version]
Content-Type: application/json
api-key: [admin key]
如果索引已成功刪除,您應該會收到 HTTP/1.1 204 No Content 回應。
使用你偏好的 Azure SDK 永久刪除索引。
Azure SDK for .NET 提供 DeleteIndexAsync 來執行此任務。
// Create a SearchIndexClient
var endpoint = new Uri("[service endpoint]");
var credential = new AzureKeyCredential("[admin key]");
var indexClient = new SearchIndexClient(endpoint, credential);
// Delete the index
await indexClient.DeleteIndexAsync("[index name]");
Console.WriteLine("Index deleted successfully.");