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.