REST API dla innych usług

Dostęp

Klucz serwisu i znaczniki dostępu

  • Każde zapytanie REST wymaga klucza serwisu w nagłówku X-Api-Key (albo Authorization: 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

  1. Dodanie dokumentu: standardize (albo standardize-batch) i zapis tablicy terms w indeksie usługi (alternatives albo stałe lemmaIds). Indeksuj terms, a nie tekst dzielony spacjami: jeden term może mieć kilka słów („Zielona Góra”).
  2. 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.
  3. 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.
  4. Nieznane słowa: osobna tablica unknown w odpowiedzi, a serwis liczy je też u siebie (strona Nieznane), żeby najczęstsze dodać do słownika własnego.
  5. Filtr: własny szybki indeks usługi zawęża miliony dokumentów do najlepszych.
  6. 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.