Dostęp
Klucz serwisu i znaczniki dostępu
- Każde zapytanie REST wymaga klucza serwisu w nagłówku
X-Api-Key(alboAuthorization: Bearer); bez niego odpowiedź to 401. Klucz należy do tenanta, czyli odizolowanego środowiska jednego serwisu (np. cpp0x.pl), nie do użytkownika, i jest tylko w konfiguracji backendu serwisu. Tenanta i jego pierwszy klucz tworzy administrator na stronie „Tenanci”. - Klucz wyznacza tenanta: żadne zapytanie go nie podaje, więc serwis pracuje tylko na swoich dokumentach i grupach. Prawa klucza:
search(normalizacja, wyszukiwanie),write(dokumenty i ich grupy),manage(opcje tenanta, tworzenie i usuwanie grup). - Dokumenty tenanta widzi tylko on, przez API. Administrator zarządza tenantami i kluczami, a podgląd danych ma wyłącznie w wersji deweloperskiej (
DeveloperMode). - Dokument ma znaczniki dostępu (
"access": ["public", "forum:12"]), zapytanie znaczniki pytającego użytkownika wyliczone przez serwis-klienta. Dokumenty bez wspólnego znacznika nie istnieją dla zapytania: ani w wynikach, ani w liczbach, grupach czy podpowiedziach. Serwis-klient sprawdza wyniki jeszcze raz swoimi uprawnieniami.
Schemat użycia
Jak z tego korzysta wyszukiwarka
- Dodanie dokumentu:
standardize(albostandardize-batch) i zapis tablicytermsw indeksie usługi (alternativesalbo stałelemmaIds). Indeksujterms, a nie tekst dzielony spacjami: jeden term może mieć kilka słów („Zielona Góra”). - Słowniki własne:
"dictionaries": ["nazwiska", "programowanie"]dołącza słowniki zapisane w serwisie, a"customForms": {"Lemat": ["forma"]}dodaje hasła tylko dla tego zapytania. Pierwszeństwo: customForms, potem słowniki w podanej kolejności, na końcu słownik główny. Dokumenty i zapytania jednej wyszukiwarki używają tej samej listy słowników. - Zapytanie: ta sama standaryzacja zapytania. Każdy term to zbiór alternatyw: wieloznaczna forma („mamy”) ma kilka lematów, a dokument pasuje, gdy ma którykolwiek z nich.
- Nieznane słowa: osobna tablica
unknownw odpowiedzi, a serwis liczy je też u siebie (strona Nieznane), żeby najczęstsze dodać do słownika własnego. - Filtr: własny szybki indeks usługi zawęża miliony dokumentów do najlepszych.
- Weryfikacja: LLM dostaje oryginalne teksty i oryginalne zapytanie, nie formy bazowe.
Pełny opis pól: Swagger. Do czasu wczytania leksykonu metody zwracają 503 ze stanem.
POST /api/lexicon/standardize
Tekst w formach bazowych
Language: "pl", "en" albo puste (wykrywanie po słowach, osobno dla każdej linii). Dictionaries i CustomForms: słowniki własne. RecordUnknown=false: nie licz nieznanych słów. IncludeTokens=true: także wszystkie słowa (z pomijanymi).
curl -s http://lexicon.ddt.pl/api/lexicon/standardize -H 'Content-Type: application/json' -d '{
"text": "Spotkałem Szawdyńskiego w Zielonej Górze z kukiełką",
"dictionaries": ["nazwiska"],
"customForms": { "Zielona Góra": ["Zielonej Górze"] }
}'
{
"language": "pl",
"text": "spotkać Szawdyński Zielona Góra kukiełka",
"terms": [
{ "text": "spotkać", "alternatives": ["spotkać"], "lemmaIds": [...], "original": "Spotkałem", "start": 0, "length": 9, "source": "dictionary" },
{ "text": "Szawdyński", "alternatives": ["Szawdyński"], "lemmaIds": [...], "original": "Szawdyńskiego", "source": "nazwiska" },
{ "text": "Zielona Góra", "alternatives": ["Zielona Góra"], "lemmaIds": [], "original": "Zielonej Górze", "source": "request" },
{ "text": "kukiełka", "alternatives": ["kukiełka"], "lemmaIds": [...], "original": "kukiełką", "source": "dictionary" }
],
"unknown": [],
"dictionaryVersions": { "nazwiska": 3 }
}POST /api/lexicon/standardize-batch
Wiele tekstów naraz
Do indeksowania: do 1000 tekstów w jednym wywołaniu, domyślnie bez listy słów.
curl -s http://lexicon.ddt.pl/api/lexicon/standardize-batch -H 'Content-Type: application/json' \
-d '{"texts": ["Ludzie szli", "I found red puppets"], "dictionaries": ["nazwiska"]}'POST /api/lexicon/match
Czy tekst pasuje do zapytania
Każde słowo zapytania musi mieć w tekście słowo ze wspólnym lematem. Window to najmniejsza liczba słów tekstu z trafieniami wszystkich słów (im mniej, tym bliżej siebie).
curl -s http://lexicon.ddt.pl/api/lexicon/match -H 'Content-Type: application/json' \
-d '{"text": "Znalazłem kukiełkę z czerwoną głową", "query": "czerwone kukiełki"}'
{ "isMatch": true, "foundTermCount": 2, "termCount": 2, "window": 2, ... }POST /api/lexicon/standardize (synonyms)
Synonimy wyrazów
"synonyms": true dokłada słownik wyraz -> synonimy (plWordNet, polskie wyrazy, jeden krok, grupy znaczeń; bez pojęć nadrzędnych). Do wyszukania alternatyw w oryginałach. W match: "expandSynonyms": true dodaje synonimy jednowyrazowe do alternatyw zapytania.
curl -s http://lexicon.ddt.pl/api/lexicon/standardize -H 'Content-Type: application/json' \
-d '{"text": "czerwony samochód chłopaka", "synonyms": true}'
{ "text": "czerwony samochód chłopak", "terms": [...],
"synonyms": { "samochód": ["wóz", "auto", "pojazd samochodowy"], "chłopak": ["chłopiec", "syn"], ... } }GET /api/lexicon/synonyms?word=zamku
Znaczenia i synonimy słowa
Słowo w dowolnej formie: grupy znaczeń z krótkim opisem oraz warianty (aspekt robić/zrobić, zdrobnienia, formy żeńskie).
curl -s 'http://lexicon.ddt.pl/api/lexicon/synonyms?word=zamku'
POST /api/lexicon/standardize (suggestions)
Podpowiedzi literówek
"suggestions": true (też w standardize-batch) dokłada do każdego słowa z unknown do 5 znanych form: brak polskich znaków (Diacritics), przytrzymany AltGr lub zbędne znaki (AltGr), 1-2 zmiany liter (Edit), z lematami. Tylko podpowiedzi: terminy tekstu nie są poprawiane.
curl -s http://lexicon.ddt.pl/api/lexicon/standardize -H 'Content-Type: application/json' \
-d '{"text": "móœiąc o wyrazóœ", "suggestions": true}'
{ "text": "móœiąc wyrazóœ", "terms": [...],
"unknown": [ { "word": "móœiąc", "original": "móœiąc", "count": 1, "positions": [0],
"suggestions": [ { "form": "mówiąc", "language": "pl", "kind": "AltGr", "edits": 0, "cost": 0.15,
"lemmas": ["mówić"], "lemmaIds": [123] }, ... ] }, ... ] }GET /api/lexicon/suggest?word=jezyk
Podpowiedzi dla jednego słowa
Znane formy, o które mogło chodzić (najlepsza pierwsza), z lematami; isKnown, gdy samo słowo jest znane (wtedy jest pierwsze, kind Exact). Opcjonalnie language i max (do 20).
curl -s 'http://lexicon.ddt.pl/api/lexicon/suggest?word=jezyk'
GET /api/lexicon/lookup?word=mamy
Lematy jednego słowa
Wszystkie lematy formy w każdym języku, z częścią mowy i liczbą form.
curl -s 'http://lexicon.ddt.pl/api/lexicon/lookup?word=mamy'
GET /api/lexicon/lemmas/{id}
Lemat i wszystkie jego formy
Formy z bazy (małymi literami) i słowniki, z których pochodzą.
curl -s http://lexicon.ddt.pl/api/lexicon/lemmas/123
PUT /api/lexicon/documents
Zapis dokumentów tenanta
Do 1000 dokumentów naraz; ten sam ExternalDocumentRef zastępuje dokument. Groups: grupy dokumentu (dowolnie wiele, brakujące powstają same), Access: znaczniki dostępu, ThreadKey: dokumenty jednego wątku razem w wynikach, Weight: punkty działu (10% oceny), Version: wersja po stronie serwisu (manifest). Usuwanie: DELETE /api/lexicon/documents/{ref} albo POST /api/lexicon/documents/delete z listą.
curl -s -X PUT http://lexicon.ddt.pl/api/lexicon/documents -H "X-Api-Key: $KEY" -H 'Content-Type: application/json' -d '[{
"externalDocumentRef": "post:123", "groups": ["forum"], "threadKey": "topic:45",
"title": "Wskaźniki w C++", "text": "Jak działa int* p = &x; ...", "url": "https://cpp0x.pl/forum/temat/?id=45",
"section": "Forum", "weight": 0.25, "access": ["public", "forum:3"], "version": "a1b2"
}]'POST /api/lexicon/search
Wyszukiwanie w dokumentach tenanta
Groups: tylko dokumenty tych grup (puste: wszystkie dokumenty tenanta). Access: znaczniki dostępu pytającego użytkownika. Wyniki do MaxResults dokumentów z oceną co najmniej MinScore, dokumenty wątku razem (MaxPerThread).
curl -s http://lexicon.ddt.pl/api/lexicon/search -H "X-Api-Key: $KEY" -H 'Content-Type: application/json' \
-d '{"query": "kurs c++", "groups": ["kursy", "artykuly"], "access": ["public"], "maxResults": 20}'PUT /api/lexicon/groups/{name}
Grupa dokumentów
Tworzy grupę albo zmienia jej opis. Lista z liczbą dokumentów: GET /api/lexicon/groups. DELETE usuwa grupę, a jej dokumenty zostają (w innych grupach).
curl -s -X PUT http://lexicon.ddt.pl/api/lexicon/groups/kursy -H "X-Api-Key: $KEY" -H 'Content-Type: application/json' -d '{"description": "Kursy C++"}'POST /api/lexicon/groups/{name}/documents
Dokumenty do grupy i z grupy
Zmienia grupy dokumentów bez ponownego wysyłania treści; brakujące dokumenty są pomijane.
curl -s http://lexicon.ddt.pl/api/lexicon/groups/sfml/documents -H "X-Api-Key: $KEY" -H 'Content-Type: application/json' \
-d '{"add": ["doc:337", "doc:2021"], "remove": ["post:123"]}'GET /api/lexicon/tenant
Tenant klucza
Opcje (język, słowa bez polskich znaków, słowniki własne), stan indeksu, liczba dokumentów i grupy. PUT z prawem manage zmienia opcje (dokumenty przygotowują się od nowa w tle). Manifest do porównania z serwisem: GET /api/lexicon/documents/manifest?after=&limit=5000.
curl -s http://lexicon.ddt.pl/api/lexicon/tenant -H "X-Api-Key: $KEY"
GET /api/lexicon/status
Stan leksykonu
Bez klucza, dla monitoringu i skryptów: tylko stan (503, dopóki leksykon nie jest wczytany).
curl -s http://lexicon.ddt.pl/api/lexicon/status
GET /api/lexicon/status/details
Stan szczegółowy
Z kluczem (search): słowniki, pamięć, wyszukiwania naraz, błędy wczytywania.
curl -s -H "X-Api-Key: $KEY" http://lexicon.ddt.pl/api/lexicon/status/details
Dane słowników
Licencje
- PoliMorf / SGJP (IPI PAN, SGJP, Morfologik): BSD 2-Clause.
- AGID (Kevin Atkinson): swobodne użycie z zachowaniem informacji o prawach autorskich.
- lemmatization-lists (Michal Měchura): ODbL 1.0.
- plWordNet 5.0 (synonimy), licencja w stylu WordNet. Wymagana nota:
plWordNet © Wrocław University of Technology. All rights reserved. THIS SOFTWARE AND DATABASE IS PROVIDED "AS IS" AND WROCŁAW UNIVERSITY OF TECHNOLOGY MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, WROCŁAW UNIVERSITY OF TECHNOLOGY MAKES NO REPRESENTATIONS OR WARRANTIES OF MERCHANT-ABILITY OR MERCHANT-FITNESS FOR ANY PARTICULAR PURPOSE; NOR DOES WROCŁAW UNIVERSITY OF TECHNOLOGY MAKE ANY REPRESENTATIONS OR WARRANTIES THAT THE USE OF THE LICENSED SOFTWARE, DATABASE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS. Title to copyright in this software, database and any associated documentation shall at all times remain with Wrocław University of Technology.