Informazioni di riferimento sull'API REST di Ricerca intelligenza artificiale di Azure
ricerca di intelligenza artificiale di Azure (in precedenza noto come Ricerca cognitiva di Azure) è un servizio di ricerca cloud completamente gestito che fornisce informazioni per il recupero di informazioni sui contenuti di proprietà dell'utente.
Le API REST del piano dati vengono usate per l'indicizzazione e i flussi di lavoro di query e sono documentate in questa sezione.
Le operazioni del piano di controllo per l'amministrazione del servizio sono trattate in un'API REST di gestione separata.
Documentazione dell'API con controllo delle versioni
La documentazione dell'API REST è ora con controllo delle versioni. Quando si apre una pagina di riferimento api, viene visualizzato un selettore di versione sopra il sommario. Assicurarsi che il riferimento all'API provena dalla cartella
Concetti chiave
Ricerca di intelligenza artificiale di Azure include i concetti relativi ai servizi di ricerca , agli indici documenti, indicizzatori, origini dati, set di competenzee mappe sinonimiche.
- Un servizio di ricerca ospita indici, indicizzatori, origini dati, set di competenze e mappe sinonimiche come oggetti di primo livello.
- Un indice di ricerca fornisce un archivio permanente dei documenti di ricerca. I documenti di ricerca sono i dati, articolati come una raccolta di campi, caricati da origini esterne e inseriti in un indice per renderli ricercabili.
- Un indicizzatore di ricerca aggiunge automazione, lettura dei dati in formati nativi e serializzazione in JSON.
- Un indicizzatore ha un'origine dati e punta a un indice.
- Un indicizzatore potrebbe anche avere un set di competenze che aggiunge arricchimento tramite intelligenza artificiale e vettorializzazione integrata alla pipeline di indicizzazione. I set di competenze sono sempre collegati a un indicizzatore. Richiamano Machine Learning per estrarre o suddividere testo, vettorizzare contenuto, dedurre funzionalità o aggiungere struttura al contenuto per migliorare l'indicizzazione da parte di un servizio di ricerca.
Nel complesso, è possibile creare gli oggetti seguenti in un servizio di ricerca:
| Oggetti | Descrizione |
|---|---|
| Origini dati | Connessione all'origine dati utilizzata da un indicizzatore per recuperare e aggiornare i documenti per l'indicizzazione. Le origini dati hanno un type. È possibile usare le connessioni fornite da Microsoft per Azure o i connettori partner. Per l'elenco completo, vedere raccolta origini dati |
| Documenti | Concettualmente, un documento è un'entità nell'indice. Mapping di questo concetto a equivalenti di database più familiari: un indice di ricerca equivale a una tabella e i documenti sono approssimativamente equivalenti alle righe di una tabella. I documenti esistono solo in un indice e vengono recuperati solo tramite query destinate all'insieme documents (/docs) di un indice. Tutte le operazioni eseguite nella raccolta, ad esempio il caricamento, l'unione, l'eliminazione o l'esecuzione di query sui documenti, vengono eseguite nel contesto di un singolo indice, pertanto le operazioni del documento in formato URL includono sempre /indexes/[index name]/docs per un determinato nome di indice. |
| Indici | Un indice viene archiviato nel servizio di ricerca e popolato con documenti JSON indicizzati e tokenizzati per il recupero delle informazioni. L'insieme fields di un indice definisce la struttura del documento di ricerca. I campi hanno un nome, tipi di dati e attributi che determinano l'utilizzo. Ad esempio, searchable campi vengono usati nella ricerca full-text e quindi vengono tokenizzati durante l'indicizzazione. Un indice definisce anche altri costrutti, ad esempio profili di punteggio per l'ottimizzazione della pertinenza, suggerimenti, configurazioni semantiche e analizzatori personalizzati. |
| Indicizzatori | Gli indicizzatori forniscono l'automazione dell'indicizzazione. Un indicizzatore si connette a un'origine dati, legge i dati e lo passa a un motore di ricerca per l'indicizzazione in un indice di ricerca di destinazione. Gli indicizzatori leggono da un'origine esterna usando le informazioni di connessione in un'origine dati e serializzano i dati in ingresso nei documenti di ricerca JSON. Oltre a un'origine dati, un indicizzatore richiede anche un indice. L'indice specifica i campi e gli attributi dei documenti di ricerca. |
| Set di competenze | Un set di competenze aggiunge passaggi di elaborazione esterni all'esecuzione dell'indicizzatore e viene usato per applicare modelli di intelligenza artificiale o deep learning per analizzare o trasformare il contenuto per migliorare la ricerca in un indice. Il contenuto di un set di competenze è costituito da una o più competenze , che possono essere competenze predefinite create da Microsoft, competenze personalizzate o una combinazione di entrambi. Esistono competenze predefinite per l'analisi delle immagini, tra cui OCR e elaborazione del linguaggio naturale. Altri esempi di competenze predefinite includono il riconoscimento delle entità, l'estrazione di frasi chiave, la suddivisione in blocchi di testo in pagine logiche, tra le altre. Un set di competenze è un oggetto autonomo di alto livello esistente a livello equivalente a indici, indicizzatori e origini dati, ma è operativo solo all'interno dell'elaborazione dell'indicizzatore. Come oggetto di alto livello, è possibile progettare un set di competenze una sola volta e quindi farvi riferimento in più indicizzatori. |
| Mappe sinonimi | Una mappa dei sinonimi è un oggetto a livello di servizio che contiene sinonimi definiti dall'utente. Questo oggetto viene mantenuto indipendentemente dagli indici di ricerca. Dopo il caricamento, è possibile puntare qualsiasi campo ricercabile alla mappa dei sinonimi (una per campo). |
Autorizzazioni e controllo di accesso
È possibile usare l'autenticazione basata su chiave o basata su ruoli tramite Microsoft Entra ID.
'autenticazione basata su chiave si basa sulle chiavi API generate per il servizio di ricerca. La presenza di una chiave valida stabilisce un trust, per ogni richiesta, tra l'applicazione che invia la richiesta e il servizio che lo gestisce. È possibile usare una chiave API amministratore per operazioni di lettura/scrittura o una chiave API di query per l'accesso in lettura alla raccolta documenti di un indice di ricerca.
l'autenticazione di Microsoft Entra ID e il controllo degli accessi in base al ruolo richiede che sia presente un tenant stabilito in Microsoft Entra ID, con entità di sicurezza e assegnazioni di ruolo. I membri dei ruoli seguenti hanno accesso al piano dati. È possibile creare ruoli personalizzati se i ruoli predefiniti non sono sufficienti.
Ruolo Accesso Collaboratore servizio di ricerca Accesso agli oggetti, ma nessun accesso al contenuto dell'indice. Questo ruolo crea un indice di ricerca e altri oggetti di primo livello, ma non può eseguire query su un indice di ricerca o aggiungere, rimuovere o aggiornare i documenti in un indice di ricerca. Questo ruolo è destinato agli sviluppatori che creano, aggiornano ed eliminano le definizioni degli oggetti. È anche per gli amministratori che devono gestire gli oggetti, ma senza la possibilità di visualizzare o accedere ai dati degli oggetti. Collaboratore indice dati di ricerca Accesso in lettura/scrittura al contenuto dell'indice. Questo ruolo è destinato agli sviluppatori o ai proprietari di indici che devono importare, aggiornare o eseguire query sulla raccolta documenti di un indice. Lettore dell'indice dati di ricerca Accesso in lettura al contenuto dell'indice. Questo ruolo è destinato ad app e utenti che eseguono query.
Quando si usano i ruoli nella connessione, l'app client presenta un token di connessione nell'intestazione di autorizzazione. Vedi Autorizzare l'accesso a un'app di ricerca usando microsoft Entra ID per informazioni su come configurare questa funzionalità.
È possibile disabilitare l'autenticazione basata su chiave o l'autenticazione basata su ruoli. Se si disabilita l'autenticazione basata su ruoli, si applica solo alle operazioni del piano dati. Le operazioni del piano di controllo, ad esempio l'amministrazione del servizio, usano sempre l'autenticazione basata sui ruoli. Per informazioni dettagliate, vedere 'autenticazione di Microsoft Entra ID e il controllo degli accessi in base al ruolo per Ricerca di intelligenza artificiale di Azure.
Chiamata delle API
Le API documentate in questa sezione forniscono l'accesso alle operazioni sui dati di ricerca, ad esempio la creazione di indici e la popolazione, il caricamento di documenti e le query. Quando si chiamano le API, tenere presenti i punti seguenti:
Le richieste devono essere inviate tramite HTTPS (sulla porta predefinita 443).
Gli URI della richiesta devono includere il versione api. Il valore deve essere impostato su una versione supportata, formattata come illustrato in questo esempio:
GET https://[search service name].search.windows.net/indexes?api-version=2023-11-01intestazioni di richiesta devono includere un chiave APIo un token di connessione per le connessioni autenticate. Facoltativamente, è possibile impostare l'intestazione Accept HTTP. Se l'intestazione del tipo di contenuto non è impostata, si presuppone che il valore predefinito sia application/json.