feat(ultraplan-local): v1.6.0 — /ultraresearch-local deep research command

Add /ultraresearch-local for structured research combining local codebase
analysis with external knowledge via parallel agent swarms. Produces research
briefs with triangulation, confidence ratings, and source quality assessment.

New command: /ultraresearch-local with modes --quick, --local, --external, --fg.
New agents: research-orchestrator (opus), docs-researcher, community-researcher,
security-researcher, contrarian-researcher, gemini-bridge (all sonnet).
New template: research-brief-template.md.

Integration: --research flag in /ultraplan-local accepts pre-built research
briefs (up to 3), enriches the interview and exploration phases. Planning
orchestrator cross-references brief findings during synthesis.

Design principle: Context Engineering — right information to right agent at
right time. Research briefs are structured artifacts in the pipeline:
ultraresearch → brief → ultraplan --research → plan → ultraexecute.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Kjell Tore Guttormsen 2026-04-08 08:58:35 +02:00
commit baa2d0220b
488 changed files with 213221 additions and 0 deletions

View file

@ -0,0 +1,459 @@
# Document Intelligence - Custom Model Training
**Last updated:** 2026-02
**Status:** GA
**Category:** Azure AI Services (Foundry Tools)
---
## Introduksjon
Azure AI Document Intelligence tilbyr custom models som gjør det mulig å trene egne modeller på spesifikke dokumenttyper og forretningsprosesser. Custom models kommer i to varianter: **custom template** (strukturerte skjemaer med konsistent layout) og **custom neural** (strukturerte, semi-strukturerte og ustrukturerte dokumenter med varierende layout). Med v4.0 (GA) API-en har custom neural models fått støtte for signaturdeteksjon, overlappende felter, og tabell-/celle-konfidensscoring.
Custom models lar organisasjoner automatisere ekstraksjon av nøkkeldata fra dokumenter som ikke dekkes av prebuilt models, som interne skjemaer, kontrakter, spesialiserte fakturaer, og bransje-spesifikke dokumenter. Modellene trenes med labeled datasets (minimum 5 dokumenter for å komme i gang), og kan kombineres til composed models for å håndtere flere dokumentvarianter i ett endepunkt.
Document Intelligence Studio tilbyr en no-code opplevelse for labeling, trening og testing, mens REST API og SDKer gir full programmatisk kontroll. Custom neural models støtter nå opptil 50,000 siders treningsdata og kan trenes i opptil 10 timer (10 gratis timer per måned, deretter betalt trening).
## Kjernekomponenter / Nøkkelegenskaper
### Custom Model Types
| Type | Bruksområde | Treningstid | Dokumentstruktur |
|------|-------------|-------------|------------------|
| **Custom Template** | Skjemaer med konsistent layout (søknader, spørreskjemaer) | 1-5 minutter | Template-basert, krever identisk visuell struktur |
| **Custom Neural** | Dokumenter med varierende layout (W2-skjemaer, fakturaer fra ulike leverandører) | 30 min - 12 timer | Strukturert, semi-strukturert, ustrukturert |
### Ekstraksjonskapabiliteter
| Funksjon | Custom Template | Custom Neural | v4.0 GA Features |
|----------|-----------------|---------------|------------------|
| Key-value pairs | ✔ | ✔ | |
| Selection marks | ✔ | ✔ | |
| Tabeller (tabular fields) | ✔ | ✔ | Tabell/rad/celle-konfidensscoring |
| Signaturdeteksjon | ✔ | ✔ | Signaturfelter (min. 5 samples) |
| Region labeling | ✔ | ✔ (bruker Layout API-resultater) | |
| Overlappende felter | ❌ | ✔ | Complete/partial overlap støtte |
### Treningskrav (Input Requirements)
| Kategori | Template Model | Neural Model |
|----------|----------------|--------------|
| **Minimum dokumenter** | 5 | 5 |
| **Maks treningssider** | 500 | 50,000 |
| **Maks treningsstørrelse** | 50 MB | 1 GB |
| **Filformater** | PDF, JPEG/JPG, PNG, BMP, TIFF, HEIF | PDF, JPEG/JPG, PNG, BMP, TIFF, HEIF |
| **Maks sider per dokument** | 2,000 (F0: 2 sider) | 2,000 (F0: 2 sider) |
| **Maks filstørrelse (analyse)** | S0: 500 MB, F0: 4 MB | S0: 500 MB, F0: 4 MB |
| **Bilde-dimensjoner** | 50×50 til 10,000×10,000 px | 50×50 til 10,000×10,000 px |
### Treningsbudsjett og Kostnader
```json
// v4.0 2024-11-30 (GA) - Paid Training Support
POST https://{endpoint}/documentintelligence/documentModels:build?api-version=2024-11-30
{
"modelId": "invoice-extractor-v2",
"description": "Invoice extraction with 10h training",
"buildMode": "neural",
"maxTrainingHours": 10,
"azureBlobSource": {
"containerUrl": "<SAS-URL>",
"prefix": "invoices/training/"
}
}
```
| API-versjon | Gratis treningsbudsjett | Maks treningslengde | Billing |
|-------------|------------------------|---------------------|---------|
| v4.0 (2024-11-30) | 10 timer/måned | 10 timer per build | Faktisk tid brukt (min. 30 min per jobb) |
| v3.1/v3.0 | 20 byggeoperasjoner/måned | 30 minutter per build | Ingen ekstra kostnad (innenfor kvote) |
**Viktig:** Betalt trening i v4.0 krever at `maxTrainingHours` settes eksplisitt. API-kall uten budsjett vil feile hvis du ber om mer enn 10 timer.
### Composed Models
Kombiner opptil 200 custom models til én modell-ID. Document Intelligence klassifiserer automatisk dokumentet og velger best match model.
```python
# Python SDK - Compose Models
from azure.ai.documentintelligence import DocumentIntelligenceAdministrationClient
admin_client = DocumentIntelligenceAdministrationClient(endpoint, credential)
poller = admin_client.begin_compose_model(
compose_request={
"modelId": "invoice-master-v1",
"description": "All invoice variants",
"componentModels": [
{"modelId": "invoice-vendor-a"},
{"modelId": "invoice-vendor-b"},
{"modelId": "invoice-vendor-c"}
]
}
)
composed_model = poller.result()
```
## Arkitekturmønstre
### Mønster 1: Single Custom Neural Model (Recommended Start)
**Bruk når:** Dokumenter har samme informasjon, men varierende layout.
**Fordeler:**
- Generaliserer på tvers av formater (én modell for alle W2-varianter fra ulike selskaper)
- Enklere vedlikehold (én modell å oppdatere)
- Lavere latens (ingen klassifiseringsoverhead)
**Ulemper:**
- Kan kreve mer treningsdata (minst 5 samples per variant)
- Treningstid 30 min - 12 timer (vs. 1-5 min for template)
**Implementering:**
1. Samle 5+ samples per dokumentvariant
2. Label alle felter i Document Intelligence Studio
3. Tren med `buildMode: "neural"`
4. Test med dokumenter fra alle varianter
```python
# Label contiguous values - VIKTIG for neural models
# ❌ FEIL: "Supplier ID: ABC123" lablet som ett felt
# ✔ RIKTIG: Kun "ABC123" lablet (uten key)
```
### Mønster 2: Custom Template + Composed Model
**Bruk når:** Dokumenter har konsistent layout per type, men flere dokumenttyper i samme prosess.
**Fordeler:**
- Rask trening (1-5 min per modell)
- Høy presisjon for strukturerte skjemaer
- Enkel å debugge (én template per format)
**Ulemper:**
- Krever én modell per layoutvariant
- Ikke robust mot layoutendringer
- Maks 200 component models per composed model
**Implementering:**
1. Tren separate template models for hver layoutvariant
2. Compose models til én modell-ID
3. Document Intelligence klassifiserer automatisk ved analyse
```bash
# REST API - Build Template Model
POST https://{endpoint}/documentintelligence/documentModels:build?api-version=2024-11-30
{
"modelId": "po-template-vendor-a",
"buildMode": "template",
"azureBlobSource": {
"containerUrl": "<SAS>",
"prefix": "vendor-a/"
}
}
```
### Mønster 3: Custom Classifier + Custom Extraction
**Bruk når:** Multi-dokument filer (én PDF med flere dokumenttyper) eller behov for å splitte dokumenter før ekstraksjon.
**Fordeler:**
- Automatisk dokumenttype-identifikasjon
- Støtter splitting (én file → mange dokumenter)
- Office-format støtte (DOCX, XLSX, PPTX) i v4.0
**Ulemper:**
- To-trinns prosess (klassifiser → ekstraher)
- Ekstra latens og kostnader
- Krever egen treningsdata for classifier
**Implementering:**
1. Tren custom classification model (min. 5 samples per klasse)
2. Tren custom extraction models for hver dokumenttype
3. Pipeline: Classify → Extract med riktig modell
## Beslutningsveiledning
### Velge mellom Template og Neural
| Scenario | Anbefaling | Begrunnelse |
|----------|-----------|--------------|
| Interne skjemaer (søknader, timesheet) | **Template** | Konsistent layout, rask trening, lavere kostnad |
| Fakturaer fra mange leverandører | **Neural** | Varierende layout, én modell for alle |
| Kontrakter (varierende struktur) | **Neural** | Semi-strukturert, ingen fast template |
| Spørreskjemaer (standardisert PDF) | **Template** | Identisk layout, høy presisjon |
| W2-skjemaer (USA tax forms) | **Neural** | Samme info, ulike selskaper = ulike layouts |
### Vanlige feil og fallgruver
| Problem | Årsak | Løsning |
|---------|-------|---------|
| Lav accuracy (<80%) | For lite treningsdata | Øk til 10-15 samples, inkluder variasjoner |
| Modellen finner ikke felt | Field ikke lablet konsistent | Bruk samme field-navn på tvers av dokumenter |
| "Region overlaps other field" error | Overlappende labels i Studio | Bruk **region labeling** (ikke field selection) for overlaps |
| Trening feiler etter 30 min | v3.x API-begrensning | Oppgrader til v4.0 eller reduser datasett |
| Tabelldata ikke ekstrahert | Tabell ikke lablet som tabular field | Label tabell med Table-type (ikke individuelle celler) |
### Røde flagg (When NOT to use Custom Models)
| Red Flag | Alternativ |
|----------|-----------|
| Dokumentet dekkes av prebuilt model (faktura, kvittering, ID-kort) | Bruk prebuilt models (lavere kostnad, ingen trening) |
| Under 5 samples tilgjengelig | Vent til du har mer data, eller bruk prebuilt → custom hybrid |
| Ekstrem layoutvariasjon (100+ unique formats) | Vurder GPT-4o/GPT-4 Turbo multimodal extraction |
| Real-time krav (<1 sek responstid) | Custom models har 5-15 sek latens (avhengig av dokumentstørrelse) |
## Integrasjon med Microsoft-stakken
### Azure AI Foundry (tidligere Azure ML)
```python
# Deploy custom model i AI Foundry project
from azure.ai.ml import MLClient
from azure.ai.ml.entities import ManagedOnlineEndpoint, ManagedOnlineDeployment
ml_client = MLClient.from_config()
# Custom model trained i Document Intelligence
model_id = "invoice-extractor-v2"
# Deploy til managed endpoint
endpoint = ManagedOnlineEndpoint(
name="invoice-extraction",
auth_mode="key"
)
ml_client.begin_create_or_update(endpoint).result()
```
### Power Automate + AI Builder
AI Builder's **Document Processing** lar deg bruke custom models direkte i Power Automate flows:
1. I AI Builder: **Use a Custom Model** → Import Document Intelligence model-ID
2. I Power Automate: **Process and save information from documents** → Velg custom model
3. Map ekstraherte felter til SharePoint/Dataverse/CRM
**Begrensning:** AI Builder custom models støtter kun **template models**, ikke neural (per januar 2026).
### Microsoft Graph + Document Intelligence
```csharp
// Analyser OneDrive/SharePoint-dokument med custom model
var graphClient = new GraphServiceClient(authProvider);
var driveItem = await graphClient.Me.Drive.Items["{item-id}"].Request().GetAsync();
using var stream = await graphClient.Me.Drive.Items["{item-id}"].Content.Request().GetAsync();
var docClient = new DocumentIntelligenceClient(new Uri(endpoint), new AzureKeyCredential(key));
var operation = await docClient.AnalyzeDocumentAsync(
WaitUntil.Completed,
"invoice-extractor-v2",
new AnalyzeDocumentContent { BytesSource = BinaryData.FromStream(stream) }
);
```
### Semantic Kernel Integration
```csharp
// Custom model som Semantic Kernel plugin
public class InvoiceExtractionPlugin
{
[SKFunction, Description("Extract invoice fields from document")]
public async Task<string> ExtractInvoiceAsync(
[Description("Document URL or base64")] string document,
SKContext context)
{
var client = new DocumentIntelligenceClient(endpoint, credential);
var result = await client.AnalyzeDocumentFromUriAsync(
WaitUntil.Completed,
"invoice-extractor-v2",
new Uri(document)
);
return JsonSerializer.Serialize(result.Value.Documents[0].Fields);
}
}
```
## Offentlig sektor (Norge)
### GDPR og Datasuverenitet
| Aspekt | Vurdering | Anbefaling |
|--------|-----------|------------|
| **Treningsdata lokasjon** | Azure Blob Storage kan være i Norge (Norway East) | Bruk Norway East for treningsdata og modeller |
| **Modell hosting** | Custom models lagres i regionen hvor de trenes | Tren i Norway East for å sikre datasuverenitet |
| **Inferens (analyse)** | API-kall kan rutes til nærmeste region | Spesifiser Norway East-endpoint eksplisitt |
| **Model copy** | Modeller kan kopieres til andre regioner | Begrens kopiering til EU/EEA-regioner |
**Neural Model Region Support:** Custom neural models kan KUN trenes i utvalgte regioner (inkl. West Europe, ikke Norway East). Løsning:
1. Tren modell i **West Europe** (EU-region, GDPR-compliant)
2. Kopier modell til **Norway East** for produksjon
3. Analyser dokumenter med Norway East-endpoint
```python
# Copy model fra West Europe til Norway East
target_client = DocumentIntelligenceAdministrationClient(
endpoint="https://<norway-resource>.cognitiveservices.azure.com",
credential=AzureKeyCredential(norway_key)
)
copy_auth = target_client.get_copy_authorization(
model_id="invoice-model-norway",
description="Production model in Norway"
)
source_client.begin_copy_model_to(
model_id="invoice-model-westeu",
target=copy_auth
)
```
### AI Act (EU) Compliance
Custom models klassifiseres som **"limited risk"** AI-system (ikke høyrisiko) hvis de brukes til:
- Dokumentautomatisering (fakturahåndtering, arkivering)
- Intern prosesseffektivisering
**Høyrisiko-klassifisering** (krever konformitetsvurdering) hvis brukt til:
- Automatiske avgjørelser som påvirker rettigheter (trygdeytelser, lånesøknader)
- Sikkerhets-kritiske prosesser (politietterforskning, grensekontroll)
**Anbefalinger for offentlig sektor:**
- Dokumenter modellens treningsdata (datasett-karakteristikk, labeling-prosess)
- Logg model accuracy og confidence scores per dokument
- Implementer human-in-the-loop for lav confidence (<0.8)
- Oppretthold audit trail (hvilken modell-versjon ble brukt for hver analyse)
### Forvaltningsloven § 11 (Innsyn)
Innbyggere har rett til innsyn i dokumenter som omhandler dem. Custom models må:
1. **Bevare original** - Lagre både original dokument OG ekstraherte data
2. **Audit trail** - Logg hvilken modell-versjon som analyserte dokumentet
3. **Manual review** - Tilby mulighet for manuell gjennomgang ved lav confidence
### Schrems II (Data Transfers)
**Problem:** Microsoft kan i teorien få ordre fra amerikanske myndigheter om innsyn i data.
**Mitigering:**
1. Bruk **EU Data Boundary** (alle tjenester i EU-regioner)
2. Krypter sensitive felter før opplasting til Azure Blob Storage
3. Vurder **customer-managed keys** (CMK) for encryption at rest
4. Implementer data retention policies (slett treningsdata etter modell-trening)
## Kostnad og lisensiering
### Prismodell (per februar 2026)
| Operasjon | Kostnad (approx.) | Enhet |
|-----------|-------------------|-------|
| **Trening (v4.0)** | Gratis: 10 timer/mnd<br>Betalt: ~$1.50/time | Per time faktisk treningstid (min. 30 min) |
| **Trening (v3.x)** | Gratis: 20 builds/mnd<br>Betalt: N/A (ikke støttet) | Per build (maks 30 min) |
| **Analyse (S0)** | ~$1.50 per 1000 sider | Per side analysert |
| **Lagring (modeller)** | Gratis | Modeller lagres i 90 dager uten kostnad |
| **Blob Storage** | Standard blob-priser | ~$0.02/GB/måned (LRS, hot tier) |
### Total Cost of Ownership (TCO) Scenario
**Case:** 10,000 fakturaer/måned, 2 siders gjennomsnitt
| Komponent | Beregning | Kostnad/mnd |
|-----------|-----------|-------------|
| Initial trening (v4.0, 5 timer) | Gratis (innenfor 10t kvote) | $0 |
| Re-trening (månedlig, 2 timer) | Gratis (innenfor 10t kvote) | $0 |
| Analyse (20,000 sider) | 20 × $1.50 | $30 |
| Blob Storage (100 GB treningsdata) | 100 × $0.02 | $2 |
| **Total** | | **$32/mnd** |
**Sammenlignet med manuell prosessering:**
- Manuell tid: 10,000 fakturaer × 2 min = 333 timer
- Kostnad (ved $30/time): $10,000/mnd
- **ROI:** 312x kostnadsinnsparning
### Optimaliseringstips
1. **Bruk prebuilt models først** - Custom models kun for unike behov
2. **Batch processing** - Reduser API-kall ved å analysere flere dokumenter i én operasjon (opptil 2000 sider)
3. **Caching** - Lagre results for identiske dokumenter (sjekk hash før analyse)
4. **Model lifecycle** - Re-tren kun når accuracy faller (ikke på fast schedule)
5. **Free tier testing** - Bruk F0 tier for utvikling/testing (4 MB limit, 2 sider)
## For arkitekten (Cosmo)
### Spørsmål å stille klienten
1. **Dokumentvariasjoner:** "Har fakturaene/dokumentene konsistent layout, eller varierer strukturen mellom leverandører/avdelinger?"
2. **Volum og frekvens:** "Hvor mange dokumenter analyserer dere per måned, og hva er topp-belastningen?"
3. **Eksisterende prosess:** "Hvordan håndteres dokumentene i dag - manuell registrering, OCR, eller ingen prosess?"
4. **Data retention:** "Hvor lenge må treningsdata og analyserte dokumenter lagres for compliance?"
5. **Accuracy-krav:** "Hva er akseptabelt feilnivå? Kan dere akseptere 5% feilrate med manuell review, eller kreves 99%+ accuracy?"
6. **Real-time vs batch:** "Må dokumenter analyseres umiddelbart (real-time), eller kan de prosesseres i batch?"
7. **Integration:** "Skal resultatene integreres med eksisterende systemer (ERP, CRM, SharePoint)? Hvilke?"
8. **Sensitive data:** "Inneholder dokumentene personopplysninger eller forretningshemmeligheter som krever ekstra sikkerhet?"
### Fallgruver og røde flagg
| Fallgruve | Symptom | Forebygging |
|-----------|---------|-------------|
| **Under-labeled dataset** | Model accuracy <70% | Krev minst 10-15 samples, ikke 5 minimum |
| **Inconsistent labeling** | Felt funnet i noen docs, ikke andre | Bruk samme field-navn, label ALLE samples |
| **Template for neural use case** | Model feiler på nye layoutvarianter | Start med neural hvis layoutvariasjon er kjent |
| **Neural for template use case** | Unødvendig lang treningstid (30 min vs 2 min) | Bruk template hvis layout ER konsistent |
| **No validation dataset** | Ingen måte å verifisere accuracy | Del dataset 80/20 (training/testing) |
| **Over-fitting** | Perfekt på treningsdata, dårlig på nye docs | Bruk diverse samples (ulike leverandører, datoer, beløp) |
### Anbefalinger per modenhetsnivå
#### Nivå 1: Proof of Concept (1-2 uker)
- **Mål:** Verifiser at custom model løser use case
- **Approach:** Document Intelligence Studio (no-code)
- **Dataset:** 5-10 representative samples
- **Model:** Custom neural (mest generell)
- **Success criteria:** >80% accuracy på test-set
#### Nivå 2: Pilot (1-2 måneder)
- **Mål:** Produksjonsklar løsning for én dokumenttype
- **Approach:** REST API + Azure Functions/Logic Apps
- **Dataset:** 20-50 samples med variasjoner
- **Model:** Template eller neural basert på POC-læring
- **Success criteria:** >90% accuracy, <10 sek latens, human-in-the-loop for <0.8 confidence
#### Nivå 3: Enterprise Scale (3-6 måneder)
- **Mål:** Multi-dokument pipeline med CI/CD
- **Approach:** SDK + Azure DevOps + monitoring
- **Dataset:** 100+ samples per dokumenttype, continuous learning
- **Model:** Composed models + custom classifier
- **Success criteria:** >95% accuracy, auto-retry logic, model versioning, A/B testing
**Arkitekturbeslutninger for scale:**
- **Model registry** - Azure Container Registry for model artifacts
- **Feature store** - Lagre ekstraherte felter i Cosmos DB/SQL for downstream analytics
- **Monitoring** - Application Insights custom metrics (accuracy per document type, confidence distribution)
- **Retraining pipeline** - Automatisk re-trening når accuracy faller under threshold
## Kilder og verifisering
### Microsoft Learn URLs (Verified via MCP)
1. **Custom Neural Model** - https://learn.microsoft.com/en-us/azure/ai-services/document-intelligence/train/custom-neural?view=doc-intel-4.0.0 (Verified: 2026-02)
2. **Custom Model Overview** - https://learn.microsoft.com/en-us/azure/ai-services/document-intelligence/train/custom-model?view=doc-intel-4.0.0 (Verified: 2026-02)
3. **Build Custom Model Guide** - https://learn.microsoft.com/en-us/azure/ai-services/document-intelligence/how-to-guides/build-a-custom-model?view=doc-intel-4.0.0 (Verified: 2026-02)
4. **Custom Template Model** - https://learn.microsoft.com/en-us/azure/ai-services/document-intelligence/train/custom-template?view=doc-intel-4.0.0 (Verified: 2026-02)
5. **Composed Models** - https://learn.microsoft.com/en-us/azure/ai-services/document-intelligence/how-to-guides/compose-custom-models?view=doc-intel-4.0.0 (Verified: 2026-02)
6. **Custom Classifier** - https://learn.microsoft.com/en-us/azure/ai-services/document-intelligence/train/custom-classifier?view=doc-intel-4.0.0 (Verified: 2026-02)
### Konfidensnivå per seksjon
| Seksjon | Konfidensgrunnlag | Merknad |
|---------|-------------------|---------|
| Introduksjon | **Verified** | MCP-basert, offisiell docs |
| Kjernekomponenter | **Verified** | Tabeller fra Microsoft Learn |
| Arkitekturmønstre | **Baseline + Expert** | Best practices fra mønster-analyse |
| Beslutningsveiledning | **Expert** | Basert på praktisk erfaring (supplerer docs) |
| Integrasjon Microsoft-stakken | **Baseline** | SDK-eksempler fra MCP, noen hybridscenarier er inferert |
| Offentlig sektor | **Expert** | GDPR/AI Act-analyse er fortolkning av regelverk |
| Kostnad og lisensiering | **Verified (pricing)** + **Expert (TCO)** | Offisiell pricing, ROI-scenarioer er eksempler |
| For arkitekten | **Expert** | Rådgivende innhold basert på Cosmo-persona |
**Disclaimer:** Priser er omtrentlige og kan variere per region og enterprise-avtaler. Valider mot Azure Pricing Calculator før budsjettbeslutninger.