IBM Cloud Docs
Riferimento alla query di filtro

Riferimento alla query di filtro

L'API REST del servizio watsonx Assistant offre potenti funzioni di ricerca dei log tramite le query di filtro. È possibile utilizzare il parametro v2 /logs API filter per cercare nel registro delle competenze gli eventi che corrispondono a una query specificata.

Il parametro filter è una query memorizzabile nella cache che limita i risultati agli elementi che corrispondono al filtro specificato. Puoi applicare un filtro su diversi oggetti che fanno parte del modello di risposta JSON (ad esempio, il testo dell'input utente, gli intenti e le entità rilevati o il punteggio di affidabilità).

Per vedere gli esempi delle query di filtro, vedi Esempi.

Per ulteriori informazioni sul metodo /logs GET e sul suo modello di risposta, consultare il Riferimento API.

Sintassi della query di filtro

Il seguente esempio mostra il formato generale di una query di filtro:

Posizione Operatore di query Termine
request.input.text :: "IBM Watson"
  • La posizione identifica il campo su cui si desidera filtrare (in questo esempio request.input.text ).
  • L' operatore di query, che specifica il tipo di corrispondenza che si desidera utilizzare (corrispondenza sfumata o esatta).
  • Il termine specifica l'espressione o il valore che si desidera utilizzare per valutare il campo per la corrispondenza. Il termine può contenere testo e operatori letterali, come descritto nella sezione successiva.

Il filtraggio per intento o entità richiede una sintassi leggermente diversa rispetto al filtraggio su altri campi. Per ulteriori informazioni, vedi Filtro per intento o entità.

Nota: la sintassi delle query di filtro utilizza alcuni caratteri che non sono ammessi nelle query HTTP. Assicurati che tutti i caratteri speciali, inclusi spazi e virgolette, siano codificati tramite URL quando inviati come parte di una query HTTP. Ad esempio, il filtro response_timestamp<2020-01-01 può essere specificato come response_timestamp%3C2020-01-01.

Operatori

Nella query di filtro puoi utilizzare i seguenti operatori.

Operatore Descrizione
: Operatore di query di corrispondenza fuzzy. Aggiungi il prefisso : al termine di query se vuoi trovare una corrispondenza con qualsiasi valore che contenga il termine di query o una variante grammaticale del termine di query. La corrispondenza fuzzy è disponibile per i valori di testo e di entità immessi dall'utente.
:: Operatore di query di corrispondenza esatta. Aggiungi il prefisso :: se vuoi trovare una corrispondenza solo con i valori esattamente uguali al termine di query.
:! Operatore di query di corrispondenza fuzzy negativa. Il prefisso del termine di query è :! se si desidera trovare solo valori che non contengono il termine di query o una sua variante grammaticale.
::! Operatore di query di corrispondenza esatta negativa. Il prefisso del termine di query è ::! se si desidera abbinare solo i valori che non corrispondono esattamente al termine di query.
<=, >=, >, < Operatori di confronto. Aggiungi questi operatori come prefisso per il termine di query per trovare una corrispondenza in base al confronto aritmetico.
`` Operatore di escape. Da utilizzare nelle query che includono caratteri di controllo che altrimenti verrebbero analizzati come operatori. Ad esempio, !hello corrisponde al testo !hello.
"" Frase letterale. Utilizzare per racchiudere un termine di query che contiene spazi o altri caratteri speciali. Nessun carattere speciale all'interno delle virgolette viene analizzato dall'API.
~ Corrispondenza approssimativa. Aggiungi questo operatore seguito da 1 o 2 alla fine del termine di query per specificare il numero consentito di differenze a carattere singolo tra la stringa di query e una corrispondenza nell'oggetto di risposta. Ad esempio, car~1 può corrispondere a car, cat o cars, ma non può corrispondere a cats. Questo operatore non è valido quando si filtra su log_id o su qualsiasi campo di data o ora, o con la corrispondenza fuzzy.
* Operatore carattere jolly. Corrisponde a qualsiasi sequenza di zero o più caratteri. Questo operatore non è valido quando si filtra in base a log_id, language, request.context.system.assistant_id, workspace_id, request.context.metadata.deployment o qualsiasi campo di data o ora.
(), [] Operatori di raggruppamento. Si usa per racchiudere un raggruppamento logico di espressioni multiple utilizzando gli operatori booleani.
| Operatore booleano o.
, Operatore booleano e operatore.

Filtro per intento o entità

A causa delle differenze nel modo in cui gli intenti e le entità sono memorizzati internamente, la sintassi per filtrare su un intento o un'entità specifica è diversa da quella utilizzata per altri campi nel JSON restituito. Per specificare un campo intent o entity in una raccolta di intents o entities, devi utilizzare l'operatore di corrispondenza : al posto di un punto.

Ad esempio, questa query corrisponde a qualsiasi evento registrato in cui la risposta include un intento rilevato denominato hello:

response.output.intents:intent::hello

Nota l'operatore : al posto di un punto (intents:intent)

Utilizza lo stesso modello per la corrispondenza su qualsiasi campo di un intento o entità rilevato nella risposta. Ad esempio, questa query corrisponde a qualsiasi evento registrato in cui la risposta include un'entità rilevata con il valore soda:

response.output.entities:value::soda

Allo stesso modo, si possono filtrare gli intenti o le entità che vengono inviati come parte della richiesta, come in questo esempio:

request.input.intents:intent::hello

Filtro per altri campi

Per filtrare su un altro campo dei dati di log, specificare la posizione come percorso che identifica i livelli di oggetti annidati nella risposta JSON dell'API /logs. Utilizza i punti (.) per specificare i livelli successivi di nidificazione nei dati JSON. Ad esempio, la posizione request.input.text identifica il campo di testo dell'utente, come mostrato nel seguente frammento JSON:

  "request": {
    "input": {
      "text": "Good morning"
    }
  }

Il filtraggio non è disponibile per tutti i campi. Puoi applicare il filtro ai seguenti campi:

  • assistant_id
  • customer_id
  • language
  • request.context.global.system.user_id
  • request.input.text
  • request_timestamp
  • response.context.global.system.user_id
  • response.output.entities
  • response.output.intents
  • response_timestamp
  • session_id
  • skill_id
  • snapshot

L'applicazione del filtro su altri campi non è attualmente supportata.

Esempi

Gli esempi seguenti illustrano vari tipi di query utilizzando questa sintassi.

Descrizione Query
La data della risposta è nel mese di luglio 2020. response_timestamp>=2020-07-01,response_timestamp<2020-08-01
La data/ora della risposta è precedente a 2019-11-01T04:00:00.000Z. response_timestamp<2019-11-01T04:00:00.000Z
Il messaggio viene etichettato con l'ID cliente my_id. customer_id::my_id
Il messaggio è stato inviato a un assistente specifico. assistant_id::dcd5c5ad-f3a1-4345-89c5-708b0b5ff4f7
Il testo dell'input utente contiene la parola "order" o una variante grammaticale (ad esempio, orders o ordering. request.input.text:order
Un nome intento nella risposta corrisponde esattamente a place_order. response.output.intents:intent::place_order
Un nome entità nella risposta corrisponde esattamente a beverage. response.output.entities:entity::beverage
Nessun nome di intento nella risposta corrisponde esattamente a order. response.intents:intent::!order
Il testo dell'input utente non contiene la parola "order" o una variante grammaticale. request.input.text:!order
Il testo dell'input utente contiene la stringa !hello. request.input.text:!hello
Il testo dell'input utente contiene la stringa IBM Watson. request.input.text:"IBM Watson"
Il testo dell'input utente contiene una stringa che non ha più di 2 differenze a carattere singolo rispetto a Watson. request.input.text:Watson~2
Il testo inserito dall'utente contiene una stringa composta da comm, seguita da zero o più caratteri, seguita da s. request.input.text:comm*s
Un nome intento nella risposta corrisponde esattamente a hello o a goodbye. response.output.intents:intent::(hello|goodbye)
Un nome intento nella risposta corrisponde esattamente a order e un nome entità nella risposta corrisponde esattamente a beverage. [response.output.intents:intent::order,response.output.entities:entity::beverage]

Filtro dei log v1

Se l'applicazione utilizza ancora l'API v1, è possibile interrogare e filtrare i log utilizzando il metodo v1 /logs. La sintassi del filtro è la stessa, ma la struttura dei log e delle richieste di messaggi v1 è diversa. Per ulteriori informazioni, consultare Riferimento API.

Con l'API /logs v1, puoi applicare il filtro sui seguenti campi:

  • language
  • meta.message.entities_count
  • request.context.metadata.deployment
  • request.context.system.assistant_id
  • request.input.text
  • response.context.conversation_id
  • response.entities
  • response.input.text
  • response.intents
  • response.top_intent
  • workspace_id

L'applicazione del filtro su altri campi non è attualmente supportata.