Semantisk søk

Krever ext

Semantisk søk, filter, likhet og forklaring krever nivået ext, som deles ut til partnere og forskningsprosjekter. Søk om det på api@nasjonalmuseet.no.

Semantisk søk finner bilder etter betydning, ikke eksakte ord. «To hester bak et gjerde» finner bilder som viser det, også når ordene ikke står i tittelen.

Når bør du bruke hva?

Du vil …	Bruk
beskrive et motiv med vanlige ord	POST /search/semantic
filtrere på verkstype, teknikk, år eller kunstnerens kjønn, uten rangering	POST /search/filter
finne bilder som ligner et bilde	POST /search/similar/{imageId}
forstå hvorfor et bilde traff	POST /search/explain
få et forslag til søketekst og filtre fra en fritekst (pub)	POST /search/interpret
finne et ord som står i katalogen	Tekstsøk, ikke semantisk søk

Slik virker det

Hvert bilde har fått nøkkelord laget av en språkmodell (KI), på norsk og engelsk. Søket sammenligner søketeksten med dem og rangerer bildene etter likhet. I tillegg søkes det på ord i katalogen, og de to listene flettes.

Fordi rangeringen bygger på KI-genererte nøkkelord, kan treffene inneholde feil. Det er derfor ikke på det åpne nivået.

Steg 1: Søk med en beskrivelse

curlPythonJavaScript

curl -s -X POST "https://api.nasjonalmuseet.no/api/v1/search/semantic" \ -H "X-API-Key: $NM_API_KEY_EXT" -H "Content-Type: application/json" \ -d '{"query": "to hester bak et gjerde", "lang": "no", "resultsPerPage": 5}'

import os import requests

API = "https://api.nasjonalmuseet.no/api/v1" headers = {"X-API-Key": os.environ["NM_API_KEY_EXT"]}

sok = { "query": "båt i stormvær", "lang": "no", "resultsPerPage": 5, "filters": {"objectName": ["Maleri"]}, } r = requests.post(f"{API}/search/semantic", json=sok, headers=headers, timeout=60) r.raise_for_status() for treff in r.json()["data"]: print(round(treff["score"], 3), treff["nmId"], treff["mainTitle"])

const API = "https://api.nasjonalmuseet.no/api/v1"; const headers = { "X-API-Key": process.env.NM_API_KEY_EXT, "Content-Type": "application/json" };

const r = await fetch(${API}/search/semantic, { method: "POST", headers, body: JSON.stringify({ query: "kvinne ved et vindu", lang: "no", resultsPerPage: 5 }), }); if (!r.ok) throw new Error(HTTP ${r.status}); for (const t of (await r.json()).data) console.log(t.score.toFixed(3), t.nmId, t.mainTitle);

lang velger språket i søket og svaret. Uten lang søkes begge språk. Hvert treff har score og bestMatchImage (bildet som traff best).

Steg 2: Avgrens med filtre

Filtrene brukes før rangeringen: objectName, techniques og materials (katalogens verdier på norsk eller engelsk), productionDateFrom/To (årstall) og creatorGender (female, male, nonBinary, unknown). Uten søketekst, sortert på inventarnummer:

import os import requests

API = "https://api.nasjonalmuseet.no/api/v1" headers = {"X-API-Key": os.environ["NM_API_KEY_EXT"]}

filtre = {"objectName": ["Maleri"], "techniques": ["Olje"], "productionDateFrom": "1880", "productionDateTo": "1900", "resultsPerPage": 5, "lang": "no"} r = requests.post(f"{API}/search/filter", json=filtre, headers=headers, timeout=60) r.raise_for_status() svar = r.json() print("Totalt:", svar["totalResults"]) for verk in svar["data"]: print(verk["nmId"], verk["mainTitle"], verk.get("productionYear"))

Steg 3: Finn lignende bilder

import os import requests

API = "https://api.nasjonalmuseet.no/api/v1" headers = {"X-API-Key": os.environ["NM_API_KEY_EXT"]}

verk = requests.get(f"{API}/objects/NG.M.00939", headers=headers, timeout=30).json() bilde_id = verk["primaryImage"]["imageId"] r = requests.post(f"{API}/search/similar/{bilde_id}", json={"nmId": "NG.M.00939", "resultsPerPage": 5, "lang": "no"}, headers=headers, timeout=60) r.raise_for_status() for t in r.json()["data"]: print(t["nmId"], t["mainTitle"])

Steg 4: Få forslag til søketekst

/search/interpret foreslår hvordan en fritekst kan deles i søketekst og filtre. Det søker ikke, og forslaget brukes bare hvis du velger det. Dette kallet virker også med pub.

curl -s -X POST "https://api.nasjonalmuseet.no/api/v1/search/interpret" \ -H "X-API-Key: $NM_API_KEY" -H "Content-Type: application/json" \ -d '{"query": "maleri av en fin soloppgang", "lang": "no"}'

Gode råd

• Beskriv motivet med flere ord. «Båt i stormvær» gir bedre treff enn «båt». Fyllord som «et» og «av» gjør ingen skade.
• Bruk objectName når du vil ha en verkstype. «Maleri av en båt» blir bedre som query: "båt" med filters.objectName: ["Maleri"]. /search/interpret gir det forslaget.
• Bla med page og hasMore. totalResults gjelder siden, ikke hele samlingen.
• Noen søk blokkeres eller skrives om etter museets søkeregler. Svaret har da blocked: true eller queryRewritten.

Vanlige feil

• 403: nøkkelen er pub. Semantisk søk krever ext.
• Få treff med creatorExact: navnet må være nøyaktig slik det står i katalogen, for eksempel «Edvard Munch».