AM2 Dokumentacja użytkownika

AM2 Dokumentacja użytkownika
Spis treści
• 1 Zarządzanie bazą wiedzy
• 1.1 Edycja w panelu
• 1.2 Wgranie bazy w pliku
• 1.3 Modyfikacje poprzez API
• 1.4 Struktura bazy wiedzy
• 1.5 Format kolumnowy
• 1.5.1 klasy
• 1.5.2 atrybuty
• 1.5.3 Uwagi do importu
• 1.6 Format Json
• 1.6.1 Składowe
• 1.6.2 Klasy i atrybuty
• 1.6.3 Uwagi
• 2 API
• 2.1 Zarządzanie pakietami wiedzy
Zarządzanie bazą wiedzy
System posiada wewnętrzną reprezentację bazy wiedzy, niedostępną do bezpośredniej edycji przez
użytkowników. Bazę wiedzy można modyfikować na trzy sposoby:
• edycja w panelu
• wgranie bazy z pliku
• modyfikacje poprzez API
Modyfikacje można przeprowadzać w trakcie prowadzonych rozmów przez użytkowników.
Edycja w panelu
Dostępne funkcje:
• podgląd informacji o pakietach bazy wiedzy
• dodawanie pakietów
• usuwanie pakietów
Wgranie bazy w pliku
• dostępne formaty to CSV i Json (w wariancie kompatybilnym z CSV i dedykowanym)
• przykładowe pliku do bezpośredniego uploadu można pobrać z
http://static.onlinetools.pl/am2/
• wszystkie pliki powinny mieć kodowanie UTF-8
Modyfikacje poprzez API
Opisane w sekcji poświęconej API
Struktura bazy wiedzy
• Wewnętrzna reprezentacja tworzy graf wiedzy, gdzie dany element może być połączony z
wieloma innymi poprzez określone atrybuty.
• Każdy element bazy wiedzy musi mieć swój identyfikator
• Dla każdego elementu istnieje zbiór właściwości, które może on posiadać np. dla
odpowiedzi może to być tekst odpowiedzi, określony plik video do odtworzenia itp.
• Baza wiedzy zawiera określone klasy i ich atrybuty
Format kolumnowy
• umożliwia zapis bazy w formacie gdzie każdy wiersz opisuje konkretną jednostkę
informacji, a jej atrybuty znajdują się w kolumnach
• kolumny zawierają wszystkie możliwe atrybuty lub tylko część
• elementy w zależności od typu wymagają innych atrybutów
• zastosowania: import danych z arkuszy, plików csv/tsv, prostych transformacji z baz danych
• aktualna implementacja przyjmuje na wejściu pliki csv oraz json imitujący strukturę csv
• ze względu na ograniczone możliwości ekspresji formatu tabelarycznego, format
kolumnowy stanowi dodatkową warstwę abstrakcji, poniżej której każdy wiersz jest
rozbijany jeden lub wiele elementów grafu wiedzy
• UWAGA: walidacja tego formatu jest na podstawowym poziomie
• status prac: specyfikacja nie wdrożona w pełni, nazwy atrybutów, ich liczba i znaczenie
mogą jeszcze ulec zmianie
klasy
Klasa określa charakterystykę danego elementu oraz jego atrybuty.
• fakt - element agregujący warunki (np. dopasowanie do tekstu) oraz akcje (np. treść
odpowiedzi)
• możliwe atrybuty:
• typowe atrybuty: text_action,
• Uwagi:
• dla uproszczenia zapisu fakt może być rozpatrywany również jako kontener
warunków, dlatego można bezpośrednio na nim definiować warunki
atrybuty
• id - wymagany, identyfikator zasobu
• text_condition - słowo lub zdanie które pojawiając się na wejściu od użytkownika powinno
aktywować dany fakt
• text_action - odpowiedź udzielana po wybraniu faktu,
• property_condition - warunek operujący na zmiennych, wartością jest wyrażenie logiczne
np. "zmienna1==3", "zmienna2==abc", "zmienna1>2 && zmienna2<= 7"
• tag_condition - nazwa taga, który powinien być aktywny (fakt go aktywujący powinien być
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
wywołany wcześniej)
follows_after_condition - identyfikator faktu, który powinien być faktem poprzedzającym
żeby aktywować dany fakt np. fakt posiadający warunek tekstowy "tak", odnoszący się do
określonego pytania powinien wskazywać na tym atrybutem na fakt z pytaniem
regex_condition - wyrażenia regularne dla którego jest testowane zapytanie użytkownika
like_condition - uproszczony regex_condition, sprawdza czy wprowadzony tekst pasuje do
szablonu zgodnego z SQL Like tj. gdzie '%' to dowolny ciąg znaków a '_' to dowolny znak
complex_condition - identyfikator warunku złożonego (mającego wiele warunków)
condition_type - typ warunku, używany jeśli identyfikator definiuje warunek złożony,
dopuszczalne wartości to 'and' (wszystkie warunki muszą być spełnione), 'or' (co najmniej
jeden musi być spełniony), 'not' (negacja podwarunku, który także może być warunkiem
złożonym)
speech_text_action - mówiona treść odpowiedzi, może być inna niż pisana, domyślnie
mówiona jest ta sama treść co pisana
tag_action - przypisanie tagu, który zostaje aktywowany po wybraniu danego faktu
label_action - etykieta faktu, używana do linkowania,
video_action - nazwa pliku video który ma się odtworzyć wraz z wypowiedzią,
open_url_action - adres strony jaka ma się otworzyć wraz z wypowiedzią,
set_property_action - ustawienie zmiennej,
unset_property_action - usunięcie zmiennej,
property_name - nazwa zmiennej,
property_value - wartość zmiennej,
property_expression - wyrażenie służące do ustawienia zmiennej
Uwagi do importu
• proste (co nie znaczy małe) bazy można konstruować wyłącznie przy użyciu trzech, czterech
atrybutów: [id, text_condition, text_action], oraz dla kilku pytań aktywujących jeden fakt,
przez definiowanie 'condition_type':'or'
• Nie deklaruje się klasy elementu, gdyż dany element może mieć wiele typów i wynikają one
ze zbioru atrybutów jakie są przypisywane do elementu.
• Import Json operuje na uproszczonym wariancie, gdzie dany element nie może w jednym
miejscu deklarować kilku wartości danego atrybutu (np. 'text_condition'), musi to robić
osobnych elementach (tak jak w pliku csv)
• jeśli fakt ma skojarzonych kilka warunków (np. dwa 'text_condition') to domyślnie każdy z
nich musi być spełniony (domyślny 'condition_type' faktu to 'and'). W przypadku kilku
'text_condition' zamiarem z reguły jest dopasowanie do jednego z nich, można to zrobić
deklarując dla faktu 'condition_type':'or'
• nieznane atrybuty są ignorowane
• dozwolone jest dodanie wielu elementów (json) lub wierszy (csv) z tym samym
identyfikatorem - ostatecznie dany element jest składany i pozwala to na dodanie np. kilku
warunków do jednego faktu
Format Json
• zawiera dane tworzące drzewo lub graf
• jest dużo bardziej bliski rzeczywistej reprezentacji wiedzy w systemie
• każdy element definiuje kompletną jednostkę informacji, która sama w sobie może zawierać
referencje do innych lub podjednostki
• elementy muszą deklarować swoje typy, typów może być wiele, w przypadku braku
deklaracji przyjmowany jest typ 'Fact', który jest agregatorem warunków i odpowiedzi
• zastosowania: import danych ze złożonych systemów, dający pełną kontrolę nad strukturą
wiedzy
• UWAGA: walidacja tego formatu jest na podstawowym poziomie
• status prac: specyfikacja nie wdrożona w pełni, nazwy atrybutów, ich liczba i znaczenie
mogą jeszcze ulec zmianie
Składowe
• klasy - deklarowane dla elementów, są one wartościami atrybutu 'type', nazwa klasy zaczyna
się z wielkiej litery i jest na ogół rzeczownikiem np. 'Answer'
• atrybuty obiektowe - wartością jest referencja do zdefiniowanego wcześniej elementu lub
pełna definicja elementu jako mapy atrybutów, nazwa atrybutu zaczyna się z małej litery i
jeśli ma kilka członów to kolejne zaczynają się z wielkiej litery i są połączone tak że
stanowią jeden wyraz np. 'hasAnswer'
• atrybuty wartościowe - wartościami są atomowe cząstki informacji tj. wartości w formie
tekstowej, nazwa jest pisana z małej litery, jest na ogół rzeczownikiem, jeśli jest
wieloczłonowa to człony są połączone znakiem podkreślenia np. 'like_pattern'
Klasy i atrybuty
Dany element jest instancją klasy jeśli pojawi się ona na liście jego atrybutu 'type'.
Każda instancja klasy może zawierać atrybuty:
• id - identyfikator, jest niezbędny jeśli do danej instancji będą odwoływać się inne instancje
• type - Brak jest równoważny "type" : "Fact", jeśli element ma deklarować kilka klas to
wartość ma postać tablicy np. "type" : ["Answer", "TextMatches"]. Dla większej
przejrzystości zaleca się nadawanie elementom jednego typu (klasy).
• comment - ignorowany w bazie wiedzy, służy do komentowania informacji, w celu np.
łatwiejszego zrozumienia zastosowanej konstrukcji
Pozostałe wymagane i opcjonalne atrybuty klas. Wartości w nawiasie kwadratowym oznaczają
dopuszczalną liczbę atrybutów: [1] - dokładnie 1, [0-1] - brak lub jeden, [0+] - zero lub wiele, [1+] jeden lub wiele. Dla atrybutów obiektowych w nawiasach wąsiastych występują nazwy klas, gdzie
wskazana instancja musi mieć jedną z nich (instancja jest podana bezpośrednio jako mapa lub jako
referencja do identyfikatora).
• Fact
• [1+] hasCondition {TextMatches, Like, Regex, FollowsAfter, BoolCondition,
RequiresTag, And, Or, Not}
• [0+] hasAction {SetProperty, UnSetProperty, Tag, UnTag, OpenUrl}
• [1+] hasAnswer {Answer} - odpowiedź jest typową akcją, ale została wyróżniona
gdyż jest stosowana na końcu, po akcjach np. ustawienia zmiennych
• Answer
• [1] text
• [0-1] speech_text
• [0+] hasVideo {Video}
• TextMatches - warunek dopasowujący tekst do zadanego w atrybucie
• [1] text_pattern
• Like - warunek dopasowujący tekst gdzie znak '%' to dowolny (również pusty) ciąg znaków,
a '_' to dowolny pojedynczy znak
• [1] like_pattern
• Regex
• [1] regex
• BoolCondition
• [1] has_expression
• FollowsAfter
• [1] followsAfter
• RequiresTag
• [1] tag_value
• Tag
• [1] tag_value
• UnTag
• [1] tag_value
• Video
• [1] video_name
• OpenUrl
• [1] url
• SetProperty
• [1] property_name
• [1] has_expression
• UnSetProperty
• [1] property_name
Uwagi
• tagi mają aktualnie bardzo podobne zastosowanie jak zmienne, w przyszłości może się to
zmienić. Ich przeznaczeniem jest głównie partycjonowanie wiedzy. Aktualnie odradza się
ich stosowanie do czasu ustalenia ostatecznej specyfikacji.
• elementy Video mają aktualnie nieokreślone wartości, specyficzne dla danego awatara, więc
to co działa dla jednego może nie działać dla innego
• import działa addytywnie tj. jeśli jakiś id zostanie zadeklarowany kilka razy to informacje
zostaną połączone do jednego elementu. Odradza się jednak stosowanie tej cechy z powodu
utrudnionej identyfikacji ewentualnych problemów
API
• przy każdym requeście wymagane 3 parametry:
• api_key - klucz publiczny
• ts - timestamp, aktualny czas w formie liczby long
• sig - hash MD5 obliczony z połączenia łańcuchów klucza prywatnego i timestampu
• komunikaty powinny używać kodowania UTF-8
Przykład
• klucz prywatny: 'klucz_prywatny1'
• klucz publiczny: 'klucz_publiczny1'
• timestamp: 1234
Prawidłowe wywołanie ma postać:
http://avatarsmarket.com/rest/kb?
api_key=klucz_publiczny1&ts=1234&sig=a3ce5185f11403658a298836d86c279f
• komunikacja poprzez API możliwa jest w formacie json (preferowany) lub xml, w związku z
tym należy ustawiać prawidłowy nagłówek Content Type p. application/json
Zarządzanie pakietami wiedzy
• przykładowy plik z treścią komunikatu json można pobrać z
http://static.onlinetools.pl/am2/test1_rest.json
Adres url do aktualizacji ma posać:
http://avatarsmarket.com/rest/kb/update
Dopuszczalne metody to POST i PUT a przekazywany obiekt Json powinien mieć:
• pole packageId - wartością jest identyfikator pakietu który ma zostać podmieniony
• pole format - opcjonalny, dopuszczalne wartości to: 'json_csv' (format kolumnowy w zapisie
json) i 'json_map' (format json), w przypadku braku przyjmowany jest 'json_csv'
• pole content - zawierające dane json w formie ciągu znaków tzn. cały ciąg powinien mieć
wyescapowane znaki specjalne, w szczególności cudzysłowy, znaki nowej linii, tabulatory
itp., tak że wartością pola jest ciąg znaków.
Rezultatem jest tekst:
• w przypadku pozytywnej aktualizacji - liczba zaimportowanych faktów
• w przypadku wystąpienia błędu - komunikat z błędem
Przykładowe wywołanie:
http://avatarsmarket.com/rest/kb/update?
api_key=klucz_publiczny1&ts=1234&sig=a3ce5185f11403658a298836d86c279f
Dane w post
Przykładowy content
{
"packageId" : "kb_1419005301087",
"content" : "{ \"items\" :
[
{
xt_condition\" : \"rower\",
\"id\" : \"test1a\",
\"te
\"text_action\" : \"lubię jeździć
rowerem\"
{
\" : \"samochód\",
}
]
}"
}
},
\"id\" : \"test1b\",
\"text_condition
\"text_action\" : \"ma cztery koła\"
Identyczny rezultat można osiągnąć wysyłając w panelu edycji plik json o następującej treści
(wybór bazy wiedzy poprzedza aktualizację więc nie trzeba przekazywać identyfikatora):
{
"items" : [
{
"id" : "test1a",
"text_condition" : "rower",
"text_action" : "lubię jeździć rowerem"
},
{
}
}
]
"id" : "test1b",
"text_condition" : "samochód",
"text_action" : "ma cztery koła"