CU-analyzere — fra portal via git til worker⚓︎

Kai bruker Azure AI Content Understanding (CU) til å klassifisere og ekstrahere saksdokumenter. Analyzerne — én classifier + ekstraksjon-analyzere per virkemiddel — er git-eide, immutable og innholds-adresserte. Denne siden forklarer jobbflyten og hvorfor den er som den er.

Delene⚓︎

Innholds-adresserte id-er⚓︎

En analyzer-id er <virkemiddelid>_<slug>_<hash8>, der hashen beregnes av definisjons-innholdet. Classifier-roten hasher også leaf-id-ene den refererer (Merkle-struktur): endres én leaf, får både leafen og roten ny id. Konsekvenser:

• Immutabilitet — en deployet analyzer endres aldri; en endring blir en ny analyzer ved siden av.
• Reproduserbarhet — case_document_extractions.analyzer_id bokfører nøyaktig hvilken analyzer som ekstraherte et dokument, og facts-blobene er keyet på analyzer-id (…/facts/{analyzerId}/{filnavn}.json). Samme id ⇒ samme definisjon, alltid.
• Trygg deploy — deploy PUT-er bare id-er som mangler og sletter aldri; gamle analyzere (og sandkasse-prosjekter i portalen) blir stående.

Jobbflyten⚓︎

flowchart LR
    subgraph Sandkasse
        Portal[CU-portalen<br/>aif-kai-test]
    end
    subgraph Git["Git (kilde til sannhet)"]
        Def[contentunderstanding/<br/>definisjons-JSON]
        Lock[analyzers.lock.json]
    end
    subgraph Miljø
        CU[(CU-ressurs<br/>aif-kai-test/-prod)]
        Worker[kai-worker<br/>lockfile innbakt i image]
    end

    Portal -- "1 · export (stdout → fil)" --> Def
    Def -- "2 · PR-review" --> Def
    Def -- "3 · deploy --env" --> CU
    Def -. "deploy/lock skriver" .-> Lock
    Lock -- "4 · merge → kai-worker-pipeline<br/>baker lockfile inn i image" --> Worker
    Worker -- "RotIdFor(virkemiddelId)" --> CU

1. Forfatt/eksperimenter i portalen (eller rediger JSON-en direkte i git). Portalen er kun et verksted — det du lager der er inert for Kai.
2. Eksporter til git: dotnet run --project tools/DeployContentUnderstanding -- export <analyzerId> skriver renset definisjon til stdout; redirect til riktig fil under contentunderstanding/virkemidler/…. Commit definisjonen og lockfilen sammen, åpne PR — analyzerne reviewes som all annen kode.
3. Deploy git → CU: … -- deploy --env test|prod skriver først lockfilen, deretter idempotent PUT av manglende id-er (leaves før rot). Trygt å kjøre før merge: worker peker fortsatt på gammel id via sin innbakte lockfile.
4. Merge → runtime: kai-worker-pipelinen path-trigges av contentunderstanding/, kjører drift-vaktene og baker den nye lockfilen inn i worker-imaget. Først når det imaget er rullet ut slår FetchDocuments opp den nye rot-id-en (AnalyzerLockOptions.RotIdFor) — dette er byttepunktet.

Eksisterende saker re-ekstraheres ikke automatisk ved analyzer-bytte — ekstraksjoner er bokført per analyzer-id, og re-kjøring er et bevisst valg (re-trigg av ExtractDocument).

Vaktene (automatisk i CI)⚓︎

• Lockfile_MatchesDefinitions — rebergener rot-id-ene fra definisjonene; har analyzers.lock.json drevet fra innholdet feiler bygget. Fiks: kjør … -- lock og commit.
• EveryRequiredField_ExistsInSomeAnalyzerDefinition — hvert felt koden faktisk leser (RequiredAnalyzerFields i Application-laget) må finnes i en definisjon. Skjemaet kan dermed ikke drive fra koden uten at bygget sier fra.

Manuelt vs. automatisk i dag⚓︎

Automatisert deploy-pipeline (egen arketype + service principal med Cognitive Services Contributor på aif-kai-{test,prod}) er bevisst utsatt og sporet som egen infra-oppgave (AB#21086). Den må også overta forutsetningen som i dag er manuell:

Videre lesning⚓︎

• Operatør-oppskriften (kommandoer, fallgruver): contentunderstanding/README.md i repoet.
• Oppstrøms datakilder: Kildesystemer — ERS og Mimir.