Gestire la base di conoscenza in Agentic Retrieval in Foundry Local

Questo articolo illustra come gestire la knowledge base in Recupero agentico. Una base di conoscenza è un oggetto di configurazione e di confine che raggruppa una o più fonti di conoscenza. Definisce i dati a cui il sistema può accedere durante l'elaborazione delle query utente.

Ogni distribuzione include una base di conoscenza predefinita che viene creata automaticamente. Le modifiche apportate alla Knowledge Base vengono sincronizzate automaticamente con l'agente interno associato.

Annotazioni

Ogni distribuzione include una knowledge base predefinita. Non è possibile creare knowledge base aggiuntive o eliminare quella predefinita. Usare GET, PATCH o PUT per visualizzare e aggiornare la Knowledge Base predefinita.

Importante

Agentic Retrieval in Foundry Local è attualmente in ANTEPRIMA. Vedi le Condizioni supplementari d'uso per le anteprime di Microsoft Azure per conoscere le condizioni legali applicabili alle funzionalità di Azure che sono in beta, in anteprima o non ancora rilasciate nella disponibilità generale.

Prerequisiti

  • Distribuire il recupero agentico in modalità combinata o agentica.

  • Creare almeno un'origine delle informazioni. Vedi Configurare un'origine di conoscenza.

  • Configurare l'autenticazione. È necessario un token di connessione con il ruolo EdgeRAGDeveloper per le operazioni di scrittura.

    az account clear
az login --tenant <your-tenant-id> --output none

TOKEN=$(az account get-access-token \
  --resource "api://<app-registration-client-id>" \
  --query accessToken -o tsv)

Passaggio 1: Ottenere la knowledge base predefinita

Per recuperare la knowledge base predefinita, inviare una richiesta GET:

curl https://<cluster-domain>/knowledge-bases?limit=1 \
  -H "Authorization: Bearer $TOKEN"

La risposta include l'ID della base di conoscenza che utilizzerai come <kb-id> nei passaggi successivi.

Le origini delle informazioni possono essere collegate alla knowledge base tramite PATCH. Per aggiungere origini, usare una richiesta PATCH per aggiornare la knowledge_source_ids matrice.

  1. Ottenere gli ID attuali della fonte delle informazioni:

    CURRENT=$(curl -s https://<cluster-domain>/knowledge-bases/<kb-id> \
  -H "Authorization: Bearer $TOKEN" | jq -r '.data.knowledge_source_ids')

  2. Inviare una richiesta PATCH con l'elenco aggiornato (includere tutti gli ID desiderati):

    curl -X PATCH https://<cluster-domain>/knowledge-bases/<kb-id> \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "knowledge_source_ids": ["<existing-ks-id>", "<new-ks-id>"]
  }'

    Importante

    PATCH sostituisce l'intero array knowledge_source_ids. Non viene aggiunto. È necessario includere tutti gli ID desiderati nella matrice. L’omissione di un ID esistente rimuove di fatto quella fonte di conoscenza dalla base di conoscenza.

Passaggio 3: Aggiornare la Knowledge Base

È possibile aggiornare una Knowledge Base usando le richieste PATCH (aggiornamento parziale) o PUT (sostituzione completa).

Operation knowledge_source_ids Comportamento Altri campi
PATCH Sostituisce l'intera matrice (non l'aggiunge). L'omissione del campo mantiene l'elenco esistente. Vengono aggiornati solo i campi specificati.
PUT Sostituisce l'intera matrice. Omettendo il campo viene reimpostato su []. Tutti i campi vengono sovrascritti. I campi omessi vengono reimpostati sulle impostazioni predefinite.

Aggiornamento parziale (PATCH)

Inviare una richiesta PATCH con solo i campi da aggiornare:

curl -X PATCH https://<cluster-domain>/knowledge-bases/<kb-id> \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "name": "Updated Product KB",
    "description": "Updated description"
  }'

Vengono aggiornati solo i campi specificati. I campi omessi rimangono invariati.

Sostituzione completa (PUT)

Inviare una richiesta PUT con tutti i campi obbligatori:

curl -X PUT https://<cluster-domain>/knowledge-bases/<kb-id> \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "name": "Replaced Product KB",
    "knowledge_source_ids": ["<new-ks-id>"]
  }'

Tutti i campi vengono sovrascritti. I campi non inclusi vengono reimpostati sulle impostazioni predefinite.

Passaggio 4: Elencare le knowledge base

Per recuperare un elenco di tutte le knowledge base, inviare una richiesta GET all'endpoint della Knowledge Base:

curl https://<cluster-domain>/knowledge-bases?limit=10&order=desc \
  -H "Authorization: Bearer $TOKEN"

La risposta include la paginazione basata su cursore con i parametri after e before per navigare set di risultati di grandi dimensioni.

Procedure consigliate

  1. Raggruppare le origini correlate: collegare tutte le origini delle informazioni correlate alla knowledge base predefinita, ad esempio manuali di prodotto e domande frequenti insieme.
  2. Iniziare con semplicità: iniziare con gli strumenti di ricerca del server MCP predefiniti, quindi aggiungere server MCP esterni in base alle esigenze.
  3. Usa i metadati: contrassegna la base di conoscenza con reparto, versione o ambiente per organizzarla.
  4. Verifica prima del PATCH: poiché PATCH sostituisce l'intero array knowledge_source_ids, leggi sempre prima lo stato corrente per evitare di rimuovere accidentalmente le origini dati.

Contenuti correlati

  • Last updated on