Filtrare i risultati con Scopes

Scopes in Microsoft Web IQ consentono di ottimizzare le richieste API di grounding includendo o escludendo URL, siti e domini dai risultati di Ricerca Web e Ricerca notizie.

Gli sviluppatori e gli amministratori aziendali possono usare Scopes per basare le esperienze di intelligenza artificiale su origini Web approvate e desiderate. Definire elenchi di inclusione ed esclusione riutilizzabili per URL, domini e percorsi per controllare quali origini possono essere restituite dalle ricerche di grounding.

Un ambito è una configurazione denominata di regole di inclusione ed esclusione. Crealo nel portale Web IQ o nell'API Gestione clienti per un account di fatturazione, quindi selezionalo in base al nome nelle richieste di Ricerca Web o Ricerca notizie. Entrambe le opzioni di gestione funzionano con gli stessi ambiti denominati. Questi ambiti di ricerca non sono ambiti di autorizzazione OAuth di Microsoft Entra.

Scenari aziendali e casi d'uso comuni

Scenario Esempio di caso d'uso Come usare Scope
Ricerca curata Basare un assistente di ricerca su fonti esaminate dall'organizzazione, ad esempio pubblicazioni mediche approvate. Includere i domini approvati, i sottodomini o le singole pagine.
Criteri dei contenuti di origine Escludere i domini soggetti a restrizioni della tua organizzazione dai risultati di grounding della ricerca Web e della ricerca di notizie. Mantenere un elenco di esclusione e selezionare l'ambito per ogni richiesta.
Ricerca nelle proprietà possedute Limitare l'esperienza di ricerca di un assistente al supporto tecnico o destinata ai dipendenti ai siti pubblici di prodotto, assistenza o aziendali. Includi i domini di proprietà e i percorsi di documentazione pertinenti.
Monitoraggio delle notizie selezionate Basa i riepiloghi delle notizie su un insieme selezionato di editori. Includi i domini di pubblicazione e selezionare l'ambito nelle richieste di Ricerca notizie.

Gli ambiti filtrano il contenuto disponibile per l'endpoint di ricerca selezionato. Un'origine dati inclusa non garantisce che il contenuto corrispondente venga indicizzato o restituito.

Prerequisites

  • Un account di fatturazione IQ Web attivo.
  • Per creare ambiti con l'API, un'applicazione Microsoft Entra esistente, l'ID tenant e l'ID applicazione (client) e le credenziali per il flusso di credenziali client OAuth 2.0. L'identità del carico di lavoro deve essere attiva e avere CustomerApiAccess accesso all'account di fatturazione Web IQ previsto.

Important

L'accesso alle API di ricerca e all'API di gestione di IQ Web viene concesso separatamente. Una chiave API di ricerca funzionante o un'applicazione Entra associata a un profilo di runtime Web IQ non concede l'autorizzazione per creare scope. Il carico di lavoro richiede un'autorizzazione separata per la gestione dell'account di fatturazione.

Per controllare l'accesso al portale, aprire Ambiti e cercare l'account di fatturazione desiderato e il controllo Nuovo ambito. Se la pagina, l'account o il controllo di creazione non è disponibile, chiedere all'amministratore dell'account di controllare l'accesso o contattare il supporto IQ Web.

Assegna un nome all'ambito e scegli le sorgenti

Scegliere un nome di ambito con un massimo di 128 caratteri dopo aver rimosso gli spazi. I caratteri supportati sono lettere ASCII, cifre, punti (.), caratteri di sottolineatura (_) e trattini (-). Gli spazi e le barre non sono supportati. I nomi devono essere univoci, senza distinzione tra maiuscole e minuscole, all'interno della raccolta di ambiti.

Gli ambiti vengono condivisi dai Web IQ AppIDs in un account di fatturazione Web IQ, tramite la raccolta di ambiti assegnata a tale account. Non sono configurazioni separate per ogni Id app. Se gli account di fatturazione condividono una raccolta, condividono gli stessi ambiti e nomi.

  • Inclusione limita i risultati alle fonti che corrispondono ad almeno una voce nell'elenco delle inclusioni dell'ambito. Se l'elenco è vuoto, tutte le fonti non escluse sono idonee.
  • L'esclusione rimuove i risultati che corrispondono a qualsiasi voce nell'elenco escluso dell'ambito, anche se corrispondono anche a una regola di inclusione. L'esclusione ha sempre la precedenza.

È possibile includere o escludere domini, percorsi URL o singole pagine Web. Ogni voce è denominata selettore:

Selettore Example Corrispondenze
Dominio example.com Il dominio e i suoi sottodomini discendenti
Prefisso percorso docs.example.org/products Il percorso specificato e i relativi sottopercorsi su quell'host, ma non percorsi come /products-old
URL esatto https://docs.example.org/products/guide Quell'URL HTTPS esatto, non tutte le pagine sotto quel percorso

L'aggiunta di https:// fa sì che un selettore corrisponda a un URL esatto anziché a un prefisso di dominio o percorso. I caratteri jolly, ad *.example.comesempio , porte esplicite, stringhe di query e frammenti non sono supportati. La combinazione di maiuscole e minuscole del percorso viene mantenuta. I selettori con ambito denominato non hanno limiti separati alla profondità della sottodirectory, ma ogni selettore deve rientrare entro 2.048 caratteri prima di tagliare e dopo la normalizzazione.

L'API normalizza, ordina e deduplica le voci. Un selettore accettato non garantisce che il contenuto corrispondente venga indicizzato o restituito.

Creare un ambito nel portale

  1. Apri Ambiti nel portale Web IQ.
  2. Selezionare l'account di fatturazione previsto.
  3. Selezionare Nuovo ambito. In Crea nuovo ambito, immettere un nome ambito, ad esempio ProductDocs, e creare l'ambito.
  4. Nella pagina dei dettagli dell'ambito usare Aggiungi siti nella scheda Inclusi per aggiungere origini da includere. Usare lo stesso pulsante nella scheda Esclusi per aggiungere origini da escludere, ad esempio ads.example.com.
  5. Esaminare entrambi gli elenchi, selezionare Pubblica e confermare Pubblicare le modifiche?

Dopo la pubblicazione, la propagazione della ricerca richiede in genere circa 10 minuti, ma può richiedere fino a 30 minuti in alcuni casi. Verificare l'ambito prima di basarsi su di esso nell'applicazione.

Selezionare l'ambito nelle richieste di ricerca

Configurare l'autenticazione di ricerca in fase di esecuzione separatamente. Il profilo dell'app Web IQ scelto deve appartenere all'account di fatturazione Web IQ la cui raccolta contiene il tuo scope.

Impostare i campi facoltativi seguenti nel corpo della richiesta JSON per POST https://api.microsoft.ai/v3/search/web o POST https://api.microsoft.ai/v3/search/news. Entrambi gli endpoint usano le stesse impostazioni con ambito denominato.

Parameter Digitare Behavior
scopeName Stringa Nome di un ambito esistente, ad esempio ProductDocs. Le regole di inclusione ed esclusione filtrano i risultati della richiesta. Se omesso o null, non viene richiesto alcun ambito denominato.
failOnMissingScope boolean Il valore predefinito è true, incluso se omesso o null. Quando true, un errore segnalato di applicazione dell'ambito restituisce un errore anziché risultati senza ambito. Quando false, la ricerca può continuare senza lo scope, se non può essere applicato. Usare false solo se i risultati senza ambito sono accettabili. Non ha alcun effetto senza scopeName.

Usare una chiave API di runtime configurata separatamente negli esempi seguenti.

Filtrare i risultati della ricerca Web

Per cercare le pagine Web consentite da ProductDocs, inviare:

POST /v3/search/web HTTP/1.1
Host: api.microsoft.ai
x-apikey: <runtime-api-key>
Content-Type: application/json

{
  "query": "product setup guide",
  "scopeName": "ProductDocs",
  "failOnMissingScope": true,
  "maxResults": 10,
  "contentFormat": "passage",
  "maxLength": 3000
}

Filtrare i risultati di Ricerca notizie

Per cercare articoli di notizie consentiti dallo stesso ambito, usare l'endpoint News Search. Scegliere origini incluse con contenuto di notizie indicizzate; una pagina Web inclusa non è necessariamente disponibile tramite Ricerca notizie.

POST /v3/search/news HTTP/1.1
Host: api.microsoft.ai
x-apikey: <runtime-api-key>
Content-Type: application/json

{
  "query": "product announcements",
  "scopeName": "ProductDocs",
  "failOnMissingScope": true,
  "maxResults": 10,
  "contentFormat": "passage",
  "maxLength": 3000
}

Interpretare i risultati

Ricerca Web restituisce i risultati in webResults; Ricerca notizie restituisce i risultati in newsResults. Un ambito valido può restituire risultati corrispondenti, ad esempio quando nessun contenuto indicizzato corrisponde sia alla query che alle regole dell'ambito.

Con failOnMissingScope: true (impostazione predefinita), un errore segnalato durante l'applicazione dell'ambito genera un errore anziché risultati senza ambito. Un ambito mancante confermato restituisce HTTP 400 (HandlerInvalidInput); altri errori dell'applicazione di ambito restituiscono HTTP 500 (ScopeFailedToApply). Per indicazioni sul ripristino, vedere errori relativi all'ambito denominato.

Se si imposta su failOnMissingScopefalse e non è possibile trovare l'ambito, la ricerca viene eseguita sull'intero indice senza l'ambito e la risposta contiene "scopeApplied": false. Ciò può verificarsi quando il nome non è corretto o l'ambito non è ancora stato propagato alla partizione o alla replica che gestisce la richiesta.

Quando viene trovato e applicato l'ambito richiesto, la risposta contiene "scopeApplied": true, anche se failOnMissingScope è false. Ciò conferma l'applicazione dell'ambito per tale richiesta, non che sia stata usata la definizione più recente o che la modifica abbia raggiunto ogni partizione o replica. La risposta omette scopeApplied quando non viene segnalato alcun esito dell'operazione. Non considerare una proprietà assente come prova che l'ambito sia stato applicato.

Se si omette scopeName o lo si imposta su null, non viene richiesto alcun ambito denominato e failOnMissingScope non ha alcun effetto. Non aspettarti che scopeApplied sia sempre presente con un valore di false per le richieste senza un ambito denominato.

Usare false solo se l'applicazione può accettare risultati senza ambito e controllare scopeApplied nella risposta. Quando è necessario un ambito, non implementare un fallback che lo rimuove e ritenta una richiesta senza restrizioni. Vedere i riferimenti Web Search e News Search per i parametri della richiesta e i campi di risposta.

Creare un ambito con l'API

Tutte le richieste di gestione usano https://api.microsoft.ai con i percorsi che iniziano /v1/customer/. Sostituire <billingAccountId> e <access-token> negli esempi con l'ID account previsto e un token di accesso solo app. Le informazioni di riferimento sulle risorse autorizzate e le informazioni di riferimento sulla gestione dell'ambito descrivono i contratti degli endpoint.

Concedere all'applicazione l'accesso all'API di gestione

Un amministratore dell'account di fatturazione o del cliente concede l'accesso:

  1. Usare una registrazione dell'app Microsoft Entra esistente o registrare un'applicazione nel portale di Azure.
  2. Aprire Impostazioni account nel portale IQ Web.
  3. Selezionare l'account di fatturazione previsto.
  4. In Accesso all'API di gestione selezionare Concedi accesso a un'app Entra.
  5. Nella finestra di dialogo Concedi a un'applicazione Entra l'accesso a questo account di fatturazione confermare il nome e l'ID dell'account di fatturazione. Immettere l'ID tenant e l'ID applicazione (client) dell'applicazione e un valore non vuoto per il nome visualizzato richiesto.
  6. Selezionare Concedi l'accesso all'API di gestione a questa applicazione e quindi selezionare Concedi accesso.

La concessione dell'accesso autorizza un'identità esistente. Non crea un'applicazione Entra, un segreto, un certificato o una chiave API di ricerca. La concessione si applica all'account di fatturazione selezionato.

L'autorizzazione assegna il ruolo CustomerApiAccess. Non è un'autorizzazione limitata ai soli ambiti o di sola lettura: consente l'individuazione dell'account, le letture e le scritture degli ambiti e la gestione dei profili di runtime Entra ID. Non consente all'applicazione di concedere l'accesso ad altre applicazioni. Limitare la concessione alle applicazioni che necessitano di queste funzionalità di gestione.

Acquisire un token solo per l'app

Usare le credenziali esistenti dell'applicazione e il flusso delle credenziali client per richiedere un token di accesso Microsoft Entra:

Setting Value
Autorità https://login.microsoftonline.com/<tenant-id>
Ambito della richiesta del token https://api.microsoft.ai/.default

Usare l'ambito esatto .default , non il nome dell'ambito di ricerca che si sta creando. Inviare il token a ogni richiesta di gestione:

Authorization: Bearer <access-token>

Non usare una chiave API di ricerca per queste chiamate di gestione. Mantenere i token di accesso e le credenziali dell'applicazione fuori dal controllo del codice sorgente e dai report di diagnostica.

Individuare l'account di fatturazione

Chiamare GET https://api.microsoft.ai/v1/customer/authorized-resources con il token solo app. Selezionare il billingAccounts[].billingAccountId dell'account desiderato per la richiesta di creazione. Non scegliere automaticamente il primo account.

Usare il authorized-resources reference per lo schema di risposta, le definizioni id e l'interpretazione del campo di autorizzazione.

Inviare la richiesta di creazione

Usando l'ID account di fatturazione selezionato, inviare POST /v1/customer/billing-accounts/{billingAccountId}/scopes con il nome del tuo ambito e le regole dell'ambito. Ad esempio:

{
  "name": "ProductDocs",
  "includeSites": ["example.com", "docs.example.org/products"],
  "excludeSites": ["ads.example.com"]
}

Specificare entrambi gli array, usando [] per un elenco intenzionalmente vuoto. In 201 Created, salva la definizione restituita e l'ETag per le modifiche successive.

Per le intestazioni, le regole di convalida e i dettagli della risposta, vedere il contratto create-scope. Per modificare un ambito esistente anziché crearne uno nuovo, usare le operazioni di aggiornamento.

Verificare l'ambito prima di usarlo

  1. Leggere l'ambito salvato e verificare che le regole corrispondano alle origini desiderate.
  2. Eseguire richieste rappresentative di Ricerca Web e Ricerca notizie con failOnMissingScope: true. Controllare i casi inclusi ed esclusi prima di abilitare il traffico dipendente.

Important

La propagazione richiede in genere circa 10 minuti, ma può richiedere fino a 30 minuti in alcuni casi. Non esiste alcuno SLA di propagazione e questi tempi non sono garantiti. Una scrittura o una lettura di gestione corretta, Publish o scopeApplied: true non dimostra che la definizione più recente è attiva. Non usare il tempo trascorso da solo come verifica di disponibilità. Per informazioni dettagliate, vedere propagazione della ricerca .

Distribuire una definizione modificata

Se l'uso temporaneamente di una definizione precedente non è accettabile, creare un ambito con un nuovo nome, ad esempio ProductDocs-v2. Completare i passaggi di verifica precedenti prima di cambiare i chiamanti e mantenere l'ambito precedente fino a quando i chiamanti non dipendono più da esso.

Questo mantiene invariato il significato del vecchio nome durante la convalida; non fornisce un passaggio globale atomico.

Mantenere la protezione della concorrenza per le modifiche successive

Leggere l'ambito corrente prima di modificarlo o eliminarlo e inviare il relativo ETag tra virgolette nel campo If-Match. Seguire le indicazioni sulla concorrenza e sul risultato incerto quando si riconciliano le modifiche simultanee o si ritenta una scrittura. Se è necessaria la cronologia delle modifiche, mantenere le definizioni esaminate nella propria fonte di verità.

Risolvere i problemi di creazione

Se l'account previsto è assente dal rilevamento, chiedere all'amministratore di controllare l'identità, la concessione di gestione e l'idoneità dell'account del carico di lavoro. Per altri errori, usare il riferimento allo stato di individuazione o il riferimento all'errore di gestione dell'ambito.

Per gli errori persistenti, contattare Web IQ Support con l'ID dell'account di fatturazione, il nome dell'ambito, l'ora operativa in formato UTC, lo stato HTTP e gli ID richiesta disponibili. Includere informazioni sanificate sul comportamento previsto ed effettivo, mai token, chiavi API o credenziali dell'applicazione.

  • Ultimo aggiornamento: