Migrar o código de recuperação por meio de agentes para a última versão

Observação

Esse recurso está atualmente em versão prévia pública. Essa visualização é fornecida sem um contrato de nível de serviço e não é recomendada para utilização em produção. Alguns recursos podem não ter suporte ou podem ter restrição de recursos. Para obter mais informações, consulte Termos de Uso Complementares para Versões Prévias do Microsoft Azure.

Se você escreveu um código de recuperação por meio de agentes usando uma API REST de versão prévia antecipada, este artigo explica quando e como migrar para a última versão. Ele também descreve as alterações interruptivas e não interruptivas para todas as versões da API REST que dão suporte à recuperação por meio de agentes.

Quando fazer a migração

Migre seu código de recuperação por meio de agentes quando um dos seguintes se aplicar:

A versão da API REST usada foi anunciada para desativação ou está entrando em uma janela de substituição.
Uma versão mais recente da API REST apresenta alterações interruptivas que afetam os recursos que você usa. Por exemplo, você precisa resolver as alterações interruptivas se o código for direcionado à 2025-05-01-preview, que usa targetIndexes nas definições de agente.
Você deseja obter recursos que só estão disponíveis em uma versão mais recente da API REST.
O código falha quando propriedades não reconhecidas são retornadas em uma resposta da API REST. Como melhor prática, seu aplicativo deve ignorar as propriedades que ele não reconhece.

Como migrar

Se você tiver criado um agente de conhecimento usando a 2025-05-01-preview, a definição do agente incluirá uma matriz targetIndexes embutida e uma propriedade defaultMaxDocsForReranker opcional.

A partir da 2025-08-01-preview, as fontes de conhecimento reutilizáveis substituem targetIndexes, e não há mais suporte para defaultMaxDocsForReranker. Essas alterações interruptivas exigem que você:

Obtenha a targetIndexesconfiguração atual.
Crie uma fonte de conhecimento equivalente.
Atualize o agente para usar knowledgeSources em vez de targetIndexes.
Envie uma consulta para testar a recuperação.
Remova o código que usa targetIndexes e atualize os clientes.

Obter a configuração de IP atual

Para recuperar a definição do agente, use a 2025-05-01-preview de Agentes de Conhecimento – Obter (API REST).

@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}}

A resposta deve ser semelhante ao exemplo a seguir. Copie os valores indexName, defaultRerankerThreshold e defaultIncludeReferenceSourceData para uso nas próximas etapas. defaultMaxDocsForReranker foi preterido, portanto, você pode ignorar o valor dele.

{
  "@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
}

Criar uma fonte de conhecimento

Para criar uma fonte de conhecimento searchIndex, use a 2025-08-01-preview de Fontes de Conhecimento – Criar (API REST). Defina searchIndexName como o valor copiado anteriormente.

@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
        }
    }

Este exemplo cria uma fonte de conhecimento que representa um índice, mas você pode ter como destino vários índices ou um blob do Azure. Para obter mais informações, veja Criar uma fonte de conhecimento.

Atualizar o agente

Para substituir targetIndexes por knowledgeSources na definição do agente, use a 2025-08-01-preview de Agentes de Conhecimento – Criar ou Atualizar (API REST). Defina rerankerThreshold e includeReferenceSourceData como os valores copiados anteriormente.

### 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
            }
        ]
    }

Este exemplo atualiza a definição para referenciar uma fonte de conhecimento, mas você pode ter como destino várias fontes de conhecimento. Você também pode usar outras propriedades para controlar o comportamento de recuperação, como alwaysQuerySource. Para obter mais informações, confira Criar um agente de conhecimento.

Testar a recuperação

Para testar a saída do agente com uma consulta, use a 2025-08-01-preview de Recuperação de Conhecimento – Recuperar (API REST).

### 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"
                    }
                ]
            }
        ]
    }

Se a resposta tem um código 200 OK HTTP, o agente recuperou com sucesso o conteúdo da fonte de conhecimento.

Atualizar o código e os clientes

Para concluir a migração, siga estas etapas de limpeza:

Substitua todas as referências a targetIndexes por knowledgeSources em arquivos de configuração, código, scripts e testes.
Atualize as chamadas de cliente para usar a 2025-08-01-preview.
Limpe ou regenere as definições do agente armazenadas em cache que foram criadas usando a forma antiga.

Alterações específicas da versão

Esta seção aborda alterações interruptivas e não interruptivas para as seguintes versões da API REST:

2025-08-01-preview
2025-05-01-preview

Apresenta as fontes de conhecimento como a nova maneira de definir fontes de dados, dando suporte às variantes searchIndex (um ou vários índices) e azureBlob. Para obter mais informações, veja Criar uma fonte de conhecimento de índice de pesquisa e Criar uma fonte de conhecimento de blob.
Exige knowledgeSources, em vez de targetIndexes nas definições de agente. Para obter as etapas de migração, veja Como migrar.
Remove o suporte de defaultMaxDocsForReranker. Essa propriedade existia no targetIndexes, mas não há substituição em knowledgeSources.

Adiciona knowledgeSources, outputConfiguration e retrievalInstructions às definições de agente. Para obter informações sobre as propriedades com suporte, veja Criar um agente de conhecimento.
Renomeia defaultRerankerThreshold como rerankerThreshold e defaultIncludeReferenceSourceData como includeReferenceSourceData. Essas propriedades existiam no targetIndexes, mas agora você as especifica em cada referência da fonte de conhecimento em knowledgeSources.

2025-05-01-preview

Esta versão da API REST apresenta a recuperação por meio de agentes e os agentes de conhecimento. Cada definição de agente exige uma matriz targetIndexes que especifica um só índice e propriedades opcionais, como defaultRerankerThreshold e defaultIncludeReferenceSourceData.

Comentários

Esta página foi útil?

Last updated on 2025-10-09