將代理檢索代碼遷移至最新版本

註

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

Important

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

如果你的代理式檢索程式碼針對較早的 API 版本，本文將說明何時以及如何遷移到較新版本。同時也說明了所有支援代理檢索的 API 版本的破壞性變更與非破壞性變更。

遷移說明的目的是幫助你在較新的 API 版本上執行現有解決方案。本文的說明能幫助你在 API 層級處理破壞性變更，讓你的應用程式能像以前一樣運作。如果你想加入新功能，可以從 What's new in Azure AI 搜尋服務開始。

提示

使用 Azure SDK 取代 REST？在升級套件並套用相關遷移變更前，先查看你 SDK 語言的變更日誌，確認目標 API 版本是否支援。

何時遷移

大多數支援代理檢索的版本都引入了破壞性變更。你可以保留 API 版本值，繼續執行舊程式碼不改動，但要享受錯誤修正、改進和新功能，必須更新程式碼。

如果您的程式碼目標是預覽版，我們建議只有在您的使用情境完全支援 2026-04-01的情況下，才遷移到最新穩定版。如果您依賴答案合成、非 minimal 推理程度，或多輪訊息，請先檢閱重大和非重大變更，再決定是否移轉。這些功能仍處於預覽階段。

移轉之前

為了了解變更範圍，請檢視每個版本的破壞性變更與非破壞性變更。
支援的遷移路徑是漸進式的。如果你的程式碼目標是 2025-05-01-preview，先遷移到 2025-08-01-preview，然後繼續執行每個版本直到達到目標版本。
對於並行移轉，請建立名稱唯一的物件，以實作前一版本的行為。這種方法在你開發和測試替換物件的同時，保留現有物件。如果某個物件支援就地更新，各版本的特定步驟會特別指出該選項。
對於每個遷移的物件，先從搜尋服務取得目前的定義，這樣你才能在指定新物件前檢視現有屬性。
只有在遷移完全測試並部署完成後，才刪除舊版本。

如何遷移

本節涵蓋以下 API 版本的遷移步驟：

2026-08-01-預覽
2026-05-01-預覽
2026-04-01
2025-11-01-預覽
2025-08-01-預覽

2026-08-01-預覽

如果你是從 2026-05-01-preview 遷移過來，可以直接遷移到 2026-08-01-preview。此移轉需要更新 Work IQ 知識來源、列表分頁、回應處理、MCP 伺服器工具，以及受影響的已產生用戶端呼叫。

移轉 Work IQ 知識來源
更新列表分頁
更新檢索回應處理
更新程式碼與用戶端

移轉 Work IQ 知識來源

要將 Work IQ 知識來源遷移到新的認證設定：

匯出其現行定義。
使用 Knowledge Sources - Create Or Update 更新現有的知識來源，或建立一個具有唯一名稱的替代知識來源，以進行並行移轉。
使用 2026-08-01-preview API 版本並設定 workIQParameters.entraAppAuthentication。 applicationId federatedCredentialId這些屬性是必要的。該 tenantId 物業為可選，並預設由搜尋服務的租戶持有。
如果你建立了替代來源，請更新每個參照先前知識來源的知識庫，使其改用替代來源的名稱。
更新擷取要求，以在 x-ms-query-work-iq-source-authorization 標頭中傳遞使用者判斷提示。

關於設定與範例，請參閱「建立 Work IQ 知識來源（預覽）」。

更新清單分頁

要將偏移分頁取代為游標分頁：

從知識來源清單要求中移除 $top、$skip 和 $count。設定 pageSize 從 1 到 3,000 來控制頁面大小。如果你省略了，服務會選擇頁面大小。
若要依名稱篩選，請設定 search 和 searchType。唯一支援 searchType 的值是 prefix，這也是預設值。以下請求回傳最多 100 個名稱以 contoso為開頭的知識來源。
```
GET {{search-endpoint}}/knowledgesources?api-version=2026-08-01-preview&pageSize=100&search=contoso&searchType=prefix
Authorization: Bearer {{search-access-token}}
```
參考資料：知識來源列表
如果回應包含 @odata.nextLink，則傳送該 URL 與回傳完全相同。不要解析或修改它的延續狀態。

更新擷取回應處理

若要處理新的 Work IQ 參照和模型支援的活動圖形：

移除對 attributions、 WorkIQAttribution、 seeMoreWebUrl和的依賴關係。從 searchSensitivityLabelInfo 讀取 Work IQ 參考資料中的敏感度標籤中繼資料。
在查詢規劃、答案彙整及網頁摘要活動記錄中，從巢狀的 deploymentId 物件讀取 modelName 和 model。巢狀物件和這兩個屬性都是可選的。

以下片段展示了反應形態的變化。

{
  "references": [
    {
      "type": "workIQ",
      "id": "<reference-id>",
      "activitySource": 1,
      "sourceData": {},
      "attributions": [
        {
          "seeMoreWebUrl": "<attribution-url>"
        }
      ]
    }
  ],
  "activity": [
    {
      "type": "modelAnswerSynthesis",
      "id": 2,
      "modelName": "<model-name>"
    }
  ]
}

在 2026-08-01-preview中，相同的片段使用以下形狀：

{
  "references": [
    {
      "type": "workIQ",
      "id": "<reference-id>",
      "activitySource": 1,
      "sourceData": {},
      "searchSensitivityLabelInfo": {
        "displayName": "<label-name>",
        "sensitivityLabelId": "<label-id>"
      }
    }
  ],
  "activity": [
    {
      "type": "modelAnswerSynthesis",
      "id": 2,
      "model": {
        "modelName": "<model-name>",
        "deploymentId": "<deployment-id>"
      }
    }
  ]
}

更新適用於 2026-08-01-preview 的程式碼和用戶端

要完成您的遷移：

在每個 MCP 伺服器tools項目中，將 inclusionMode 取代為 resultsProcessing。將 reranked 映射到 rerank，並將 always 映射到 none。 rerank 值為預設值。這個 none 值繞過重新排序，並保留工具的底層結果順序。關於設定，請參見「配置 MCP 伺服器知識來源工具」。
如果你使用 Azure SDK，請安裝支援 2026-08-01-preview的套件，並檢視位置列表呼叫以判斷參數順序變更。 REST 呼叫者不會受到影響，因為 HTTP 參數是以名稱來鍵定的。在 C# 中，偏好命名參數，例如 GetKnowledgeSourcesAsync(search: ..., pageSize: ...)。在 Python 中，將列表選項作為關鍵字參數傳遞。
在更新生產環境之前，請先測試 Work IQ 的驗證與參照、游標分頁、活動記錄的反序列化、MCP 伺服器結果排序，以及產生的用戶端呼叫。
如果你建立了替代的 Work IQ 知識來源，請在遷移通過所有測試、更新的應用程式部署完畢且沒有知識庫引用之前名稱後刪除早期的來源。

2026-05-01-預覽

如果你是從 2026-04-01 或 2025-11-01-preview 遷移過來，你可以直接移到 2026-05-01-preview。這些版本的請求、回應與持久物件仍保持相容。差異在於加法功能與語言 SDK 的重新命名。

在 REST 請求中將 API 版本更新為 2026-05-01-preview。 SDK 用戶端使用套件的預設 API 版本，因此不需要傳遞明確 serviceVersion 的參數。建議升級到 2026-05-01-preview SDK 套件。
如果你使用 Python 或 JavaScript SDK，請將擷取用戶端更新為 KnowledgeBaseRetrievalClient，並呼叫 retrieve(...)，取代舊有的 retrieveKnowledge(...)。完整的 SDK 形狀映射，請參閱 2026-05-01 預覽版的更新程式碼與客戶端。
（選用）採用新的 2026-05-01-preview 功能，例如新鮮度感知擷取、每個來源和最終結果的文件數量上限、持續保存的擷取預設值、知識庫的 CORS，以及擷取回應中的 Purview 敏感度標籤中繼資料。這些功能並非維持現有解決方案運作的必要條件。

更新適用於 2026-05-01-preview 的程式碼與用戶端

SDK 2026-05-01-preview 在支援語言中引入代碼形態變更：

語言	遷移更新
Python	將 retrieve 用戶端建立為 `KnowledgeBaseRetrievalClient(endpoint=..., credential=..., knowledge_base_name=...)`。建構例如 `KnowledgeRetrievalLowReasoningEffort()` 這類的推理強度實例，並在知識庫或檢索請求中傳入字串 `output_mode="answerSynthesis"`。傳遞 `AzureOpenAIVectorizerParameters(resource_url=...)`（由 `resource_uri` 重新命名而來），使用資源根端點，而非 `/openai/v1` 端點。
.NET	將擷取用戶端建立為 `new KnowledgeBaseRetrievalClient(endpoint, knowledgeBaseName, credential)`，並傳遞 `AzureKeyCredential` 或權杖認證。若要將基於金鑰的 Azure OpenAI 模型附加到知識庫，請將模型 API 金鑰設為 `AzureOpenAIVectorizerParameters.ApiKey`。
JAVA	使用 `KnowledgeBaseRetrievalClientBuilder` 來建立擷取客戶端並讀取結果為 `KnowledgeBaseRetrievalResult`。 `KnowledgeBaseRetrievalOptions` 現在除了公開 `setMessages(...)` 與 `setIntents(...)` 之外，還公開了 `setRetrievalReasoningEffort`、`setOutputMode`、`setMaxOutputSize` 和 `setMaxOutputDocuments`，因此以訊息為基礎的擷取與答案合成無需語意意圖變通作法即可運作。 `KnowledgeBase`加上`setOutputMode`、`setRetrievalReasoningEffort`、`setRetrievalInstructions`、`setAnswerInstructions`和`setCorsOptions`。 `SearchIndexKnowledgeSourceParams` 新增 `setAlwaysQuerySource`、`setFailOnError`、`setMaxOutputDocuments`和`setEnableImageServing`。
JavaScript 和 TypeScript	請使用 `KnowledgeRetrievalClient.retrieve({ intents: [{ type: "semantic", search: query }] })`。前述 `retrieveKnowledge(...)` 方法被移除，改為 `retrieve(...)`。

更新客戶端圖形後，執行整個流程，建立索引、上傳文件、建立知識來源、建立知識庫、發出檢索請求，並清理資源以確認端到端遷移。

2026-04-01

如果你是從 2025-11-01-preview 遷移，可以直接遷移到 2026-04-01。您的索引和內容保持不變。你只需要更新知識庫架構和取回請求的 shape 即可。

遷移知識來源
遷移知識庫
更新取回請求
更新帳單同意
更新程式碼與用戶端

遷移知識來源

在 2026-04-01 中，searchIndex、azureBlob、indexedOneLake 和 web 這幾種知識來源類型已正式推出。其他知識來源類型仍處於預覽階段。

使用 Knowledge Sources - Get （REST API）來取得目前的定義。

GET {{search-endpoint}}/knowledge-sources/{{knowledge-source-name}}?api-version=2025-11-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

在回應中，請明確哪些要帶過去，哪些要刪除：
- 對於 searchIndex 和 web，所有屬性值都會被繼承。
- 對於 azureBlob 和 indexedOneLake，將所有性質值都帶進去，但要從 ingestionPermissionOptions 省略 ingestionParameters。在 2026-04-01 中不支援此屬性。

使用 Knowledge Sources - Create 或 Update （REST API）來建立一個擁有獨特名稱、 2026-04-01 API 版本及前一步屬性值的新知識來源。

以下範例展示了一個 searchIndex 知識來源。對 azureBlob、indexedOneLake 和 web 知識來源使用類似的模式。

PUT {{search-endpoint}}/knowledge-sources/{{new-knowledge-source-name}}?api-version=2026-04-01
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

{
  "name": "{{new-knowledge-source-name}}",
  "description": "Knowledge source backed by a search index.",
  "kind": "searchIndex",
  "searchIndexParameters": {
    "searchIndexName": "{{index-name}}",
    "sourceDataFields": [
      { "name": "id" },
      { "name": "page_chunk" },
      { "name": "page_number" }
    ]
  }
}

進行知識庫遷移

知識 2026-04-01 庫的架構比 2025-11-01-preview 版本簡單：它保留 knowledgeSources 並刪除答案產生設定。在建立新物件前，請先檢視目前的定義。

使用 Knowledge Bases - Get （REST API）來取得目前的定義。

GET {{search-endpoint}}/knowledgebases/{{knowledge-base-name}}?api-version=2025-11-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

在回應中，請明確哪些要帶過去，哪些要刪除：
- 請注意這些 knowledgeSources 參考資料。將這些知識帶入新的知識庫。
- 若存在，則移除 outputMode、 answerInstructions、 retrievalInstructions。這些屬性在 2026-04-01 中不受支援。
- 如果你的知識庫使用 web 知識來源，請保留 models。網路檢索需要模型支持的摘要。對於所有其他知識來源類型，請移除 models。

使用 Knowledge Bases - Create 或 Update （REST API）來建立一個擁有唯一名稱、 2026-04-01 API 版本且僅支援屬性的新知識庫。

PUT {{search-endpoint}}/knowledgebases/{{new-knowledge-base-name}}?api-version=2026-04-01
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

{
  "name": "{{new-knowledge-base-name}}",
  "description": "Minimal knowledge base for search index retrieval.",
  "knowledgeSources": [
    { "name": "{{new-knowledge-source-name}}" }
  ]
}

更新取回請求

2026-04-01取回請求的形狀與預覽版本不同：

用 intents 代替 messages。
用 maxOutputSizeInTokens 代替 maxOutputSize。
若存在，則移除 retrievalReasoningEffort 和 alwaysQuerySource。這些參數在 2026-04-01 中不支援。
對於後續問題，請發送一個新的取回請求，並設定新的語意意圖。 2026-04-01 不會保留持續累積的訊息記錄。

要用查詢測試你的知識庫輸出，可以使用 2026-04-01Knowledge Retrieval - Retrieve （REST API）的版本。

POST {{search-endpoint}}/knowledgebases/{{new-knowledge-base-name}}/retrieve?api-version=2026-04-01
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

{
  "intents": [
    {
      "type": "semantic",
      "search": "{{query-text}}"
    }
  ],
  "knowledgeSourceParams": [
    {
      "knowledgeSourceName": "{{new-knowledge-source-name}}",
      "kind": "searchIndex",
      "includeReferences": true,
      "includeReferenceSourceData": true,
      "rerankerThreshold": 2.5
    }
  ],
  "maxRuntimeInSeconds": 30,
  "maxOutputSizeInTokens": 6000
}

如果回應有 200 OK HTTP 代碼，代表你的知識庫成功從知識來源取得內容。

從 2026-04-01 API 版本開始，代理式擷取的計費同意由專用的 knowledgeRetrieval 屬性控制，該屬性獨立於 semanticSearch；而 semanticSearch 現在僅適用於語意排序工具的計費。 knowledgeRetrieval 是管理平面屬性，因此你透過搜尋管理 REST API 來設定，而非搜尋服務 REST API。

使用 Services - Create Or Update (REST API) 的最新預覽版本，在搜尋服務上設定 knowledgeRetrieval。

PATCH https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2026-03-01-preview
Content-Type: application/json
Authorization: Bearer {{management-access-token}}

{
  "properties": {
    "knowledgeRetrieval": "standard"
  }
}

關於有效的值與計費細節，請參閱啟用或停用代理檢索計費。

更新 2026-04-01 的程式碼與用戶端

要完成您的遷移：

更新客戶端呼叫以使用 2026-04-01 API版本。
更新程式碼中任何硬編碼的知識庫或知識來源名稱，以參考遷移過程中新建立的物件。
如果你已經遷移了知識來源 azureBlob 或 indexedOneLake，請更新任何以名稱引用相關索引、索引器、資料來源或技能組的程式碼或腳本，使其指向新物件。
更新處理擷取回應的程式碼。回應回傳的是擷取的接地內容，包括 activity 和 references，而非合成的答案。
只有在新物件完全驗證並部署完成後，才刪除預覽物件。

2025-11-01-預覽

如果你是從 2025-08-01-preview 遷移過來，「knowledge agent」會被重新命名為「knowledge base」，且多個屬性會被重新定位到物件定義中的不同物件和層級。

更新搜尋索引知識來源
更新 azureBlob 知識來源
將知識代理人替換為知識庫
更新擷取請求並發送查詢來測試你的更新
更新用戶端程式碼

更新 searchIndex 知識來源

此程序會在與前一2025-08-01版本相同的功能層級建立新的2025-11-01-previewsearchIndex知識來源。底層指數本身不需要更新。

以名稱列出所有知識來源以找到你的知識來源。

### List all knowledge sources by name
GET {{search-endpoint}}/knowledge-sources?api-version=2025-08-01-preview&$select=name
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

取得目前的定義以檢視現有屬性。

### Get a specific knowledge source
GET {{search-endpoint}}/knowledge-sources/search-index-ks?api-version=2025-08-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

回應應該與以下範例相似。

{
     "name": "search-index-ks",
     "kind": "searchIndex",
     "description": "This knowledge source pulls from a search index created using the 2025-08-01-preview.",
     "encryptionKey": null,
     "searchIndexParameters": {
     "searchIndexName": "earth-at-night-idx",
     "sourceDataSelect": "id, page_chunk, page_number"
     },
     "azureBlobParameters": null
}

擬定一個建立知識來源請求作為遷移的基礎。

從 08-01-preview 的 JSON 開始。
```
POST {{search-endpoint}}/knowledge-sources/search-index-ks?api-version=2025-08-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

{
    "name": "search-index-ks",
    "kind": "searchIndex",
    "description": "A sample search index knowledge source",
    "encryptionKey": null,
    "searchIndexParameters": {
        "searchIndexName": "my-search-index",
        "sourceDataSelect": "id, page_chunk, page_number"
  }
}
```
請針對 2025-11-01-preview 遷移進行以下更新：
- 給知識來源取個新名字。
- 將 API 版本改為 2025-11-01-preview。
- 將 sourceDataSelect 重新命名為 sourceDataFields，並將字串變更為陣列，其中每個您要查詢的可擷取欄位都有名稱/值配對。這些欄位是搜尋結果中要回傳的欄位，類似於經典查詢中的 select 子句。

檢視你的更新後，再發送建立物件的請求。

PUT {{search-endpoint}}/knowledge-sources/search-index-ks-11-01?api-version=2025-11-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

{
    "name": "search-index-ks-11-01",
    "kind": "searchIndex",
    "description": "knowledge source migrated to 2025-11-01-preview",
    "encryptionKey": null,
    "searchIndexParameters": {
        "searchIndexName": "my-search-index",
        "sourceDataFields": [
            { "name": "id" }, { "name": "page_chunk" }, { "name": "page_number" }
        ]
    }
}

你現在擁有一個已遷移的 searchIndex 知識來源，與先前版本向下相容，並使用適用於 2025-11-01-preview 的正確屬性規格。

回應包含新物件的完整定義。關於此知識來源類型新增屬性的更多資訊，請參見「如何建立搜尋索引知識來源」。

更新 azureBlob 知識來源

此程序會在與前一2025-08-01版本相同的功能層級建立新的2025-11-01-previewazureBlob知識來源。它會建立一組新的生成物件：資料來源、技能集、索引器、索引。

以名稱列出所有知識來源以找到你的知識來源。

### List all knowledge sources by name
GET {{search-endpoint}}/knowledge-sources?api-version=2025-08-01-preview&$select=name
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

取得目前的定義以檢視現有屬性。

### Get a specific knowledge source
GET {{search-endpoint}}/knowledge-sources/azure-blob-ks?api-version=2025-08-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

如果你的工作流程包含模型，回應應該類似以下範例。請注意，回應中包含了產生物件的名稱。這些物件完全獨立於知識來源，即使你更新或刪除它們的知識來源，仍然能正常運作。

 {
   "name": "azure-blob-ks",
   "kind": "azureBlob",
   "description": "A sample azure blob knowledge source.",
   "encryptionKey": null,
   "searchIndexParameters": null,
   "azureBlobParameters": {
     "connectionString": "<redacted>",
     "containerName": "blobcontainer",
     "folderPath": null,
     "disableImageVerbalization": false,
     "identity": null,
     "embeddingModel": {
       "name": "embedding-model",
       "kind": "azureOpenAI",
       "azureOpenAIParameters": {
         "resourceUri": "<redacted>",
         "deploymentId": "text-embedding-3-large",
         "apiKey": "<redacted>",
         "modelName": "text-embedding-3-large",
         "authIdentity": null
       },
       "customWebApiParameters": null,
       "aiServicesVisionParameters": null,
       "amlParameters": null
     },
     "chatCompletionModel": {
       "kind": "azureOpenAI",
       "azureOpenAIParameters": {
         "resourceUri": "<redacted>",
         "deploymentId": "gpt-4o-mini",
         "apiKey": "<redacted>",
         "modelName": "gpt-4o-mini",
         "authIdentity": null
       }
 },
     "ingestionSchedule": null,
     "createdResources": {
       "datasource": "azure-blob-ks-datasource",
       "indexer": "azure-blob-ks-indexer",
       "skillset": "azure-blob-ks-skillset",
       "index": "azure-blob-ks-index"
     }
   }
 }

擬定一個建立知識來源請求作為遷移的基礎。

從 08-01-preview 的 JSON 開始。

POST {{search-endpoint}}/knowledge-sources/azure-blob-ks?api-version=2025-08-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

{
    "name": "azure-blob-ks",
    "kind": "azureBlob",
    "description": "A sample azure blob knowledge source.",
    "encryptionKey": null,
    "azureBlobParameters": {
        "connectionString": "<redacted>",
        "containerName": "blobcontainer",
        "folderPath": null,
        "disableImageVerbalization": false,
        "identity": null,
        "embeddingModel": {
            "name": "embedding-model",
            "kind": "azureOpenAI",
            "azureOpenAIParameters": {
            "resourceUri": "<redacted>",
            "deploymentId": "text-embedding-3-large",
            "apiKey": "<redacted>",
            "modelName": "text-embedding-3-large",
            "authIdentity": null
            },
            "customWebApiParameters": null,
            "aiServicesVisionParameters": null,
            "amlParameters": null
        },
        "chatCompletionModel": null,
        "ingestionSchedule": null
  }
}

請針對 2025-11-01-preview 遷移進行以下更新：

給知識來源取個新名字。
將 API 版本改為 2025-11-01-preview。
將ingestionParameters、"embeddingModel"、"chatCompletionModel"、"ingestionSchedule"等以下子屬性加入"contentExtractionMode"容器。

檢視你的更新後，再發送建立物件的請求。新產生的物件會被創建以用於索引器管線。

PUT {{search-endpoint}}/knowledge-sources/azure-blob-ks-11-01?api-version=2025-11-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

{
    "name": "azure-blob-ks",
    "kind": "azureBlob",
    "description": "A sample azure blob knowledge source",
    "encryptionKey": null,
    "azureBlobParameters": {
        "connectionString": "{{blob-connection-string}}",
        "containerName": "blobcontainer",
        "folderPath": null,
        "ingestionParameters": {
            "embeddingModel": {
                "kind": "azureOpenAI",
                "azureOpenAIParameters": {
                    "deploymentId": "text-embedding-3-large",
                    "modelName": "text-embedding-3-large",
                    "resourceUri": "{{aoai-endpoint}}",
                    "apiKey": "{{aoai-key}}"
                }
            },
            "chatCompletionModel": null,
            "disableImageVerbalization": false,
            "ingestionSchedule": null,
            "contentExtractionMode": "minimal"
        }
    }
}

你現在擁有一個已遷移的 azureBlob 知識來源，與先前版本向下相容，並使用適用於 2025-11-01-preview 的正確屬性規格。

回應包含新物件的完整定義。關於此知識來源類型新增的屬性（現在可透過更新取得）的更多資訊，請參見「建立一個 blob 知識來源」。

將知識代理人替換成知識庫

知識庫需要知識來源。在開始之前，請先確保你有以 2025-11-01-preview 為目標的知識來源。

取得目前的定義以檢視現有屬性。

### Get a knowledge agent by name
GET {{search-endpoint}}/agents/earth-at-night?api-version=2025-08-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

回應應該與以下範例相似。

{
  "name": "earth-at-night",
  "description": "A sample knowledge agent that retrieves from the earth-at-night knowledge source.",
  "retrievalInstructions": null,
  "requestLimits": null,
  "encryptionKey": null,
  "knowledgeSources": [
    {
      "name": "earth-at-night",
      "alwaysQuerySource": null,
      "includeReferences": null,
      "includeReferenceSourceData": null,
      "maxSubQueries": null,
      "rerankerThreshold": 2.5
    }
  ],
  "models": [
    {
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "<redacted>",
        "deploymentId": "gpt-5-mini",
        "apiKey": "<redacted>",
        "modelName": "gpt-5-mini",
        "authIdentity": null
      }
    }
  ],
  "outputConfiguration": {
    "modality": "answerSynthesis",
    "answerInstructions": null,
    "attemptFastPath": false,
    "includeActivity": null
  }
}

制定知識庫申請作為遷移的基礎。

從 08-01-preview 的 JSON 開始。
```
PUT {{search-endpoint}}/knowledgebases/earth-at-night?api-version=2025-08-01-preview  HTTP/1.1
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

{
    "name": "earth-at-night",
    "description": "A sample knowledge agent that retrieves from the earth-at-night knowledge source.",
    "retrievalInstructions": null,
    "encryptionKey": null,
    "knowledgeSources": [
        {
          "name": "earth-at-night",
          "alwaysQuerySource": null,
          "includeReferences": null,
          "includeReferenceSourceData": null,
          "maxSubQueries": null,
          "rerankerThreshold": 2.5
        }
    ],
    "models": [
        {
            "kind": "azureOpenAI",
            "azureOpenAIParameters": {
                "resourceUri": "<redacted>",
                "apiKey": "<redacted>",
                "deploymentId": "gpt-5-mini",
                "modelName": "gpt-5-mini"
            }
        }
    ],
    "outputConfiguration": {
        "modality": "answerSynthesis"
    }
}
```
請針對 2025-11-01-preview 遷移進行以下更新：
- 替換端點： /knowledgebases/{{knowledge-base-name}}。給知識庫取一個獨特的名稱。
- 將 API 版本改為 2025-11-01-preview。
- 刪除 requestLimits。 maxRuntimeInSeconds 和 maxOutputSize 屬性現在會直接在擷取要求中指定。
- 更新 knowledgeSources：
  - 刪除 maxSubQueries 並替換為 retrievalReasoningEffort （參見設定檢索推理努力（預覽））。
- 將alwaysQuerySource、includeReferenceSourceData、includeReferences和rerankerThreshold移至knowledgeSourceParams的擷取操作區域。
- 對於models，沒有變動。
- 更新 outputConfiguration：
  - 將替換 outputConfiguration 為 outputMode。
  - 刪除 attemptFastPath。它已經不存在了。可透過將 retrievalReasoningEffort 設為最小值來實現等價的行為（請參閱設定擷取推理強度（預覽））。
  - 如果模態設定為 answerSynthesis，請確保檢索推理努力設為低（預設）或中等。
- 新增 ingestionParameters 為建立 2025-11-01-preview azureBlob 知識來源的必要條件。

檢視你的更新後，再發送建立物件的請求。新產生的物件會被創建以用於索引器管線。

 PUT {{search-endpoint}}/knowledgebases/earth-at-night-11-01?api-version={{api-version}}
 Authorization: Bearer {{search-access-token}}
 Content-Type: application/json

 {
   "name": "earth-at-night-11-01",
   "description": "A sample knowledge base at the same functional level as the previous knowledge agent.",
   "retrievalInstructions": null,
   "encryptionKey": null,
   "knowledgeSources": [
     {
         "name": "earth-at-night-ks"
     }
   ],
   "models": [
     {
       "kind": "azureOpenAI",
       "azureOpenAIParameters": {
           "resourceUri": "<redacted>",
           "apiKey": "<redacted>",
           "deploymentId": "gpt-5-mini",
           "modelName": "gpt-5-mini"
         }
     }
   ],
   "retrievalReasoningEffort": null,
   "outputMode": "answerSynthesis",
   "answerInstructions": "Provide a concise and accurate answer based on the retrieved information."
 }

你現在擁有一個知識庫，而非知識代理，且物件與先前版本向下相容。

回應包含新物件的完整定義。關於知識庫新增屬性的更多資訊，現在可以透過更新來實現，請參閱「如何建立知識庫」。

更新並測試 2025-11-01-preview 更新的擷取

已針對 2025-11-01-preview 修改擷取要求，以支援更多格式，包括可將 LLM 處理降到最低的較簡單要求。欲了解更多關於本預覽檢索的資訊，請參閱使用知識庫檢索資料。本節說明如何更新你的程式碼。

將端點改 /agents/retrieve 為 /knowledgebases/retrieve。
將 API 版本改為 2025-11-01-preview。
如果你使用 medium 或 messages 的檢索推理強度，則無須對 low 進行任何更改。如果使用推理，請將 messages 替換為 intents（請參閱 minimal）。
修改knowledgeSourceParams以包含從代理人中移除的任何屬性：rerankerThreshold， alwaysQuerySource， includeReferenceSourceDataincludeReferences，，。
如果您使用了 retrievalReasoningEffort，將 minimum 設定新增至 attemptFastPath。如果你之前用的是 maxSubQueries，那它就已經不存在了。使用設定 retrievalReasoningEffort 來指定子查詢處理（參見設定檢索推理努力（預覽））。

若要使用查詢測試知識庫的輸出結果，可以使用 2025-11-01-preview 的。

### Send a query to the knowledge base
POST {{search-endpoint}}/knowledgebases/earth-at-night-11-01/retrieve?api-version=2025-11-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

{
    "messages": [
        {
            "role": "user",
            "content": [
                { "type": "text", "text": "What are some light sources on the ocean at night" }
            ]
        }
    ],
    "includeActivity": true,
    "retrievalReasoningEffort": { "kind": "medium" },
    "outputMode": "answerSynthesis",
    "maxRuntimeInSeconds": 30,
    "maxOutputSize": 6000
}

如果回應有 200 OK HTTP 代碼，代表你的知識庫成功從知識來源取得內容。

更新程式碼與用戶端至2025-11-01預覽版

要完成遷移，請遵循以下清理步驟：

僅針對 Blob 知識來源，請將用戶端更新為使用新的索引。如果你有執行索引器的程式碼或腳本，或引用資料來源、索引或技能組，務必更新新物件的參考。
將所有代理引用替換為 knowledgeBases 設定檔、程式碼、腳本和測試。
更新用戶端呼叫，改用 2025-11-01-preview。
清除或重新產生使用舊圖形建立的快取定義。

2025-08-01-預覽

如果你使用 2025-05-01-preview 建立知識代理，你的代理定義包含一個內嵌 targetIndexes 陣列和一個可選 defaultMaxDocsForReranker 屬性。

自 2025-08-01-preview API 版本起，可重複使用的知識來源取代 targetIndexes了，且 defaultMaxDocsForReranker 不再支援。這些突破性變更要求你：

取得目前的 targetIndexes 配置
建立一個等效的知識來源
更新代理程式，使其取代knowledgeSourcestargetIndexes
發送查詢以測試擷取
移除使用targetIndexes的程式碼並更新客戶端

取得目前的配置

要取得代理的定義，請使用 2025-05-01-previewKnowledge Agents - Get （REST API）。

@search-endpoint = <search-endpoint>
@agent-name = <agent-name>
@search-access-token = <search-access-token>

### Get agent definition
GET {{search-endpoint}}/agents/{{agent-name}}?api-version=2025-05-01-preview  HTTP/1.1
    Authorization: Bearer {{search-access-token}}

回應應該與以下範例相似。複製 indexName、 defaultRerankerThreshold和 defaultIncludeReferenceSourceData 數值，方便後續步驟使用。 defaultMaxDocsForReranker 已被棄用，所以你可以忽略它的值。

{
  "@odata.etag": "0x1234568AE7E58A1",
  "name": "my-knowledge-agent",
  "description": "My description of the agent",
  "targetIndexes": [
    {
      "indexName": "my-index",
      "defaultRerankerThreshold": 2.5,
      "defaultIncludeReferenceSourceData": true,
      "defaultMaxDocsForReranker": 100
    }
  ]
}

建立知識來源

要建立 searchIndex 知識來源，請使用 Knowledge Sources - Create (REST API) 的 2025-08-01-preview。設定 searchIndexName 為你之前複製的值。

@source-name = <source-name>

### Create a knowledge source
PUT {{search-endpoint}}/knowledgeSources/{{source-name}}?api-version=2025-08-01-preview  HTTP/1.1
    Content-Type: application/json
    Authorization: Bearer {{search-access-token}}

    {
        "name": "{{source-name}}",
        "description": "My description of the knowledge source",
        "kind": "searchIndex",
        "searchIndexParameters": {
            "searchIndexName": "my-index"
        }
    }

前一個例子會建立一個代表一個索引的知識來源，但你也可以針對多個索引或 Azure 的 blob 來設定。欲了解更多資訊，請參閱建立知識來源。

更新代理程式

若要在代理程式的定義中將 targetIndexes 替換為 knowledgeSources，請使用 Knowledge Agents - 建立或更新（REST API）的 2025-08-01-preview。將 rerankerThreshold 和 includeReferenceSourceData 設定為你之前複製的數值。

### Replace targetIndexes with knowledgeSources
POST {{search-endpoint}}/agents/{{agent-name}}?api-version=2025-08-01-preview  HTTP/1.1
    Content-Type: application/json
    Authorization: Bearer {{search-access-token}}

    {
        "name": "{{agent-name}}",
        "knowledgeSources": [
            {
                "name": "{{source-name}}",
                "rerankerThreshold": 2.5,
                "includeReferenceSourceData": true
            }
        ]
    }

前一個範例更新了定義，指向一個知識來源，但你也可以針對多個知識來源。你也可以使用其他屬性來控制檢索行為，例如 alwaysQuerySource。欲了解更多資訊，請參閱建立知識代理。

測試 2025-08-01-preview 更新的擷取

要用查詢測試代理的輸出，請使用 2025-08-01-previewKnowledge Retrieval - Retrieve（REST API）的

### Send a query to the agent
POST {{search-endpoint}}/agents/{{agent-name}}/retrieve?api-version=2025-08-01-preview  HTTP/1.1
    Content-Type: application/json
    Authorization: Bearer {{search-access-token}}

    {
      "messages": [
            {
                "role": "user",
                "content" : [
                    {
                        "text": "<query-text>",
                        "type": "text"
                    }
                ]
            }
        ]
    }

如果回應帶有 200 OK HTTP 代碼，代表你的代理成功從知識來源取得內容。

2025-08-01-preview 更新程式碼與客戶端

要完成遷移，請遵循以下清理步驟：

將所有 targetIndexes 參考資料替換為 knowledgeSources 設定檔、程式碼、腳本和測試。
更新用戶端呼叫，改用 2025-08-01-preview。
清除或重新產生使用舊圖形建立的快取代理程式定義。

版本專屬變更

本節涵蓋以下 API 版本的破壞性與非破壞性變更：

2026-08-01-預覽
2026-05-01-預覽
2026-04-01
2025-11-01-預覽
2025-08-01-預覽
2025-05-01-預覽

2026-08-01-預覽

2026-08-01-preview 版本以 2026-05-01-preview 為基礎，並包含會影響下列應用程式的重大變更：使用 Work IQ 知識來源、以位移為基礎的清單分頁、以模型為基礎的活動記錄、MCP 伺服器結果處理，或已產生用戶端的位置引數呼叫。

若要查看本版本的 REST API 參考文件，請選擇 2026-08-01-preview 頁面頂端的 API 版本篩選器。

重大變更
非破壞性變更

workIQParameters 是工作智商知識來源中所必需的，且必須包含 entraAppAuthentication。就地更新來源，或建立替代項目以進行並行移轉。在擷取要求中，於 x-ms-query-work-iq-source-authorization 標頭傳遞使用者斷言。
Work IQ 參照會移除 attributions、WorkIQAttribution 形狀和 seeMoreWebUrl。重塑後的參照會顯示 searchSensitivityLabelInfo。移除對已刪除欄位的依賴，並更新新的敏感標籤形狀的參考處理。
$top、$skip 及 $count 這些僅供預覽的參數已移除。集合列表運算使用 search、 pageSize、 searchType和。回應使用 @odata.nextLink 進行接續分頁。更新清單要求，並完全依照傳回的內容逐一存取每個 @odata.nextLink。
查詢規劃、答案綜合及網頁摘要活動記錄會移除標量 modelName。替代 model 物件包含 modelName 和 deploymentId。將巢 model 狀物件反序列化以建立模型支援的活動記錄。
McpServerTool.inclusionMode 被移除。在每個 MCP 伺服器的tools項目中，將reranked對應到resultsProcessing: "rerank"，並將resultsProcessing: "none"對應到always。若省略， resultsProcessing 則預設為 rerank; none 繞過重新排序並保留底層結果順序。
新的清單參數會改變產生的方法參數順序，但不影響 REST 參數綁定。安裝支援 2026-08-01-preview的 SDK 套件後，請檢視位置呼叫。若有，偏好指定參數或選項。

支援針對 Blob、已編製索引的 SharePoint、已編製索引的 OneLake，以及已編製索引的 Azure SQL 知識來源進行私人網路擷取。
檔案知識來源元資料、檔案更新、篩選檔案清單及 corsOptions 設定。
支援 gpt-5.6-terra、gpt-5.6-luna 和模型名稱的 gpt-5.6-sol。
關於持久擷取請求限制的知識庫 retrieveDefaults 。
擷取動作透過 Accept: text/event-stream 要求標頭支援伺服器傳送事件 (SSE) 回應。
將 retrievalReasoningEffort 設定為 auto，以使用自動擷取推理。
在搜尋索引支援的知識來源定義中儲存 queryHints，並在每個適用的 knowledgeSourceParams 項目中設定要求層級的 queryHintOverrides。
在請求時使用 neverQuerySource 排除知識來源。
使用 resultsProcessing 控制各來源的重新排名。
已編製索引的知識來源參照上由服務產生的 citationUrl 值。
elapsedMs 中的活動時間欄位（、startedAt 和 completedAt）。

2026-05-01-預覽

2026-05-01-preview 在 2025-11-01-Preview 基礎上新增知識庫、知識來源及檢索功能，且未移除先前持久化的屬性。你在早期預覽版本中建立的現有知識庫和知識來源仍能正常運作。此版本主要揭露新功能，並回退部分預覽限定限制。

若要查看本版本的 REST API 參考文件，請選擇 2026-05-01-preview 頁面頂端的 API 版本篩選器。

重大變更
非破壞性變更

在 2026-05-01-preview 和 2025-11-01-preview 之間沒有破壞性變更。當你將 API 版本改為 2026-05-01-preview時，現有的目標2025-11-01-preview請求仍會繼續運作。

隨附 2026-05-01-preview 支援的語言 SDK 引進了程式碼結構變更，因而在 SDK 層級造成重大變更。如需完整 SDK 形狀對應，請參閱更新 2026-05-01-preview 的程式碼和用戶端。

透過 freshnessPolicy 上的 ingestionParameters，對索引知識來源進行感知新鮮度擷取。
知識庫 corsOptions，用於瀏覽器來源存取 REST 擷取端點。
GPT-5 模型家族的知識庫支援（例如 gpt-5.4-mini）。
每個來源的 knowledgeSourceParams.maxOutputDocuments，用於限制每個知識來源的候選文件。
擷取要求上的最上層 maxOutputDocuments，用於限制最終基礎設置文件數目。
每個來源的 knowledgeSourceParams.failOnError，用於要求知識來源在擷取期間必須成功。
搜尋索引知識來源上的持續性擷取預設值 (例如 searchIndexParameters.baseFilter)，以及執行階段 filterAddOn 覆寫。
搜尋索引知識來源上的選用 semanticConfigurationName，用於支援的擷取流程。
擷取回應中的 Purview 敏感度標籤中繼資料：每個參考的 sensitivityLabelInfo，以及回應層級的 metadata.responseSensitivityLabelInfo。
當擷取要求上設定 modelName 時，模型支援活動記錄上的 includeActivity。
服務統計計數器 knowledgeBasesCount 與 knowledgeSourcesCount。
知識庫和知識來源清單作業，以及其他預覽版清單端點上的分頁支援 ($top、$skip、$count)。
每個知識庫的知識來源數量上限，對於 minimal、low 和 medium 檢索推理工作而言皆相同。早期的預覽版 API 保留了 low 和 medium的下限。

2026-04-01

2026-04-01 是第一個穩定的代理檢索 API 版本。它建立了一個最小化的擷取性檢索合約，並移除了預覽時代基於訊息的查詢規劃與答案綜合功能。

若要查看本版本的 REST API 參考文件，請選擇 2026-04-01 頁面頂端的 API 版本篩選器。

重大變更
非破壞性變更

以下變更影響知識庫架構與擷取請求：

retrievalReasoningEffort 被移除。先前已設定為使用 low 或 medium 推理工作量的知識庫與 2026-04-01 不相容，且必須重新建立。
outputMode 被移除。檢索預設會回傳抽取型基礎內容。答案合成不支援。

以下變更僅影響取回請求：

intents 取代 messages。
alwaysQuerySource 從 knowledgeSourceParams 中移除。
maxOutputSize 被重新命名為 maxOutputSizeInTokens。
對話狀態不會在請求間維持。不支援基於messages的多回合模式。

以下變更影響 azureBlob 與 indexedOneLake 知識來源：

ingestionPermissionOptions 從 ingestionParameters 中移除。 azureBlob 和 indexedOneLake 包含此特性的知識來源必須在移除該特性後重新建立。

註

傳送移除欄位會回傳 400 Bad Request HTTP 代碼。擷取請求不會丟棄或接受此版本中已不存在的欄位。

searchIndex、、 azureBlob、 indexedOneLake以及 web 知識來源類型通常可在 2026-04-01中取得。現有的索引內容仍然有效;遷移需要重新建立知識來源物件，而非重建索引。
索引與遠端 SharePoint 知識來源仍處於預覽階段，且無法在 2026-04-01 中使用。
知識來源 status 操作現在直接包含知識來源類型，並提供更豐富的索引錯誤細節。
若從取回請求 maxRuntimeInSeconds 中省略，預設為 90 秒，且 maxOutputSizeInTokens 預設為 5,000 個代幣。
執行階段來源控制在knowledgeSourceParams的擷取請求時仍然有效：includeReferences、includeReferenceSourceData、rerankerThreshold（適用於所有知識來源類型）、以及filterAddOn（僅適用於搜尋索引知識來源）。
除非知識庫包含models知識來源，否則該web陣列在知識庫中是可選的。當 web 有知識來源存在時， models 是網頁內容摘要所必需的，且若摘要失敗，檢索功能可返回 206 Partial Content 。
即使請求合約較窄，Retrieve 回應仍包含 activity 和 references。
在 2026-04-01 及更新版本中，新的管理平面屬性 knowledgeRetrieval 可獨立於 semanticSearch 控制代理式擷取的計費。預設值為 free。要啟用付費使用，請設定 knowledgeRetrieval 為 standard。欲了解更多資訊，請參閱啟用或停用代理檢索計費。

2025-11-01-預覽

若要查看本版本的 REST API 參考文件，請選擇 2025-11-01-preview 頁面頂端的 API 版本篩選器。

重大變更
非破壞性變更

知識代理被重新命名為知識庫。

先前路線新路線

/agents /knowledgebases

/agents/agent-name /knowledgebases/knowledge-base-name

/agents/agent-name/retrieve /knowledgebases/knowledge-base-name/retrieve
知識代理（基底） outputConfiguration 會被重新命名 outputMode 並從物件變更為字串列舉器。數個物業受到影響：
- includeActivity 會直接從 outputConfiguration 移至擷取請求上。
- 在attemptFastPath中的outputConfiguration已完全移除。新的 minimal 推理作業是替代方案。
知識代理（基地） requestLimits 被移除。 maxRuntimeInSeconds 和 maxOutputSize 的子屬性會直接移至 retrieve 要求中。
知識代理（基地） knowledgeSources 參數現在只列出知識庫所使用的知識來源名稱。其他原本位於 knowledgeSources 之下的子屬性，已移至 retrieve 要求的 knowledgeSourceParams 屬性中：
- rerankerThreshold
- alwaysQuerySource
- includeReferenceSourceData
- includeReferences
maxSubQueries 屬性不見了。其替代品是新的檢索推理努力屬性。
知識代理（基礎）取回請求：semanticReranker 活動記錄已由 agenticReasoning 活動記錄類型取代。
azureBlob 和 searchIndex 的知識來源：identity、embeddingModel、chatCompletionModel、disableImageVerbalization 和 ingestionSchedule 的頂層屬性現在成為知識來源中 ingestionParameters 物件的一部分。所有從搜尋索引擷取的知識來源都有一個 ingestionParameters 物件。
僅針對 searchIndex 知識來源： sourceDataSelect 被重新命名為 sourceDataFields ，且是一個接受 fieldName 和 fieldToSearch的陣列。

先前路線	新路線
`/agents`	`/knowledgebases`
`/agents/agent-name`	`/knowledgebases/knowledge-base-name`
`/agents/agent-name/retrieve`	`/knowledgebases/knowledge-base-name/retrieve`

新增 OneLake、SharePoint（本地）、SharePoint（遠端）作為知識來源，這些來源可直接從 SharePoint 擷取內容；Web（Bing）作為知識來源，則從 Bing 索引擷取內容。
所有從搜尋索引擷取的知識來源都有新的擷取選項：ingestionPermissionOptions 以支援來源特定的存取模型，contentExtractionMode 支援 Foundry 工具整合中的 Azure 內容理解，當 aiServices 時"contentExtractionMode": "minimal" 端點用於 Azure 內容理解。
所有從搜尋索引拉取的知識來源都有 status 一個操作，會回傳知識來源與其資料來源的同步狀態。
searchIndex知識來源新增了semanticConfigurationName，其會覆寫擷取要求所使用的預設語意設定。
searchIndex知識來源會新增sourceDataFields和searchDataFields來指定查詢時使用哪些欄位，並在回應中回傳。
知識代理（基礎）檢索回應現在會回傳 HTTP 206 狀態碼以表示部分成功。檢索請求現在會採用一個可選 retrievalReasoningEffort 性質，指定 LLM 處理的層級（參見設定檢索推理工作量（預覽））。
知識代理程式 (基礎版) 會新增一個新的 intent 物件以用於 minimal 擷取推理作業，其中 intent 會取代 messages 給 LLM。 An intent 是直接傳送給搜尋引擎的查詢字串，無需中間的 LLM 查詢規劃步驟。
檢索回應中的活動記錄現在有可選 error 輸出，指示該活動是否代表失敗操作。

2025-08-01-預覽

若要查看本版本的 REST API 參考文件，請選擇 2025-08-01-preview 頁面頂端的 API 版本篩選器。

重大變更
非破壞性變更

引入知識來源作為定義資料來源的新方式，支援 searchIndex （一個或多個索引）及 azureBlob 類型。欲了解更多資訊，請參閱建立搜尋索引知識來源及建立一個大集合知識來源。
在代理人定義中需要 knowledgeSources 而非 targetIndexes。關於遷移步驟，請參見「如何遷移」。
移除 defaultMaxDocsForReranker 支持。此性質先前存在於 targetIndexes，但在 knowledgeSources 中沒有替代品。

將knowledgeSources、outputConfiguration 和retrievalInstructions加入代理定義中。有關支援屬性的資訊，請參見建立知識代理。
將 defaultRerankerThreshold 重新命名為 rerankerThreshold，將 defaultIncludeReferenceSourceData 重新命名為 includeReferenceSourceData。這些屬性先前存在於targetIndexes，但現在你必須在每個knowledgeSources的知識來源中指定它們。

2025-05-01-預覽

此 API 版本引入了代理檢索與知識代理。每個代理人定義都需要一個 targetIndexes 陣列，指定單一索引及可選屬性，如 defaultRerankerThresholddefaultIncludeReferenceSourceData和。

若要查看本版本的 REST API 參考文件，請選擇 2025-05-01-preview 頁面頂端的 API 版本篩選器。

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-09-17

將代理檢索代碼遷移至最新版本

何時遷移

移轉之前

如何遷移

2026-08-01-預覽

移轉 Work IQ 知識來源

更新清單分頁

更新擷取回應處理

更新適用於 2026-08-01-preview 的程式碼和用戶端

2026-05-01-預覽

更新適用於 2026-05-01-preview 的程式碼與用戶端

2026-04-01

遷移知識來源

進行知識庫遷移

更新取回請求

更新付款同意

更新 2026-04-01 的程式碼與用戶端

2025-11-01-預覽

更新 searchIndex 知識來源

更新 azureBlob 知識來源

將知識代理人替換成知識庫

更新並測試 2025-11-01-preview 更新的擷取

更新程式碼與用戶端至2025-11-01預覽版

2025-08-01-預覽

取得目前的配置

建立知識來源

更新代理程式

測試 2025-08-01-preview 更新的擷取

2025-08-01-preview 更新程式碼與客戶端

版本專屬變更

2026-08-01-預覽

2026-05-01-預覽

2026-04-01

2025-11-01-預覽

2025-08-01-預覽

2025-05-01-預覽

相關內容

意見反應

其他資源