Configurare una fonte di conoscenza in Agentic Retrieval in Foundry Local

Questa guida illustra come configurare le origini delle informazioni in Recupero agentico. Una fonte di conoscenza è una registrazione indipendente della connessione a un server MCP, facoltativamente vincolata a uno specifico riferimento a una fonte indicizzata. Ogni origine della knowledge base include tutti i dettagli della connessione al server MCP (URL, tipo di autenticazione).

Prerequisiti

• Distribuisci Agentic Retrieval in modalità combinata o agentica.

• Server MCP. Uno dei due: il server MCP di Agentic Retrieval integrato o uno esterno.

• Token di connessione con il ruolo EdgeRAGDeveloper per le operazioni di scrittura.

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

Tipi di origine delle informazioni

La tabella seguente descrive i due tipi di origini delle conoscenze che è possibile creare:

Passaggio 1: Creare un'origine delle conoscenze MCP remota

Per registrare un server MCP esterno direttamente come origine della knowledge base, inviare una richiesta POST con i dettagli della connessione al server:

curl -X POST https://<cluster-domain>/edgeai/knowledgesources \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "name": "my-external-mcp",
    "kind": "remote_mcp",
    "auth_type": "unauthenticated",
    "description": "External MCP server for document search",
    "remote_mcp_parameters": {
      "server_url": "https://my-mcp-server.example.com/mcp",
      "server_label": "doc-search"
    }
  }'

È possibile verificare la risposta riuscita (201 Creato):

{
  "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
  "name": "my-external-mcp",
  "kind": "remote_mcp",
  "description": "External MCP server for document search",
  "auth_type": "unauthenticated",
  "remote_mcp_parameters": {
    "server_url": "https://my-mcp-server.example.com/mcp",
    "server_label": "doc-search"
  },
  "indexed_sources_parameters": null,
  "validation_status": "active",
  "validation_error": null,
  "validated_at": "2026-03-29T12:00:00.000000+00:00",
  "created_by": null,
  "created_at": "2026-03-29T12:00:00.000000+00:00",
  "updated_at": "2026-03-29T12:00:00.000000+00:00"
}

Campi remote_mcp_parameters

La tabella seguente descrive i parametri per le connessioni MCP remote:

Passaggio 2: Creare un'origine di conoscenza MCP indicizzata

Per registrare il server MCP predefinito che punta a un'origine indicizzata specifica (raccolta), inviare una richiesta POST con i dettagli della connessione all'origine indicizzata:

curl -X POST https://<cluster-domain>/edgeai/knowledgesources \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "name": "my-docs-search",
    "kind": "indexed_sources_mcp",
    "auth_type": "microsoft_entra_id",
    "description": "Search the my-docs collection",
    "indexed_sources_parameters": {
      "server_url": "https://<cluster-domain>/edgeai/mcp",
      "indexed_source_ref": "my-docs",
      "server_label": "indexed-sources-mcp-server"
    }
  }'

Campi indexed_sources_parameters

Nella tabella seguente vengono descritti i parametri per le connessioni di origine indicizzate:

Convalida e autenticazione MCP

Quando viene creata un'origine conoscenze o i relativi parametri di connessione vengono aggiornati, il servizio convalida la connessione MCP prima di rendere persistente:

• Estrae server_url dai parametri.
• Esegue un controllo di sicurezza SSRF/DNS (blocca indirizzi IP privati/interni).
• Invia una richiesta di JSON-RPC initialize al server MCP (timeout connessione: 5s, timeout di lettura: 30s).
• Ritenta fino a tre volte con backoff esponenziale (1s, 2s).
• Se la convalida ha esito positivo: validation_status è impostata su active, il record viene salvato in modo permanente.
• Se la convalida ha esito negativo: la richiesta viene rifiutata con 400 Bad Request. Non viene salvato in modo permanente (in caso di creazione) o modificato (in caso di aggiornamento).

Tipi di autenticazione supportati

Nella tabella seguente vengono descritti i tipi di autenticazione supportati per le origini delle informazioni:

Passaggio 3: Aggiorna una fonte di conoscenza

Per modificare una fonte di conoscenza esistente, inviare una richiesta PATCH con i campi da aggiornare. Se i parametri di connessione o auth_type vengono modificati, la convalida MCP viene eseguita di nuovo. Se la riconvalida ha esito negativo, non vengono aggiornati campi.

Inviare una richiesta PATCH con i campi da aggiornare:

curl -X PATCH https://<cluster-domain>/edgeai/knowledgesources/<ks-id> \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "name": "updated-name",
    "description": "Updated description"
  }'

Passaggio 4: Eliminare le origini delle informazioni

È possibile eliminare le origini delle informazioni singolarmente o in operazioni batch.

1. Eliminare una singola origine delle informazioni.

   curl -X DELETE https://<cluster-domain>/edgeai/knowledgesources/<ks-id> \
     -H "Authorization: Bearer $TOKEN"
   

2. Eliminare in batch più origini di informazioni.

   curl -X POST https://<cluster-domain>/edgeai/knowledgesources/batch-delete \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $TOKEN" \
     -d '{
       "ks_ids": ["<ks-id-1>", "<ks-id-2>"]
     }'
   

Passaggio 5: Completa un esempio completo

Segui questo flusso completo per creare una fonte di conoscenza e collegarla alla base di conoscenza predefinita.

1. Crea una fonte di conoscenza per la tua collezione.

   KS_RESPONSE=$(curl -s -X POST https://<cluster-domain>/edgeai/knowledgesources \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $TOKEN" \
     -d '{
       "name": "my-docs-search",
       "kind": "indexed_sources_mcp",
       "auth_type": "microsoft_entra_id",
       "description": "Search the my-docs collection",
       "indexed_sources_parameters": {
         "server_url": "https://<cluster-domain>/edgeai/mcp",
         "indexed_source_ref": "my-docs",
         "server_label": "indexed-sources-mcp-server"
         }
       }
     }')
   
   KS_ID=$(echo $KS_RESPONSE | jq -r '.id')
   echo "Knowledge Source ID: $KS_ID"
   

2. Ottieni l'ID predefinito della knowledge base.

   KB_ID=$(curl -s https://<cluster-domain>/knowledge-bases?limit=1 \
     -H "Authorization: Bearer $TOKEN" | jq -r '.data[0].id')
   echo "Knowledge Base ID: $KB_ID"
   

3. Collega la fonte di conoscenza alla base di conoscenza predefinita.

   curl -X PATCH https://<cluster-domain>/knowledge-bases/$KB_ID \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $TOKEN" \
     -d "{
       \"knowledge_source_ids\": [\"$KS_ID\"]
     }"
   

La Knowledge Base è ora pronta per l'uso. Per creare thread, inviare messaggi ed eseguire esecuzioni, vedere Avvio rapido: Eseguire query sui dati.

Contenuti correlati

• Gestire la base di conoscenza in Agentic Retrieval
• Il livello agentico nell'Agentic Retrieval
• Server MCP nel recupero agentico