Logo UK Logo MFF

Institute of Formal and Applied Linguistics


Charles University, Czech Republic
Faculty of Mathematics and Physics

ÚFAL
PONK

Uživatelský manuál PONKu

  1. Spuštění PONKu
  2. Webové rozhraní

Tato sekce popisuje nástroj pro příkazovou řádku. REST API je popsáno na stránce s referencí API.

1. Spuštění PONKu

Nejjednodušší způsob, jak spustit PONK, je poskytnout prostý text jako standardní vstup a získat výsledek ve formátu HTML na standardní výstup. 

./ponk.pl --stdin

Předpokládá se, že vstup je v kódování UTF-8 a může se jednat buď o prostý text nebo (s přepínačem --input-format md) text ve formátu MarkDown.

Následující příkaz spustí PONK se vstupním souborem ve formátu MarkDown; výsledek ve formátu CoNLL-U půjde na standardní výstup. 

./ponk.pl --input-file [název_vstupního_souboru] --input-format md --output-format conllu

Vstupní soubor může být ve formátu MS Word DOCX, jako v následujícím příkladu; v takovém případě je interně převeden na MarkDown (pomocí lokálně nainstalovaného Pandoc) a zpracován jako takový. V tomto příkladu navíc nastavujeme výstupní formát na HTML a úroveň logování na 0, tj. plné logování. 

./ponk.pl --input-file ../data/pokus.docx --input-format docx --output-format html --logging-level 0

Výsledek ve zvoleném výstupním formátu je vždy odeslán na standardní výstup; pro účely logování lze navíc výsledek uložit do souboru. Následující příkaz pošle výsledek v HTML na standardní výstup a zároveň uloží výsledek ve formátu CoNLL-U do souboru. 

./ponk.pl --input-file [název_vstupního_souboru] --output-format html --store-format conllu

Úplná syntaxe příkazu pro spuštění PONKu 

Použití: ponk.pl [možnosti]
možnosti: -i|--input-file [název vstupního textového souboru]
         -si|--stdin (vstupní text poskytnutý přes stdin)
         -if|--input-format [vstupní formát: txt (výchozí), md, docx]
         -of|--output-format [výstupní formát: html (výchozí), conllu]
         -os|--output-statistics (přidat statistiky PONK k výstupu; pokud je uvedeno, výstup je JSON se dvěma položkami: data (ve výstupním formátu) a statistiky (v HTML))
        -uil|--ui-language [jazyk: lokalizovat odpověď, kdekoliv je to možné, do zadaného jazyka: en (výchozí), cs]
         -sf|--store-format [formát: uložit výstup v zadaném formátu: html, conllu]
         -ss|--store-statistics (uložit statistiky do souboru HTML)
         -ap|--apps [čárkou dělený seznam interních aplikací k volání, možné hodnoty: app1 (výchozí), app2]
         -ll|--logging-level (přepsat výchozí (anonymní) úroveň protokolování (0=plné, 1=omezené, 2=anonymní))
          -v|--version (vytiskne verzi programu a skončí)
          -n|--info (vytiskne verzi programu a podporované funkce jako JSON a skončí)
          -h|--help (vytiskne krátkou nápovědu a skončí)

1.1. Vstupní formáty

Vstupní formát lze specifikovat pomocí možnosti --input-format. Aktuálně podporované vstupní formáty jsou:

  • txt (výchozí): vstup je prostý text
  • md: vstup je text ve formátu MarkDown
  • docx: vstup je soubor MS Word DOCX

1.2. Výstupní formáty

Výstupní formát je specifikován pomocí možnosti --output-format. Aktuálně podporované výstupní formáty jsou:

  • html: výstup v HTML
  • txt: výstup v prostém textu (zatím neimplementováno)
  • md: výstup ve formátu MarkDown (zatím neimplementováno)
  • conllu: formát CoNLL-U - není dostupný přes API (a zatím neimplementováno)

2. Webové rozhraní

2.1. Celkové metriky

Dokumentace k celkovým metrikám

2.2. Gramatická pravidla

Anaforické odkazy

Vyhýbejte se vágním anaforickým odkazům (např. „co se týče výše uvedeného“). Viz Šamánková a Kubíková (2022, s. 42).

Opakování pádů

Shluky podstatných jmen a přídavných jmen ve stejném pádu mohou znepřehlednit text. Například v příkladu (1) se instrumentál opakuje 6krát. Doporučujeme revidovat shluky delší než 3 slova, pokud je to možné. Čárky, předložky a spojky se nepočítají. Viz Sgall a Panevová (2014, s. 88-90).

(1) Některé druhy řas se dovedou v úrodných vodách v horních vrstvách rozmnožit v ohromném množství.

Potvrzovací výrazy

Extrémní výrazy, které zbytečně potvrzují již předpokládanou jistotu autora (např. „jednoznačně“, „jasně“, „nepochybně“). Viz Šamánková a Kubíková (2022, s. 42).

Vzdálenost mezi objektem a řídícím slovem

Objekt vzdálený od přísudku (jeho lexikální složky, pokud je složený) může narušit plynulost textu. V příkladu (2) je přísudek 19 tokenů od objektu (včetně interpunkce). Doporučujeme revidovat vzdálenosti větší než 4 slova, pokud je to možné. Viz Šamánková a Kubíková (2022, s. 53-54).

(2) Dne 5. 2. 2022 jste podal proti rozhodnutí, kterým jsme Vám nepřiznali starobní důchod, protože jste nezískal potřebnou dobu důchodového pojištění, námitky a přiložil jste aktuální lékařské posudky.

Vzdálenost mezi přísudkem a podmětem

Podmět vzdálený od přísudku (jeho gramatické složky, pokud je složený) může narušit plynulost textu. V příkladu (3) je přísudek („nese“) 27 tokenů od podmětu („žalobce“), včetně interpunkce. Doporučujeme revidovat vzdálenosti větší než 5 slov, pokud je to možné. Viz Šamánková a Kubíková (2022, s. 53-54), Šváb (2023, s. 21-22).

(3) Podle rozhodnutí nese nepříznivé následky toho, že se nepodařilo doložit listinu prokazující jednoznačně existenci právního titulu, na jehož základě by některému z dědiců svědčila práva k dílu, žalobce.

Literární styl

Výrazy spojené s literárním stylem (např. „jenž“, „jestliže“, genitivní objekty). Viz Sgall a Panevová (2014, s. 42, 66-69, 79-80).

Dlouhé výrazy

Výrazy, které lze zkrátit (např. „v důsledku toho“ → „proto“, „týkající se“ → „o“, „prostřednictvím kterého“ → „kterým“). Viz Šamánková a Kubíková (2022, s. 44), Šváb (2023, s. 118).

Participiální pasiva

Počet pasivních konstrukcí s „být“. Viz Šváb (2023, s. 27), Šamánková a Kubíková (2022, s. 38-40).

Přísudek daleko ve větě

Umístění přísudku (jeho finitní složky, pokud je složený) daleko v klauzi může narušit plynulost textu. V příkladu (4) je přísudek 6. tokenem ve větě. Doporučujeme revidovat věty, kde je přídudek dále než 5 slov od začátku. Viz Šamánková a Kubíková (2022, s. 53-54).

(4) Již od roku 2001 ochránce chrání osoby před nezákonným či jinak nesprávným jednáním nebo nečinností správních úřadů a dalších institucí.

Nadbytečné výrazy

Výrazy, které nejsou potřeba k předání informace (např. „je nutné zdůraznit“). Viz Šamánková a Kubíková (2022, s. 42-43).

Relativistické výrazy

Relativistické výrazy (např. „poněkud“, „jeví se“, „patrně“). Viz Šamánková a Kubíková (2022, s. 42).

Rozptýlené složené slovesné tvary

Pomocná slova složeného slovesa (pomocná slovesa a klitiky) vzdálené od lexikální složky mohou narušit plynulost textu. V příkladu (5) jsou pomocné sloveso a příčestí pasivní 9 slov od sebe. Doporučujeme revidovat tvary, kde jsou části vzdáleny více než 4 slova. Viz Šamánková a Kubíková (2022, s. 53-54).

(5) Daný objekt není dle zveřejněných informací na webových stránkách NPÚ dlouhodobě využíván a vinou neprováděné údržby dochází k degradaci autentických stavebních konstrukcí a prvků stavební výbavy.

Příliš málo sloves

Slovesa přinášejí informace o ději a dynamizují text. Označíme věty, kde je pouze každé 16. slovo sloveso (průměrný poměr sloves k délce věty je méně než 0,06). V příkladu (6) je jedno sloveso a celkem 24 slov, tedy poměr 1/24≈0,04. Viz Šamánková a Kubíková (2022, s. 37).

(6) Vzhledem k četnosti opakování rozhodování o žádostech o rekvalifikaci mimo správní řízení pokládá Úřad práce za vhodné usměrnění a sjednocení praxe vydáním vnitřního předpisu.

Příliš dlouhé věty

Dlouhé věty jsou obtížné na zapamatování. Doporučujeme revidovat věty delší než 22 slov. Viz Šamánková a Kubíková (2022, s. 51), Šváb (2023, s. 17-18).

Příliš mnoho negací

Negativní formulace zastírají význam. Doporučujeme revidovat věty s více než 2 negacemi, pokud se opakují. V příkladu (7) jsou 3 negace a pouze 2 negovatelná slova bez negace. Viz Šamánková a Kubíková (2022, s. 40-41), Šváb (2023, s. 33).

(7) V této situaci není dodatečné povolení stavby krokem, který by nepovolenou stavbu nevyřešil, ale krokem, který nepřinese urovnání sousedského sporu.

Příliš mnoho nominálních konstrukcí

Průměrný počet podstatných jmen v klauzi. Například věta v příkladu (8) obsahuje 5 podstatných jmen. Viz Sgall a Panevová (2014, s. 41).

(8) Otázku zavinění pak nelze směšovat s otázkou porušení povinnosti.

Abstraktní podstatná jména se slabým významem

Sémanticky slabá abstraktní podstatná jména (např. „základ“, „situace“, „úvaha“). Viz Šamánková a Kubíková (2022, s. 41).

Slova se slabým významem

Semanticky slabá slova (např. „zaměřit“, „postup“, „velmi“). Viz Šamánková a Kubíková (2022, s. 37-38, 39), Sgall a Panevová (2014, s. 86), Šváb (2023, s. 32).

2.3. Lexikální překvapení

Pro výpočet lexikálního překvapení je použit model GPT2-Czech-XL.

Úroveň lexikálního překvapení je spočítána pro každý textový token (tokenem zde myslíme řetězec písmen často kratší než slovo) podle jeho pravděpodobnosti v daném kontextu relativně vzhledem k ostatním možným tokenům. Pravděpodobnosti jednotlivých tokenů jsou násobeny a výsledná hodnota je přiřazena celému slovu.

Nástroj barevně rozlišuje 16 úrovní lexikálního překvapení.

Detaily k implementaci: https://github.com/ufal/glitter/.

Vysoká míra lexikálního překvapení

Slova jsou obarvena do žluta, oranžova až červena.
Slova vyhodnocena jako vysoce překvapivá označují buď náhlou změnu kontextu nebo pro kontext nečekaný a pravděpodobně těžko srozumitelný výraz.

Střední míra lexikálního překvapení

Slova jsou obarvena do světle modra, tyrkysova až zelena.
Slova vyhodnocena jako středně překvapivá označují mírnou změnu kontextu a často označují výrazy, které jsou hlavními nositeli informace v textu.

Nízka míra lexikálního překvapení

Slova jsou obarvena do tmavě modra až fialova.
Slova s nízkou mírou překvapivosti často označují pokračování ustálených spojení a delší pasáže mohou poukazovat na nadbytečnosti v textu.

2.4. Rétorické role

Tento modul odhaduje, co autor chce vyjádřit.  Vychází z teorie právního psaní, která rozlišuje texty na argumentativní a normativní a každému z těchto dvou žánrů přisuzuje jeho typický inventář tzv. řečových aktů (Speech Acts) nebo rétorických rolí (Rhetorical Roles). Systém tedy hledá v textu segmenty, kterým by mohl přiřadit jednoznačný komunikační záměr. Není svázán hranicemi vět ani odstavců.

Argumentativní a normativní texty v právu a administrativě

Argumentativní texty

Argumentativní  texty se vztahují ke konkrétnímu případu – skutku, stavu, nebo ději.

Příklady:

Sdělujeme panu Novákovi, že dostal pokutu za špatné parkování.     

Paní Nováková žádá o prodloužení lhůty k nahlášení ...

Normativní texty

Normativní texty se vztahují k modelovým a hypotetickým situacím. Zákony a předpisy bývají obecnější a píšou se ve třetí osobě.

Příklad: 

„Za nezvěstného může soud prohlásit svéprávného člověka, který opustil své bydliště, nepodal o sobě zprávu a není o něm známo, kde se zdržuje. Soud uvede v rozhodnutí den, kdy nastaly účinky prohlášení nezvěstnosti.“

Návody a právní rady se často píšou ve druhé osobě.

Příklad:  

„Pokud jste se stali předmětem nějakého právního jednání poté, co jste byli prohlášení za nezvěstné, například zanikl váš pracovní poměr, nemůžete jejich důsledky po svém návratu zrušit, tj. nemáte nárok na to, abyste byli přijati zpět. “

Interpretace výsledku

Zhruba platí, že čím víc textu systém dokáže rozřadit do segmentů se správně určenými rétorickými rolemi, tím bude čtenáři jasnější, co mu autor chce sdělit.

Kategorie rétorických rolí

Normativní texty

Argumentativní texty

Situace

Pravidlo (obecný předpoklad)

Kontext

Příběh (konkrétní předpoklad)

Postup (co můžete udělat)

Závěr

Doporučení (doporučení co dělat)

Právní otázka

Proces (co bude dělat úřad/protistrana)

Výzva

Podmínky (kdy něco můžete udělat)

Rada

Odkazy (na další podobné materiály Frank Bold)

Metatext (procesní technikálie)

Prameny (externí citace, především právní předpisy)

 

Nezařaditelné

 

 

Poznámka

Tento modul zatím není stabilní. Provádíme výzkum úspěšnosti řady  jazykových modelů.