Delen via

Agentische ophaalcode migreren naar de nieuwste versie

Opmerking

Deze functie is momenteel beschikbaar als openbare preview-versie. Deze preview wordt geleverd zonder service level agreement en wordt niet aanbevolen voor productieworkloads. Bepaalde functies worden mogelijk niet ondersteund of hebben mogelijk beperkte mogelijkheden. Voor meer informatie, zie Aanvullende Gebruiksvoorwaarden voor Microsoft Azure Previews.

Als u agentische ophaalcode hebt geschreven met behulp van een vroege preview-REST API, wordt in dit artikel uitgelegd wanneer en hoe u migreert naar de nieuwste versie. Ook worden belangrijke en niet-brekende wijzigingen beschreven voor alle REST API-versies die ondersteuning bieden voor agentisch ophalen.

Wanneer moet worden gemigreerd

Migreer uw agentische ophaalcode wanneer een van de volgende aanvragen van toepassing is:

  • De REST API-versie die u gebruikt, wordt aangekondigd voor buitengebruikstelling of voert een afschaffingsvenster in.

  • Een nieuwere REST API-versie introduceert belangrijke wijzigingen die van invloed zijn op functies die u gebruikt. U moet bijvoorbeeld belangrijke wijzigingen aanpakken als uw code is gericht op de preview van 2025-05-01, die wordt gebruikt targetIndexes in agentdefinities.

  • U wilt functies die alleen beschikbaar zijn in een nieuwere REST API-versie.

  • Uw code mislukt wanneer niet-herkende eigenschappen worden geretourneerd in een REST API-antwoord. Als best practice moet uw toepassing eigenschappen negeren die niet worden begrepen.

Hoe te migreren

Als u een kennisagent hebt gemaakt met de preview van 2025-05-01, bevat de definitie van uw agent een inlinematrix targetIndexes en een optionele defaultMaxDocsForReranker eigenschap.

Vanaf de preview van 2025-08-01 worden herbruikbare kennisbronnen vervangen targetIndexesen defaultMaxDocsForReranker wordt deze niet meer ondersteund. Voor deze belangrijke wijzigingen moet u het volgende doen:

  1. Haal de huidige targetIndexes configuratie op.
  2. Maak een equivalente kennisbron.
  3. Werk de agent bij zodat deze wordt gebruikt knowledgeSources in plaats van targetIndexes.
  4. Verzend een query om het ophalen te testen.
  5. Verwijder code die clients gebruikt targetIndexes en bijwerkt.

De huidige configuratie ophalen

Gebruik de 2025-05-01-preview van Knowledge Agents - Get (REST API) om de definitie van uw agent op te halen.

@search-url = <YourSearchServiceUrl>
@agent-name = <YourAgentName>
@api-key = <YourApiKey>

### Get agent definition
GET https://{{search-url}}/agents/{{agent-name}}?api-version=2025-05-01-preview  HTTP/1.1
    api-key: {{api-key}}

Het antwoord moet er ongeveer uitzien als in het volgende voorbeeld. Kopieer de indexName, defaultRerankerThresholden defaultIncludeReferenceSourceData waarden voor gebruik in de komende stappen. defaultMaxDocsForReranker is afgeschaft, zodat u de waarde ervan kunt negeren.

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

Een kennisbron maken

Als u een searchIndex kennisbron wilt maken, gebruikt u de 2025-08-01-preview van Kennisbronnen - Maken (REST API). Stel searchIndexName deze waarde in op de waarde die u eerder hebt gekopieerd.

@source-name = <YourSourceName>

### Create a knowledge source
PUT https://{{search-url}}/knowledgeSources/{{source-name}}?api-version=2025-08-01-preview  HTTP/1.1
    Content-Type: application/json
    api-key: {{api-key}}
    
    {
        "name": "{{source-name}}",
        "description": "My description of the knowledge source",
        "kind": "searchIndex",
        "searchIndexParameters": {
            "searchIndexName": "my-index" // Use the previous value
        }
    }

In dit voorbeeld wordt een kennisbron gemaakt die één index vertegenwoordigt, maar u kunt zich richten op meerdere indexen of een Azure-blob. Zie Een kennisbron maken voor meer informatie.

De agent bijwerken

Als u wilt vervangen door targetIndexesknowledgeSources de definitie van uw agent, gebruikt u de preview-versie 2025-08-01 van Knowledge Agents - Maken of bijwerken (REST API). Stel rerankerThreshold en includeReferenceSourceData op de waarden die u eerder hebt gekopieerd in.

### Replace targetIndexes with knowledgeSources
POST https://{{search-url}}/agents/{{agent-name}}?api-version=2025-08-01-preview  HTTP/1.1
    Content-Type: application/json
    api-key: {{api-key}}

    { 
        "name": "{{agent-name}}", 
        "knowledgeSources": [  
            {  
                "name": "{{source-name}}",
                "rerankerThreshold": 2.5, // Use the previous value
                "includeReferenceSourceData": true // Use the previous value
            }
        ]
    }

In dit voorbeeld wordt de definitie bijgewerkt om te verwijzen naar één kennisbron, maar u kunt zich richten op meerdere kennisbronnen. U kunt ook andere eigenschappen gebruiken om het ophaalgedrag te beheren, zoals alwaysQuerySource. Zie Een kennisagent maken voor meer informatie.

Het ophalen testen

Als u de uitvoer van uw agent wilt testen met een query, gebruikt u de preview van 2025-08-01 van Knowledge Retrieval - Ophalen (REST API).

### Send a query to the agent
POST https://{{search-url}}/agents/{{agent-name}}/retrieve?api-version=2025-08-01-preview  HTTP/1.1
    Content-Type: application/json
    api-key: {{api-key}}
        
    {
      "messages": [
            {
                "role": "user",
                "content" : [
                    {
                        "text": "<YourQueryText>",
                        "type": "text"
                    }
                ]
            }
        ]
    }

Als het antwoord een 200 OK HTTP-code heeft, heeft uw agent inhoud opgehaald uit de kennisbron.

Code en clients bijwerken

Voer de volgende opschoonstappen uit om uw migratie te voltooien:

  • Vervang alle targetIndexes verwijzingen door knowledgeSources in configuratiebestanden, code, scripts en tests.
  • Werk clientoproepen bij om de preview-versie van 2025-08-01 te gebruiken.
  • Wist of genereer definities van agents in de cache die zijn gemaakt met behulp van de oude shape.

Versiespecifieke wijzigingen

In deze sectie worden belangrijke en niet-brekende wijzigingen beschreven voor de volgende REST API-versies:

2025-08-01-preview

  • Introduceert kennisbronnen als de nieuwe manier om gegevensbronnen te definiëren, die zowel searchIndex (één of meerdere indexen) als azureBlob soorten ondersteunen. Zie Een kennisbron voor een zoekindex maken en een blob-kennisbron maken voor meer informatie.

  • Vereist knowledgeSources in plaats van targetIndexes in agentdefinities. Zie Migreren voor migratiestappen.

  • Hiermee verwijdert u defaultMaxDocsForReranker ondersteuning. Deze eigenschap bestond al eerder, targetIndexesmaar er is geen vervanging in knowledgeSources.

2025-05-01-preview

Deze REST API-versie introduceert agentische ophaal- en kennisagents. Elke agentdefinitie vereist een targetIndexes matrix die één index en optionele eigenschappen opgeeft, zoals defaultRerankerThreshold en defaultIncludeReferenceSourceData.

Verwante inhoud

  • Last updated on