Wprowadzenie
W Navigatorze rozwiązania AI działają w 2 warstwach:
- Warstwa usług – metody API, które mogą być wywoływane do konkretnych zadań wdrożeniowych
- Warstwa implementacji w systemie Navigator – konkretne funkcjonalności systemu wykorzystujące usługi AI w określonych obszarach
Uczenie maszynowe zostało zaimplementowane dla systemów Windows 10 oraz Linux.
Usługi AI
Usługi AI udostępniane są w architekturze konteneryzacyjnej. Określony zestaw usług, które mogą ze sobą współpracować zamykane są w obrębie tzw. dockera – przenośnego wirtualnego kontenera, który można uruchomić na serwerze Linux. Instalacja dockera jest szybka i prosta. Usługi działają w infrastrukturze klienta i nie wymagają udostępniania danych na zewnątrz (do chmury).
OCR
Celem OCR (optical character recognition) jest wygenerowanie tekstu lub przeszukiwanego PDFA z załadowanego zdjęcia lub pliku PDF.
Metoda: ./ocr
Parametry wejściowe:
- file – plik jpg/jpeg, png, tif, pdf
- use_photo_scanner – domyślnie true. W przypadku załadowania zdjęcia dokumentu zrobionego smartfonem, system stosuje zestaw filtrów (zwiększanie kontrastu, usuwanie cieni, etc.), które zwiększają skuteczność OCR
Zwraca:
· file – plik PDFA (przeszukiwalny PDF)
Przykład:

Text classification
Celem tej grupy usług jest określenie dowolnej klasy (typu dokumentu, kategorii, właściciela, numeru konta etc.) na podstawie analizy tekstu na dokumencie.
Metoda ./v1/text_classification/list
Celem metody jest zwrócenie listy klasyfikatorów zapisanych na serwerze
Parametry wejściowe:
- brak
Zwraca:
- Lista dostępnych klasyfikatorów, zawierającą
- ranking_id – id klasyfikatora,
- ranking_name – nazwa klasyfikatora,
- is_fitted – czy jest nauczony
Przykład:

Metoda: ./v1/text_classification/create
Celem metody jest utworzenie klasyfikatora.
Parametry wejściowe:
- name – nazwa klasyfikatora
Zwraca:
- classifer_id – id utworzonego klasyfikatora
Przykład:

Metoda: ./v1/text_classification/{classifier_id}/fit
Celem metody jest wyuczenie klasyfikatora
Parametry wejściowe:
- classifier_id – id klasyfikatora
- kolekcja (kolekcja tekstów uczących)
- entry_type – nazwa klasy (np. faktura, CV, pismo etc.)
- entry_content – blok tekstowy (kompletna treść dokumentu, wszystko co zwraca OCR)
Zwraca:
- kod 200 – pozytywne wyuczenie modelu
- kod 422 – błąd (zwracany jest komunikat błędu)
Przykład:

Metoda: ./v1/text_classification/{classifier_id}/remove
Celem metody jest usunięcie klasyfikatora
Parametry wejściowe:
- classifier_id – id klasyfikatora, który chcemy usunąć z serwera
Zwraca:
- kod 200 – pozytywne usunięcie modelu
- kod 422 – błąd (zwracany jest komunikat błędu)
Przykład:

Metoda: ./v1/text_classification/{classifier_id}/predict
Celem metody jest wykonanie klasyfikacji tekstu dla danego klasyfikatora
Parametry wejściowe:
- classifier_id– id klasyfikatora, w oparciu o który ma być wykonana klasyfikacja
- text – tekst, który ma zostać sklasyfikowany
- file – plik PDFA, który ma zostać sklasyfikowany
Uwagi:
można podać albo plik (file) albo tekst.
Zwraca:
- Uszeregowane według prawdopodobieństwa kolekcja klas dla przekazanego tekstu:
- pred_proba – prawdopodobieństwo
- type_id – klasa
- rank – pozycja w rankingu
Przykład:

Data capture
Celem tej grupy usług jest przechwycenie danych z badanego dokumentu. Dla przykładu dla faktur są to : numer faktury, numery nip, daty, numer konta, stawki i kwoty VAT, tabelka z pozycjami dokumentu
Metoda ./v1/data_capture/general/list
Zwraca dostępne aktualnie modele ogólne
Parametry:
- Brak
Zwraca:
- Lista dostępnych modeli ogólnych z ich id
Przykład:

Metoda ./v1/data_capture/general/{model_id}/locale/list
Celem metody jest zwrócenie wspieranych języków i dostępnych w nich prefiksów
Metoda tylko dla modelu ogólnego faktur – nr 1
Parametry:
- model_id – id modelu, którego prefiksy zwróci metoda
Zwraca:
- Lista słowników z informacją na temat wspieranych języków oraz dostępnych w nich prefiksów
Przykład:

Metoda ./v1/data_capture/general/1/locale/upload
Umożliwia dodania własnego wspieranego języka poprzez podanie prefiksów
Metoda tylko dla modelu ogólnego faktur – nr 1
Parametry:
- locale_name – nazwa local’a (języka), którego prefiksy chcemy przekazać, musi być to jeden z:
af, ar, bg, bn, ca, cs, cy, da, de, el, en, es, et, fa, fi, fr, gu, he, hi, hr, hu, id, it, ja, kn, ko, lt, lv, mk, ml, mr, ne, nl, no, pa, pl, pt, ro, ru, sk, sl, so, sq, sv, sw, ta, te, th, tl, tr, uk, ur, vi, zh-cn, zh-tw
- prefixes_json – słownik, zawierający dla każdego z kluczy (invoice_number, nip_number, orders_and_taxes (vat_rates), invoice_date, payment_date, sale_date) listę prefiksów występujących w danym języku
Zwraca:
- Kod 200 – pozytywne nauczenie modelu
- Kod 400 – błąd
Przykład:

Metoda ./v1/data_capture/general/{model_id}/locale/{locale_name}/remove
Usunięcie wspieranego języka
Metoda tylko dla modelu ogólnego faktur – nr 1
Parametry:
- locale_name – nazwa języka do usunięcia, np. ‘en’
- model_id – id modelu, z którego usuwamy locale
Zwraca:
- Kod 200 – pomyślne usunięcie
Przykład:

Metoda ./v1/data_capture/general/{model_id}/predict
Zwrócenie informacji zawartych w tekście przesłanego pliku.
Parametry:
- model_id – id modelu, za pomocą którego wykonamy predykcję
- file – przeszukiwalny plik PDF
- locale (opcjonalnie) – nazwa języka dokumentu. Jeśli nie podany, program sam określi język na podstawie tekstu i użyje odpowiadające mu prefiksy
- response_format (opcjonalnie) – format, w którym zwrócone zostaną informacje, do wyboru: brak, xml, json
Zwraca:
- Uzyskane z tekstu informacje w formacie json lub xml
Przykład:

File splitter
Usługa pozwalająca na rozdzielanie dokumentów zeskanowanych razem do jednego pliku do osobnych plików, gdzie każdy plik odpowiada osobnemu dokumentowi. Posiada możliwość nauczenia dowolnej ilości własnych splitterów do własnego typu dokumentów
Metoda ./v1/file_splitter/list
Zwraca listę splitterów (modeli)
Parametry:
- brak
Zwraca:
- Listę dostępnych splitterów, zawierającą dla każdego: jego nazwę, id oraz informację, czy jest nauczony
Przykład:

Metoda ./v1/file_splitter/create
Tworzenie własnego splittera
Parametry:
- name – nazwa splittera
Zwraca:
- Id utworzonego splittera
Przykład:

Metoda ./v1/file_splitter/{splitter_id}/fit
Nauczenie splittera rozdzielania dokumentów
Parametry:
- splitter_id – id splittera który chcemy nauczyć
- files – lista plików, na podstawie których splitter nauczy się rozdzielać dokumenty
Zwraca:
- Kod 200 – poprawnie nauczony splitter
- Kod 400 – błąd
Przykład:

Metoda ./v1/file_splitter/{splitter_id}/remove
Usunięcie wybranego splittera
Parametry:
- splitter_id – id splittera do usunięcia
Zwraca:
- Kod 200 – pozytywne usunięcie
- Kod 400 – błąd
Przykład:

Metoda ./v1/file_splitter/{splitter_id}/split
Rozdzielenie pliku z wieloma dokumentami do pojedynczych
Parametry:
- splitter_id – id splittera, którego używamy do rozdziału pliku
- file – przeszukiwalny plik PDF, który chcemy rozdzielić
Zwraca:
- Plik zip z zapisanymi osobnymi plikami pdf
Przykład:

Aby rozpocząć pracę z usługą AI, należy wprowadzić kilka zmian, które obejmować będą bazę danych oraz Navigatora. Na początku należy wprowadzić ustawienia w bazie, a następnie można przejść do ustawień w systemie.
Ustawienia w bazie danych
Włączenie usługi AI
Aby usługi AI były aktywne, należy w bazie danych systemu, w tabeli ustawień [Sg] wpisać właściwy adres serwera AI. Sprawdzenie, jaki adres jest ustawiony obecnie, odbywa się poprzez wpisanie komendy: SELECT * FROM Sg WHERE Code = ‘Address_AI_API’ i wywołaniu jej.

W celu aktualizacji wartości, która widoczna jest w kolumnie Value, wpisujemy komendę:
UPDATE Sg SET Value = ’Wartość nowego adresu’ WHERE Code = ‘Address_AI_API’ i wywołujemy ją.
Określenie zbioru uczącego
Zbiór uczący to zestaw dokumentów, na podstawie których uczona jest usługa. Z poziomu bazy danych możemy określić ile dokumentów ma znajdować się w zbiorze uczącym. Aby sprawdzić ilość wpisujemy komendę: SELECT * FROM Sg WHERE Code = ‘MaxFilesPerType’. Domyślnie wartość ta wynosi 50.

W celu aktualizacji wartości, która widoczna jest w kolumnie Value, wpisujemy komendę:
UPDATE Sg SET Value = ‘Ilość dokumentów’ WHERE Code = ‘MaxFilesPerType’ i wywołujemy ją.
Automatyczne odświeżanie modelu
Wszystkie modele ustawione mają automatyczne odświeżenie, które uruchamiane jest codziennie, przy pierwszym zalogowaniu do systemu. Aby wyłączyć/włączyć automatyczne odświeżanie należy zmienić wartość w tabeli [Sg]. Sprawdzenie czy automatyczne odświeżanie jest włączone, odbywa się poprzez wpisanie komendy: SELECT * FROM Sg WHERE Code = ‘RecommedationAutoRefreshModel’

W kolumnie Value znajduje się wartość, która odpowiada za automatyczne odświeżanie.
- 0 – wyłączone
- 1 – włączone
W celu aktualizacji wartości, która widoczna jest w kolumnie Value, wpisujemy komendę:
UPDATE Sg SET Value = ’0 lub 1’ WHERE Code = ‘RecommedationAutoRefreshModel’ i wywołujemy ją.
Ustawienia w systemie
Rekomendacje na polach formularza
Usługa AI Text classification jest wykorzystana do rekomendowania wartości na wybranych polach formularza. Wyuczony model jest uruchamiany w procesie OCR-owania załączników. Po zakończeniu pracy OCR efekt na takim polu będzie następujący:

Tworzenie modelu
Aby utworzyć model dla konkretnego pola należy zaznaczyć opcje Pokaż rekomendacje.

W tej chwili opcja jest dostępna dla pól systemowych: kontrahent, kontrahent edycja, właściciel, firma, kategoria, typ oraz atrybutu typu autowyszukiwanie.
Po kliknięciu „Zapisz” model jest uczony (w tle). Zajmuje to ok. 20 sekund. Po tym czasie po zakończeniu procesu OCR na dokumencie powinny się pojawić rekomendacje w tym polu. Jeżeli się nie pojawią należy odczekać dłużą chwilę (ok. 10 min.). Być może proces uczenia jest dłuższy (np. wskutek większego zbioru uczącego lub obciążenia serwera).
Ważne:
- Model będzie działać jeżeli w bazie znajduje się dostateczna ilość prawidłowo wprowadzonych dokumentów. Najlepiej podać więcej niż 20 przykładów dla każdej klasy (np. 20 dokumentów z uzupełnionym właścicielem)
- Najlepiej, żeby rozkład w każdej klasie był zrównoważony (np. faktury dekretowane na różnych właścicieli)
- System Business Navigator pobiera do procesu uczenia tylko najnowsze dane. Pod uwagę brane są tylko dokumenty, które mają załączniki, które są z OCR-owane (mają dane w [OcrText] w tabeli [Fi]).
- Model zapisuje się na serwerze usług AI z nazwą KodFirmy_TypPola_IdPola (np. FRUCTON_FlSy_5, FRUCTON_FL_8660), gdzie:
- KodFirmy – CompanyCode z tabeli [Sg]
- TypPola – FlSy dla pól systemowych, Fl dla atrybutów lub Di dla słowników
- IdPola – ID z tabeli FlSy, Fl, lub Di
- Nie ma możliwości usunięcia modelu z serwera AI z poziomu systemu Business Navigator. Aby przestać z niego korzystać wystarczy odznaczyć pole Pokaż rekomendacje. Aby usunąć model z serwera AI należy użyć API.
- W celu aktualizacji modelu należy kliknąć „Resetuj model” (model jest usuwany i proces uczenia zaczyna się od nowa).
OCR BN
Pod nazwą silnika OCR „BN” znajduje się zestaw usług AI: OCR, Text Classification, Data capture. Dodatkowo system wykonuje inne procesy automatyzujące (np. ładowanie dokumentu wzorcowego, pobieranie danych kontrahenta z GUS etc.)
Silnik wybieramy dla określonego typu dokumentu.

Kroki w ramach procesu OCR wykonywanego przez silnik BN:
- OCR
- Jeśli załącznik nie zawiera tekstu (nie jest przeszukiwalnym PDF-em albo nie został wcześniej OCR-owany) wysyłany jest do API AI (/ocr)
- zwrócony przeszukiwalny PDFA jest zapisywany w bazie Navigatora w tabeli „Fi” w kolumnie „PdfFile”)
- Data capture
- Plik PDFA wysyłany jest do procesu API AI (./data_capture/general/1/predict). API zwraca plik xml oraz czysty tekst pliku.
- Czysty tekst zapisywany jest w bazie Navigatora w tabeli „Fi” w kolumnie „OcrText”
- Plik XML zapisywany jest w bazie Navigatora w tabeli „Fi” w kolumnie „OcrData”
- Text classification
- Czysty tekst wysyłany jest do procesu „Text classification” API AI (/text_classification/{classifier_id}/predict). Proces jest wykonywany dla wszystkich modeli zdefiniowanych we wszystkich formularzach obszaru Dokumenty
- Decyzja jaka Firma, Typ dokumentu, Kategoria:
- W przypadku wywołania OCR poprzez „Dodaj wiele z OCR” silnik wykorzystuje znaną z kontekstu wywołania kategorię i typ. Nawet jeżeli Text Classification zwrócił inną rekomendację dla tych pól nie jest ona brana pod uwagę
- Podobnie w przypadku wybranej firmy, ona również będzie ustawiana dla dokumentu niezależnie od wskazania Text Classification
- W przypadku użycia „AI hot folder” system będzie określał Typ, Kategorię, Firmę na podstawie najwyżej rekomendowanego wskazania Text Classification. Uwaga! Każde z tych pół przynajmniej na jednym formularzu musi być oznaczone „Wstaw pozycję najbardziej prawdopodobną”.
- Ustawienie kontrahenta
- Data capture zwraca 2 NIPY (pola VATID i VATID1). Jako kontrahent będzie wytypowany ten który nie jest „naszą firmą”, tzn. nie jest przypisany do którejś z firm (Ustawienia -> Kartoteki -> Firmy -> Edytuj -> Kontrahent).
- Jeżeli istnieje kontrahent o tym NIP w kartotece Kontrahenci wstawiany jest do formularza
- Jeżeli nie istnieje kontrahent o tym NIP w kartotece kontrahenci jest on zaczytywany z bazy GUS
- Uzupełnienie nieuzupełnionych pól wyboru na podstawie rekomendacji Text classification
- Uzupełnienie nieuzupełnionych pól na podstawie pliku Data capture (kolumna „OcrData” w tabeli „Fi”)
- Jeżeli dla kontrahenta dla wybranego typu dokumentu istnieje model szczegółowy Data capture uruchamiana jest usługa AI ./data_capture/templates/{template_id}/predict. Nieuzupełnione dotychczas pola są uzupełniane wartościami zwróconymi przez tą usługę.
- Uzupełnienie reszty nieuzupełnionych pól na podstawie dokumentu wzorcowego kontrahenta danego typu (jeżeli istnieje)
Dodatkowe uwagi:
- Aby usługa Text classification wybrała Typ należy w co najmniej jednym formularzu dla pola „Typ” wybrać opcję „Pokaż rekomendację” oraz „Wstaw pozycję najbardziej prawdopodobną”.
- Jeśli klasyfikator wskazał najbardziej prawdopodobny typ, rekomendacje są podpowiadane tylko dla tego typu (przykład: Jeśli na typie „Faktura zakupu” (formularz “Faktura zakupu”) mam zaznaczoną opcję „Wstaw pozycję najbardziej prawdopodobną” dla pól „Typ” i „Kategoria” a klasyfikator wskazał, że to typ „Faktura sprzedaży” (formularz “Faktura sprzedaży”), na którym nie mam zaznaczonej tej opcji, to pola nie zostaną uzupełnione.
- Dokument bez typu i kategorii nie zostanie utworzony (komunikaty „Nieznany typ dokumentu.” lub „Nieznana kategoria dokumentu.”).
- Opcje „Hot folder” i „Dodaj wiele z OCR” tworzą nowy dokument i zapisują go w bazie. OCR-owanie na formularzu nowego dokumentu tylko uzupełnia pola (nie tworzy nowego dokumentu ani nie zapisuje wartości do bazy).
AI hot folder
AI hot folder jest najbardziej zaawansowanym scenariuszem procesu opisywanego powyżej. Z punktu widzenia użytkownika wrzuca on skany dokumentów w jedno miejsce. Następnie system sam rozdziela je do odpowiednich szufladek (kategorii) wykorzystując do tego celu usługi klasyfikacji tekstu.
Poniżej w skrócie opisano co system robi po dodaniu pliku do AI hot folder:
- Wykonuje proces OCR (przekształcanie obrazu w tekst)
- Określa 3 kluczowe cechy na postawie klasyfikacji: Firma, Typ dokumentu, Kategoria. Na podstawie tych cech rozmieszcza pliki do odpowiednich kategorii
- Uruchamia proces tworzenia dokumentu na bazie pliku

Szczegółowo kroki opisane są w punkcie OCR BN powyżej.
Na razie usługa działa w obrębie dokumentów.
Ustawianie modelu szczegółowego Data capture
Model szczegółowy data capture pozwala na przechwycenie dowolnej wartości z dowolnego typu dokumentu.
Aby rozpocząć pracę z modelem szczegółowym należy najpierw aktywować przycisk „Aktualizuj model szczegółowy”, poprzez dodanie go do menu dokumentu, który będziemy poddawać procesowi „OCRowania”. Aby włączyć przycisk, należy przejść do modułu Ustawienia -> Personalizacja -> Menu, wybrać z listy te menu, które jest podpięte pod dokument, a następnie kliknąć Edytuj. (Domyślnie zawsze jest to Menu systemowe Dokumenty). Po otwarciu formularza, należy z drzewka po lewej wybrać Więcej, a następnie kliknąć Więcej -> Dodaj i w formularzu dodawania nowego przycisku skonfigurować przycisk jak poniżej. Na końcu klikamy Zapisz. Więcej o konfiguracji menu można dowiedzieć się tutaj.

Aby wytrenować model szczegółowy należy:
- Prawidłowo wprowadzić min. 3 dokumenty (załącznik musi być musi być “zOCRowany” czyli mieć warstwę tekstową, dane wprowadzone do formularza muszą być prawidłowe)
- Dla każdego z dokumentów należy kliknąć opcję “Aktualizuj model szczegółowy”. Ten proces może trwać nawet do kilku minut w zależności od ilości pół na formularzu oraz liczby stron dokumentu.
Po tych dwóch krokach model jest już gotowy. Aby go przetestować należy wykonać proces OCR dla kolejnego dokumentu.
Podczas procesu OCR system:
- Najpierw wykona data capture w oparciu o model ogólny (./data_capture/general/1/predict)
- Następnie wykona data capture w oparciu o model szczegółowy i uzupełni te pola, które uda mu się przechwycić (./data_capture/templates/{template_id}/predict)
Na poniższej animacji zaprezentowano jak przechwycić niestandardowe informacje z faktury.

Szczegółowe informacje odnoście trenowania modelu szczegółowego
Trenowanie modelu szczegółowego odbywa się poprzez usługę AI /data_capture/templates/{template_id}/fit
Pola formularza, które są wysyłane do uczenia:
- numer obcy (kolumna [ForeignNumber] z tabeli [Do])
- data dokumentu ([DocumentDate])
- data płatności ([PayDate])
- numer rachunku bankowego kontrahenta (kolumna [AccountNumber] z [CoAc])
- nip kontrahenta (kolumna [NIP] z [Co]) zarówno z pola ‚Kontrahent’ jak i ‚Kontrahent edycja’
- waluta (kolumna [Symbol] z tabeli [Cu])
- opis ([Description])
- kwota netto ([Net])
- kwota vat ([Nat])
- kwota brutto ([Gross])
- wszystkie atrybuty (kolumna [Text] z [FlVa]) typu:
- Pole tekstowe
- Wielowierszowe pole tekstowe
- Data
- Data i czas
- Liczba
- Liczba zmiennoprzecinkowa
Szczegółowe informacje odnośnie odczytu informacji z modelu szczegółowego
Krok 1:
Na początek odpytywana jest usługa ./data_capture/general/{model_id}/predict dla modelu faktury. Zwraca ona plik XML, który wygląda tak:
- numer obcy (nazwa pola w XML ABBYY: _InvoiceNumber)
- data dokumentu (_InvoiceDate)
- data płatności (_DueDate)
- data zdarzenia (_FactDate)
- kontrahent (na podstawie NIPu z _VATID lub _VATID1 w zależności od firmy)
- numer konta rachunku bankowego kontrahenta (_BankAccount)
- elementy (_LineItems):
- jednostkę miary (_UnitOfMeasurement)
- stawkę vat (_VATPercentage)
- ilość (_Quantity)
- asortyment (_Description)
- wartość brutto (_TotalPriceBrutto)
- wartość netto (_TotalPriceNetto)
- wartość vat (_VATValue)
- stawki VAT:
- stawka vat (_TaxRate)
- wartość netto (_NetAmount)
- wartość vat (_TaxAmount)
- wartość brutto (_GrossAmount)
Krok 2:
Następnie system sprawdza, czy istnieje model szczegółowy dla tego kontrahenta i tego typu dokumentu (./data_capture/templates/list). Jeżeli jest, odpytywana jest usługa ./data_capture/templates/{template_id}/predict. Dane, które zwróci są dopisywane do pliku XML uzyskanego w kroku 1 tylko w przypadku gdy model ogólny jej nie uzupełnił. Dodatkowo dopisywane są gałęzie:
- opis (_Description)
- waluta (_Currency)
- atrybuty (_Attributes)
Tak przygotowany plik jest zapisywany w tabeli „Fi” w kolumnie „OcrData”. Z tego pliku są uzupełniane dane w formularzu dokumentu.