Eseguire la migrazione del codice di recupero agentico alla versione più recente

Se è stato scritto codice di recupero agentico usando una versione precedente dell'API REST, questo articolo spiega quando e come eseguire la migrazione a una versione più recente. Descrive anche le modifiche di rottura e non di rottura per tutte le versioni API che supportano il recupero agentico.

Le istruzioni di migrazione consentono di eseguire una soluzione esistente in una versione più recente dell'API. Le istruzioni contenute in questo articolo consentono di risolvere le modifiche di rilievo a livello di API in modo che l'app venga eseguita come prima. Per informazioni su come aggiungere nuove funzionalità, iniziare con Novità di Azure AI Search.

Suggerimento

Uso di Azure SDK invece di REST? Leggere questo articolo per informazioni sulle modifiche di rilievo e quindi installare il pacchetto più recente per iniziare gli aggiornamenti. Prima di iniziare, controllare i log delle modifiche dell'SDK per confermare gli aggiornamenti api: Python, .NET, JavaScript, Java.

Quando eseguire la migrazione

Ogni versione che supporta il recupero agentico ha introdotto cambiamenti radicali. È possibile continuare a eseguire il codice meno recente mantenendo il valore della versione dell'API, ma per trarre vantaggio da correzioni di bug, miglioramenti e funzionalità più recenti, è necessario aggiornare il codice.

Se il codice è destinato a una versione di anteprima, è consigliabile eseguire la migrazione alla versione stabile più recente solo se il caso d'uso è completamente supportato da 2026-04-01. Se fai affidamento sulla sintesi delle risposte, su un impegno di ragionamento non minimo o su messaggi a più turni, esamina le modifiche che causano e quelle che non causano interruzioni prima di decidere di procedere con la migrazione. Queste funzionalità rimangono in anteprima.

Come eseguire la migrazione

  • Il percorso di migrazione supportato è incrementale. Se il codice è destinato alla versione 2025-05-01-preview, eseguire prima la migrazione a 2025-08-01-preview e quindi a 2025-11-01-preview e così via.

  • Per comprendere l'ambito delle modifiche, esaminare le modifiche compatibili e incompatibili per ogni versione.

  • "Migrazione" significa creare nuovi oggetti denominati in modo univoco che implementano i comportamenti della versione precedente. Non è possibile sovrascrivere un oggetto esistente se le proprietà vengono aggiunte o eliminate nell'API. Uno dei vantaggi della creazione di nuovi oggetti è la possibilità di mantenere gli oggetti esistenti mentre quelli nuovi vengono sviluppati e testati.

  • Per ogni oggetto di cui si esegue la migrazione, iniziare recuperando la definizione corrente dal servizio di ricerca in modo da poter esaminare le proprietà esistenti prima di specificarne una nuova.

  • Eliminare le versioni precedenti solo dopo che la migrazione è stata testata e distribuita completamente.

Se si esegue la migrazione dal 2025-11-01-preview, è possibile eseguire la migrazione direttamente a 2026-04-01. L'indice e il contenuto rimangono invariati; solo lo schema della Knowledge Base e la forma di richiesta di recupero richiedono aggiornamenti.

  1. Eseguire la migrazione delle fonti di conoscenza
  2. Eseguire la migrazione della Knowledge Base
  3. Aggiornare la richiesta di recupero
  4. Aggiornare il consenso alla fatturazione
  5. Aggiornare codice e client

Eseguire la migrazione delle origini delle informazioni

searchIndexI tipi di origine delle informazioni , azureBlobindexedOneLake, e web sono disponibili a livello generale in 2026-04-01. Altri tipi di origine delle informazioni rimangono in anteprima.

  1. Usare Le origini delle informazioni - Ottenere (API REST) per ottenere la definizione corrente.

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

  2. Nella risposta identificare cosa portare avanti e cosa rimuovere:

    • Per searchIndex e web, trasferire tutti i valori delle proprietà.

    • Per azureBlob e indexedOneLake, portare avanti tutti i valori delle proprietà, ma omettere ingestionPermissionOptions da ingestionParameters. Questa proprietà non sarà supportata a partire dal 1º aprile 2026.

  3. Usare Fonti di Conoscenza - Crea o Aggiorna (API REST) per creare una nuova fonte di conoscenza con un nome univoco, la versione dell'API 2026-04-01 e i valori delle proprietà dal passaggio precedente.

    Nell'esempio seguente viene illustrata un'origine searchIndex delle informazioni. Usare un modello simile per azureBlob le origini di conoscenza, indexedOneLake, e web.

    PUT {{search-endpoint}}/knowledge-sources/{{new-knowledge-source-name}}?api-version=2026-04-01
api-key: {{api-key}}
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" }
    ]
  }
}

Eseguire la migrazione della Knowledge Base

La Knowledge Base 2026-04-01 ha uno schema più semplice rispetto alla versione 2025-11-01-preview: mantiene knowledgeSources e elimina le impostazioni di generazione delle risposte. Esaminare la definizione corrente prima di creare un nuovo oggetto.

  1. Usare Knowledge Bases - Get (API REST) per ottenere la definizione corrente.

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

  2. Nella risposta identificare cosa portare avanti e cosa rimuovere:

    • Prendere nota dei knowledgeSources riferimenti. Portare questi dati nella nuova Knowledge Base.

    • Se presente, rimuovere outputMode, answerInstructionse retrievalInstructions. Queste proprietà non sono supportate nel 2026-04-01.

    • Se la knowledge base usa un'origine web delle informazioni, mantenere models. Il recupero Web richiede una sintesi supportata da modelli. Per tutti gli altri tipi di origine delle informazioni, rimuovere models.

  3. Usare knowledge base - Creare o aggiornare (API REST) per creare una nuova Knowledge Base con un nome univoco, la versione dell'API 2026-04-01 e solo le proprietà supportate.

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

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

Aggiornare la richiesta di recupero

La richiesta di recupero 2026-04-01 ha una forma diversa rispetto alla versione di anteprima:

  • Usare intents anziché messages.

  • Usare maxOutputSizeInTokens anziché maxOutputSize.

  • Se presente, rimuovere retrievalReasoningEffort e alwaysQuerySource. Questi parametri non sono supportati nel 2026-04-01.

  • Per domande di completamento, inviare una nuova richiesta di recupero con una nuova finalità semantica. 2026-04-01 non mantiene una trascrizione dei messaggi in esecuzione.

Per testare l'output della Knowledge Base con una query, usare la versione 2026-04-01 di Recupero informazioni - Recuperare (API REST).

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

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

Se la risposta ha un codice HTTP 200 OK, la base di conoscenza ha recuperato correttamente il contenuto dalla fonte di conoscenza.

A partire dal 2026-04-01, il consenso per il recupero agentico della fatturazione è controllato da una proprietà dedicata knowledgeRetrieval separata da semanticSearch, che ora si applica solo alla fatturazione del ranker semantico. knowledgeRetrieval è una proprietà del piano di gestione, quindi la si imposta tramite l'API REST di gestione della ricerca, non l'API REST del servizio di ricerca.

Usare la versione di anteprima più recente di Servizi - Creare o aggiornare (API REST) per impostare knowledgeRetrieval nel servizio di ricerca.

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

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

Per i valori validi e i dettagli di fatturazione, vedere Abilitare o disabilitare la fatturazione per il recupero agentico.

Aggiornare il codice e i client per 2026-04-01

Per completare la migrazione:

  1. Aggiornare le chiamate client per usare la versione api 2026-04-01.

  2. Aggiorna qualsiasi knowledge base codificata fissa o nomi delle fonti della knowledge base nel codice in modo da riferirsi ai nuovi oggetti creati durante la migrazione.

  3. Se sono state migrate azureBlob o indexedOneLake le origini delle conoscenze, aggiornare il codice o gli script che fanno riferimento, per nome, all'indice, all'indicizzatore, all'origine dati o allo skillset in modo che puntino ai nuovi oggetti.

  4. Aggiornare il codice che elabora le risposte di recupero. Le risposte restituiscono contenuti estrattivi con activity e references, non risposte sintetizzate.

  5. Eliminare gli oggetti di anteprima solo dopo che i nuovi oggetti vengono convalidati e distribuiti completamente.

Modifiche specifiche della versione

Questa sezione copre le modifiche che causano e non causano interruzioni per le seguenti versioni dell'API REST:

01-04-2026

2026-04-01 è la prima versione dell'API stabile per il recupero agentico. Definisce un contratto di recupero estrativo minimo e rimuove le funzionalità di pianificazione e sintesi delle risposte basate su messaggi di anteprima.

Per esaminare la documentazione di riferimento dell'API REST per questa versione, selezionare il filtro della versione dell'API 2026-04-01 nella parte superiore della pagina.

Le modifiche seguenti influiscono sia sullo schema della Knowledge Base che sulla richiesta di recupero:

  • retrievalReasoningEffort viene rimosso. Knowledge base configurate in precedenza con ragionamento low o medium non sono compatibili con il 1 aprile 2026 e devono essere ricreate.

  • outputMode viene rimosso. Il recupero restituisce contenuto estratto a terra per impostazione predefinita. La sintesi delle risposte non è supportata.

Le modifiche seguenti influiscono solo sulla richiesta di recupero:

  • intents sostituisce messages.

  • alwaysQuerySource viene rimosso da knowledgeSourceParams.

  • maxOutputSize viene rinominato in maxOutputSizeInTokens.

  • Lo stato della conversazione non viene mantenuto tra le diverse richieste. Il modello a più turni basato su messages non è supportato.

La modifica seguente influisce su azureBlob e indexedOneLake fonti di conoscenza:

  • ingestionPermissionOptions viene rimosso da ingestionParameters. azureBlob e indexedOneLake le origini di conoscenza che includono questa proprietà devono essere ricreate senza di essa.

Nota

L'invio di campi rimossi restituisce un 400 Bad Request codice HTTP. La richiesta di recupero non elimina né ignora campi non più esistenti in questa versione.

2025-11-01-preview

Per esaminare la documentazione di riferimento dell'API REST per questa versione, selezionare il filtro della versione dell'API 2025-11-01-preview nella parte superiore della pagina.

  • L'agente della conoscenza viene rinominato in base di conoscenza.

    Route precedente Nuova route
    /agents /knowledgebases
    /agents/agent-name /knowledgebases/knowledge-base-name
    /agents/agent-name/retrieve /knowledgebases/knowledge-base-name/retrieve

  • L'agente di knowledge base outputConfiguration viene rinominato in outputMode e modificato da un oggetto a un enumeratore di stringhe. Sono interessate diverse proprietà:

    • includeActivity viene trasferito da outputConfiguration direttamente sull'oggetto della richiesta di recupero.
    • attemptFastPath in outputConfiguration viene rimosso completamente. La sostituzione è rappresentata dal nuovo minimal sforzo di ragionamento.

  • L'agente knowledge base (base) requestLimits viene rimosso. Le proprietà figlio di maxRuntimeInSeconds e maxOutputSize vengono trasferite direttamente sull'oggetto richiesta di recupero dati.

  • I parametri dell'agente di conoscenza di base knowledgeSources ora elencano solo i nomi delle fonti di conoscenza utilizzate da una base di conoscenza. Altre proprietà figlio che erano sotto knowledgeSources sono state spostate alle proprietà dell'oggetto di richiesta di recupero knowledgeSourceParams.

    • rerankerThreshold
    • alwaysQuerySource
    • includeReferenceSourceData
    • includeReferences

    La maxSubQueries proprietà non è più disponibile. La sua sostituzione è la nuova proprietà di ragionamento per il recupero.

  • Oggetto richiesta di recupero per l'agente del sistema di conoscenza: il record dell'attività semanticReranker viene sostituito con il tipo di record dell'attività agenticReasoning.

  • Fonti di conoscenza per entrambe azureBlob e searchIndex: le proprietà di primo livello per identity, embeddingModel, chatCompletionModel, disableImageVerbalization e ingestionSchedule ora fanno parte di un oggetto ingestionParameters nella fonte di conoscenza. Tutte le fonti di conoscenza che estraggono da un indice di ricerca hanno un oggetto ingestionParameters.

  • Solo per searchIndex le origini delle informazioni: sourceDataSelect viene rinominato in sourceDataFields e è una matrice che accetta fieldName e fieldToSearch.

2025-08-01-preview

Per esaminare la documentazione di riferimento dell'API REST per questa versione, selezionare il filtro della versione dell'API 2025-08-01-preview nella parte superiore della pagina.

  • Introdurre le fonti di conoscenza come nuovo modo per definire le origini dati, supportare sia searchIndex (uno o più indici) che azureBlob tipi. Per ulteriori informazioni, consulta Creare una fonte di conoscenza per l'indice di ricerca e Creare una fonte di conoscenza BLOB.

  • Richiede knowledgeSources anziché nelle definizioni dell'agente targetIndexes . Per la procedura di migrazione, vedere Come eseguire la migrazione.

  • Rimuove il supporto defaultMaxDocsForReranker. Questa proprietà esisteva in precedenza in targetIndexes, ma non esiste alcuna sostituzione in knowledgeSources.

Anteprima 2025-05-01

Questa versione dell'API REST introduce il recupero agentico e gli agenti di conoscenza. Ogni definizione dell'agente richiede una targetIndexes matrice che specifica un singolo indice e proprietà facoltative, ad esempio defaultRerankerThreshold e defaultIncludeReferenceSourceData.

Per esaminare la documentazione di riferimento dell'API REST per questa versione, selezionare il filtro della versione dell'API 2025-05-01-preview nella parte superiore della pagina.

Contenuto correlato

  • Last updated on