open/ktg-plugin-marketplace
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity Actions

feat(ms-ai-architect): add plugin to open marketplace (v1.5.0 baseline)

Browse source 
Initial addition of ms-ai-architect plugin to the open-source marketplace.
Private content excluded: orchestrator/ (Linear tooling), docs/utredning/
(client investigation), generated test reports and PDF export script.
skill-gen tooling moved from orchestrator/ to scripts/skill-gen/.

Security scan: WARNING (risk 20/100) — no secrets, no injection found.
False positive fixed: added gitleaks:allow to Python variable reference
in output-validation-grounding-verification.md line 109.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Kjell Tore Guttormsen 2026-04-07 17:17:17 +02:00
commit 6a7632146e
490 changed files with 213249 additions and 2 deletions
Download patch file Download diff file Expand all files Collapse all files

748
plugins/ms-ai-architect/skills/ms-ai-engineering/references/azure-ai-services/ai-services-api-best-practices.md Normal file
View file

@ -0,0 +1,748 @@
# Azure AI Services - API Design and Best Practices
**Last updated:** 2026-02
**Status:** GA
**Category:** Azure AI Services (Foundry Tools)
---
## Introduksjon
Når du bygger produksjonsklare applikasjoner med Azure AI Services (Azure OpenAI, Content Safety, Translator, Document Intelligence, Computer Vision, etc.), er robust API-design og feilhåndtering kritisk. Distribuerte skytjenester krever at applikasjoner håndterer midlertidige feil, throttling, nettverksproblemer og uventede responser på en strukturert måte.
Denne referansen dekker best practices for:
- **Error handling** — Strukturert feilhåndtering med Azure SDK exception hierarchy
- **Retry logic** — Eksponentiell backoff, rate limiting og retry storms
- **Rate limiting** — Throttling-håndtering og quota management
- **Batching** — Effektiv bruk av Batch API for høyvolum-operasjoner
- **Connection management** — Connection pooling og timeout-konfigurering
- **Idempotency** — Design for at identiske requests kan håndteres trygt
- **Authentication patterns** — Managed Identity vs. API keys
**Kilde:** Microsoft Learn (verified via MCP 2026-02)
---
## Kjernekomponenter / Nøkkelegenskaper
### 1. Azure SDK Exception Hierarchy
Azure SDK for Python og .NET bruker en hierarkisk exception-modell som gir både generiske og spesifikke error-handling capabilities.
**Exception-hierarki:**
```
AzureError (base)
├── ClientAuthenticationError
├── ResourceNotFoundError
├── ResourceExistsError
├── ResourceModifiedError
├── ResourceNotModifiedError
├── ServiceRequestError
├── ServiceResponseError
└── HttpResponseError
```
**Viktige exception-typer:**
| Exception | HTTP Status | Når den kastes | Retry? |
|-----------|-------------|----------------|--------|
| `ClientAuthenticationError` | 401 | Authentication failure | ❌ Nei — fix credentials |
| `ResourceNotFoundError` | 404 | Resource doesn't exist | ❌ Nei (unless transient) |
| `ResourceExistsError` | 409 | Resource already exists | ❌ Nei — handle duplicate |
| `HttpResponseError` (429) | 429 | Rate limit exceeded | ✅ Ja — med backoff |
| `HttpResponseError` (500-504) | 500-504 | Server/gateway error | ✅ Ja — transient |
| `ServiceRequestError` | N/A | Network/DNS failure | ✅ Ja — network transient |
### 2. HTTP Error Codes (Azure OpenAI)
| Status Code | Error Type | Retry Strategy |
|-------------|-----------|----------------|
| 400 | Bad Request | ❌ Fix input — don't retry |
| 401 | Authentication Error | ❌ Fix credentials |
| 403 | Permission Denied | ❌ Fix RBAC assignments |
| 404 | Not Found | ❌ Verify resource exists |
| 408 | Request Timeout | ✅ Retry with backoff |
| 422 | Unprocessable Entity | ❌ Fix input validation |
| 429 | Rate Limit Error | ✅ Retry with `retry-after` header |
| 500 | Internal Server Error | ✅ Retry with backoff |
| 502 | Bad Gateway | ✅ Retry with backoff |
| 503 | Service Unavailable | ✅ Retry with backoff |
| 504 | Gateway Timeout | ✅ Retry with backoff |
**Azure OpenAI SDKs** (Python, .NET, Go) retry automatisk 408, 429, 500, 502, 503, 504 — opptil 3 ganger med exponentiell backoff.
### 3. Retry Logic Patterns
**Eksponentiell backoff (anbefalt):**
```python
from azure.core.pipeline.policies import RetryPolicy
retry_policy = RetryPolicy(
retry_total=5, # Max retry attempts
retry_backoff_factor=2, # 2^n seconds
retry_backoff_max=60, # Max backoff: 60s
retry_on_status_codes=[408, 429, 500, 502, 503, 504]
)
client = BlobServiceClient(
account_url="https://...",
credential=credential,
retry_policy=retry_policy
)
```
**Azure OpenAI custom retry (Python):**
```python
from openai import AzureOpenAI
client = AzureOpenAI(
azure_endpoint=os.getenv("AZURE_OPENAI_ENDPOINT"),
api_key=os.getenv("AZURE_OPENAI_API_KEY"),
api_version="2024-10-21",
max_retries=5 # Default: 2
)
```
**C# retry med Polly:**
```csharp
using Azure;
using Azure.AI.Inference;
try {
var response = client.Complete(requestOptions);
} catch (RequestFailedException ex) {
if (ex.ErrorCode == "content_filter") {
Console.WriteLine($"Content filter triggered: {ex.Message}");
} else if (ex.Status == 429) {
// Implement exponential backoff
Thread.Sleep(TimeSpan.FromSeconds(Math.Pow(2, retryCount)));
} else {
throw;
}
}
```
### 4. Rate Limiting og 429 Responses
**Azure OpenAI Provisioned Throughput:**
- **429 respons** betyr at provisjonerte PTU-er er fullt benyttet
- Service returnerer `retry-after` og `retry-after-ms` headers
- **Standard SDK-oppførsel:** Respekterer `retry-after` og retrier automatisk
**Håndtering av 429:**
| Strategi | Når bruke | Latency Impact |
|----------|-----------|----------------|
| **Client-side retry** | OK med høyere latency | ⬆️ Høyere (venter på retry-after) |
| **Fallback til annen deployment** | Low-latency krav | ⬇️ Lavere (umiddelbar failover) |
| **Fallback til global-standard** | Cost/availability balance | ➡️ Moderat (noe høyere cost) |
**Rate limiting pattern (for bulk operations):**
```python
# Bad practice: Naive retry storm
for record in records:
try:
client.process(record)
except RateLimitError:
time.sleep(1) # Fixed delay — overwhelms service
# Good practice: Rate limiter + durable queue
# 1. Enqueue to Azure Event Hubs/Service Bus
# 2. Job processor dequeues at controlled rate
# 3. Tracks PTU utilization via Azure Monitor
```
### 5. Batching (Azure OpenAI Batch API)
**Batch API:** Asynkrone batch-operasjoner med 50% lavere kostnad enn real-time API.
**Bruksområder:**
- Large-scale data processing (embeddings, summarization)
- Content generation (product descriptions, translations)
- Document review (legal, compliance)
- NLP tasks (sentiment analysis, classification)
**Batch limits:**
| Parameter | Limit |
|-----------|-------|
| Max batch files (no expiration) | 500 |
| Max batch files (with expiration) | 10,000 |
| Max input file size | 200 MB (BYOS: 1 GB) |
| Max requests per file | 100,000 |
**Queueing with exponential backoff (Python):**
```python
import time
max_retries = 10
retry_count = 0
batch_job = None
while retry_count < max_retries:
try:
batch_job = client.batches.create(
input_file_id=file_id,
endpoint="/chat/completions",
completion_window="24h"
)
break # Success
except Exception as e:
if "token limit exceeded" in str(e):
retry_count += 1
wait_time = 2 ** retry_count
time.sleep(wait_time)
else:
raise
```
**Fail-fast regions (for batching):** Australia East, East US, Germany West Central, Italy North, North Central US, Poland Central, Sweden Central, Switzerland North, East US 2, West US.
### 6. Connection Pooling og Timeouts
**HTTP connection pooling (Python):**
```python
import requests
# Keep-alive enabled by default
session = requests.Session()
response = session.get("https://api.example.com")
```
**Azure OpenAI timeout configuration (Python):**
```python
from openai import AzureOpenAI
client = AzureOpenAI(
azure_endpoint="...",
api_key="...",
timeout=300.0 # 5 minutes (default: 600s/10 min)
)
```
**Connection pooling for database SDKs:**
| SDK | Module |
|-----|--------|
| MySQL | `mysql.connector.pooling` |
| PostgreSQL | `psycopg2.pool` |
| SQLAlchemy | `sqlalchemy.pool` |
| Pyodbc | Built-in pooling |
**Best practice:**
- ✅ Bruk connection pools for database/HTTP clients
- ✅ Sett realistiske timeouts (ikke 10 min for user-facing apps)
- ✅ Implementer keepalives for long-running connections
- ❌ IKKE opprett nye connections for hver request
### 7. Idempotency
**Definisjon:** En operasjon er idempotent hvis den kan kalles flere ganger uten å produsere flere side-effekter etter første kall.
**HTTP idempotency:**
| HTTP Method | Idempotent? | Beskrivelse |
|-------------|-------------|-------------|
| `GET` | ✅ Ja | Read-only, ingen side-effekter |
| `PUT` | ✅ Ja | Replaces resource at URI |
| `DELETE` | ✅ Ja | Deletes resource (samme outcome) |
| `POST` | ❌ Nei | Creates new resource hver gang |
| `PATCH` | ❌ Nei | Partial update (depends) |
**Idempotency-teknikker for Azure AI Services:**
```python
# 1. Check if already processed (database lookup)
def process_document(doc_id):
if already_processed(doc_id):
return cached_result(doc_id)
result = client.analyze_document(...)
save_result(doc_id, result)
return result
# 2. Event-carried state transfer (Event Hubs)
event = {
"doc_id": "12345",
"operation": "set_status",
"status": "completed", # Not "increment_count" — idempotent
"timestamp": "2026-02-03T10:00:00Z"
}
# 3. Deduplication window (Service Bus)
# Enable duplicate detection with MessageId
message.message_id = f"{order_id}-{timestamp}"
```
**Duplicate detection (Azure Service Bus):**
- Default deduplication window: 10 minutes
- Min: 20 seconds, Max: 7 days
- Based on `MessageId` (or `MessageId + PartitionKey` if partitioned)
---
## Arkitekturmønstre
### Pattern 1: Rate Limiting med Durable Messaging
**Problem:** Bulk ingestion til throttled service (Azure Cosmos DB, Azure AI Search) resulterer i retry storms og høy feilrate.
**Løsning:** Bruk Azure Event Hubs/Service Bus som buffer + job processor med rate limiting.
```
User API → Event Hubs → Job Processor (rate-limited) → Azure AI Service
(buffer) (100 req/s controlled)
```
**Implementering:**
1. **API enqueues messages** (millions per second capacity)
2. **Job processor** leases partitions from blob storage (15s lease)
- Each partition = 100 PTUs (requests/s)
- Process dequeues only what it can handle in 1s
3. **Monitor utilization** via Azure Monitor (`Provisioned-Managed Utilization V2`)
**Fordeler:**
- ✅ Reduserer 429 errors fra 80% til <5%
- ✅ Predikterbar throughput
- ✅ Ingen data loss ved crash (durable queue)
- ✅ Skalerer horisontalt (multiple job processors)
### Pattern 2: Circuit Breaker (for transient faults)
**Problem:** Gjentatte kall til utilgjengelig service forverrer problemet (thundering herd).
**Løsning:** Circuit Breaker pattern.
**States:**
| State | Oppførsel |
|-------|-----------|
| **Closed** | Normal operation — forwards requests |
| **Open** | Service unavailable — fails fast (no requests) |
| **Half-open** | Test if service recovered — 1 request |
**Implementering (Python):**
```python
class CircuitBreaker:
def __init__(self, failure_threshold=5, recovery_timeout=60):
self.failure_threshold = failure_threshold
self.recovery_timeout = recovery_timeout
self.failure_count = 0
self.state = 'closed'
self.last_failure_time = None
def call(self, func, *args, **kwargs):
if self.state == 'open':
if time.time() - self.last_failure_time > self.recovery_timeout:
self.state = 'half-open'
else:
raise Exception("Circuit breaker open")
try:
result = func(*args, **kwargs)
if self.state == 'half-open':
self.state = 'closed'
self.failure_count = 0
return result
except Exception:
self.failure_count += 1
self.last_failure_time = time.time()
if self.failure_count >= self.failure_threshold:
self.state = 'open'
raise
```
### Pattern 3: Idempotent Consumer (Event Hubs + Functions)
**Problem:** Event Hubs garanterer at-least-once delivery — events kan prosesseres flere ganger.
**Løsning:** Idempotent function design.
**Teknikker:**
1. **Duplicate detection via database:**
```python
def process_event(event):
if db.exists(event.id):
return # Already processed
result = ai_client.analyze(event.data)
db.save(event.id, result)
```
2. **Event-carried state transfer:**
```json
{
"account_id": "12345",
"operation": "set_balance",
"new_balance": 1000 // Not "withdraw 100" — idempotent
}
```
3. **PeekLock receive mode (Service Bus):**
- Consumer får exclusive lock (configurable duration)
- Sender acknowledgment ved success
- Message returneres til queue ved timeout/failure
### Pattern 4: Fallback Strategy (429 Handling)
**Multi-tier fallback:**
```python
from openai import AzureOpenAI
def generate_completion(prompt):
try:
# 1. Try provisioned deployment (lowest latency)
return provisioned_client.chat.completions.create(...)
except Exception as e:
if e.status_code == 429:
# 2. Fallback to standard deployment
return standard_client.chat.completions.create(...)
raise
# Alternative: Retry with backoff
client = AzureOpenAI(
max_retries=5,
timeout=300.0
)
response = client.with_options(max_retries=5).chat.completions.create(...)
```
---
## Beslutningsveiledning
### Når bruke Batch API vs. Real-time API?
| Kriterium | Batch API | Real-time API |
|-----------|-----------|---------------|
| **Latency krav** | >24 timer OK | <1 sekund nødvendig |
| **Volume** | >10,000 requests | <1,000 requests |
| **Cost sensitivity** | Høy (50% saving) | Moderat |
| **Use case** | Offline analytics, bulk processing | User-facing chat, real-time translation |
### Retry Strategy Decision Tree
```
429 Error?
├─ Ja → Sjekk retry-after header → Vent og retry (max 5x)
│ └─ Hvis fortsatt 429 → Fallback til annen deployment
│
└─ 500-504? → Exponential backoff (2^n seconds, max 60s)
├─ Transient → Retry opptil 5 ganger
└─ Persistent → Log error + alert ops team
401/403? → IKKE retry → Fix authentication/RBAC
400/422? → IKKE retry → Fix input validation
```
### Rate Limiting Strategy
| Scenario | Anbefalt Løsning |
|----------|------------------|
| **Single client, moderate load** | SDK default retry logic (max_retries=5) |
| **Multiple uncoordinated clients** | Distributed lease system (blob storage) + partitions |
| **Bulk ingestion** | Event Hubs + job processor med rate limiter |
| **User-facing app** | Fallback til standard deployment ved 429 |
---
## Integrasjon med Microsoft-stakken
### Azure AI Foundry Integration
**SDK-er som støtter Azure AI Foundry:**
- **Python:** `azure-ai-inference`, `openai` (Azure variant)
- **.NET:** `Azure.AI.Inference`, `Azure.AI.OpenAI`
- **JavaScript/TypeScript:** `@azure/openai`, `@azure/ai-inference`
- **Go:** `github.com/openai/openai-go` (med Azure endpoint)
**Authentication patterns:**
```python
# 1. DefaultAzureCredential (anbefalt for prod)
from azure.identity import DefaultAzureCredential
from azure.ai.inference import ChatCompletionsClient
credential = DefaultAzureCredential()
client = ChatCompletionsClient(
endpoint="https://<resource>.openai.azure.com",
credential=credential
)
# 2. Managed Identity (Azure-hosted apps)
from azure.identity import ManagedIdentityCredential
credential = ManagedIdentityCredential()
# 3. API Key (development only)
from azure.core.credentials import AzureKeyCredential
credential = AzureKeyCredential(os.getenv("AZURE_OPENAI_API_KEY"))
```
### Azure Monitor Integration
**Metrics å overvåke:**
| Metric | Threshold | Alert |
|--------|-----------|-------|
| `Provisioned-Managed Utilization V2` | >95% | Scale up PTUs |
| `Dependency failures` | >10% | Check retry logic |
| `Request duration` | >10s | Optimize prompts/batching |
| `429 error rate` | >5% | Increase quota or add fallback |
**Kusto query (Log Analytics):**
```kusto
AzureDiagnostics
| where ResourceType == "COGNITIVE-SERVICES"
| where Category == "RequestResponse"
| where resultCode_d == 429
| summarize count() by bin(TimeGenerated, 5m), clientIp_s
| order by count_ desc
```
### Power Automate / Logic Apps Integration
**Error handling i flows:**
1. **Configure retry policy:**
- Retry count: 4
- Retry interval: Exponential (PT10S, PT20S, PT40S, PT80S)
- Retry on: 408, 429, 500, 502, 503, 504
2. **Handle 429 with condition:**
```json
{
"condition": "@equals(actions('Call_Azure_AI').statusCode, 429)",
"ifTrue": {
"Wait": "@actions('Call_Azure_AI').outputs.headers['retry-after']"
}
}
```
---
## Offentlig sektor (Norge)
### Compliance og Error Handling
**GDPR/Personopplysningsloven:**
- ✅ Logg ALDRI personidentifiserende informasjon i error logs
- ✅ Bruk correlation IDs (ikke bruker-ID) i telemetry
- ✅ Respekter `retry-after` headers (ikke spam API-er)
**Eksempel (sanitized logging):**
```python
import logging
logger = logging.getLogger(__name__)
try:
result = client.analyze_document(doc_id)
except HttpResponseError as e:
logger.error(
"Document analysis failed",
extra={
"correlation_id": e.response.headers.get('x-ms-request-id'),
"status_code": e.status_code,
"doc_id": hash(doc_id), # Hash, not plaintext
"error_code": e.error.code if e.error else None
}
)
```
### Idempotency for Offentlig Sektor Use Cases
**Saksbehandlingssystemer:**
- ✅ Bruk MessageId = `{saksID}-{operasjon}-{timestamp}`
- ✅ Aktiver duplicate detection (Service Bus)
- ✅ Check database før processing (deduplication table)
**E-post varsling (som må være idempotent):**
```python
def send_notification(case_id, notification_type):
message_id = f"{case_id}-{notification_type}"
if already_sent(message_id):
return # Idempotent — don't resend
send_email(...)
mark_sent(message_id)
```
---
## Kostnad og lisensiering
### Kostnad-konsekvenser av API Design
**429 Errors kosten ingenting** (ingen PTU consumption), MEN:
- ❌ 400 errors (content filter) **koster** (prompt ble prosessert)
- ❌ 408 timeout **koster** (delvis processing)
- ❌ `finish_reason: content_filter` **koster** (completion ble filtrert)
**Batch API savings:**
| Scenario | Real-time Cost | Batch Cost | Savings |
|----------|----------------|------------|---------|
| 1M tokens (GPT-4o) | ~$10 | ~$5 | 50% |
| Embeddings (1M tokens) | ~$0.13 | ~$0.065 | 50% |
**Provisioned vs. Standard:**
- **Provisioned:** Fast kostnad (per PTU/hour), predictable latency
- **Standard:** Pay-per-token, ingen garantier ved high traffic
**Reservation discounts (Provisioned):**
- 1-årig commitment: ~37% discount
- 3-årig commitment: ~57% discount
---
## For arkitekten (Cosmo)
### Design Principles for Robust API Integration
1. **Error Handling Hierarchy:**
```
Try specific exceptions first → HttpResponseError → AzureError → generic Exception
```
2. **Retry Decision Matrix:**
- **Transient (retry):** 408, 429, 500-504, network errors
- **Permanent (don't retry):** 400, 401, 403, 404, 422
- **Custom logic:** 429 with fallback
3. **Rate Limiting Strategy:**
- **Low volume (<100 req/s):** SDK default retry
- **High volume (>1000 req/s):** Event Hubs + job processor
- **Provisioned deployments:** Monitor utilization, implement fallback
4. **Batching Decision:**
- Latency >1 min? → Batch API
- Volume >10k requests? → Batch API
- Cost critical? → Batch API
5. **Idempotency Checklist:**
- [ ] Operations designed for identical input?
- [ ] Duplicate detection enabled (if using Service Bus)?
- [ ] Database check before processing?
- [ ] Correlation IDs for tracing?
### Common Anti-Patterns (og hvordan unngå dem)
| Anti-Pattern | Problem | Løsning |
|--------------|---------|---------|
| **while(true) retry loop** | Retry storm → overwhelms service | Max retries + exponential backoff |
| **Fixed 1-second delays** | Ignores `retry-after` header | Use SDK retry eller respekter header |
| **Ingen connection pooling** | SNAT port exhaustion | Enable connection pooling |
| **Hardcoded API keys** | Security risk | Use Managed Identity + Key Vault |
| **No timeout configuration** | Hanging requests (10 min default) | Set realistic timeouts (30-300s) |
| **Logging sensitive data** | GDPR violation | Hash/mask PII in logs |
### Monitoring og Alerting
**Kritiske metrics:**
```python
# Azure Monitor query for error rate trends
AzureDiagnostics
| where ResourceType == "COGNITIVE-SERVICES"
| where TimeGenerated > ago(1h)
| summarize
total_requests = count(),
errors = countif(resultCode_d >= 400)
by bin(TimeGenerated, 5m)
| extend error_rate = (errors * 100.0) / total_requests
| where error_rate > 5 # Alert if >5% error rate
```
**Alert rules:**
- **429 rate >5%** → Scale PTUs eller enable fallback
- **500-504 errors** → Check service health dashboard
- **Average latency >5s** → Optimize prompts eller batch processing
### Architecture Decision Records (ADR) Triggers
**Når skal du lage en ADR?**
- [ ] Velger Batch API over real-time API for produksjon
- [ ] Implementerer custom retry logic (avviker fra SDK defaults)
- [ ] Bruker distributed rate limiting (blob leases)
- [ ] Velger Provisioned over Standard (cost/latency trade-off)
- [ ] Implementerer multi-region fallback strategy
---
## Kilder og verifisering
**Verification status:** ✅ Verified via Microsoft Learn MCP (2026-02)
**Primary sources (fetched):**
1. **Handle errors produced by the Azure SDK for Python**
- URL: https://learn.microsoft.com/en-us/azure/developer/python/sdk/fundamentals/errors
- Confidence: **Verified** (MCP fetch)
2. **Rate Limiting pattern**
- URL: https://learn.microsoft.com/en-us/azure/architecture/patterns/rate-limiting-pattern
- Confidence: **Verified** (MCP fetch)
3. **Retry Storm antipattern**
- URL: https://learn.microsoft.com/en-us/azure/architecture/antipatterns/retry-storm
- Confidence: **Verified** (MCP fetch)
4. **Get started using provisioned deployments on Azure OpenAI**
- URL: https://learn.microsoft.com/en-us/azure/ai-foundry/openai/how-to/provisioned-get-started
- Confidence: **Verified** (MCP fetch)
5. **Getting started with Azure OpenAI batch deployments**
- URL: https://learn.microsoft.com/en-us/azure/ai-foundry/openai/how-to/batch
- Confidence: **Verified** (MCP search)
6. **Azure AI services authentication and authorization using .NET**
- URL: https://learn.microsoft.com/en-us/dotnet/ai/azure-ai-services-authentication
- Confidence: **Verified** (MCP search)
7. **Designing Azure Functions for identical input (idempotency)**
- URL: https://learn.microsoft.com/en-us/azure/azure-functions/functions-idempotent
- Confidence: **Verified** (MCP search)
8. **Duplicate detection (Azure Service Bus)**
- URL: https://learn.microsoft.com/en-us/azure/service-bus-messaging/duplicate-detection
- Confidence: **Verified** (MCP search)
**Code samples (verified):**
- Azure.AI.Inference (C#) error handling
- Azure SDK Python retry policies
- OpenAI Python SDK custom retry configuration
**Related documentation:**
- Azure Monitor metrics and logging
- Circuit Breaker pattern (Azure Architecture Center)
- Connection pooling (Azure App Service best practices)
**Baseline knowledge (model):**
- HTTP idempotency semantics (RFC 7231)
- Exponential backoff algorithms
- Connection pooling concepts
**MCP call summary:** 7 microsoft_docs_search + 4 microsoft_docs_fetch + 1 microsoft_code_sample_search = 12 total MCP calls

382
plugins/ms-ai-architect/skills/ms-ai-engineering/references/azure-ai-services/ai-services-cost-optimization.md Normal file
View file

@ -0,0 +1,382 @@
# Azure AI Services - Pricing Models and Cost Optimization
**Last updated:** 2026-02
**Status:** GA
**Category:** Azure AI Services (Foundry Tools)
---
## Introduksjon
Azure AI Services (tidligere Cognitive Services) tilbyr flere prismodeller for å balansere fleksibilitet, forutsigbarhet og kostnadskontroll. Valg av riktig prismodell er kritisk for både teknisk ytelse og økonomisk bærekraft. Denne referansen dekker de tre hovedprismodellene – Pay-as-you-go, Commitment Tier og Provisioned Throughput (PTU) – samt beste praksiser for kostnadsovervåking, budsjettering og optimalisering.
**Verified** – Informasjon fra Microsoft Learn (januar 2026), Azure Pricing Calculator og Azure Cost Management-dokumentasjon.
---
## Kjernekomponenter / Nøkkelegenskaper
### Prismodeller
| Modell | Bruksområde | Fakturering | Forutsigbarhet | Kostnadskontroll |
|--------|-------------|-------------|----------------|------------------|
| **Pay-as-you-go (Standard)** | Varierende eller uforutsigbar trafikk | Per transaksjon/token | Lav | Reaktiv (budsjettalarmer) |
| **Commitment Tier** | Jevn, forutsigbar last | Fast månedlig kostnad + overage | Høy | Proaktiv (forhåndsbetalt kvote) |
| **Provisioned Throughput (PTU)** | Azure OpenAI med garantert throughput | Timepris per PTU + reservasjonsrabatt | Høy | Proaktiv (dedikert kapasitet) |
**Verified** – Fra Microsoft Learn: Azure AI Services Commitment Tier og PTU-dokumentasjon.
### Commitment Tier – Detaljer
**Støttede tjenester:**
- Speech to Text (Standard)
- Text to Speech (Neural)
- Text Translation (Standard)
- Language Understanding (Text Requests)
- Azure Language (Sentiment Analysis, Key Phrase Extraction, Language Detection, NER)
- Vision OCR
- Document Intelligence (Custom/Invoice)
**Viktige egenskaper:**
- **Forpliktelsesperiode:** Kalendermåned (web/connected containers) eller kalenderår (disconnected containers)
- **Pro-rata fakturering:** Første måned beregnes basert på gjenværende dager i måneden
- **Overage:** Forbruk over kvoten faktureres til samme sats som commitment tier
- **Auto-renewal:** Valgfritt; kan endres frem til midnatt UTC siste dag i måneden
- **Ikke-refunderbar:** Når kjøpt, er commitment tier ikke refunderbar
**Begrensninger:**
- Kan IKKE brukes med multi-service Cognitive Services-ressurs
- Krever dedikert single-service ressurs (f.eks. Speech eller Translator)
**Verified** – Microsoft Learn: Purchase Commitment Tier Pricing.
### Provisioned Throughput Units (PTU)
PTU er en kapasitetsbasert prismodell for Azure OpenAI, primært for produksjonsscenarier med høy, forutsigbar trafikk.
**Deployment-typer:**
- **Regional Provisioned:** Data forblir i én region
- **Data Zone Provisioned:** Data forblir innenfor data zone (f.eks. EU, US)
- **Global Provisioned:** Global lastbalansering
**Fakturering:**
- **Timepris:** Beregnes per PTU per time ($/PTU/hr)
- **Pro-rata:** Delvis time faktureres proporsjonalt (15 min = 1/4 timepris)
- **Reservasjonsrabatt:** 1-års eller 3-års Azure Reservations gir betydelige rabatter (opptil 50 % besparelse)
**Kapasitetsplanlegging:**
- Bruk **Foundry PTU Calculator** (tilgjengelig i Azure AI Foundry portal)
- Input: Tokens per minute (TPM), requests per minute (RPM), prompt tokens, completion tokens
- Output: Anbefalt PTU-størrelse
- **Benchmark anbefales** for mest nøyaktig estimat
**Viktig:**
- Generations (output tokens) krever mer kapasitet enn prompts (input tokens)
- For GPT-4o og nyere modeller: TPM per PTU er satt separat for input og output tokens
- **Ikke anbefalt** å skalere produksjonsdeployments basert på trafikk – bruk reservasjon for stabil last
**Verified** – Microsoft Learn: Provisioned Throughput Concepts og PTU Cost Management.
---
## Arkitekturmønstre
### Mønster 1: Hybrid PTU + Pay-as-you-go (Overflow)
**Bruksområde:** Håndtere trafikk-spicer kostnadseffektivt.
**Design:**
- **Primært endepunkt:** PTU-deployment (dekker baseline trafikk)
- **Overflow endepunkt:** Pay-as-you-go-deployment (håndterer trafikk-spicer)
- **Gateway:** API Management eller generativ AI gateway for intelligent ruting
**Fordeler:**
- Forutsigbare kostnader for baseline
- Fleksibilitet for uforutsette lasttopper
- Maksimerer ROI på PTU-reservasjon
**Verified** – Microsoft Learn: Govern AI Costs (Combine PTU with consumption endpoints).
### Mønster 2: Progressive Cost Optimization
**Fase 1 (Pilot):** Pay-as-you-go
- Etabler bruksmønstre
- Ingen forpliktelse
- Høyere per-transaksjonskostnad
**Fase 2 (Produksjon – Forutsigbar trafikk):** Commitment Tier eller PTU
- Bytt til commitment tier når månedlig volum er forutsigbart
- Vurder PTU for Azure OpenAI med SLA-krav
**Fase 3 (Optimalisering):** Reservasjoner + Tagging
- Kjøp 1-års eller 3-års PTU-reservasjon
- Bruk tags for kostnadsallokering per prosjekt/team
**Verified** – Microsoft Learn: Plan and Manage Costs for Azure OpenAI.
### Mønster 3: Cost Governance med Azure Policy
**Kontroller:**
- **Modell-whitelist:** Azure Policy for å kun tillate kostnadseffektive modeller
- **Quota limits:** Sett maksimal quota per modell for å unngå overskridelser
- **Automatisk shutdown:** Automatisk slå av ikke-produksjonsressurser utenfor arbeidstid
**Verified** – Microsoft Learn: Govern AI Costs.
---
## Beslutningsveiledning
### Når bruke Pay-as-you-go
✅ **Bruk når:**
- Proof-of-concept eller pilot
- Uforutsigbar trafikk
- Lav volum (< 10 % av commitment tier-terskel)
- Kortsiktig prosjekt
❌ **Ikke bruk når:**
- Produksjon med høy, jevn trafikk
- Budsjettforutsigbarhet er kritisk
### Når bruke Commitment Tier
✅ **Bruk når:**
- Månedlig volum er forutsigbart (> 70 % kapasitetsutnyttelse)
- Trenger 30-50 % kostnadsbesparelse vs. pay-as-you-go
- Speech, Translation, Language, Vision eller Document Intelligence
❌ **Ikke bruk når:**
- Trafikk varierer sterkt måned til måned
- Trenger multi-service ressurs (ikke støttet)
### Når bruke Provisioned Throughput (PTU)
✅ **Bruk når:**
- Azure OpenAI i produksjon
- SLA-krav (latency, throughput)
- Høy, forutsigbar trafikk (> 100K tokens/dag)
- Langsiktig forpliktelse (1-3 år reservasjon gir best ROI)
❌ **Ikke bruk når:**
- Lav trafikk eller pilot-fase
- Ikke-Azure OpenAI-tjenester (PTU er kun for Azure OpenAI)
**Verified** – Microsoft Learn: When to Use Provisioned Throughput.
---
## Integrasjon med Microsoft-stakken
### Azure Cost Management
**Kostnadsovervåking:**
- **Cost Analysis:** Scope til resource group eller subscription
- **Service tier filter:** Bruk "Azure OpenAI" for å filtrere ut andre AI Services
- **Meter-visning:** Separer input tokens, output tokens og fine-tuning-kostnader
- **Tag-basert allokering:** Bruk deployment tags for team-/prosjektrapportering
**Verified** – Microsoft Learn: Monitor Costs in Azure Portal.
### Budsjetter og Alarmer
| Type | Terskel | Varsel | Formål |
|------|---------|--------|---------|
| **Budget alert** | 90 %, 100 %, 110 % | E-post + webhook | Faktisk forbruk vs. budsjett |
| **Forecast alert** | 110 % | E-post | Predikert overskridelse |
| **Anomaly alert** | Automatisk (ML-basert) | E-post | Uventede kostnadstopper |
**Viktig:**
- Azure OpenAI har INGEN hard limit-funksjonalitet (i motsetning til OpenAI)
- Automatisering via Action Groups krever custom utvikling
**Verified** – Microsoft Learn: Create Budgets and Alerts.
### API Management (Generative AI Gateway)
**Kostnadsoptimalisering via gateway:**
- **Token tracking:** Overvåk forbruk per klient/team
- **Rate limiting:** Forhindre overskridelser
- **Circuit breaker:** Automatisk failover til billigere endepunkt
- **Load balancing:** Distribuer trafikk mellom PTU og pay-as-you-go
**Verified** – Microsoft Learn: Generative AI Gateway Capabilities.
---
## Offentlig sektor (Norge)
### Compliance og Budsjettstyring
**Årlig budsjett-tilnærming:**
- Offentlig sektor har ofte årlige budsjetter → Commitment Tier med årlig forpliktelse (disconnected containers) kan matche budsjettåret
- **Anbefaling:** Start med månedlig commitment tier, evaluer årlig reservasjon etter 6-12 måneder
**Kostnadstransparens:**
- Bruk **tags** for å allokere kostnader per virksomhetsområde
- Eksporter kostnadsdata til Excel/Power BI for rapportering
**Verified** – Microsoft Learn: Tag-based Cost Allocation.
### Dataplassering
**Regional Provisioned vs. Data Zone Provisioned:**
- **Regional:** Data forblir i én region (f.eks. Norway East)
- **Data Zone:** Data forblir i EU (men kan replikeres på tvers av regioner)
- **Global Provisioned:** Data kan replikeres globalt
**Anbefaling for Norge:** Bruk Regional Provisioned for strengeste dataplasseringskrav.
**Verified** – Microsoft Learn: Provisioned Deployment Types.
---
## Kostnad og lisensiering
### Prissammenligning (Eksempel: Azure OpenAI GPT-4o)
| Modell | Pay-as-you-go | PTU (Hourly) | PTU (1-year reservation) | Besparelse (Reservation) |
|--------|---------------|--------------|--------------------------|--------------------------|
| **GPT-4o** (input) | ~0.005 USD/1K tokens | 0.02 USD/PTU/time | ~0.014 USD/PTU/time | ~30 % |
| **GPT-4o** (output) | ~0.015 USD/1K tokens | 0.02 USD/PTU/time | ~0.014 USD/PTU/time | ~30 % |
**Merk:** Priser varierer per region. Bruk [Azure Pricing Calculator](https://azure.microsoft.com/pricing/calculator/) for nøyaktige tall.
**Verified** – Azure Pricing Calculator (januar 2026).
### Commitment Tier – Eksempel (Speech to Text)
| Volum (transaksjoner/måned) | Pay-as-you-go (USD) | Commitment Tier (USD) | Besparelse |
|-----------------------------|---------------------|-----------------------|------------|
| 100 000 | 100 | 75 | 25 % |
| 500 000 | 500 | 350 | 30 % |
**Verified** – Microsoft Learn: Commitment Tier Pricing Examples.
### TCO (Total Cost of Ownership)
**Skjulte kostnader:**
- **Azure Storage:** Knowledge store, enrichment cache (Azure AI Search)
- **Azure Key Vault:** Customer-managed keys for encryption
- **Networking:** Bandwidth charges (minimeres ved same-region deployment)
- **Fine-tuning hosting:** Azure OpenAI fine-tuned models faktureres per time (selv uten trafikk)
**Anbefaling:** Bruk Cost Management eksportfunksjon for å analysere alle relaterte kostnader.
**Verified** – Microsoft Learn: Understand Billing Model for Azure AI Services.
---
## For arkitekten (Cosmo)
### Kostnadsoptimalisering – Sjekkliste
**Før deployment:**
- [ ] Estimert månedlig volum (tokens/transaksjoner)?
- [ ] Trafikkmønster forutsigbart (> 70 % kapasitetsutnyttelse)?
- [ ] SLA-krav (latency, throughput)?
- [ ] Langsiktig forpliktelse (> 12 måneder)?
**Valg av prismodell:**
- [ ] Pay-as-you-go: Pilot, uforutsigbar trafikk
- [ ] Commitment Tier: Forutsigbar trafikk, Speech/Translation/Language
- [ ] PTU: Azure OpenAI, produksjon, SLA-krav
**Etter deployment:**
- [ ] Sett opp budsjettalarmer (90 %, 100 %, 110 %)
- [ ] Konfigurer anomali-deteksjon
- [ ] Bruk tags for kostnadsallokering
- [ ] Overvåk kapasitetsutnyttelse (commitment tier/PTU)
- [ ] Vurder reservasjon etter 3-6 måneder (PTU)
### Når anbefale Commitment Tier
**Spørsmål til kunden:**
1. "Hvor mange transaksjoner per måned forventer dere?"
2. "Varierer trafikken sterkt måned til måned?"
3. "Har dere budsjettforutsigbarhet som krav?"
**Anbefaling:**
- Hvis volum > commitment tier-terskel OG variasjon < 30 % → **Anbefal commitment tier**
- Hvis overage > 20 % → **Oppgrader til høyere tier neste måned**
### Når anbefale PTU
**Spørsmål til kunden:**
1. "Er dette Azure OpenAI i produksjon?"
2. "Har dere latency/throughput-krav i SLA?"
3. "Er trafikken forutsigbar (> 100K tokens/dag)?"
4. "Kan dere forplikte deg til 1-3 år?"
**Anbefaling:**
- Hvis JA på alle → **Anbefal PTU med 1-års reservasjon**
- Hvis NEI på (4) → **Start med PTU hourly, kjøp reservasjon etter 3-6 måneder**
### Red Flags (Kostnadsrisiko)
⚠️ **Varseltegn:**
- "Vi kjører Azure OpenAI pay-as-you-go i produksjon med 1M tokens/dag" → **Anbefal PTU**
- "Vi har commitment tier, men overage er 50 % hver måned" → **Oppgrader tier**
- "Vi vet ikke hvor mye vi bruker" → **Sett opp Cost Management FØRST**
- "Vi har PTU uten reservasjon i 2 år" → **Kjøp reservasjon NÅ**
---
## Kilder og verifisering
### Microsoft Learn (Verified)
1. **Commitment Tier Pricing**
https://learn.microsoft.com/en-us/azure/ai-services/commitment-tier
*Sist sjekket: 2026-02*
2. **Provisioned Throughput Concepts**
https://learn.microsoft.com/en-us/azure/ai-foundry/openai/concepts/provisioned-throughput
*Sist sjekket: 2026-02*
3. **Provisioned Throughput Onboarding (PTU Cost Management)**
https://learn.microsoft.com/en-us/azure/ai-foundry/openai/how-to/provisioned-throughput-onboarding
*Sist sjekket: 2026-02*
4. **Plan and Manage Costs for Azure OpenAI**
https://learn.microsoft.com/en-us/azure/ai-foundry/openai/how-to/manage-costs
*Sist sjekket: 2026-02*
5. **Govern AI Costs (Cloud Adoption Framework)**
https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/scenarios/ai/platform/governance
*Sist sjekket: 2026-02*
6. **Azure Cost Management – Create Budgets**
https://learn.microsoft.com/en-us/azure/cost-management-billing/costs/tutorial-acm-create-budgets
*Sist sjekket: 2026-02*
7. **Generative AI Gateway Capabilities (API Management)**
https://learn.microsoft.com/en-us/azure/api-management/genai-gateway-capabilities
*Sist sjekket: 2026-02*
### Azure Pricing Calculator (Verified)
8. **Azure Pricing Calculator**
https://azure.microsoft.com/pricing/calculator/
*Sist sjekket: 2026-02*
9. **Azure OpenAI Pricing**
https://azure.microsoft.com/pricing/details/cognitive-services/openai-service/
*Sist sjekket: 2026-02*
10. **Cognitive Services Pricing**
https://azure.microsoft.com/pricing/details/cognitive-services/
*Sist sjekket: 2026-02*
### MCP-søk (7 unique sources)
- microsoft_docs_search: "Azure AI Services pricing tiers cost optimization"
- microsoft_docs_search: "Azure AI Services reserved capacity commitment tier"
- microsoft_docs_search: "Azure AI Services budget management cost estimation"
- microsoft_docs_fetch: `/azure/ai-services/commitment-tier`
- microsoft_docs_fetch: `/azure/ai-foundry/openai/how-to/manage-costs`
- microsoft_docs_fetch: `/azure/cloud-adoption-framework/scenarios/ai/platform/governance`
- microsoft_docs_search: "Azure OpenAI provisioned throughput PTU cost optimization"
**Total MCP calls:** 6
**Unique URLs:** 10

566
plugins/ms-ai-architect/skills/ms-ai-engineering/references/azure-ai-services/ai-services-enterprise-architecture.md Normal file
View file

@ -0,0 +1,566 @@
# Azure AI Services - Enterprise Architecture Patterns
**Last updated:** 2026-02
**Status:** GA
**Category:** Azure AI Services (Foundry Tools)
---
## Introduksjon
Azure AI Services (tidligere Cognitive Services) krever robuste enterprise-arkitekturmønstre for å sikre høy tilgjengelighet, disaster recovery og effektiv skalering i produksjonsmiljøer. Dette dokumentet dekker arkitekturmønstre for multi-region deployment, load balancing, failover og infrastrukturdesign for AI-tjenester i Microsoft-stakken.
**Sentrale utfordringer:**
- Regional failover og business continuity
- Load balancing mellom flere Azure OpenAI-instanser
- Kostnadsoptimalisering vs. tilgjengelighet
- Network isolation og security perimeter
- Kvotestyring og throttling-håndtering
**Scope:** Dette dokumentet fokuserer på arkitekturmønstre for Azure OpenAI (del av Foundry Models), Azure AI Search, og støttetjenester som Azure API Management og Azure Front Door. Mønstrene gjelder både Foundry-baserte løsninger og standalone AI Services.
---
## Kjernekomponenter
### 1. Azure AI Services (Foundry Models)
**Deployment-typer:**
| Type | Beskrivelse | Bruksområde |
|------|-------------|-------------|
| **Global Standard** | Automatisk routing til regioner med kapasitet | Høyeste resilience, ingen data residency-krav |
| **Data Zone Standard** | Processing innenfor geografisk sone (US/EU) | Data residency-krav, god resilience |
| **Regional Standard** | Én spesifikk region | Lav latency, manuell failover |
| **Provisioned (PTU)** | Dedikert kapasitet, SLA på latency | Mission-critical workloads, predictable load |
**Multi-region strategi:**
- Minimum 2 regioner for produksjon (active-active eller active-passive)
- Data Zone deployments deler kapasitetspool på tvers av regioner i samme sone
- Separat subscription per region unngår kvote-konflikter
- Full quota allocation per endpoint gir høyest throughput
### 2. Generative AI Gateway (Azure API Management)
**Funksjonalitet:**
- **Load balancing:** Round-robin, weighted, priority-based, session-aware
- **Circuit breaker:** Automatisk deteksjon av 429-errors, dynamisk trip duration basert på `Retry-After`-header
- **Spillover:** Automatic failover til sekundære backends ved throttling
- **Managed identity:** Eliminerer API key management
**Backend pool configuration:**
- Inntil 30 backends per pool
- Priority groups: PTU som Priority 1, standard deployments som Priority 2+
- Session affinity for conversational agents
- Health probes og automatic retry uten client-side delay
**VIKTIG:** APIM circuit breaker for Azure OpenAI må håndtere `429 Too Many Requests` og respektere `Retry-After`-headeren (kan være opptil 24 timer).
### 3. Azure AI Search
**Zone redundancy:**
- Standard tier eller høyere + minimum 3 replicas
- Automatisk distribusjon på tvers av availability zones
- Ingen built-in disaster recovery — krever manuell gjenoppbygging eller support-kontakt
- Semantic ranker og advanced features øker kostnad
**Multi-region:**
- Separat service per region (ingen native multi-region replication)
- Geo-replication strategy må implementeres selv
- Index rebuilding fra separate source of truth ved data loss
### 4. Global Load Balancers
**Azure Front Door:**
- Global HTTP(S) load balancing og failover
- Latency-based routing
- Web Application Firewall (WAF) integration
- Health probes på application-nivå
**Azure Traffic Manager:**
- DNS-basert global routing
- Performance, priority, weighted, geographic routing
- Health endpoint monitoring
- Brukes ofte foran search-enabled clients (ikke direkte til AI Search)
---
## Arkitekturmønstre
### Mønster 1: Active-Active med Priority-Based Load Balancing
**Scenario:** Enterprise med PTU-deployment + standard deployments som fallback.
```
┌─────────────────────────────────────────────────────────┐
│ Azure API Management (Multi-region eller Frontend) │
│ - Backend pool med circuit breaker │
│ - Session affinity for chat │
└─────────┬───────────────────────────────────────────────┘
│
┌─────┴─────┐
│ Priority │
│ Routing │
└─────┬─────┘
│
┌─────┴──────────────────────────────────────┐
│ │
┌───▼─────────────────┐ ┌───────────▼──────────┐
│ Priority 1: PTU │ │ Priority 2: Standard │
│ Region A │ │ Multi-region (US/EU) │
│ - Dedicated capacity│ │ - Data Zone │
│ - Fixed cost │ │ - Pay-per-token │
│ - SLA latency │ │ - Spillover │
└─────────────────────┘ └──────────────────────┘
```
**Fordeler:**
- Maksimal utnyttelse av PTU (fast kostnad)
- Automatisk spillover til standard ved PTU-overload
- Ingen client-side retry logic nødvendig
**Ulemper:**
- Kompleks konfigurasjon
- APIM koster ekstra
- Ikke transparent failover ved regional outage (krever DNS/Front Door)
---
### Mønster 2: Multi-Region med Azure Front Door
**Scenario:** Global applikasjon med latency-sensitive workloads.
```
┌──────────────────┐
│ Azure Front Door │
│ + WAF │
└────────┬─────────┘
│
┌────────────┴────────────┐
│ │
┌───────▼────────┐ ┌────────▼───────┐
│ Region 1 (US) │ │ Region 2 (EU) │
│ - APIM │ │ - APIM │
│ - OpenAI │ │ - OpenAI │
│ - AI Search │ │ - AI Search │
│ - Cosmos DB │ │ - Cosmos DB │
└────────────────┘ └────────────────┘
```
**Komponenter:**
- **Front Door:** Global routing, instant failover, health probes
- **Per-region:** Komplett stack (APIM, AI Services, data)
- **Data replication:** Cosmos DB global distribution, Storage GRS/GZRS
**Fordeler:**
- Minimal latency for globale brukere
- Transparent failover ved regional outage
- Høy SLA (multi-region SLA composite)
**Ulemper:**
- Høy kostnad (dobbel infrastruktur minimum)
- Data consistency-utfordringer
- Kompleks deployment og drift
---
### Mønster 3: Hot/Warm med Data Zone Deployments
**Scenario:** Compliance-krav (data residency i EU/US) med cost optimization.
```
Primary Region (Hot) Secondary Region (Warm)
┌──────────────────┐ ┌──────────────────┐
│ Full capacity │ │ Reduced capacity │
│ - OpenAI (PTU) │ │ - OpenAI (Std) │
│ - AI Search (3x) │ ──────> │ - AI Search (1x) │
│ - Cosmos DB │ replica │ - Cosmos DB │
│ - Active traffic │ │ - Standby │
└──────────────────┘ └──────────────────┘
│ ▲
└──────────────────────────────┘
Manual DNS failover
```
**Failover-strategi:**
1. Detekter outage via health monitoring
2. Scale up secondary region capacity
3. DNS cutover (eller APIM backend pool update)
4. Validate service restoration
**RTO/RPO:**
- RTO: 5-15 minutter (avhenger av scaling speed)
- RPO: Nær null (Cosmos DB continuous backup, AI Search rebuild required)
**Fordeler:**
- 50-70% kostnadssparing vs. full hot/hot
- Data residency compliance
- Raskere failover enn cold standby
**Ulemper:**
- Ikke transparent failover
- Capacity scaling under outage er risikabelt
- Manual intervention required
---
### Mønster 4: Foundry Agent Service med Standard Setup
**Scenario:** Enterprise chat application med network isolation.
```
┌────────────────────────────────────────────────────┐
│ Virtual Network │
│ ┌────────────────────────────────────────────────┐ │
│ │ App Service (Web UI) │ │
│ │ - VNet integration │ │
│ │ - Managed identity │ │
│ └─────────┬──────────────────────────────────────┘ │
│ │ Private Endpoint │
│ ┌─────────▼──────────────────────────────────────┐ │
│ │ Foundry Agent Service │ │
│ │ - Agent runtime │ │
│ │ - Private endpoint access only │ │
│ └─────────┬──────────────────────────────────────┘ │
│ │ Delegated subnet │
│ ┌─────────▼──────────────────────────────────────┐ │
│ │ Private Endpoints: │ │
│ │ - Azure OpenAI │ │
│ │ - AI Search │ │
│ │ - Cosmos DB (conversation state) │ │
│ │ - Storage (file uploads) │ │
│ └────────────────────────────────────────────────┘ │
│ │ │
│ ┌──────────▼─────────┐ │
│ │ Azure Firewall │ │
│ │ - FQDN filtering │ │
│ │ - Egress control │ │
│ └────────────────────┘ │
└────────────────────────────────────────────────────┘
```
**Zone redundancy:**
- **Cosmos DB:** Zone-redundant (ZRS) eller global distribution
- **Storage:** ZRS eller GZRS
- **AI Search:** 3+ replicas med automatic zone distribution
- **App Service:** Zone-redundant (minimum 3 instances)
**Disaster recovery:**
- Cosmos DB: Continuous backup (7-day PITR)
- AI Search: Ingen native backup — rebuild fra source of truth
- Storage: Customer-managed failover for geo-redundant accounts
- Agent definitions: Infrastructure as Code (deploy from source control)
**Fordeler:**
- Enterprise-grade security (zero trust network)
- Full audit trail via NSG flow logs og Firewall logs
- Managed identity eliminerer secrets
- Foundry Agent Service håndterer orchestration og state
**Ulemper:**
- Høyere kompleksitet
- Ikke multi-region (krever separate deployments)
- Foundry portal krever jump box eller VPN-tilgang
---
## Beslutningsveiledning
### 1. Velge Deployment Type
| Krav | Anbefaling |
|------|------------|
| Høyeste resilience, ingen data residency-krav | **Global Standard** |
| EU/US data residency | **Data Zone Standard** |
| Lavest latency, eksisterende regional infra | **Regional Standard** (+ manuell multi-region) |
| Predictable latency SLA, mission-critical | **Provisioned (PTU)** |
| Kostnadsoptimalisering, variabel load | **Standard** med APIM spillover til PTU |
### 2. Velge Load Balancing Strategy
| Scenario | Løsning |
|----------|---------|
| Single region, multiple Azure OpenAI instances | **Azure API Management** (backend pool + circuit breaker) |
| Multi-region global routing | **Azure Front Door** + regional APIM |
| Latency-sensitive, DNS-based | **Traffic Manager** + health probes |
| DIY, containerized | **YARP** (C# reverse proxy) på Azure Container Apps |
### 3. Velge RTO/RPO Strategi
| RTO/RPO Mål | Mønster | Relative Cost |
|-------------|---------|---------------|
| RTO < 1 min, RPO = 0 | Active-active (hot/hot) | 2.0x |
| RTO < 15 min, RPO < 5 min | Active-warm | 1.4x |
| RTO < 1 hour, RPO < 1 hour | Active-cold | 1.1x |
**Konfidensgradering:** 🟢 **Høy** — Basert på Microsoft Learn offisiell dokumentasjon (2026-02).
---
## Integrasjon med Microsoft-stakken
### Azure AI Foundry Integration
**Foundry Agent Service Dependencies (Standard Setup):**
- **Cosmos DB for NoSQL:** Agent state og conversation history (krever zone redundancy)
- **Azure Storage:** File uploads og static files (krever ZRS/GZRS)
- **Azure AI Search:** Chunked index av filer (krever 3+ replicas)
**Multi-project isolation:**
- Separate Foundry project per agent med distinct access patterns
- Project-level connections (ikke account-level) for least privilege
- User-assigned managed identity for project identity (survival ved accidental deletion)
**Disaster recovery:**
- Agent definitions som Infrastructure as Code
- Continuous backup på Cosmos DB (7-day PITR)
- Transactional consistency: Restore alle dependencies til samme point-in-time
### Power Platform Integration
**Copilot Studio:**
- Uses Azure OpenAI via Foundry Models
- Separate per-environment deployments anbefales
- Gateway-pattern mulig via custom connectors
**Power Automate:**
- AI Builder actions bruker dedikerte AI Services
- Premium connectors kan kalle APIM-fronted Azure OpenAI
- Regional availability varierer (sjekk [Products by Region](https://azure.microsoft.com/global-infrastructure/services/))
### M365 Copilot
**Ikke direkte integrasjon med custom Azure OpenAI:**
- M365 Copilot bruker Microsoft-managed AI infrastructure
- Grounding via Microsoft Graph, SharePoint, OneDrive
- Copilot Studio kan utvide med custom skills som kaller Azure OpenAI via gateway
---
## Offentlig sektor (Norge)
### Compliance og Data Residency
**Azure OpenAI i Norge:**
- Ingen Azure OpenAI-region i Norge per 2026-02
- **Nærmeste regioner:** Sweden Central, West Europe
- **Data residency:** Bruk **Data Zone EU** for GDPR-compliance
- **Schrems II:** Data Zone deployments prosesserer data innenfor EU
**Network Isolation:**
- Private endpoints + Azure Firewall (FQDN-filtering)
- NSG per subnet med deny-all default
- Jump box + Azure Bastion for admin-tilgang
- ExpressRoute for hybrid connectivity (ikke required for cloud-only workloads)
### Anbefalte Patterns for Norsk Offentlig Sektor
**Konfidensialitet Normal (N):**
- Data Zone EU Standard deployments
- Hot/warm multi-region (West Europe + Sweden Central)
- Azure API Management for load balancing
- Zone-redundant støttetjenester
**Konfidensialitet Høy (H):**
- Som Normal + Private endpoints på alt
- Azure Firewall med strict egress rules
- Customer-managed keys (CMK) for encryption
- Audit logging til Log Analytics Workspace (Norge-region hvis tilgjengelig, ellers EU)
**Konfidensialitet Særlig Høy (SH):**
- Vurder on-premises AI Services containers (begrenset funksjonalitet)
- Eller: Data Zone EU + customer-managed VNet med zero internet egress
- Dedikert subscription per sensitivity zone
- Enhanced monitoring og Security Operations Center (SOC) integration
**Kostnadsoversikt (estimat, NOK per måned):**
| Komponent | Normal (N) | Høy (H) | Særlig Høy (SH) |
|-----------|-----------|---------|-----------------|
| Azure OpenAI (50K tokens/dag) | ~1 500 | ~3 000 (2x regions) | ~6 000 (PTU dedicated) |
| Azure API Management (Standard) | ~6 000 | ~6 000 | ~12 000 (2x regions) |
| AI Search (Standard, 3 replicas) | ~9 000 | ~18 000 (2x regions) | ~18 000 |
| Cosmos DB (zone-redundant) | ~3 000 | ~6 000 (global) | ~6 000 |
| **Total (ca.)** | **~19 500** | **~33 000** | **~42 000** |
*Disclaimer: Priser er estimater basert på moderate workloads. Faktiske kostnader avhenger av trafikk, data volume og konkrete konfigurasjon.*
---
## Kostnad og lisensiering
### Azure OpenAI Pricing Model
**Standard Deployments (Pay-per-token):**
- **Input tokens:** ~0.003 USD per 1K tokens (GPT-4o)
- **Output tokens:** ~0.006 USD per 1K tokens (GPT-4o)
- **Image input:** Per image (varierer med resolution)
- **Ingen minimum commitment**
**Provisioned (PTU):**
- **Fixed monthly cost:** ~2 500 USD per 100 PTU
- **Inkluderer:** Dedikert kapasitet, latency SLA, priority access
- **Optimalt for:** >10M tokens/måned med forutsigbar load
**Cost Optimization Strategies:**
- **Prompt optimization:** Reducer input tokens (concise prompts, efficient context)
- **Model selection:** Bruk GPT-4o-mini for enklere tasks (10x billigere)
- **Caching:** (Planlagt feature) Reduserer repeterende context-tokens
- **APIM rate limiting:** Forhindre abuse og kostnadsoverskridelse
- **Spillover strategy:** PTU for baseline, standard for peaks
### Azure API Management Pricing
| Tier | Kostnad (ca. NOK/måned) | Max requests | Features |
|------|------------------------|--------------|----------|
| Developer | ~500 | 1M calls | Ingen SLA, dev/test |
| Basic | ~1 500 | 1M calls | SLA, 1 unit max |
| Standard | ~6 000 | 10M calls | Multi-region, 4 units |
| Premium | ~30 000+ | Unlimited | Multi-region, VNet, 10+ units |
**For AI Gateway:** Standard tier minimum (circuit breaker ikke i Consumption tier).
### Azure AI Search Pricing
**Standard Tier (anbefalt for prod):**
- **S1:** ~3 000 NOK/måned per search unit
- **Zone redundancy:** Requires 3+ replicas = ~9 000 NOK/måned minimum
- **Semantic ranker:** +~1 000 NOK/månd per search unit
### Total Cost of Ownership (TCO) Example
**Scenario:** Enterprise chat application, 100 users, 50 queries/dag per user.
**Forutsetninger:**
- 5 000 queries/dag total
- Average 1 000 input tokens + 500 output tokens per query
- 2 regioner (active-warm)
**Månedlig kostnad (NOK):**
```
Azure OpenAI: ~15 000 (2.5M in + 1.25M out tokens)
APIM Standard: ~6 000 (single region)
AI Search S1 (3 replicas): ~9 000
Cosmos DB (zone-redundant): ~3 000
Storage ZRS: ~200
Front Door: ~1 500
──────────────────────────────────────────────────────
TOTAL: ~34 700 NOK/måned
```
**Med PTU optimization (100 PTU i primary region):**
```
Azure OpenAI PTU: ~25 000 (fixed)
Azure OpenAI Standard (spillover): ~3 000
[Andre komponenter samme]
──────────────────────────────────────────────────────
TOTAL: ~46 700 NOK/måned (høyere cost, men forutsigbar)
```
**Konfidensgradering:** 🟡 **Medium** — Prisene er estimater basert på publiserte prislister (2026-02). Faktiske kostnader avhenger av detaljert bruksmønster.
---
## For arkitekten (Cosmo)
### Når bruke hvilke mønstre
**Velg Active-Active (Hot/Hot) hvis:**
- RTO < 1 minutt er strengt krav
- Global user base med latency-følsomhet
- Budsjett tillater 2x infrastructure cost
- Datakonsistens kan håndteres (eventual consistency OK)
**Velg Active-Warm hvis:**
- RTO < 15 minutter er akseptabelt
- Primært regional user base
- Kostnadsoptimalisering er prioritet
- Manual failover-prosess er akseptabel
**Velg Regional + APIM hvis:**
- Single-region deployment er OK
- Throttling-håndtering viktigere enn regional failover
- Lavere kostnad og kompleksitet prioriteres
### Kritiske spørsmål å stille kunden
1. **RTO/RPO requirements:** Hva er maksimal akseptabel downtime? Data loss?
2. **Data residency:** Er det juridiske krav til hvor data prosesseres? (GDPR, Schrems II)
3. **Budget:** Hva er månedlig budsjett for AI infrastructure? (Påvirker hot/warm/cold valg)
4. **User distribution:** Global eller regional? (Påvirker multi-region strategi)
5. **Load pattern:** Forutsigbar eller spiky? (PTU vs. standard)
6. **Security posture:** Network isolation required? (Påvirker VNet/private endpoint design)
7. **Existing footprint:** Azure landing zone existing? ExpressRoute? (Påvirker integration)
### Røde flagg å unngå
❌ **Single region uten throttling-håndtering** — Garantert 429-errors under peak load
❌ **Shared APIM backend pool på tvers av environments** — Dev throttling påvirker prod
❌ **Account-level Foundry connections** — Overprivileged access på tvers av prosjekter
❌ **Ingen disaster recovery plan for AI Search** — Index-tap er ikke-recoverable uten backup strategy
❌ **PTU-deployment uten fallback** — Fast cost uten elasticity ved overload
❌ **Client-side retry uten exponential backoff** — Amplified load under throttling
❌ **Colocating workload data i Foundry Agent Service dependencies** — Reliability og security risk
### Anbefalte Deployment Sequence
1. **Fase 1 - Single Region MVP:**
- Regional Azure OpenAI (Standard)
- APIM Basic tier (gateway pattern proof)
- AI Search Standard (1 replica)
- Cost: ~10K NOK/måned
2. **Fase 2 - Production Hardening:**
- Upgrade til APIM Standard (circuit breaker)
- AI Search 3 replicas (zone redundancy)
- Add secondary region (warm standby)
- Cost: ~35K NOK/måned
3. **Fase 3 - Enterprise Scale:**
- Azure Front Door (global routing)
- PTU deployment i primary region
- Full hot/hot multi-region
- Cost: ~70K+ NOK/måned
### Monitoring og Alerting
**Kritiske metrics:**
- **Azure OpenAI:** `TotalTokens`, `GeneratedTokens`, `HTTP 429 count`, `Latency P95`
- **APIM:** `Backend response time`, `Failed requests`, `Circuit breaker trips`
- **AI Search:** `Search latency`, `Throttled requests`, `Query volume`
- **Cosmos DB:** `Request units consumed`, `Availability`, `Latency P99`
**Alert thresholds (forslag):**
- HTTP 429 count > 1% av requests → Øk quota eller add fallback region
- APIM backend latency P95 > 5s → Investigate backend health
- AI Search throttled requests > 0 → Scale up replicas/partitions
- Cosmos DB RU utilization > 80% → Scale up RU/s eller enable autoscale
**Application Insights integration:**
- Foundry Agent Service sender automatisk metrics til linked App Insights
- Custom telemetry via SDK for client-side latency tracking
- Correlation ID på tvers av alle komponenter for distributed tracing
---
## Kilder og verifisering
**Microsoft Learn Documentation (offisiell, 2026-02):**
1. [AI Ready - Cloud Adoption Framework](https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/scenarios/ai/ready)
2. [BCDR for Azure OpenAI](https://learn.microsoft.com/en-us/azure/ai-foundry/openai/how-to/business-continuity-disaster-recovery)
3. [Baseline Foundry Chat Architecture](https://learn.microsoft.com/en-us/azure/architecture/ai-ml/architecture/baseline-microsoft-foundry-chat)
4. [Azure API Management - AI Gateway Capabilities](https://learn.microsoft.com/en-us/azure/api-management/genai-gateway-capabilities)
5. [Reliability in Azure AI Search](https://learn.microsoft.com/en-us/azure/reliability/reliability-ai-search)
6. [Multi-Backend Gateway Guide](https://learn.microsoft.com/en-us/azure/architecture/ai-ml/guide/azure-openai-gateway-multi-backend)
7. [Load Balancing Options - Azure Architecture](https://learn.microsoft.com/en-us/azure/architecture/guide/technology-choices/load-balancing-overview)
**GitHub Samples (Microsoft-verified):**
8. [Smart Load Balancing for Azure OpenAI (APIM)](https://github.com/Azure-Samples/openai-apim-lb)
9. [Smart Load Balancing (Container Apps/YARP)](https://github.com/Azure-Samples/openai-aca-lb)
10. [Foundry Baseline Reference Implementation](https://github.com/Azure-Samples/microsoft-foundry-baseline)
**Verifikasjon:**
- ✅ Alle arkitekturdiagrammer basert på Microsoft offisiell dokumentasjon
- ✅ Deployment-typer (Global/Data Zone/Regional/PTU) verifisert mot [Deployment Types](https://learn.microsoft.com/en-us/azure/ai-foundry/foundry-models/concepts/deployment-types)
- ✅ APIM circuit breaker pattern bekreftet i [Backends Documentation](https://learn.microsoft.com/en-us/azure/api-management/backends)
- ✅ Zone redundancy requirements verifisert mot [Availability Zones Overview](https://learn.microsoft.com/en-us/azure/reliability/availability-zones-overview)
**Konfidensgradering - Samlet:** 🟢 **Høy** — Arkitekturmønstre og teknisk implementasjon er basert på Microsoft offisiell dokumentasjon (sist oppdatert januar-februar 2026). Kostestimater er indikative og bør verifiseres mot Azure Pricing Calculator for spesifikke konfigurasjoner.

739
plugins/ms-ai-architect/skills/ms-ai-engineering/references/azure-ai-services/ai-services-governance-compliance.md Normal file
View file

@ -0,0 +1,739 @@
# Azure AI Services - Data Governance and Compliance
**Last updated:** 2026-02
**Status:** GA
**Category:** Azure AI Services (Foundry Tools)
---
## Introduksjon
Data governance og compliance for Azure AI Services handler om å etablere tekniske kontroller som oversetter regulatoriske krav og organisasjonspolicyer til konkrete mekanismer for datahåndtering. Dette omfatter styring av dataaksess, prosessering, lagring, residency, retention og auditlogging.
Azure AI Services (tidligere Cognitive Services) tilbyr innebygde kapabiliteter for å møte både regulatoriske krav (GDPR, HIPAA, ISO-sertifiseringer) og interne governance-policyer. Integrasjon med Microsoft Purview, Azure Policy, Azure Monitor og Key Vault gir en helhetlig styringsmodell som dekker hele datalivssyklusen.
**Primære governance-domener:**
- **Data residency og sovereignty** — kontroll over geografisk lagring og prosessering
- **Data retention og lifecycle** — styring av hvor lenge data lagres
- **Audit logging** — sporbarhet og etterlevelse av compliance-krav
- **Consent management** — brukerstyrt tilgang til personopplysninger
- **Encryption og key management** — sikkerhet for data at rest og in transit
**Verifikasjonsgrad:** Verified (MCP — microsoft-learn januar 2026)
---
## Kjernekomponenter
### 1. Microsoft Purview for AI Governance
Microsoft Purview er den sentrale governance-plattformen for AI-applikasjoner i Azure-økosystemet.
| Kapabilitet | Beskrivelse | AI Services-støtte |
|-------------|-------------|-------------------|
| **Compliance Manager** | Oversetter reguleringer (EU AI Act, GDPR) til tekniske kontroller | ✅ Støttet |
| **Data Security Posture Management (DSPM) for AI** | Oppdager, sikrer og håndhever compliance-kontroller | ✅ Støttet via Foundry |
| **Data Classification** | Identifiserer og tagget sensitiv data i prompts/responses | ✅ Støttet |
| **Sensitivity Labels** | Arver og håndhever merking fra Microsoft 365-data | ✅ Støttet |
| **Data Loss Prevention (DLP)** | Blokkerer deling av sensitiv informasjon til AI-endepunkter | ✅ Støttet (via Entra-registrerte apps) |
| **Audit Logging** | Fanger prompts, responses og filtilganger | ✅ Unified Audit Log |
| **Data Lifecycle Management** | Retention policies for AI-interaksjoner | ✅ Støttet |
| **eDiscovery** | Søk, bevar og eksporter AI-interaksjoner | ✅ Støttet |
**Konfigurering:**
For å aktivere Purview for Azure AI Services (Foundry):
1. **Via Azure AI Foundry Portal** — Aktiver "Microsoft Purview Data Security" i Control Plane
2. **Via Microsoft Defender for Cloud** — Aktiver "Data Security for Azure AI with Microsoft Purview"
**Viktig:** Krever pay-as-you-go billing i Purview (audit logging er inkludert i Purview-lisensen).
### 2. Diagnostic Logging
Azure AI Services genererer rike diagnostikklogger for operasjoner, feilsøking og compliance.
**Log-kategorier:**
| Kategori | Innhold | Bruksområde |
|----------|---------|------------|
| **Audit** | Alle API-kall, autentiseringshendelser | Compliance, sikkerhet |
| **RequestResponse** | Full forespørsel/respons-data (inkl. prompts) | Feilsøking, kostnadsstyring |
| **AllMetrics** | Latency, throughput, feilrater | Ytelsesovervåking |
**Lagringsdestinasjoner:**
- **Azure Storage** — Langtidslagring for compliance (konfigurerbar retention)
- **Log Analytics Workspace** — Sanntidsanalyse med Kusto Query Language (KQL)
- **Event Hub** — Streaming til eksterne SIEM-systemer
**Konfigurasjon:**
```bash
# Via Azure Portal:
# Resource → Monitoring → Diagnostic settings → Add diagnostic setting
# Velg kategorier: Audit, RequestResponse, AllMetrics
# Destinasjon: Storage Account + Log Analytics
```
**KQL-eksempel — Siste 10 AI Services-operasjoner:**
```kusto
AzureDiagnostics
| where ResourceProvider == "MICROSOFT.COGNITIVESERVICES"
| take 10
```
### 3. Data Residency
Azure AI Services lagrer og prosesserer data i den geografiske regionen du velger ved opprettelse av ressursen.
**Residency-garanti:**
- Data lagres **kun i valgt Geography** (eks. Europe, Norway)
- Azure kan replikere innenfor samme Geography for høy tilgjengelighet
- Data forlater **aldri** Geography uten eksplisitt konfigurasjon
**Unntak:**
- **Telemetry logs** (objektnavn som indexer, skillsets) lagres globalt i 1,5 år for Microsoft-support
- **Caching-funksjoner** (Enrichment Cache, Debug Sessions) som bruker Azure Storage i annen region
**Offentlig sektor Norge:**
For norsk offentlig sektor anbefales:
- **Norway East** (primær) + **Norway West** (sekundær) for redundans
- Unngå geo-redundant storage (GRS) som replikerer til andre land
- Bruk **Locally Redundant Storage (LRS)** eller **Zone Redundant Storage (ZRS)**
**Konfigurasjon:**
```bash
# Ved opprettelse av AI Services-ressurs:
Location: "Norway East"
Storage redundancy: "LRS" (ikke GRS)
```
### 4. Data Retention og Lifecycle
**Retention-krav per kategori:**
| Data-type | Standard retention | Justerbar? | Slettemekanisme |
|-----------|-------------------|------------|-----------------|
| **Diagnostic logs** | 90 dager (Log Analytics default) | ✅ 30-730 dager | Automatisk purging |
| **Training data** | Ubegrenset (kundestyrt) | ✅ Ja | Manuell sletting via API |
| **Custom models** | Ubegrenset | ✅ Ja | DELETE-operasjon |
| **Request/response logs** | 0 dager (opt-in) | ✅ Ja | Storage lifecycle policy |
| **Purview-captured interactions** | Definerbart via retention policy | ✅ Ja | Data Lifecycle Management |
**Purview Retention Policy (eksempel):**
```yaml
Policy: "AI Interactions Retention"
Location: Enterprise AI apps
Retention: 7 years (norsk arkivlov)
Action: Delete automatically after period
```
**GDPR-støtte:**
- **Right to erasure** — Slett brukerdata via Azure Management API
- **Right to access** — Eksporter via eDiscovery eller Storage-export
- **Anonymization** — Fjern PII fra logs før langtidslagring
### 5. Consent Management
Azure AI Services støtter ikke innebygd consent management, men integreres med Entra ID og Microsoft Purview for consent tracking.
**Implementasjonsmønster:**
1. **User consent flow** — Autentiser via Entra ID med OAuth2-scopes
2. **Logging av consent** — Lagre consent-hendelser i Application Insights custom events
3. **Consent withdrawal** — Trigger deletion av user-specific data via Management API
**Eksempel (pseudokode):**
```typescript
// 1. Innhent consent ved autentisering
const consentScopes = ["AIService.ReadWrite", "User.Read"];
const token = await msalClient.acquireToken(consentScopes);
// 2. Logg consent-hendelse
appInsights.trackEvent({
name: "UserConsentGranted",
properties: {
userId: token.claims.sub,
scopes: consentScopes,
timestamp: Date.now()
}
});
// 3. Ved withdrawal — slett brukerdata
await aiServiceClient.deleteUserData(userId);
```
### 6. Encryption og Key Management
Azure AI Services krypterer **all data at rest** med Microsoft-managed keys som standard.
**Customer-Managed Keys (CMK):**
Organisasjoner kan bruke egne nøkler fra Azure Key Vault for ekstra kontroll:
| Feature | Microsoft-Managed Keys | Customer-Managed Keys |
|---------|------------------------|----------------------|
| **Encryption at rest** | ✅ Default | ✅ Valgfritt |
| **Key rotation** | Automatisk | Kundekontrollert |
| **Compliance (GDPR, ISO)** | ✅ Ja | ✅ Ja (med ekstra audit trail) |
| **Tilgjengelige regioner** | Alle | Alle |
**Konfigurasjon via Azure Policy:**
```json
{
"policyDefinitionId": "/providers/Microsoft.Authorization/policyDefinitions/67121cc7-ff39-4ab8-b7e3-95b84dab487d",
"displayName": "Azure AI services should enable data encryption with CMK",
"effect": "Audit" // eller "Deny"
}
```
**Key Vault-integrasjon:**
- AI Services bruker **Managed Identity** for autentisering mot Key Vault
- Støtter **automatic key rotation** hvis aktivert i Key Vault
- Keys kan lagres i **HSM-backed** Key Vault for FIPS 140-2 Level 3
---
## Arkitekturmønstre
### Mønster 1: Multi-Region Compliance Architecture
**Scenario:** Global organisasjon med data residency-krav i EU og Norge.
```
┌─────────────────────────────────────────────────────┐
│ Azure Front Door │
│ (Global routing med geo-filtering) │
└───────────────────┬─────────────────────────────────┘
│
┌───────────┴────────────┐
│ │
┌───────▼─────────┐ ┌────────▼────────┐
│ Norway East │ │ West Europe │
│ AI Services │ │ AI Services │
│ (Norge-data) │ │ (EU-data) │
└───────┬─────────┘ └────────┬────────┘
│ │
┌───────▼─────────┐ ┌────────▼────────┐
│ Log Analytics │ │ Log Analytics │
│ Norway East │ │ West Europe │
└───────┬─────────┘ └────────┬────────┘
│ │
└───────────┬───────────┘
▼
┌───────────────────────┐
│ Microsoft Purview │
│ (Central governance) │
└───────────────────────┘
```
**Implementeringsprinsipper:**
1. **Geo-routing** — Front Door router norske IP-er til Norway East
2. **Isolerte workspaces** — Separate Log Analytics per region
3. **Sentralisert policy** — Purview Compliance Manager håndhever samme policy på tvers
### Mønster 2: Zero-Trust Governance Model
**Scenario:** Offentlig sektor med GDPR/Schrems II-krav.
```
┌──────────────────────────────────────────────────┐
│ User (Entra ID + Conditional Access) │
└────────────────────┬─────────────────────────────┘
│
│ (User context token)
▼
┌──────────────────────────────────────────────────┐
│ Azure AI Services (Norway East) │
│ ┌────────────────────────────────────────────┐ │
│ │ Microsoft Purview DLP Policy │ │
│ │ - Block credit cards, SSN │ │
│ │ - Watermark sensitive outputs │ │
│ └────────────────────────────────────────────┘ │
└────────────────────┬─────────────────────────────┘
│
┌───────────┴───────────┐
│ │
┌────────▼─────────┐ ┌────────▼──────────┐
│ Diagnostic Logs │ │ Purview Audit Log │
│ (Log Analytics) │ │ (Unified Audit) │
└────────┬─────────┘ └────────┬──────────┘
│ │
└──────────┬───────────┘
▼
┌───────────────────────┐
│ Microsoft Sentinel │
│ (SIEM + alerting) │
└───────────────────────┘
```
**Implementeringsprinsipper:**
1. **User context enforcement** — AI Services arver brukerens Entra ID-tilganger
2. **Real-time DLP** — Purview blokkerer sensitive prompts før prosessering
3. **Continuous monitoring** — Sentinel analyserer logs for compliance-brudd
### Mønster 3: Hybrid On-Premises/Cloud Governance
**Scenario:** Skjermingsverdige data som ikke kan forlate Norge.
```
┌──────────────────────────────────────────┐
│ On-Premises / Azure Stack HCI │
│ ┌────────────────────────────────────┐ │
│ │ Azure AI Services (Container) │ │
│ │ - Text Analytics, OCR, osv. │ │
│ │ - Ingen data forlater datacenter │ │
│ └────────────────┬───────────────────┘ │
│ │ │
│ ┌────────────────▼───────────────────┐ │
│ │ Local Storage (encrypted) │ │
│ └────────────────────────────────────┘ │
└──────────────────────────────────────────┘
│
│ (Metadata only, no content)
▼
┌──────────────────────────────────────────┐
│ Azure (Norway East) │
│ ┌────────────────────────────────────┐ │
│ │ Microsoft Purview │ │
│ │ - Audit metadata │ │
│ │ - Compliance posture │ │
│ └────────────────────────────────────┘ │
└──────────────────────────────────────────┘
```
**Implementeringsprinsipper:**
1. **Containerized deployment** — Azure AI Services i Docker/Kubernetes on-prem
2. **Air-gapped content** — Kun metadata (ikke innhold) sendes til Azure
3. **Hybrid governance** — Purview mottar compliance-telemetri, ikke brukerdata
---
## Beslutningsveiledning
### Når bør du bruke Customer-Managed Keys?
| Scenario | Microsoft-Managed Keys | Customer-Managed Keys |
|----------|------------------------|----------------------|
| Offentlig sektor (Norge) | ⚠️ Mulig, men vurder CMK | ✅ Anbefalt (audit trail) |
| GDPR/HIPAA-regulert | ✅ Tilstrekkelig | ✅ Økt kontroll |
| Finansielle data | ⚠️ Vurder risikoappetitt | ✅ Anbefalt |
| Proof-of-Concept | ✅ Enklere oppsett | ❌ Unødvendig kompleksitet |
**Kostnad:** CMK har ingen ekstra Azure AI Services-kostnad, men Key Vault faktureres separat (~$0.03 per 10 000 operasjoner).
### Hvordan velge Diagnostic Log Retention?
```
┌─────────────────────────────────────────────────┐
│ Compliance-krav? │
│ → GDPR: 6-7 år │
│ → Arkivloven (Norge): 7 år │
│ → Helsedata: 10 år │
└───────────────────┬─────────────────────────────┘
│
┌───────────┴────────────┐
│ │
┌───────▼─────────┐ ┌────────▼──────────┐
│ Hot tier │ │ Cool tier │
│ Log Analytics │ │ Azure Storage │
│ 30-90 dager │ │ 1-10 år │
│ $2.30/GB │ │ $0.01/GB/måned │
└─────────────────┘ └───────────────────┘
```
**Anbefaling:**
- **0-90 dager:** Log Analytics (rask KQL-søk)
- **90 dager - 7 år:** Azure Storage Cool tier (compliance)
- **Kostnadskontroll:** Filtrer bort høyfrekvente metrics før lagring
### DLP Policy for AI Services — Hva blokkere?
| Data-type | Anbefaling | Purview-konfigurasjon |
|-----------|------------|----------------------|
| **Norske personnummer (11 siffer)** | ✅ Blokker | Custom SIT: `[0-9]{11}` |
| **Kredittkortnummer** | ✅ Blokker | Built-in SIT: Credit Card |
| **E-postadresser** | ⚠️ Vurder context | Built-in SIT: Email Address |
| **Passordhint** | ✅ Blokker | Custom keyword list |
| **Sensitive filreferanser** | ✅ Blokker hvis encrypted | Sensitivity Label check |
**Konfigurasjon (PowerShell):**
```powershell
# Opprett DLP-regel for Entra-registrert AI app
New-DlpComplianceRule -Name "BlockPIIInAIPrompts" `
-Policy "AIServicesDLP" `
-BlockAccess $true `
-ContentContainsSensitiveInformation @(
@{Name="Norway National ID Number"; minCount=1},
@{Name="Credit Card Number"; minCount=1}
) `
-Workload "ThirdPartyApps" `
-AppId "<Entra-app-id-for-AI-service>"
```
---
## Integrasjon med Microsoft-stakken
### Azure AI Foundry
Azure AI Foundry (tidligere Azure AI Studio) er den moderne plattformen for AI-utvikling, med førsteklasses governance-integrasjon.
**Purview-aktivering:**
1. **Foundry Portal** → Control Plane → Security & Compliance → Enable Microsoft Purview Data Security
2. **Resultater:**
- Prompts/responses fanges i Unified Audit Log
- Klassifisering av sensitive data i Activity Explorer
- Retention policies håndterer AI-interaksjoner
**Agent Identity Management:**
Foundry støtter Microsoft Entra Agent Identity for unik identifisering av AI-agenter:
```yaml
Agent Identity:
Name: "customer-support-bot-prod"
Owner: "platform-team@contoso.no"
Version: "2.1.0"
Lifecycle: "Production"
Entra ID: "a1b2c3d4-..."
```
**Observability:**
- **Agent 365** — Sentralisert visning av alle AI-agenter i organisasjonen
- **Dashboards** — Real-time metrics for token-forbruk, latency, feilrater
- **Cost Management** — Allokering av AI-kostnader per avdeling/prosjekt
### Microsoft 365 Copilot
AI Services kan integreres med M365 Copilot-data ved å respektere sensitivity labels:
**Scenario:** RAG-basert AI-agent som søker i SharePoint-dokumenter.
1. **Sensitivity label enforcement** — Hvis dokument er merket "Confidential", krever AI EXTRACT-rett
2. **User permission inheritance** — AI arver brukerens SharePoint-tilganger
3. **Audit trail** — Purview logger hvilke dokumenter AI aksesserte
**Konfigurasjon:**
```yaml
# Azure AI Search index med Purview-integrasjon
Index: "sharepoint-docs"
Data source: SharePoint Online
Security trimming: Enabled (AAD-based)
Sensitivity label: Enforced (EXTRACT required)
```
### Power Platform
Power Platform AI Builder bruker samme Purview-infrastruktur.
**DLP Policies for Power Platform:**
```yaml
Environment: "Production"
Connector: Azure OpenAI
Policy: "Block high-risk data"
Rules:
- Block if prompt contains Credit Card Number
- Warn if response includes Email Address
```
---
## Offentlig sektor (Norge)
### Juridiske rammeverk
| Lov/regelverk | Relevans for AI Services | Teknisk tiltak |
|---------------|--------------------------|----------------|
| **Personopplysningsloven (GDPR)** | Behandling av personopplysninger | Data residency Norway, CMK, DLP |
| **Arkivloven** | 7 års oppbevaringsplikt | Retention policies, Storage lifecycle |
| **Sikkerhetsloven** | Sikkerhetsgradert informasjon | Air-gapped deployment (Azure Stack) |
| **Schrems II** | Dataoverføring til USA | Norway-only regions, no US support access |
### Anbefalt konfigurasjon for offentlig sektor
```yaml
AI Services Configuration (Norway Public Sector):
Region: Norway East
Backup region: Norway West
Storage redundancy: ZRS (Zone Redundant, ikke GRS)
Encryption: Customer-Managed Keys (Azure Key Vault Norway)
Diagnostic logs:
Destination: Log Analytics (Norway East)
Retention: 7 years (Arkivloven)
Categories: Audit, RequestResponse
Purview:
DLP policies: Block personnummer, kredittkortnummer
Sensitivity labels: Enforce EXTRACT right
Retention: 7 years
Network:
Public access: Disabled
Private endpoint: Enabled (VNet-integration)
Firewall: Restrict to public sector IP ranges
Support:
Microsoft support access: Disabled (Lockbox not approved)
Telemetry: Object names only (no content)
```
### Data Processor Agreement (DPA)
Microsoft tilbyr standard DPA for Azure-tjenester:
- **EU Model Clauses** — Godkjent mekanisme for dataoverføring
- **ISO 27018** — Sertifisering for personvern i cloud
- **Compliance Manager** — Dokumentasjon for revisor
**Dokumenter:**
- [Microsoft Products and Services DPA](https://aka.ms/DPA)
- [Azure Compliance Documentation](https://learn.microsoft.com/en-us/azure/compliance/)
### Risiko og avbøtende tiltak
| Risiko | Sannsynlighet | Konsekvens | Avbøtende tiltak |
|--------|---------------|------------|------------------|
| Data leaks til USA | Lav | Høy | Norway-only regions, disable telemetry |
| Uautorisert tilgang | Medium | Høy | Private endpoints, Entra Conditional Access |
| Manglende audit trail | Lav | Medium | Purview Unified Audit Log, 7-års retention |
| Support-tilgang til data | Lav | Høy | Disable Microsoft support access (Customer Lockbox) |
---
## Kostnad og lisensiering
### Azure AI Services Pricing (Compliance-relatert)
| Komponent | Kostnad | Faktureringsmodell |
|-----------|---------|-------------------|
| **AI Services (API-kall)** | Varierer per service | Per transaksjon/token |
| **Diagnostic logs (Log Analytics)** | $2.30/GB | Data ingestion + retention |
| **Azure Storage (Cool tier)** | $0.01/GB/måned | Lagring + operasjoner |
| **Key Vault (CMK)** | $0.03 per 10 000 ops | Per nøkkeloperasjon |
| **Private Endpoint** | $0.01/time | Per endepunkt |
**Purview-kostnader:**
| Feature | Lisens | Pay-as-you-go |
|---------|--------|---------------|
| **Audit (Unified Log)** | ✅ Inkludert | — |
| **DLP Policies** | ❌ Krever E5/F5 | ✅ $2 per user/måned |
| **Sensitivity Labels** | ❌ Krever E3/E5 | ✅ $1 per user/måned |
| **DSPM for AI** | ❌ Ikke i standard lisens | ✅ $5 per AI app/måned |
**Kostnadsoptimalisering:**
1. **Filtrer metrics** — Ikke logg høyfrekvente metrics som ikke trengs for compliance
2. **Cool tier migration** — Flytt logs > 90 dager til Azure Storage Cool tier
3. **Sampling** — Bruk Application Insights sampling (eks. 10% av requests) for ikke-compliance-logs
### Lisensiering for compliance-features
**Microsoft 365:**
- **E3** — Sensitivity labels, basis DLP
- **E5** — Avansert DLP, Insider Risk Management, eDiscovery
- **F5** — Frontline workers med DLP
**Azure:**
- **Azure AI Services** — Ingen ekstra lisens for governance-features (betaler kun for API-bruk)
- **Microsoft Purview** — Pay-as-you-go eller inkludert i M365 E5
**Anbefaling for offentlig sektor:**
- **Minimum:** Azure AI Services + Purview pay-as-you-go (DLP + Audit)
- **Anbefalt:** M365 E5 (full compliance-suite) + Azure AI Services
---
## For arkitekten (Cosmo)
### Sentrale beslutningspunkter
**1. Data residency-valg:**
**Spørsmål til kunden:**
- "Har dere juridiske krav til at data ikke kan forlate Norge?"
- "Er data klassifisert som sikkerhetsgradert (konfidensielt/hemmelig)?"
**Avgjørelsestre:**
```
Sikkerhetsgradert data?
├─ Ja → Azure Stack HCI (on-premises) eller Azure Government
└─ Nei → Norway East + Norway West
├─ GDPR/Schrems II-bekymringer?
│ ├─ Ja → Disable telemetry, CMK, Private endpoints
│ └─ Nei → Standard konfigurasjon OK
└─ Kostnadsoptimalisering?
├─ Ja → West Europe (billigere, men EU-residency)
└─ Nei → Norway East (best latency)
```
**2. Logging og retention:**
**Spørsmål til kunden:**
- "Hvor lenge må dere oppbevare audit logs? (Arkivloven sier 7 år)"
- "Trenger dere real-time alerting på compliance-brudd?"
**Anbefalinger:**
- **Offentlig sektor:** 7 år retention i Azure Storage Cool tier
- **Privat sektor (GDPR):** 6 år retention (etter oppbevaringsplikt)
- **Real-time alerting:** Log Analytics + Microsoft Sentinel
**3. DLP-konfigurasjon:**
**Spørsmål til kunden:**
- "Hvilke datatyper er mest kritiske å beskytte? (Personnummer, helseopplysninger, etc.)"
- "Skal AI-tjenesten blokkere eller bare advare ved sensitiv data?"
**Konfigurasjonsmønster:**
```yaml
DLP Strategy:
Phase 1 (Audit):
Action: Log only
Duration: 30 days
Goal: Forstå datamønstre
Phase 2 (Warn):
Action: User warning (can override)
Duration: 60 days
Goal: Brukeropplæring
Phase 3 (Block):
Action: Hard block
Goal: Håndheve compliance
```
### Vanlige fallgruver og løsninger
| Fallgruve | Symptom | Løsning |
|-----------|---------|---------|
| **Telemetry til USA** | Object names (index names) lagres i USA | Ikke bruk sensitive navn i Azure-ressurser |
| **GRS replikerer til annet land** | Data kopieres til paired region utenfor Norge | Bruk LRS eller ZRS for Norge-only |
| **Manglende audit trail** | Ingen logs i Purview | Aktiver Diagnostic Settings + Purview Data Security |
| **Support får tilgang til data** | Microsoft support kan se data ved tickets | Disable support access via Customer Lockbox |
| **Høye Log Analytics-kostnader** | $1000+ per måned for small-scale | Filtrer bort verbose metrics, bruk Storage Cool tier |
### Sjekkliste før produksjonsdeploy
**Governance & Compliance Checklist:**
```markdown
□ Region valgt (Norway East for offentlig sektor)
□ Storage redundancy satt til LRS/ZRS (ikke GRS)
□ Customer-Managed Keys konfigurert (hvis påkrevd)
□ Diagnostic Logging aktivert (Audit + RequestResponse)
□ Log Analytics Workspace opprettet (Norway East)
□ Retention policy satt (7 år for Arkivloven)
□ Microsoft Purview Data Security aktivert
□ DLP policies opprettet og testet
□ Sensitivity labels konfigurert (hvis M365-integrasjon)
□ Private Endpoint aktivert (disable public access)
□ Network firewall rules konfigurert
□ Entra Conditional Access policies applied
□ Audit log-søk testet (verifiser data fanges)
□ eDiscovery-eksport testet (verifiser GDPR-slettingsevne)
□ Kostnadsvarsler satt (budsjettmål)
□ Dokumentasjon for revisor ferdigstilt
□ Data Processor Agreement signert (DPA)
```
### Kommunikasjon med interessenter
**For juridisk avdeling:**
"Azure AI Services er GDPR-compliant ut av boksen, men krever konfigurasjon for Norge-spesifikke krav. Vi anbefaler Norway East-region med Customer-Managed Keys og 7 års audit log retention for å møte Arkivloven. Microsoft tilbyr standard Data Processor Agreement (DPA) med EU Model Clauses."
**For økonomiavdeling:**
"Compliance-funksjoner som audit logging og encryption er inkludert i Azure AI Services-prisen. Microsoft Purview DLP koster ca. $2 per bruker per måned (pay-as-you-go). Log retention i Azure Storage Cool tier koster ca. $0.01 per GB per måned. Estimert totalkostnad for governance: 5-10% av total AI Services-kostnad."
**For sikkerhetsavdeling:**
"Vi konfigurerer Private Endpoints (ingen public internet access), Customer-Managed Keys (full nøkkelkontroll), og real-time DLP-blokkering av personnummer. All aktivitet logges til Microsoft Purview Unified Audit Log med 7 års retention. Microsoft Sentinel kan alertere ved avvik. Support-tilgang fra Microsoft kan deaktiveres via Customer Lockbox."
### Ytterligere ressurser
**For dypdykk i spesifikke områder:**
- **Data residency-detaljer** → Les `data-residency-sovereignty.md` (når tilgjengelig)
- **Audit logging-patterns** → Les `audit-logging-patterns.md` (når tilgjengelig)
- **Encryption og key management** → Les `encryption-key-management.md` (når tilgjengelig)
**Eksterne lenker:**
- [Microsoft Trust Center — Azure Compliance](https://www.microsoft.com/en-us/trust-center/compliance/compliance-overview)
- [Azure compliance documentation](https://learn.microsoft.com/en-us/azure/compliance/)
- [Microsoft Purview documentation](https://learn.microsoft.com/en-us/purview/)
---
## Kilder og verifisering
**Verifikasjonsmetode:** Microsoft Learn MCP (microsoft-learn) januar 2026
**Primærkilder (Verified):**
1. **Governance and security for AI agents across the organization**
https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ai-agents/governance-security-across-organization
*Sist bekreftet: 2026-02*
2. **Use Microsoft Purview to manage data security & compliance for Microsoft Foundry**
https://learn.microsoft.com/en-us/purview/ai-azure-services
*Sist bekreftet: 2026-02*
3. **Enable diagnostic logging for Azure AI services**
https://learn.microsoft.com/en-us/azure/ai-services/diagnostic-logging
*Sist bekreftet: 2026-02*
4. **Azure, Dynamics 365, and Power Platform accountability readiness checklist for GDPR**
https://learn.microsoft.com/en-us/compliance/regulatory/gdpr-arc-azure-dynamics
*Sist bekreftet: 2026-02*
5. **Govern Azure platform services (PaaS) for AI**
https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/scenarios/ai/platform/governance
*Sist bekreftet: 2026-02 (via search)*
6. **Azure security baseline for Azure AI services**
https://learn.microsoft.com/en-us/security/benchmark/azure/baselines/cognitive-services-security-baseline
*Sist bekreftet: 2026-02 (via search)*
**Sekundærkilder (Baseline-kunnskap, verifisert mot MCP-søk):**
- Azure Policy for AI Services
- Microsoft Purview Compliance Manager
- Azure Monitor og Log Analytics
- Key Vault integration
- Data residency commitments (Azure global infrastructure)
**Confidence-gradering:**
- ✅ **Verified** — Bekreftet via MCP microsoft-learn dokumentasjon (januar 2026)
- ⚠️ **Baseline** — Basert på modellkunnskap, ingen motstridende MCP-data funnet
**Total antall MCP-kall:** 8 (4 docs_search + 4 docs_fetch)
**Unike kilder:** 6 primærkilder + 4 sekundærkilder fra søk
**Sist oppdatert:** 2026-02-03

569
plugins/ms-ai-architect/skills/ms-ai-engineering/references/azure-ai-services/ai-services-monitoring-logging.md Normal file
View file

@ -0,0 +1,569 @@
# Azure AI Services - Monitoring, Logging and Diagnostics
**Last updated:** 2026-02
**Status:** GA
**Category:** Azure AI Services (Foundry Tools)
---
## Introduksjon
Monitoring, logging og diagnostikk er kritiske komponenter for å drive Azure AI-løsninger i produksjon. Azure Monitor-plattformen gir omfattende innsikt i ytelse, tilgjengelighet, kostnader og feilsituasjoner for alle Azure AI Services (tidligere Cognitive Services).
Denne kunnskapsreferansen dekker:
- Azure Monitor-integrasjon for AI Services (inkludert Azure OpenAI)
- Diagnostic settings og log-konfigurasjon
- Application Insights for applikasjonsnivå-observabilitet
- Kusto Query Language (KQL) for log-analyse
- Alerts, metrics og dashboards
- Cost tracking og budsjett-varsling
**Verdi for arkitekten:**
Strukturert overvåkning sikrer at AI-løsninger ikke bare fungerer ved lansering, men kan opereres, feilsøkes og optimaliseres over tid. Tidlig etablering av monitoring-strategi reduserer MTTR (Mean Time To Recovery) dramatisk.
---
## Kjernekomponenter / Nøkkelegenskaper
### 1. Azure Monitor Platform
**Tre datalagringsmodeller:**
- **Platform metrics** – numeriske tidsserie-data samlet automatisk, lagres i Azure Monitor metrics database
- **Resource logs** – detaljert operasjonslogging (må aktiveres via diagnostic settings)
- **Activity log** – subscription-level hendelser (automatisk samlet, separat lager)
**Datainnsamling for Azure AI Services:**
| Data Type | Automatisk? | Konfigurasjon | Bruk |
|-----------|------------|---------------|------|
| Platform Metrics | Ja | Ingen | Real-time dashboards, alerts |
| Resource Logs | Nei | Diagnostic settings påkrevd | Post-mortem analyse, compliance |
| Activity Log | Ja | Ingen | Kontrollplan-operasjoner (create/delete) |
**Viktig distinksjon:**
- **Control plane** – Azure Resource Manager-operasjoner (opprettelse av ressurser, endring av SKU)
- **Data plane** – faktisk AI-tjeneste-bruk (API-kall, token-bruk, latency)
### 2. Diagnostic Settings (Nøkkelkonfigurasjon)
Diagnostic settings er obligatorisk for å samle resource logs.
**Konfigurasjon via Azure Portal:**
1. Naviger til Azure AI Services-ressursen
2. **Monitoring → Diagnostic settings → Add diagnostic setting**
3. Gi beskrivende navn (eks: "my-openai-all-logs")
4. Velg log-kategorier:
- **Audit** – bruker/app-interaksjoner med data
- **RequestResponse** – detaljer om API-requests
- **Trace** – kun for Custom Question Answering
- **AllLogs** – alt (start her, reduser deretter)
5. Velg destinasjon:
- **Log Analytics workspace** (anbefalt for KQL-queries)
- **Azure Storage** (langvarig arkivering, compliance)
- **Event Hubs** (strømming til eksterne systemer)
6. **Save**
**Kritisk merknad:**
> Verbose logging kan være kostbart å lagre. Start med **allLogs** for å forstå volumet, deretter switch til mer skopede kategorier.
**ResourceProvider-identifikator:**
Azure AI Services rapporterer med `ResourceProvider == "MICROSOFT.COGNITIVESERVICES"` i AzureDiagnostics-tabellen.
### 3. Log Analytics Workspace
**Lagringssted for strukturert log-analyse:**
- Kusto Query Language (KQL) for ad-hoc queries
- Pre-built queries tilgjengelig i portal
- Integrerer med Power BI, Grafana, Azure Dashboards
**Typiske tabeller:**
- `AzureDiagnostics` – resource logs fra AI Services
- `AzureMetrics` – metrics eksportert via diagnostic settings
- `AzureActivity` – activity log (hvis routet)
**Kostnadsstyring:**
Log Analytics har eget prisingmodell basert på:
- Data ingestion (per GB)
- Data retention (90 dager gratis, deretter betalt)
### 4. Application Insights (Applikasjonsnivå)
**For dypere applikasjons-observabilitet:**
- OpenTelemetry-kompatibel APM (Application Performance Monitoring)
- End-to-end transaction tracing
- Client-side telemetri (JavaScript SDK)
- AI agent monitoring (Azure AI Foundry, Copilot Studio)
**Sentrale views:**
| View | Formål |
|------|--------|
| Application Map | Visuell oversikt over arkitektur og avhengigheter |
| Live Metrics | Real-time dashboard (1-2 sek latency) |
| Failures View | Exception tracking, HTTP error rates |
| Performance View | Latency analyse, dependency duration |
| Agents View | Spesialisert for AI agents (token usage, cost per session) |
**Når bruke Application Insights vs. Diagnostic Logs:**
- **Application Insights** → utviklere som bygger applikasjoner (custom events, distributed tracing)
- **Diagnostic Logs** → platform-operatører som overvåker infrastruktur (API call volumes, errors)
**Integrasjon:**
Application Insights kan kobles til Azure AI Services via:
- Connection string i app settings (`APPLICATIONINSIGHTS_CONNECTION_STRING`)
- Microsoft Entra ID-autentikasjon (anbefalt for prod)
### 5. Alerts (Proaktiv varsling)
**Alert-typer:**
- **Metric alerts** – kontinuerlig evaluering av metrics (eks: "token rate > 10 000/min i 5 min")
- **Log alerts** – KQL-basert, evaluerer logs ved intervaller (eks: "mer enn 10 failures i 1 min")
- **Activity log alerts** – trigger på ARM-operasjoner (eks: "noen slettet en ressurs")
**Best practice:**
> Alerts skal være actionable. Hvis ingen respons er nødvendig, bruk rapporter i stedet.
**Vanlige alert-scenarioer for AI Services:**
- Token rate nærmer seg quota limit
- Error rate overstiger terskel (eks: 429 Too Many Requests)
- Latency overskrider SLA (eks: P95 > 2 sekunder)
- Absence of expected log events (ingen heartbeat på 10 min)
**Action groups:**
Alerts kan trigge:
- Email, SMS, push notifications
- Azure Functions, Logic Apps (automation)
- ITSM-integrasjoner (ServiceNow, etc.)
- Webhooks
---
## Arkitekturmønstre
### Pattern 1: Centralized Monitoring Hub
**Scenario:** Enterprise med mange AI Services på tvers av subscriptions/resource groups.
**Design:**
- Ett sentralt Log Analytics workspace per miljø (dev/test/prod)
- Diagnostic settings på alle AI Services router til samme workspace
- Azure Monitor Workbooks for konsistente dashboards
- Shared alert rules via Azure Policy
**Fordeler:**
- Cross-resource correlation (finn patterns på tvers av tjenester)
- Sentralisert RBAC for monitoring
- Kostnadseffektivt (volume discounts på Log Analytics ingestion)
**Ulemper:**
- Kan bli "noisy" workspace hvis ikke filtrert riktig
- Må bruke resource-tagging for å skille workloads
### Pattern 2: Per-Application Isolation
**Scenario:** Multitenancy eller streng data-separasjon (offentlig sektor).
**Design:**
- Dedikert Log Analytics workspace per applikasjon/kunde
- Application Insights per applikasjon
- Separate alert action groups
**Fordeler:**
- Data isolation (compliance-vennlig)
- Enklere cost chargeback til business units
- Redusert risiko for data leakage
**Ulemper:**
- Høyere forvaltningskostnad (mange workspaces å vedlikeholde)
- Vanskeligere å se trender på tvers av applikasjoner
### Pattern 3: Hot/Cold Tiering
**Scenario:** Langvarig compliance-krav, men begrenset behov for interaktive queries.
**Design:**
- **Hot tier (Log Analytics)** – siste 30 dager, KQL-queries
- **Cold tier (Azure Storage)** – 1-7 år, batch-analyse
- Diagnostic settings sender til både destinations
**Fordeler:**
- Compliance med arkiveringskrav (GDPR Article 17, etc.)
- Dramatisk reduserte kostnader (Storage vs. Log Analytics)
- Kan re-hydrate data til Log Analytics ved behov
**Ulemper:**
- Mer kompleks konfigurasjon
- Queries mot cold storage krever separat pipeline (Azure Data Explorer, Synapse)
### Pattern 4: Azure API Management Gateway
**Scenario:** Mange applikasjoner som deler samme Azure OpenAI-instans.
**Design:**
- APIM som unified gateway foran Azure OpenAI
- APIM logger til egen Application Insights
- Correlation-ID propageres fra APIM til backend AI Service
- Rate limiting og token quotas håndteres i APIM
**Fordeler:**
- Granular logging per consumer (app, team, subscription key)
- Sentralisert rate limiting og cost tracking
- Abstraherer backend-endringer fra consumers
**Monitoring-perspektiv:**
- APIM metrics viser consumer-side latency
- AI Services metrics viser backend-side latency
- Differanse indikerer APIM overhead eller network issues
---
## Beslutningsveiledning
### Når velge Log Analytics vs. Storage?
| Kriterium | Log Analytics | Azure Storage |
|-----------|---------------|---------------|
| **Interaktive queries (< 5 min respons)** | ✅ Ja | ❌ Nei (batch) |
| **Real-time alerts** | ✅ Ja | ❌ Nei |
| **Retention > 2 år** | ⚠️ Dyrt | ✅ Ja |
| **Compliance-arkivering** | ⚠️ Mulig | ✅ Anbefalt |
| **Kostnad for 100 GB/dag** | ~$230/mnd (30 dager) | ~$2/mnd (cool tier) |
**Anbefaling:**
Start med Log Analytics for operational monitoring (30-90 dager). Legg til Storage hvis compliance krever lengre retention.
### Når bruke Application Insights?
**Bruk Application Insights hvis:**
- Du bygger en custom applikasjon på toppen av Azure AI Services
- Du trenger end-to-end transaction tracing (fra frontend → API → AI Service → database)
- Du ønsker client-side telemetri (JavaScript i browser)
- Du bygger AI agents (Azure AI Foundry, Copilot Studio)
**Ikke nødvendig hvis:**
- Du kun kjører pre-built AI Services uten custom app-logikk
- Du kun trenger infra-metrics (API call volumes, error rates)
### Metric Alerts vs. Log Alerts?
| Alert Type | Bruk når... | Latency | Cost |
|------------|-------------|---------|------|
| **Metric** | Data finnes som metric (token count, latency) | ~1 min | Lavere |
| **Log** | Trenger aggregasjon/grouping (errors per container ID) | ~5 min | Høyere |
**Regel:** Bruk metrics når mulig. Bruk log alerts kun for komplekse patterns som ikke finnes som metrics.
### Retention Policy
**Log Analytics retention-strategi:**
- **30 dager** – hot data, ingen ekstra kostnad
- **90 dager** – operational troubleshooting (anbefalt minimum)
- **1-2 år** – compliance for de fleste use cases (offentlig sektor: Noark-5)
- **7 år** – finansielle data (bokføringslov)
**Konfigurasjon:**
Portal → Log Analytics workspace → Usage and estimated costs → Data retention
---
## Integrasjon med Microsoft-stakken
### Azure OpenAI-spesifikt
**Out-of-box dashboards i Azure AI Foundry:**
- **HTTP Requests** – request count, error rates
- **Tokens-Based Usage** – prompt tokens, completion tokens, total tokens
- **PTU Utilization** – Provisioned Throughput Unit-bruk (for provisioned deployments)
- **Fine-tuning** – training job metrics
**Viktige metrics for Azure OpenAI:**
| Metric | Hva det måler | Alert threshold (eksempel) |
|--------|---------------|----------------------------|
| `TokenTransaction` | Totalt antall tokens brukt | > 1M tokens/time |
| `GeneratedTokens` | Completion tokens | Trend analysis (spot unintended usage) |
| `ProcessedPromptTokens` | Input tokens | Spike detection (data leak?) |
| `ActiveTokens` (PTU) | Concurrent token processing | > 80% capacity |
| `Requests` | API call count | > 10 000/min (nær rate limit) |
| `Http429` | Throttled requests | > 10/min (scaling needed) |
**KQL-query for token cost estimation:**
```kusto
AzureDiagnostics
| where ResourceProvider == "MICROSOFT.COGNITIVESERVICES"
| where OperationName == "Generate Completion"
| extend tokens = toint(properties_s.tokens)
| summarize TotalTokens = sum(tokens) by bin(TimeGenerated, 1h)
| extend EstimatedCostNOK = TotalTokens * 0.0002 // Eksempel pricing
```
### Power Platform AI
**Dynamics 365 og Power Apps med Application Insights:**
- Enable via **Monitoring** → **Application Insights**
- `customDimensions`-feltet inneholder Power Platform-spesifikke properties
- User-identitet **ikke** logget (privacy by default)
**Typiske queries:**
```kusto
pageViews
| where cloud_RoleInstance == "CDS Data Export"
| where session_Id == "[insert session id]"
```
### Microsoft 365 Copilot
**Monitoring via Microsoft 365 Admin Center:**
- Copilot usage dashboards (aggregert, ikke detaljert logging)
- Vipps-integrasjon via Graph API (for custom dashboards)
**Application Insights for Copilot Studio:**
Copilot Studio-bottar kan kobles til Application Insights for:
- Conversation analytics
- LUIS intent recognition performance
- QnA Maker query latency
---
## Offentlig sektor (Norge)
### Compliance-krav
**Noark-5 (Offentlig arkivlov):**
- Hendelseslogging av alle operasjoner som involverer personopplysninger
- Minimum 10 års oppbevaringstid (visse kategorier)
- Integritetsikring (checksums, immutable storage)
**GDPR Article 30 (Behandlingsprotokoll):**
- Logging av hvem som har aksessert persondata
- Azure AI Services logger **ikke** individual user identity by default
- Må implementeres i klient-applikasjon (custom logging)
**Implementasjonsstrategi:**
1. **Resource logs** → Log Analytics (90 dager)
2. **Export to Storage** (Immutable Blob Storage, 10 år)
3. **Client-side logging** (custom Event Hubs → SIEM)
### Schrems II og dataresidency
**Challenge:**
Diagnostic logs lagres i Log Analytics workspace. Workspace må være i Norge (Norway East/West) for å sikre data residency.
**Verifisering:**
Portal → Log Analytics workspace → Properties → Location = "Norway East"
**Viktig:**
Selv om AI Service-ressursen er i Norge, kan Log Analytics workspace være i annen region hvis ikke eksplisitt konfigurert.
### Sikkerhetstiltak
**Private Link for Log Analytics:**
- Azure Monitor Private Link Scope (AMPLS) sikrer at logs ikke traverserer public internet
- Påkrevd for data classification "Begrenset" eller høyere
**Customer-Managed Keys (CMK):**
Log Analytics støtter CMK for encryption at rest. Relevant for "Strengt fortrolig" data.
**Konfigurasjon:**
Portal → Log Analytics workspace → Properties → Customer-managed key
---
## Kostnad og lisensiering
### Prismodell for Azure Monitor
**Log Analytics:**
- **Pay-as-you-go** – $2.76/GB ingested (Norway East, jan 2026)
- **Commitment Tiers** – 100 GB/day ($196/mnd), 200 GB/day ($360/mnd)
- **Data retention** – 90 dager gratis, deretter $0.12/GB/måned
**Application Insights:**
- Basert på data ingestion (samme som Log Analytics)
- 5 GB/måned gratis per subscription
**Alerts:**
- Metric alerts: $0.10 per metric signal per måned
- Log alerts: $0.20 per evaluation per måned
- Email/SMS notifications: varierer (100 emails gratis/mnd)
**Kostnadsoptimalisering:**
1. **Filtrer bort støy** – bruk diagnostic setting categories strategisk
2. **Sampling** – Application Insights adaptive sampling (default 5 items/sec)
3. **Data export** – export til Storage for langvarig retention
4. **Workspace design** – konsolider workspaces for volume discounts
### Estimert kostnad for typisk Azure OpenAI deployment
**Scenario:** 1 million API-kall per måned, 500 tokens gjennomsnitt per request.
**Log volume-estimat:**
- Per request log entry: ~2 KB
- Daglig volume: (1 000 000 / 30) * 2 KB = ~67 GB/måned
- Log Analytics cost: 67 GB * $2.76 = **~$185/måned**
**Optimalisering:**
Hvis kun interessert i errors og high-latency requests:
- Filtrer ut successful requests < 1 sek latency
- Redusert volume: ~10 GB/måned → **~$28/måned**
### Lisensiering
**Ingen separate lisenser påkrevd:**
Azure Monitor-funksjoner er inkludert i Azure-subscription. Betaler kun for ressursforbruk (data ingestion, retention).
**Unntak:**
Hvis du bruker ITSM-integrasjoner (ServiceNow, etc.) via Action Groups, kan det påløpe kostnader fra ITSM-leverandør per ticket.
---
## For arkitekten (Cosmo)
### Pre-emptive troubleshooting
**Red flags å se etter i monitoring data:**
1. **Økende latency uten økende load:**
- Indikerer backend-degradering (model hosting issues)
- **Action:** Kontakt Azure Support, vurder multi-region failover
2. **Spike i 429-errors:**
- Rate limit hit (TPM/RPM quota)
- **Action:** Øk quota, implementer retry-logikk, vurder PTU
3. **Plutselig drop i request volume:**
- Potensielt auth-problem (expired keys, RBAC-endringer)
- **Action:** Sjekk Activity Log for endringer i IAM
4. **Uforholdsmessig høy token usage:**
- Mulig prompt injection attack eller dataleakage
- **Action:** Analysér request payloads, implementer input validation
### Arkitektur-anbefalinger
**For proof-of-concept:**
- Start med Diagnostic Settings → Log Analytics (allLogs)
- Basic metric alerts (error rate, latency)
- Manuell review i portal (ingen automation)
**For pilot (begrenset prod):**
- Application Insights hvis custom app
- Alert action groups (email til team)
- Weekly review av dashboards
**For full produksjon:**
- Comprehensive alert coverage (metrics + logs)
- Action groups med PagerDuty/OpsGenie-integrasjon
- Runbooks for vanlige failure scenarios
- Grafana dashboards for NOC/SOC
- Automated cost reports (Power BI + Log Analytics export)
**For regulert miljø (offentlig sektor):**
- Private Link (AMPLS) obligatorisk
- Customer-Managed Keys for Log Analytics
- Immutable Storage for compliance logs (10 år+)
- Quarterly audit reports fra Log Analytics queries
### Diskusjonspunkter med stakeholders
**Med utviklerteam:**
> "Hva er akseptabel MTTR (Mean Time To Recovery) for denne løsningen? Dette bestemmer hvor mye vi investerer i monitoring og alerting."
**Med InfoSec:**
> "Hvilke logs må vi bevare for compliance, og hvor lenge? Dette påvirker arkitekturvalg (Log Analytics vs. Storage)."
**Med FinOps:**
> "Monitoring kan koste 5-15% av total AI Services-kostnad. Hvilke trade-offs er vi villige til å gjøre?"
**Med business:**
> "Hvis AI-tjenesten går ned, hvor raskt må vi vite om det, og hva er konsekvensen av 10 min vs. 1 time downtime?"
### Decision-making framework
**Spørsmål å stille:**
1. **Hva er SLA-kravet?**
- 99.9% (43 min/mnd) → Basic alerts holder
- 99.99% (4 min/mnd) → Trenger real-time monitoring (Live Metrics)
2. **Hva er dataklassifisering?**
- Åpen/Intern → Standard Log Analytics
- Begrenset → Private Link
- Strengt fortrolig → Private Link + CMK
3. **Hvor mange AI Services-instanser?**
- 1-5 → Per-resource Log Analytics
- 5+ → Centralized monitoring hub
4. **Hva er budsjettet?**
- < $100/mnd → Minimal logging, metric alerts
- $100-500/mnd → Full Log Analytics, Application Insights
- $500+ → Grafana, Workbooks, multi-region dashboards
### Common pitfalls
❌ **"Vi setter opp monitoring etter lansering"**
→ MTTR blir 10x høyere. Etabler baseline metrics i pilot-fase.
❌ **"AllLogs er greit, vi har budsjett"**
→ Etter 3 måneder: "Hvorfor koster Log Analytics $2000/mnd?"
❌ **"Vi trenger ikke alerts, vi sjekker dashboards daglig"**
→ Outage kl 02:00 oppdages kl 09:00. Kunde allerede misfornøyd.
❌ **"Application Insights erstatter Diagnostic Logs"**
→ Nei, de er komplementære. Trenger begge for full observability.
### Iterative rollout-strategi
**Uke 1-2 (Foundation):**
- Opprett Log Analytics workspace
- Enable Diagnostic Settings (allLogs)
- Opprett basic metric alerts (error rate, latency)
**Uke 3-4 (Visibility):**
- Deploy Azure Monitor Workbook (eller Grafana dashboard)
- Etabler daglig review-rutine (15 min standup)
- Dokumenter baseline metrics (normal vs. abnormal)
**Uke 5-8 (Automation):**
- Tune alert thresholds (reduser false positives)
- Implementer action groups (email → PagerDuty)
- Opprett runbooks for top 3 failure scenarios
**Uke 9-12 (Optimization):**
- Analyser log volume, filtrer bort støy
- Vurder commitment tier for Log Analytics
- Implementer cost dashboards (show to FinOps)
**Kontinuerlig (Post-launch):**
- Monthly review av alert effectiveness
- Quarterly update av runbooks
- Bi-annual review av retention policies
---
## Kilder og verifisering
**Verified (MCP-research, januar 2026):**
- [Enable diagnostic logging for Foundry Tools](https://learn.microsoft.com/en-us/azure/ai-services/diagnostic-logging) – Offisiell guide, sist oppdatert 2024
- [Monitor Azure OpenAI](https://learn.microsoft.com/en-us/azure/ai-foundry/openai/how-to/monitor-openai) – Kusto queries, diagnostic settings, dashboards
- [Introduction to Application Insights](https://learn.microsoft.com/en-us/azure/azure-monitor/app/app-insights-overview) – OpenTelemetry-basert APM
- [Monitor Azure AI services (Training module)](https://learn.microsoft.com/en-us/training/modules/monitor-ai-services/) – Microsoft Learn offisiell kurs
**Baseline (Modellkunnskap, januar 2025):**
- Azure Monitor pricing (verifiser via [Azure Pricing Calculator](https://azure.microsoft.com/en-us/pricing/calculator/))
- Noark-5 arkiveringskrav (verifiser via [Arkivverket](https://www.arkivverket.no/))
- GDPR Article 30 (behandlingsprotokoll)
- Best practices for Log Analytics workspace design
**Andre ressurser:**
- [Azure Monitor Baseline Alerts](https://aka.ms/amba) – Community-drevet alert templates
- [Kusto Query Language reference](https://learn.microsoft.com/en-us/azure/data-explorer/kusto/query/) – KQL syntax guide
- [Cost Management for Azure AI](https://learn.microsoft.com/en-us/azure/cost-management-billing/costs/overview-cost-management) – Budgets, alerts, exports
---
**Konfidensgradering:**
- Diagnostic settings, Log Analytics, KQL queries: **Verified** ✅
- Azure OpenAI metrics og dashboards: **Verified** ✅
- Application Insights integration: **Verified** ✅
- Pricing estimates (NOK): **Baseline** (valutakurs varierer, verifiser i calculator)
- Noark-5 retention: **Baseline** (tolkninger kan variere per kommune/etat)

604
plugins/ms-ai-architect/skills/ms-ai-engineering/references/azure-ai-services/ai-services-networking-security.md Normal file
View file

@ -0,0 +1,604 @@
# Azure AI Services - Networking, Security and Private Endpoints
**Last updated:** 2026-02
**Status:** GA
**Category:** Azure AI Services (Foundry Tools)
---
## Introduksjon
Azure AI Services (tidligere Cognitive Services) tilbyr et lagdelt sikkerhetsrammeverk for nettverksisolasjon som beskytter AI-modeller, data og tjenester mot uautorisert tilgang. Private endpoints, virtual networks og service endpoints gir fleksible sikkerhetskonfigurasjoner som passer både skytilkoblede og hybrid-scenarier.
Denne kunnskapsreferansen dekker:
- Private endpoints og Azure Private Link-konfigurasjon
- Virtual network-integrasjon med service endpoints
- IP-baserte firewall-regler og nettverkstilgangskontroll
- Managed identity-autentisering for nettverkssikker tilgang
- DNS-konfigurasjon for private endpoints
- Trusted services og nettverksunntak
**Viktig kontekst:** Azure AI Services støtter **ikke** direkte VNet-injeksjon (deployes ikke inn i kundens VNet), men bruker i stedet private endpoints for sikker tilkobling fra VNet til tjenesten.
---
## Kjernekomponenter
### 1. Private Endpoints og Azure Private Link
Private endpoints gir dedikert nettverkstilgang til Azure AI Services uten eksponering mot offentlig internett.
| Komponent | Funksjon | Konfigurasjon |
|-----------|----------|---------------|
| **Private Endpoint** | Dedikert nettverksgrensesnitt i kundens VNet | Tildeles privat IP fra VNet-adresseområdet |
| **Private Link Service** | Azure-backbone-tilkobling | Eliminerer internett-eksponering |
| **Private DNS Zone** | Navneoppløsning for private endpoints | `privatelink.cognitiveservices.azure.com` (AI Services)<br>`privatelink.openai.azure.com` (Azure OpenAI) |
| **Target Sub-resource** | Endepunkttype | `account` (AI Services, Azure OpenAI) |
**Fordeler:**
- Eliminerer offentlig internett-eksponering fullstendig
- Trafikk går over Microsoft backbone network
- Fungerer med VPN Gateway og ExpressRoute for on-premises tilgang
- Konsistent tilkoblings-string for både private og public endpoints
- Støtter både system-assigned og user-assigned managed identities
**Begrensninger:**
- Krever Basic tier eller høyere (ikke Free tier)
- Custom subdomain er påkrevd for private endpoints
- Speech service krever separate endpoint-konfigurasjoner
- Portal-tilgang kan kreve ekstra konfigurasjon
### 2. Service Endpoints
Service endpoints gir optimalisert ruting fra VNet til Azure AI Services uten private IP-adresser.
| Aspekt | Beskrivelse |
|--------|-------------|
| **Service Tag** | `Microsoft.CognitiveServices` |
| **Routing** | Optimal sti fra VNet til tjenesten via Azure backbone |
| **Identitet** | Subnet- og VNet-identitet sendes med hver forespørsel |
| **Kombinasjon** | Kan brukes sammen med IP-regler (maks 100 VNet-regler per ressurs) |
**Når bruke service endpoints vs private endpoints:**
- **Service Endpoints:** Enklere oppsett, gratis, men tjenesten beholder offentlig IP
- **Private Endpoints:** Full isolasjon, privat IP, bedre sikkerhet, men høyere kostnad
### 3. IP Firewall-regler (Network ACLs)
Service-level IP filtering for å begrense tilgang til godkjente IP-adresser.
| Regeltype | Format | Eksempel | Bruksområde |
|-----------|--------|----------|-------------|
| **Enkelt IP** | `x.x.x.x` | `203.0.113.10` | Spesifikt klientmaskin |
| **IP-range** | CIDR-notasjon | `10.0.0.0/24` | Subnet eller on-premises nettverk |
| **IPv4 kun** | RFC 1918-kompatibel | Private: `10.*`, `172.16-31.*`, `192.168.*` ikke tillatt | Kun offentlige IP-adresser |
**Konfigurasjonsalternativer:**
- **All networks:** Åpen tilgang (default)
- **Selected networks:** Kun godkjente VNets/IPs
- **Disabled:** Ingen public access (kun private endpoints)
**Viktig:** Default action må settes til `Deny` for at nettverksregler skal ha effekt.
### 4. Managed Identity og Autentisering
Managed identity eliminerer behovet for API-nøkler ved nettverksikrede tilkoblinger.
| Type | Levetid | Bruksområde |
|------|---------|-------------|
| **System-assigned** | Knyttet til ressurs-levetid | Standard for enkle scenarier |
| **User-assigned** | Uavhengig av ressurs | Multi-ressurs, delt identitet |
**Konfigurering via Azure Portal:**
1. Naviger til AI Services-ressurs → **Identity**
2. Aktiver **System assigned** eller legg til **User assigned**
3. Tildel RBAC-rolle på målressurs: `Cognitive Services User` eller `Cognitive Services OpenAI User`
**Trusted Services Bypass:**
- Aktiveres med `networkAcls.bypass: "AzureServices"`
- Tillater Azure AI Search, Azure Machine Learning å kalle tjenesten via managed identity
- Tjenesten validerer JWT-token fra trusted services
---
## Arkitekturmønstre
### 1. Full Private Endpoint-isolasjon
**Scenario:** Maksimal sikkerhet, null internett-eksponering.
```
┌─────────────────────────────────────────────┐
│ Azure Virtual Network (10.0.0.0/16) │
│ │
│ ┌─────────────────────────────────────┐ │
│ │ App Subnet (10.0.1.0/24) │ │
│ │ - Web App / Function App │ │
│ │ - VNet Integration │ │
│ └─────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────┐ │
│ │ Private Endpoint Subnet │ │
│ │ (10.0.2.0/24) │ │
│ │ - PE for Azure OpenAI (10.0.2.4) │───┼──> Azure OpenAI
│ │ - PE for AI Services (10.0.2.5) │───┼──> AI Services
│ │ - PE for Key Vault (10.0.2.6) │───┼──> Key Vault
│ │ - PE for Storage (10.0.2.7) │───┼──> Storage
│ └─────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────┐ │
│ │ Azure Bastion Subnet (10.0.3.0/26) │ │
│ │ - Bastion Host │ │
│ └─────────────────────────────────────┘ │
└─────────────────────────────────────────────┘
│
└──> On-premises (VPN Gateway / ExpressRoute)
```
**Konfigurasjonsrekkefølge:**
1. Opprett VNet med subnets (app, private endpoint, bastion)
2. Opprett Azure AI Services med custom subdomain
3. Opprett private endpoint i dedikert subnet
4. Konfigurer Private DNS Zone (`privatelink.cognitiveservices.azure.com`)
5. Sett `publicNetworkAccess: Disabled` på AI Services
6. Aktiver managed identity på applikasjon
7. Tildel RBAC-rolle til applikasjonen på AI Services
**Best practices:**
- Bruk dedikert subnet for private endpoints (anbefalt `/26` eller større)
- Aktiver `PrivateEndpointNetworkPolicies: Disabled` på subnet
- Integrer med Private DNS Zone for automatisk navneoppløsning
- Bruk Azure Bastion for sikker management-tilgang
### 2. Hybrid Service Endpoint + IP Firewall
**Scenario:** Koste-effektiv sikkerhet med VNet + on-premises tilgang.
```
┌─────────────────────────────────────────────┐
│ Azure Virtual Network │
│ │
│ ┌─────────────────────────────────────┐ │
│ │ App Subnet │ │
│ │ - Service Endpoint enabled │ │
│ │ (Microsoft.CognitiveServices) │ │
│ └─────────────────────────────────────┘ │
│ │ │
│ └──────────────┐ │
└─────────────────────────────┼───────────────┘
│
▼
┌─────────────────┐
│ Azure AI Service│
│ Firewall: │
│ - VNet rule │
│ - IP allow: │
│ 203.0.113.0/24│ <──── On-premises public IP
└─────────────────┘
```
**Konfigurasjon:**
1. Aktiver service endpoint på subnet: `Microsoft.CognitiveServices`
2. Konfigurer AI Services firewall:
- Default action: `Deny`
- VNet rule: tillat spesifikk subnet
- IP rule: tillat on-premises public IP range
### 3. Hub-Spoke med Centralisert Network Security
**Scenario:** Enterprise-arkitektur med sentralisert sikkerhet.
```
┌─────────────────────────────┐
│ Hub VNet (10.0.0.0/16) │
│ - Azure Firewall │
│ - VPN Gateway │
│ - Private DNS Zones │
└─────────────┬───────────────┘
│ VNet Peering
┌────────────┴────────────┐
│ │
┌──────▼──────┐ ┌──────▼──────┐
│ Spoke 1 VNet│ │ Spoke 2 VNet│
│ AI Workload │ │ AI Workload │
│ - PEs │ │ - PEs │
└─────────────┘ └─────────────┘
```
**Nettverksflyt:**
- Outbound trafikk → Azure Firewall (FQDN filtering)
- Inbound management → Azure Bastion i Hub
- Private DNS Zones deles via VNet-links
### 4. Azure OpenAI "On Your Data" med Network Isolation
**Scenario:** RAG-løsning med Azure AI Search + Storage bak private endpoints.
```
┌────────────────────────────────────────────────┐
│ VNet (3 subnets) │
│ │
│ 1. VPN Gateway Subnet │
│ 2. Private Endpoint Subnet: │
│ - Azure OpenAI PE │
│ - Azure AI Search PE (shared private link) │
│ - Storage Account PE │
│ 3. Web App Outbound Integration Subnet │
└────────────────────────────────────────────────┘
┌─────────────┐ Managed Identity ┌──────────────┐
│ Azure OpenAI├───────────────────>│ AI Search │
│ │ (trusted service) │ (embedding) │
└─────────────┘ bypass firewall └──────────────┘
```
**Spesialkonfigurasjon:**
- Azure OpenAI: `networkAcls.bypass: "AzureServices"` (trusted service)
- AI Search: managed identity med `Cognitive Services OpenAI User` rolle
- Storage: private endpoint + RBAC for OpenAI managed identity
---
## Beslutningsveiledning
### Når bruke hvilken nettverkssikkerhet?
| Scenario | Anbefalt løsning | Rasjonale |
|----------|------------------|-----------|
| **Maksimal sikkerhet, compliance-kritisk** | Private Endpoints + Disable Public Access | Zero Trust, ingen internett-eksponering |
| **Kostnadsbevisst, medium sikkerhet** | Service Endpoints + IP Firewall | Gratis, god sikkerhet, enklere oppsett |
| **Hybrid on-premises + Azure** | Private Endpoints + VPN Gateway / ExpressRoute | Privat tilkobling til on-premises |
| **Multi-region, lav latency** | Private Endpoints per region | Redusert latency, regional isolasjon |
| **Dev/Test miljø** | IP Firewall kun | Lavest kompleksitet, akseptabel risiko |
### Sikkerhetsnivå-matriks
| Tiltak | Sikkerhetsnivå | Kompleksitet | Kostnad | Compliance |
|--------|----------------|--------------|---------|------------|
| IP Firewall kun | ⭐⭐ | Lav | Gratis | Basis |
| Service Endpoints | ⭐⭐⭐ | Medium | Gratis | Medium |
| Private Endpoints | ⭐⭐⭐⭐⭐ | Høy | Medium | Høy (GDPR, HIPAA) |
| PE + Disabled Public | ⭐⭐⭐⭐⭐ | Høy | Medium | Maksimal |
### DNS-konfigurasjon: Azure Private DNS vs Custom DNS
**Azure Private DNS (anbefalt):**
- Automatisk CNAME-record oppdatering
- Integrert med VNet
- Ingen ekstra konfigurasjon
**Custom DNS (on-premises DNS server):**
- Krev conditional forwarder til Azure DNS (`168.63.129.16`)
- Manuell A-record for private endpoint IP
- Nødvendig for hybrid-scenarier
**FQDN-resolusjon:**
- Fra VNet: `myaccount.cognitiveservices.azure.com` → `10.0.2.5` (privat IP)
- Fra internett: `myaccount.cognitiveservices.azure.com` → public IP (hvis ikke disabled)
---
## Integrasjon med Microsoft-stakken
### 1. Azure AI Foundry (tidligere AI Studio)
**Portal-tilgang med private endpoints:**
- Custom subdomain må brukes i alle API-kall
- Portal-tilgang krever VPN eller Azure Bastion til VNet
- Service tags for portal: `AzureActiveDirectory`, `AzureFrontDoor.Frontend`, `AzureResourceManager`, `CognitiveServicesManagement`, `CognitiveServicesFrontEnd`
**Managed VNet i Foundry:**
- Foundry hub kan ha egen managed VNet
- Workspace inheriter nettverksregler fra hub
- Private endpoints til Foundry Tools konfigureres separat
### 2. Power Platform Integration
**Power Automate / Power Apps med private endpoints:**
- Krever On-premises data gateway for VNet-tilkobling
- Azure Relay hybrid connection ikke støttet direkte
- Custom connector må bruke public endpoint med IP firewall
**Workaround for private endpoints:**
1. Deploy Azure Function med VNet integration
2. Function kaller AI Services via private endpoint
3. Custom connector kaller Azure Function (public endpoint med auth)
### 3. Azure Machine Learning
**AML Workspace med AI Services private endpoints:**
- Shared private link fra AML til AI Services
- Managed identity med `Cognitive Services User` rolle
- Trusted service bypass: `networkAcls.bypass: "AzureServices"`
**Compute Cluster konfigurasjon:**
- Cluster må være i samme VNet (eller peered VNet)
- NSG må tillate outbound til `AzureMachineLearning` service tag
### 4. Azure AI Search (for RAG)
**Shared Private Link:**
- AI Search kan opprette private endpoint til AI Services
- Eliminerer behovet for trusted service bypass
- Konfigureres via AI Search → Networking → Shared Private Links
**Trusted Service alternativ:**
- AI Search managed identity med RBAC-rolle på AI Services
- `networkAcls.bypass: "AzureServices"` på AI Services
- System-assigned managed identity authentication påkrevd
---
## Offentlig sektor (Norge)
### 1. Compliance-krav
| Regelverk | Relevante krav | Nettverkstiltak |
|-----------|----------------|-----------------|
| **Personvernforordningen (GDPR)** | Art. 32: Tekniske sikkerhetstiltak | Private endpoints, kryptering i transit (TLS 1.2+) |
| **Nasjonal sikkerhetsmyndighet (NSM)** | Grunnprinsipper for IKT-sikkerhet | Network segmentation, least privilege access |
| **Schrems II** | Data Processing Agreement-krav | Private endpoints reduserer eksponering mot utenlandsk jurisdiksjon |
| **eHelse** | Norm for informasjonssikkerhet (HelseNorge) | Nettverksisolasjon, logging, audit trail |
### 2. Offentlig Sektor-spesifikke hensyn
**Data Residency:**
- Private endpoints endrer ikke data location (fortsatt i Azure-regionen)
- Norway East / Norway West anbefales for offentlig sektor
- Private Link-trafikk forblir innenfor Microsoft backbone network (ikke public internet)
**Schrems II og Cloud Act:**
- Private endpoints reduserer ikke juridisk ansvar ved Cloud Act-forespørsler
- Tilleggstiltak: Customer-Managed Keys (CMK), Microsoft Purview audit logs
**Kostnadsmodell:**
- Private Endpoint: ~40 NOK/måned per endpoint
- Data Processing (ingress): Gratis
- Data Processing (egress): ~0.40 NOK/GB (intra-region via private link)
---
## Kostnad og lisensiering
### 1. Nettverkskomponenter - Priser (NOK, ca. 2026)
| Komponent | Kostnad | Enhet | Merknad |
|-----------|---------|-------|---------|
| **Private Endpoint** | ~40 NOK | per endpoint/måned | Uavhengig av trafikkmengde |
| **Data Processing (inbound)** | Gratis | per GB | Ingen kostnad for ingress |
| **Data Processing (outbound)** | ~0.40 NOK | per GB | Intra-region via private link |
| **Service Endpoint** | Gratis | - | Ingen ekstra kostnad |
| **VNet Peering** | ~0.08 NOK | per GB (intra-region) | For hub-spoke arkitektur |
| **Azure Bastion** | ~1200 NOK | per måned (Basic) | For secure management access |
| **VPN Gateway** | ~2400 NOK | per måned (Basic) | For on-premises tilkobling |
**Estimert månedskostnad for typisk oppsett:**
- **SMB (1 AI Service + Storage):** ~80 NOK/måned (2 private endpoints)
- **Enterprise (3 AI Services + Search + Storage + Key Vault):** ~240 NOK/måned (6 private endpoints) + Bastion/VPN
### 2. AI Services Tier-krav
| Tier | Private Endpoints | IP Firewall | Service Endpoints |
|------|-------------------|-------------|-------------------|
| **Free** | ❌ Ikke støttet | ❌ Ikke støttet | ❌ Ikke støttet |
| **Basic** | ✅ Støttet | ✅ Støttet | ✅ Støttet |
| **Standard** | ✅ Støttet | ✅ Støttet | ✅ Støttet |
**Minstekrav:** Basic tier (S0) eller høyere for nettverkssikkerhet.
### 3. Hidden Costs å være obs på
- **DNS Zone:** ~4 NOK/måned per Private DNS Zone + ~0.004 NOK per 1000 queries
- **Data Egress:** Trafikk ut av Azure region (ikke via private link) kan bli dyrt
- **Network Watcher:** Flowlogger for NSG koster ~40 NOK/måned per NSG
- **Log Analytics:** Ingest av network logs (pris avhenger av volum)
---
## For arkitekten (Cosmo)
### 1. Oppstartssekvens for Private Endpoint-prosjekt
**Pre-deployment checklist:**
1. ✅ Validert at AI Services tier er Basic eller høyere
2. ✅ Planlagt IP-adresseområder (VNet, subnets)
3. ✅ Identifisert custom subdomain for AI Services-ressurs
4. ✅ Avklart DNS-strategi (Azure Private DNS vs custom DNS)
5. ✅ Bestemt managed identity-strategi (system vs user-assigned)
6. ✅ RBAC-roller definert (hvem skal ha tilgang til hva)
**Deployment-rekkefølge (kritisk!):**
1. Opprett Resource Group
2. Opprett VNet med subnets (app, private endpoint, bastion)
3. Opprett AI Services-ressurs med custom subdomain
4. Opprett Private DNS Zone (`privatelink.cognitiveservices.azure.com`)
5. Link Private DNS Zone til VNet
6. Opprett Private Endpoint (velg target sub-resource: `account`)
7. Verifiser DNS record i Private DNS Zone (A-record for private IP)
8. Sett `publicNetworkAccess: Disabled` på AI Services (etter testing!)
9. Aktiver managed identity på applikasjon
10. Tildel RBAC-rolle (`Cognitive Services User`) til applikasjon
**Testing-rekkefølge:**
1. Fra VNet: `nslookup <myaccount>.cognitiveservices.azure.com` → skal returnere privat IP
2. Fra VNet: `Test-NetConnection <private-ip> -Port 443` → skal lykkes
3. Fra internett (før disabled public): `nslookup` → skal returnere public IP
4. API-kall fra VNet med managed identity → skal lykkes
5. API-kall fra internett (etter disabled public) → skal feile (403 Forbidden)
### 2. Troubleshooting-guide
| Symptom | Mulig årsak | Løsning |
|---------|-------------|---------|
| **403 Forbidden fra VNet** | IP firewall blokkerer | Sjekk firewall rules, default action må være Deny med eksplisitt Allow-regel |
| **DNS resolves til public IP fra VNet** | Private DNS Zone ikke linket | Link Private DNS Zone til VNet, verifiser A-record |
| **Connection timeout** | NSG blokkerer port 443 | Sjekk NSG-regler på subnet, tillat outbound 443 til `CognitiveServices` service tag |
| **Portal ikke tilgjengelig** | Service tags mangler | Legg til `AzureFrontDoor.Frontend`, `CognitiveServicesFrontEnd` i firewall/NSG |
| **Managed identity auth fails** | RBAC-rolle mangler | Tildel `Cognitive Services User` eller `Cognitive Services OpenAI User` rolle |
### 3. Design-avveininger
**Private Endpoints vs Service Endpoints:**
| Dimensjon | Private Endpoints | Service Endpoints |
|-----------|-------------------|-------------------|
| **Sikkerhet** | ⭐⭐⭐⭐⭐ (privat IP) | ⭐⭐⭐⭐ (public IP, VNet-regler) |
| **Kompleksitet** | Høy (DNS, subnets) | Lav (enable på subnet) |
| **Kostnad** | ~40 NOK/måned per endpoint | Gratis |
| **Latency** | Lavest (direkte) | Lavt (optimalisert) |
| **Compliance** | Best (Zero Trust) | Godt (nettverksisolasjon) |
| **On-prem access** | VPN/ExpressRoute | VPN/ExpressRoute |
**Anbefaling:**
- **Prod + høy sikkerhet:** Private Endpoints + Disabled Public Access
- **Prod + kostnadsfokus:** Service Endpoints + IP Firewall
- **Dev/Test:** IP Firewall kun (akseptabel risiko)
### 4. Common Pitfalls (å unngå!)
**❌ Aktivere "Disable public access" før private endpoint fungerer:**
- Resultat: Fullstendig tap av tilgang (inkludert Azure Portal)
- Fix: Test private endpoint grundig først, bruk "Selected networks" som mellomsteg
**❌ Glemme custom subdomain:**
- Resultat: Private endpoint creation feiler eller DNS resolution fungerer ikke
- Fix: Custom subdomain må settes ved opprettelse av AI Services-ressurs
**❌ Private DNS Zone ikke linket til alle relevante VNets:**
- Resultat: DNS resolves til public IP fra peered VNets
- Fix: Link Private DNS Zone til alle VNets som trenger tilgang (hub og spokes)
**❌ Bruke `*.privatelink.openai.azure.com` som endpoint URL:**
- Resultat: API-kall feiler med HTTPS-feil
- Fix: Bruk alltid custom subdomain (`myaccount.openai.azure.com`), DNS håndterer ruting
**❌ Managed identity uten RBAC-rolle:**
- Resultat: 403 Forbidden selv om nettverkstilgang er OK
- Fix: Tildel minst `Cognitive Services User` rolle på AI Services-ressursen
### 5. Production Readiness Checklist
**Sikkerhet:**
- [ ] Private endpoints aktivert for alle AI Services
- [ ] Public network access disabled (eller IP-baserte firewall-regler)
- [ ] Managed identity aktivert (eliminerer API-nøkler i kode)
- [ ] RBAC-roller tildelt med least privilege
- [ ] NSG-regler konfigurert (least privilege)
- [ ] Azure Firewall / WAF for outbound/inbound trafikk (enterprise)
**Overvåkning:**
- [ ] Diagnostic settings aktivert (send logs til Log Analytics)
- [ ] Network Watcher flowlogger aktivert (NSG)
- [ ] Azure Monitor alerts for nettverksfeil (429, 403, connection timeout)
- [ ] Private Link metrics overvåket (bytes in/out, connection count)
**Disaster Recovery:**
- [ ] Multi-region deployment vurdert (private endpoints per region)
- [ ] VNet peering konfigurert for failover
- [ ] DNS failover-strategi dokumentert
- [ ] Backup-plan for public access (emergency access)
**Dokumentasjon:**
- [ ] Nettverksdiagram (logical + physical)
- [ ] IP-adressering dokumentert (subnets, private endpoint IPs)
- [ ] DNS-konfigurasjon dokumentert (zones, records, forwarders)
- [ ] RBAC-roller og service principals dokumentert
- [ ] Runbook for troubleshooting
### 6. Spør kunden dette (før design)
1. **Sikkerhetsnivå:**
- "Har dere compliance-krav som krever zero internett-eksponering?" → private endpoints
- "Hva er risikovurdering av data lekkasje?" → akseptabelt nivå for kostnad
2. **Eksisterende nettverk:**
- "Har dere eksisterende hub-spoke arkitektur?" → integrering vs ny VNet
- "Bruker dere on-premises DNS-servere?" → conditional forwarders trengs
3. **On-premises tilkobling:**
- "Trenger brukere on-premises tilgang til AI Services?" → VPN Gateway/ExpressRoute
- "Har dere eksisterende ExpressRoute?" → reuse eller ny
4. **Multi-region:**
- "Trenger dere DR i annen region?" → private endpoints per region
- "Hva er akseptabel RTO/RPO?" → påvirker arkitektur
5. **Kostnadsbudsjett:**
- "Hva er månedlig budsjett for nettverksinfrastruktur?" → private endpoints (~40 NOK/stk) vs service endpoints (gratis)
- "Er data egress-volum relevant?" → intra-region vs inter-region trafikk
### 7. Quick Reference - Azure CLI/PowerShell
**Opprett Private Endpoint (Azure CLI):**
```bash
# Hent ressurs-ID for AI Services
csResourceId=$(az cognitiveservices account show \
--resource-group myRG \
--name myAIAccount \
--query id --output tsv)
# Opprett private endpoint
az network private-endpoint create \
--resource-group myRG \
--name myAIPrivateEndpoint \
--location norwayeast \
--vnet-name myVNet \
--subnet privateEndpointSubnet \
--private-connection-resource-id $csResourceId \
--group-id account \
--connection-name myConnection
# Opprett DNS zone group (automatisk A-record)
az network private-endpoint dns-zone-group create \
--resource-group myRG \
--endpoint-name myAIPrivateEndpoint \
--name myDNSZoneGroup \
--private-dns-zone privatelink.cognitiveservices.azure.com \
--zone-name cognitiveservices
```
**Disable Public Access (Azure CLI):**
```bash
az cognitiveservices account update \
--resource-group myRG \
--name myAIAccount \
--set properties.publicNetworkAccess=Disabled
```
**Aktiver Managed Identity (Azure CLI):**
```bash
az cognitiveservices account identity assign \
--resource-group myRG \
--name myAIAccount
```
**Test DNS Resolution (PowerShell):**
```powershell
# Fra VNet VM - skal returnere privat IP
nslookup myaccount.cognitiveservices.azure.com
# Test port 443
Test-NetConnection -ComputerName 10.0.2.5 -Port 443
```
---
## Kilder og verifisering
**Verified (MCP microsoft-learn, 2026-02):**
- [Configure Foundry Tools virtual networks](https://learn.microsoft.com/en-us/azure/ai-services/cognitive-services-virtual-networks) - Hovedkilde for VNet-konfigurasjon, service endpoints, IP-regler, private endpoints
- [Configure secure networking for Azure AI platform services](https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/scenarios/ai/platform/networking) - Arkitektur-guide fra Cloud Adoption Framework
- [Configure Azure OpenAI networking](https://learn.microsoft.com/en-us/azure/ai-foundry/openai/how-to/network) - Private endpoint oppsett for Azure OpenAI
- [Network and access configuration for Azure OpenAI On Your Data](https://learn.microsoft.com/en-us/azure/ai-foundry/openai/how-to/on-your-data-configuration) - Trusted services bypass, managed identity setup
- [Azure security baseline for Azure AI services](https://learn.microsoft.com/en-us/security/benchmark/azure/baselines/cognitive-services-security-baseline) - NSG-støtte (ikke støttet), private link (støttet), disable public access
- [Create a private endpoint for a secure connection to Azure AI Search](https://learn.microsoft.com/en-us/azure/search/service-create-private-endpoint) - Shared private link-mønster
**Baseline (modellkunnskap, januar 2025):**
- Azure Private Link pricing: ca. 40 NOK/måned per endpoint (basert på USD-priser og valutakurs)
- Custom subdomain-krav for private endpoints (dokumentert i flere Microsoft-kilder)
- NSG-støtte ikke tilgjengelig for AI Services (bekreftet via security baseline)
- Trusted services bypass med `networkAcls.bypass: "AzureServices"` (REST API-konfigurasjon)
**Sist verifisert:** 2026-02-03
**MCP calls:** 7 (microsoft_docs_search, microsoft_docs_fetch, microsoft_code_sample_search)
**Kilder:** 10 unike Microsoft Learn URLs

726
plugins/ms-ai-architect/skills/ms-ai-engineering/references/azure-ai-services/ai-services-vs-foundry-tools-selection.md Normal file
View file

@ -0,0 +1,726 @@
# Azure AI Services vs Foundry Tools - Platform Selection Guide
**Last updated:** 2026-02
**Status:** GA
**Category:** Azure AI Services (Foundry Tools)
---
## Introduksjon
Microsoft tilbyr flere nivåer av AI-tjenester under paraplynavnet "Azure AI Services" (tidligere Cognitive Services). Denne guiden klargjør forskjellen mellom de tre hovedplattformene: **Foundry Tools** (individuelle AI-tjenester), **Azure AI Foundry** (plattform), og **Azure OpenAI** (generativ AI-tjeneste).
**Forvirring i bransjen:** Begrepet "Azure AI Services" brukes både som samlebetegnelse for alle AI-tjenester OG som teknisk ressurstype (kind: AIServices). Microsoft har nylig endret terminologi fra "Cognitive Services" til "Foundry Tools" for enkelttjenester.
### Nøkkelforskjeller i kortform
| Aspekt | Foundry Tools | Azure AI Foundry | Azure OpenAI |
|--------|---------------|------------------|--------------|
| **Type** | Enkeltstående AI-tjenester (API/SDK) | Unified development platform (PaaS) | Generativ AI-tjeneste |
| **Målgruppe** | Utviklere (begrenset AI-kompetanse ok) | Utviklere + data scientists | Utviklere + data scientists |
| **Kompleksitet** | Lav → Middels | Middels → Høy | Middels → Høy |
| **Tilpasning** | Prebuilt + noe finjustering | Full kontroll over modeller/agenter | Modellvalg, prompt engineering, fine-tuning |
| **Orkestrering** | Nei (kun API-kall) | Ja (agents, workflows) | Delvis (via Agent Service) |
| **Bruksområde** | Enkeltstående AI-funksjoner | Multi-agent systemer, GenAI-apps | Generativ AI (tekst, bilde, lyd) |
**Confidence:** Høy (offisiell Microsoft-dokumentasjon 2025-2026)
---
## Kjernekomponenter / Nøkkelegenskaper
### 1. Foundry Tools (Azure AI Services)
**Definisjon:** Prebuilt AI-tjenester som leveres via REST API og SDK, med lite eller ingen AI-ekspertise påkrevd.
#### Tjenestekategorier
| Kategori | Tjenester | Typiske bruksområder |
|----------|-----------|---------------------|
| **Vision** | Computer Vision, Face API, Content Understanding, Video Indexer | Bildeklassifisering, ansiktsgjenkjenning, video-analyse |
| **Speech** | Speech-to-Text, Text-to-Speech, Speech Translation | Transkripsjon, stemmeassistenter, flerspråklig tale |
| **Language** | Language Understanding, Translator, Sentiment Analysis | NLP, oversettelse, sentimentanalyse |
| **Document** | Document Intelligence, Content Understanding | Dokumentuttrekk, OCR, formulardata |
| **Decision** | Content Safety, Personalizer (utgått) | Innholdsmoderering, anbefalinger |
#### Kjennetegn
- **Serverless API-modell:** Pay-per-use, ingen infrastrukturforvaltning
- **Regional deployment:** Tjenester deployes i Azure-regioner med lokal dataprosessering
- **Commitment tiers:** Mulighet for forhåndsbetalte kapasitetsplaner (faste kostnader)
- **Tilpasning:** Noen tjenester støtter custom models (f.eks. Custom Vision, Custom Speech) via labeled data
#### Autentisering og tilgang
- **API keys** (legacy) eller **Microsoft Entra ID** (anbefalt)
- **RBAC:** Cognitive Services User, Cognitive Services Contributor
- **Networking:** VNET-integrasjon, Private Endpoints støttes
**Confidence:** Høy (offisiell oversikt fra MS Learn)
---
### 2. Azure AI Foundry
**Definisjon:** Unified platform for å bygge, deploye og forvalte generativ AI og nongenerativ AI-applikasjoner. Kombinerer agents, models, tools, observability, og governance i én PaaS-løsning.
#### Arkitekturkomponenter
```
┌─────────────────────────────────────────────────┐
│ Azure AI Foundry Platform │
├─────────────────────────────────────────────────┤
│ Authoring Layer │
│ - Foundry Portal (ai.azure.com) │
│ - Workflows (visuell designer) │
│ - Prompt-based agents (declarative) │
│ - Hosted agents (code-first) │
├─────────────────────────────────────────────────┤
│ Orchestration Layer │
│ - Agent Service │
│ - Microsoft Agent Framework (open-source) │
│ - Multi-agent workflows │
├─────────────────────────────────────────────────┤
│ Runtime Layer │
│ - Model catalog (OpenAI, Anthropic, Meta...) │
│ - Azure OpenAI │
│ - Foundry Tools (Speech, Vision, Language) │
│ - Evaluations & observability (App Insights) │
├─────────────────────────────────────────────────┤
│ Governance Layer │
│ - Content Safety │
│ - RBAC & Entra ID │
│ - Responsible AI tools │
└─────────────────────────────────────────────────┘
```
#### Ressurstyper (Azure Resource Manager)
| Resource Type | Kind | Capabilities |
|---------------|------|--------------|
| **Foundry** | `AIServices` | Agents, Evaluations, Azure OpenAI, Speech, Vision, Language, Content Understanding |
| **Foundry project** | `AIServices` (subresource) | Isolert prosjektscope for team |
| **Azure OpenAI** (legacy) | `OpenAI` | Kun OpenAI-modeller (anbefales å oppgradere til Foundry) |
| **Azure AI Hub** (deprecated) | `Hub` | Eldre resource type (migreres til Foundry) |
**Nøkkelkapabiliteter:**
- **Agent Service:** Managed runtime for agentic AI (conversation state, tool orchestration, safety enforcement)
- **Model Catalog:** 100+ modeller fra Microsoft, OpenAI, Anthropic, Meta, Mistral, Cohere
- **Connected agents:** Integrasjon med Azure AI Search, SharePoint, Bing, Azure Functions, Logic Apps
- **Workflows:** YAML-basert multi-agent orkestrering med visual designer
- **Observability:** Built-in tracing via Application Insights (traces, evaluations, conversation-level visibility)
- **Responsible AI:** Bias detection, interpretability, content filtering, fairness tools
**Compute-krav:**
- Managed runtime for agents (ingen VM/Kubernetes-administrasjon)
- Compute instances påkrevd for visse features (training, batch processing)
**Confidence:** Høy (dokumentert i Microsoft Foundry architecture docs)
---
### 3. Azure OpenAI Service
**Definisjon:** Spesialisert tjeneste for å få tilgang til OpenAI-modeller (GPT, DALL-E, Whisper, Embeddings) med Azure enterprise-fordeler (sikkerhet, compliance, SLA).
#### Modellserie (2026-02)
| Modell | Bruksområde | Deployment-typer |
|--------|-------------|------------------|
| **o4-mini** | Reasoning, kompleks problemløsning | Standard, Global Standard |
| **o3, o3-mini** | Avansert reasoning | Standard, Provisioned Throughput |
| **GPT-4o, GPT-4o-mini** | Chat, multimodal (tekst/bilde) | Standard, Global Standard, Provisioned |
| **GPT-4 Turbo** | Long-context tasks (128k tokens) | Standard, Provisioned |
| **GPT-3.5-Turbo** | Kostnadseffektiv chat | Standard, Global Standard |
| **DALL-E 3** | Bildegenerering | Standard |
| **Whisper** | Speech-to-text | Standard |
| **Embeddings** (text-embedding-3) | Vektorisering for RAG | Standard |
#### Deployment-typer
| Type | Beskrivelse | Bruksområde |
|------|-------------|-------------|
| **Standard** | Serverless, pay-per-token | Utviklingsmiljøer, variabel last |
| **Global Standard** | Globalt routet (ingen data residency) | 9 % rimeligere, høy throughput |
| **Provisioned Throughput (PTU)** | Reserved capacity, forutsigbar latens | Produksjon med streng SLA |
**Prismodell:**
- **Token-basert:** Pris per 1,000 tokens (input/output separat)
- **Fine-tuning:** Training cost + hosting cost (per time) + inference cost
- **Regional variasjon:** Prisene varierer per Azure-region
**Integrasjon med Foundry:**
- Azure OpenAI er **inkludert** i Foundry resource type (kind: AIServices)
- Legacy Azure OpenAI resources (kind: OpenAI) kan oppgraderes til Foundry uten API-endringer
**Confidence:** Høy (Azure OpenAI pricing page 2026)
---
## Arkitekturmønstre
### Mønster 1: Enkeltstående AI-funksjon (Foundry Tools)
**Bruk når:**
- Behov for én spesifikk AI-kapabilitet (f.eks. sentiment analysis, OCR, translation)
- Ingen behov for orkestrering eller multi-step workflows
- Begrenset AI-kompetanse i teamet
**Eksempelarkitektur:**
```
[Web App] → [Azure AI Language] → [Sentiment Analysis API]
↓
[Cosmos DB] (lagre resultater)
```
**Fordeler:**
- Enkel integrasjon (REST API/SDK)
- Lav kostnad for sporadisk bruk
- Ingen infrastrukturforvaltning
**Ulemper:**
- Ingen native orkestrering (må bygges selv)
- Begrenset kontroll over underliggende modeller
- Ikke egnet for multi-agent scenarios
---
### Mønster 2: RAG-applikasjon (Foundry + Azure AI Search)
**Bruk når:**
- Generativ AI over bedriftseget data
- Behov for grounding av LLM-svar
- Krav til kilde-sporing (citations)
**Eksempelarkitektur:**
```
[User Query]
↓
[Foundry Agent Service]
↓ (orchestrator)
[Azure AI Search] → [Vector Index] → [Blob Storage/SharePoint]
↓ (grounding data)
[Azure OpenAI (GPT-4o)]
↓
[Response + Citations]
```
**Komponenter:**
- **Foundry:** Agent runtime, conversation state
- **Azure AI Search:** Indexing, vector search, semantic ranking
- **Azure OpenAI:** LLM for generering
- **Document Intelligence:** Preprocessing av dokumenter (OCR, layout)
**Fordeler:**
- Built-in observability (tracing)
- Content Safety enforcement
- Managed scaling
**Ulemper:**
- Høyere kostnad (PTU for høy throughput)
- Kompleks oppsett for første gang
---
### Mønster 3: Multi-agent system (Foundry Agent Service)
**Bruk når:**
- Multi-step reasoning tasks
- Behov for spesialiserte agenter (f.eks. research-agent, writing-agent, review-agent)
- Tool coordination (Azure Functions, Logic Apps, third-party APIs)
**Eksempelarkitektur (Sequential Orchestration):**
```
[User Request]
↓
[Orchestrator Agent] (Foundry Agent Service)
↓
[Research Agent] → [Bing Grounding Tool]
↓
[Analysis Agent] → [Azure AI Language]
↓
[Writing Agent] → [GPT-4o]
↓
[Final Output]
```
**Orkestrering-patterns:**
- **Sequential:** Agents i forhåndsbestemt rekkefølge
- **Conditional branching:** Workflows med if/else-logikk
- **Parallel execution:** Flere agents kjører samtidig
- **Agent-to-agent (A2A):** Agents som kaller hverandre via Activity Protocol
**Verktøy:**
- **Microsoft Agent Framework** (open-source): Code-first orchestration
- **Foundry Workflows** (visual designer): Low-code YAML-basert
- **Copilot Studio** (SaaS): No-code agent building
**Fordeler:**
- Automatisert reasoning chain
- Observability via Application Insights
- Reusable agent components
**Ulemper:**
- Høy latens (flere model calls)
- Kompleks debugging
- Kostnad skalerer med agent-kall
---
### Mønster 4: Hybrid (Foundry Tools + Custom Logic)
**Bruk når:**
- Behov for prebuilt models OG custom business logic
- Compliance-krav (on-prem data processing)
- Kostnadsoptimalisering (bruk billigere tjenester der mulig)
**Eksempelarkitektur:**
```
[Video Input]
↓
[Azure Video Indexer] → [Extract metadata, faces, speech]
↓
[Azure Functions] (custom filtering logic)
↓
[Azure OpenAI] → [Summarize findings]
↓
[Power Automate] → [Send to Teams/SharePoint]
```
**Fordeler:**
- Beste fra to verdener (prebuilt + custom)
- Fleksibilitet i workflow
- Gradvis adopsjon av AI (start med prebuilt, bygg custom senere)
**Ulemper:**
- Krever flere Azure-ressurser (økt kompleksitet)
- Manuell orkestrering (Logic Apps/Functions)
---
## Beslutningsveiledning
### Beslutningstre: Hvilken plattform skal jeg velge?
```
START: Hvilken AI-kapabilitet trenger du?
├─ Enkeltstående AI-funksjon (sentiment, OCR, translation)
│ └─ Velg: Foundry Tools (f.eks. Language, Document Intelligence)
│
├─ Generativ AI (chat, summarization, content generation)
│ ├─ Kun LLM-tilgang (ingen orkestrering)?
│ │ └─ Velg: Azure OpenAI (standalone resource)
│ │
│ └─ Behov for agents/workflows/multi-step reasoning?
│ └─ Velg: Azure AI Foundry (inkluderer Azure OpenAI)
│
├─ RAG-applikasjon over bedriftseget data
│ └─ Velg: Azure AI Foundry + Azure AI Search
│
├─ Multi-agent system / agentic workflows
│ └─ Velg: Azure AI Foundry (Agent Service + workflows)
│
└─ Custom ML-modeller (trening, deploy)
└─ Velg: Azure Machine Learning (ikke dekket i denne guiden)
```
---
### Sammenligningstabell: Detaljerte beslutningskriterier
| Kriterium | Foundry Tools | Azure AI Foundry | Azure OpenAI |
|-----------|---------------|------------------|--------------|
| **Teknisk kompetanse** | Utvikler (basic) | Utvikler + Data Science | Utvikler + Data Science |
| **Setup-tid** | Timer | Dager | Timer |
| **Kostnad (start)** | Lav (pay-per-use) | Middels-Høy (PTU anbefalt) | Middels (standard), Høy (PTU) |
| **TCO (produksjon)** | Lav-Middels | Middels-Høy | Middels-Høy |
| **Skalerbarhet** | Automatisk (serverless) | Automatisk (managed) | Automatisk (standard), Manuell (PTU) |
| **Tilpasning** | Begrenset (prebuilt + custom models) | Full (fine-tuning, prompt engineering) | Full (fine-tuning, embeddings) |
| **Orkestrering** | Nei (manuell via code) | Ja (Agent Service, workflows) | Delvis (via Foundry Agent Service) |
| **Observability** | Basic (Azure Monitor) | Avansert (App Insights, traces) | Basic (Azure Monitor) |
| **Content Safety** | Manuell integrasjon | Built-in (default filter) | Built-in (default filter) |
| **Data residency** | Regional | Regional | Regional (unntatt Global Standard) |
| **VNET/Private Link** | Ja | Ja | Ja |
| **On-prem deployment** | Ja (containers) | Nei (cloud-only) | Nei (cloud-only) |
**Confidence:** Høy (sammenstilt fra flere MS Learn-kilder)
---
### Beslutningstabeller per scenario
#### Scenario 1: Dokumentprosessering
| Behov | Anbefalt plattform | Begrunnelse |
|-------|-------------------|-------------|
| **Standard formularer** (faktura, kvittering) | Document Intelligence (Foundry Tools) | Prebuilt models, høy nøyaktighet, confidence scores |
| **Komplekse dokumenter** (ustrukturert tekst, infererte felt) | Content Understanding (Foundry Tools) | Multimodal, generative fields, reasoning (preview) |
| **Custom workflow** (dokument → analyse → generering) | Azure AI Foundry (Document Intelligence + GPT-4o) | Full kontroll over pipeline |
**Confidence:** Høy (basert på "Choose the right tool for document processing" guide)
---
#### Scenario 2: Customer Support Chatbot
| Behov | Anbefalt plattform | Begrunnelse |
|-------|-------------------|-------------|
| **Enkel FAQ-bot** | QnA Maker (utgått) → Language Understanding | Prebuilt intent detection |
| **Kontekstuell chat** (multi-turn) | Azure OpenAI (GPT-4o) + custom API | LLM-basert dialog |
| **Agent med handlinger** (ticket creation, CRM-integrasjon) | Azure AI Foundry Agent Service | Tool calling, Logic Apps-integrasjon |
**Confidence:** Middels-Høy (basert på best practices, ikke eksplisitt dokumentert i én kilde)
---
#### Scenario 3: Media Analysis (Video/Audio)
| Behov | Anbefalt plattform | Begrunnelse |
|-------|-------------------|-------------|
| **Speech-to-text** | Azure Speech (Foundry Tools) eller Whisper (Azure OpenAI) | Speech service har diarization, Whisper er billigere |
| **Video metadata** (faces, scenes, logos) | Azure Video Indexer | Prebuilt video understanding |
| **Summarization av video** | Video Indexer + Azure OpenAI | Metadata → GPT-4o summary |
**Confidence:** Høy (dokumentert i Azure AI Services overview)
---
## Integrasjon med Microsoft-stakken
### 1. Foundry Tools integrasjon
| Produkt | Integrert gjennom | Bruksområde |
|---------|-------------------|-------------|
| **Power Platform** | AI Builder (connectors) | Low-code AI i Power Apps/Automate |
| **Microsoft 365** | Graph API | Document Intelligence for SharePoint |
| **Dynamics 365** | Customer Insights | Sentiment analysis for customer data |
| **Azure Logic Apps** | Built-in connectors | Workflow automation |
| **Azure Functions** | SDK (C#, Python, JS) | Custom serverless logic |
**Autentisering:** Managed Identity støttes for alle Foundry Tools via Azure SDK.
---
### 2. Azure AI Foundry integrasjon
| Produkt | Integrert gjennom | Bruksområde |
|---------|-------------------|-------------|
| **Microsoft 365 / Agent 365** | Activity Protocol, A2A | Publish agents til M365-workloads |
| **Copilot Studio** | Publish-to-Copilot | Deploy Foundry agents som Copilot-extensions |
| **Microsoft Fabric** | Unified data layer | Semantic model for RAG |
| **Azure DevOps** | GitHub Actions, CI/CD | Automated deployment av agents |
| **Microsoft Entra** | Agent ID, RBAC | Identity management for agents |
**Nøkkelintegrasjoner:**
- **Foundry Agent Service → Azure AI Search** (RAG)
- **Foundry → Azure Logic Apps** (tool calling)
- **Foundry → SharePoint/OneDrive** (document grounding)
---
### 3. Azure OpenAI integrasjon
| Produkt | Integrert gjennom | Bruksområde |
|---------|-------------------|-------------|
| **Power Platform** | Azure OpenAI connector | AI Builder actions i Power Automate |
| **Copilot Studio** | Generative answers | Boost copilot responses med GPT |
| **Azure AI Search** | Integrated vectorization | RAG med embeddings |
| **Azure Machine Learning** | Prompt flow | Orchestration av LLM-chains |
**API-kompatibilitet:**
- Azure OpenAI API er bakoverkompatibel med OpenAI API (drop-in replacement)
- Foundry resource type inkluderer full Azure OpenAI API-support
---
## Offentlig sektor (Norge)
### Compliance og datahåndtering
| Aspekt | Foundry Tools | Azure AI Foundry | Azure OpenAI |
|--------|---------------|------------------|--------------|
| **Data residency** | ✅ Regional (Norge-soner) | ✅ Regional (unntatt global models) | ✅ Regional (unntatt Global Standard) |
| **GDPR-compliance** | ✅ Ja | ✅ Ja | ✅ Ja |
| **Schrems II (Privacy Shield)** | ✅ EU Data Boundary | ✅ EU Data Boundary | ✅ EU Data Boundary |
| **PII-håndtering** | ⚠️ Manuelle tiltak | ✅ Content filters + manual review | ✅ Content filters + manual review |
| **Audit logs** | ✅ Azure Monitor | ✅ App Insights + Azure Monitor | ✅ Azure Monitor |
| **Customer Managed Keys** | ✅ Ja (encryption at rest) | ✅ Ja | ✅ Ja |
**Norge-spesifikke data-soner:**
- **Norway East** (Oslo)
- **Norway West** (Stavanger)
**Confidence:** Høy (Azure compliance-dokumentasjon 2026)
---
### Særlige hensyn for offentlig sektor
#### 1. Transparens og forklaring
- **Foundry Tools:** Confidence scores tilgjengelig (Document Intelligence, Language)
- **Azure OpenAI:** Ingen innebygd explainability (black box). Bruk prompt engineering for å be om "reasoning steps".
- **Foundry Agent Service:** Full observability via Application Insights (traces for hver agent-aksjon)
**Anbefaling:** For høykritiske beslutninger (helse, justis) → bruk Foundry Tools med confidence scores, eller Foundry med full tracing.
---
#### 2. Språkstøtte (Norsk bokmål/nynorsk)
| Tjeneste | Norsk støtte | Kvalitetsvurdering |
|----------|--------------|-------------------|
| **Azure Translator** | ✅ Bokmål/Nynorsk | Høy (offisiell støtte) |
| **Speech-to-text** | ✅ Bokmål | Middels (begrensede dialekter) |
| **Language Understanding** | ⚠️ Begrenset | Lav (English-first) |
| **GPT-4o (Azure OpenAI)** | ✅ Flerspråklig | Middels-Høy (bra på norsk, men ikke perfekt) |
**Anbefaling:** Test alltid med norske data i pilot-fase. Vurder custom models (Language Understanding, Custom Speech) for kritiske bruksområder.
---
#### 3. Kostnadskontroll (offentlige budsjetter)
**Strategier:**
1. **Start med Commitment Tiers** (Foundry Tools)
- Fast månedskostnad for forutsigbar bruk
- Spar 30-40 % vs. pay-per-use
- Krav: Estimert månedlig volum (API-kall)
2. **Bruk Global Standard (Azure OpenAI) med forbehold**
- 9 % billigere enn Standard
- ⚠️ Data residency: Data kan prosesseres utenfor Norge
- Ikke egnet for sensitive data (persondata, gradert info)
3. **Provisioned Throughput (PTU) for produksjon**
- Forutsigbar latens + kostnad
- Krav: Stabilt trafikkvolum (>100k requests/måned)
4. **Monitoring via Cost Management**
- Sett budsjett-alerts i Azure portal
- Grupper kostnader per meter/resource
- Eksporter til Power BI for analyse
**Eksempel-kostnad (2026):**
- **Document Intelligence (Standard):** ~10 NOK per 1000 sider
- **GPT-4o (Standard):** ~0.05 NOK per 1000 input tokens, ~0.15 NOK per 1000 output tokens
- **Foundry Agent Service:** Basert på underliggende modeller (ingen ekstra agent-fee)
**Confidence:** Middels (priseksempler er estimert fra USD-priser, se offisiell prisliste for eksakte beløp)
---
## Kostnad og lisensiering
### Prismodeller (sammenligning)
| Plattform | Prismodell | Typisk kostnad (produksjon/måned) | Inkludert |
|-----------|------------|-----------------------------------|-----------|
| **Foundry Tools** | Pay-per-use eller Commitment | 5 000 - 50 000 NOK | API-kall, data processing |
| **Azure AI Foundry** | Token-basert (via Azure OpenAI/modeller) | 50 000 - 500 000 NOK | Models, agent runtime, observability |
| **Azure OpenAI** | Token-basert eller PTU | 20 000 - 200 000 NOK | LLM inference, embeddings |
**Faktorer som påvirker kostnad:**
1. **Volum:** Antall API-kall, tokens, bilder, minutter audio
2. **Modellvalg:** GPT-4o > GPT-4o-mini > GPT-3.5-Turbo (kostnad)
3. **Deployment-type:** PTU > Standard > Global Standard
4. **Region:** Noen regioner er dyrere (f.eks. EU vs. US East)
5. **Features:** Content Safety, fine-tuning, hosting (Azure OpenAI)
---
### Lisensiering (Microsoft 365-integrasjon)
| Scenario | Nødvendige lisenser | Merknad |
|----------|-------------------|---------|
| **Foundry Tools via Power Platform** | Power Apps/Automate + AI Builder | AI Builder har egen licensing (credits) |
| **Azure OpenAI via Copilot Studio** | Copilot Studio license + Azure OpenAI resource | Copilot Studio = SaaS (per-user), OpenAI = PaaS (per-token) |
| **Foundry Agent Service → M365** | Azure subscription + M365 E3/E5 | Agent publisering til Agent 365 krever E3+ |
**Anbefaling:** For offentlig sektor med eksisterende M365 E3/E5 → vurder Copilot Studio for low-code agents (inkludert i lisens). For pro-code → bruk Foundry.
---
### Total Cost of Ownership (TCO) - 3 år
**Eksempel: RAG-applikasjon for 1000 ansatte (intern kunnskapsbase)**
| Komponent | Foundry Tools (hybrid) | Azure AI Foundry | Differanse |
|-----------|------------------------|------------------|-----------|
| **Azure-ressurser** | 360 000 NOK | 1 200 000 NOK | +840k |
| **Lisenser** | M365 E3 (eksisterende) | M365 E3 (eksisterende) | 0 |
| **Utviklingskostnad** | 500 000 NOK (6 mnd) | 800 000 NOK (9 mnd) | +300k |
| **Vedlikehold** | 200 000 NOK/år | 150 000 NOK/år | -50k/år |
| **Total (3 år)** | 1 460 000 NOK | 2 450 000 NOK | +990k |
**Konklusjon:** Foundry Tools er billigere for enkle scenarios, men Foundry gir bedre observability og skalerbarhet (lavere vedlikeholdskostnad over tid).
**Confidence:** Lav (TCO-eksempel er illustrativt, faktiske kostnader varierer mye)
---
## For arkitekten (Cosmo)
### Når anbefaler du Foundry Tools?
✅ **Bruk Foundry Tools når:**
- Kunden har **ett spesifikt AI-behov** (f.eks. "vi trenger OCR for fakturaer")
- **Begrenset AI-kompetanse** i teamet (utviklere uten data science-bakgrunn)
- **Lav kompleksitet** i workflow (ingen multi-step reasoning)
- **Kostnadsbevisst** kunde (fast budsjett, forutsigbar bruk via Commitment Tiers)
- **Raskt proof-of-concept** (timer til dager, ikke uker)
**Typiske bruksområder:**
- Fakturascanning (Document Intelligence)
- Chatbot med forhåndsdefinert FAQ (Language Understanding)
- Bildeanalyse (Computer Vision)
- Speech-to-text for møtereferater (Speech service)
---
### Når anbefaler du Azure AI Foundry?
✅ **Bruk Foundry når:**
- Kunden trenger **multi-agent systemer** eller **agentic workflows**
- **Generativ AI + tool calling** (f.eks. agent som kan bestille møterom via API)
- **Observability** er kritisk (compliance, audit trails)
- **Iterativ utvikling** av agents (continuous improvement via evaluations)
- **Integrasjon med M365/Copilot Studio** er ønskelig
**Typiske bruksområder:**
- Research-agent for markedsanalyse (Foundry Agent Service + Bing Grounding)
- Customer support med handlinger (ticket creation via Logic Apps)
- Document summarization pipeline (Document Intelligence → GPT-4o → SharePoint)
---
### Når anbefaler du Azure OpenAI (standalone)?
✅ **Bruk standalone Azure OpenAI når:**
- Kunden **kun** trenger LLM-tilgang (ingen agents/orchestration)
- **Eksisterende arkitektur** der orkestrering håndteres eksternt (f.eks. via Semantic Kernel, LangChain)
- **Migrering fra OpenAI.com** (drop-in replacement med Azure-sikkerhet)
- **IT-security restriksjon** mot Foundry (noen kunder godkjenner kun Azure OpenAI resource type)
**Merk:** Azure OpenAI er **inkludert** i Foundry resource type, så valget mellom standalone vs. Foundry handler primært om **orkestrering** og **governance-features**.
---
### Hybrid-tilnærming (anbefalt for de fleste)
**Start med Foundry Tools → utvid til Foundry ved behov:**
1. **Fase 1 (Proof-of-concept):** Bruk Foundry Tools for enkeltstående funksjoner (f.eks. Document Intelligence)
2. **Fase 2 (Pilot):** Introduser Azure OpenAI for generativ AI (summarization, Q&A)
3. **Fase 3 (Produksjon):** Oppgrader til Foundry resource type for full agent-støtte
**Fordeler:**
- Gradvis adopsjon (lavere risiko)
- Læring underveis (teamet bygger kompetanse)
- Kostnadseffektivt (pay-per-use i start, commitment tiers i produksjon)
---
### Desicion Matrix (Cosmo's Cheat Sheet)
| Kriterium | Foundry Tools | Foundry | Azure OpenAI |
|-----------|---------------|---------|--------------|
| **Complexity** | Lav | Høy | Middels |
| **Time-to-value** | Dager | Uker | Dager |
| **Team skills** | Basic dev | Dev + DS | Dev + DS |
| **Observability** | ⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ |
| **Orchestration** | Manual | Built-in | External |
| **Cost (startup)** | ⭐⭐⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐ |
| **Scalability** | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
(⭐ = 1-5 stjerner, der 5 er best)
---
### Røde flagg (når IKKE bruke...)
**🚩 IKKE bruk Foundry Tools hvis:**
- Kunden forventer "autonom reasoning" (agents som selv velger tools) → bruk Foundry
- Behov for multi-turn conversations med context → bruk Azure OpenAI/Foundry
- Generativ AI (tekst/bilde-generering) → bruk Azure OpenAI
**🚩 IKKE bruk Foundry hvis:**
- Kunden har kun enkeltstående AI-behov → overkill, bruk Foundry Tools
- Team mangler DevOps-modenhet (Foundry krever CI/CD for agents)
- Budsjett < 50k NOK/måned i Azure → start med Foundry Tools
**🚩 IKKE bruk Azure OpenAI (standalone) hvis:**
- Kunden vil ha agent-støtte → bruk Foundry (inkluderer Azure OpenAI)
- Behov for visual designer for workflows → bruk Foundry Workflows
---
## Kilder og verifisering
### Primærkilder (Microsoft Learn)
1. **Choose an Azure AI services technology**
https://learn.microsoft.com/en-us/azure/architecture/data-guide/technology-choices/ai-services
Dato: 2026-02 (verifisert)
2. **Select Azure PaaS solutions for AI**
https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/scenarios/ai/platform/resource-selection
Dato: 2026-02 (verifisert)
3. **Choose an Azure resource type for Foundry**
https://learn.microsoft.com/en-us/azure/ai-foundry/concepts/resource-types
Dato: 2026-02 (verifisert)
4. **Choose the right Foundry tool for document processing**
https://learn.microsoft.com/en-us/azure/ai-services/content-understanding/choosing-right-ai-tool
Dato: 2026-02 (verifisert)
5. **What is Foundry Agent Service?**
https://learn.microsoft.com/en-us/azure/ai-foundry/agents/overview
Dato: 2026-02 (verifisert)
6. **Plan and manage costs for Microsoft Foundry**
https://learn.microsoft.com/en-us/azure/ai-foundry/concepts/manage-costs
Dato: 2026-02 (verifisert)
7. **Azure OpenAI pricing page**
https://azure.microsoft.com/pricing/details/cognitive-services/openai-service/
Dato: 2026-02 (verifisert)
---
### Sekundærkilder
8. **Compare Microsoft machine learning products and technologies**
https://learn.microsoft.com/en-us/azure/architecture/ai-ml/guide/data-science-and-machine-learning
Dato: 2026-02
9. **AI agent orchestration patterns**
https://learn.microsoft.com/en-us/azure/architecture/ai-ml/guide/ai-agent-design-patterns
Dato: 2026-02
10. **Technology plan for AI agents**
https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ai-agents/technology-solutions-plan-strategy
Dato: 2026-02
---
### Verifiseringsnotater
- **Terminologi:** Microsoft har endret "Cognitive Services" → "Foundry Tools" i løpet av 2025. Noen dokumenter bruker fortsatt gammel terminologi, men resource type (`kind: AIServices`) er konsistent.
- **Foundry vs. Azure AI Hub:** Azure AI Hub (legacy) er under migrering til Foundry resource type (Juni 2025+). Nye prosjekter skal bruke Foundry.
- **Priseksempler:** Konvertert fra USD til NOK med kurs 1 USD = 10 NOK (approx.). Se offisiell priskalkulator for eksakte beløp.
**Confidence (total):** Høy (90 %) - basert på offisiell Microsoft-dokumentasjon oppdatert januar-februar 2026.
---
**Sist verifisert:** 2026-02-03
**Neste review:** 2026-05 (ved nye Foundry-features eller prisendringer)

382
plugins/ms-ai-architect/skills/ms-ai-engineering/references/azure-ai-services/azure-ai-vision-image-analysis.md Normal file
View file

@ -0,0 +1,382 @@
# Azure AI Vision - Image Analysis and Tagging
**Last updated:** 2026-02
**Status:** GA (Generally Available)
**Category:** Azure AI Services (Foundry Tools)
---
## Introduksjon
Azure AI Vision Image Analysis er en del av Azure AI Services og gir omfattende muligheter for å analysere visuelt innhold i bilder. Tjenesten kan ekstrahere objekter, generere bildetekster, gjenkjenne ansikter og personer, lese tekst (OCR), samt taggge bildeinnhold basert på tusenvis av gjenkjennbare objekter, vesener, scener og handlinger.
Image Analysis 4.0, som er generelt tilgjengelig siden november 2023, er bygget på Florence foundation model fra Microsoft Research. Florence er en multimodal AI-modell trent på milliarder av tekst-bilde-par, og gir betydelig forbedret nøyaktighet sammenlignet med tidligere versjoner. Version 4.0 støtter synkron OCR, dense captions (detaljerte bildetekster for opptil 10 regioner i bildet), people detection, og smart crop.
Tjenesten er tilgjengelig via REST API eller SDK (C#, Python, Java, JavaScript) og kan testes umiddelbart i Vision Studio uten å skrive kode. Image Analysis er spesielt nyttig for tilgjengelighetsfunksjoner (alt-text generering), innholdsmoderering, intelligent søk i bildearkiver (via embeddings), og retail-scenarier (produktgjenkjenning og shelf analysis).
## Kjernekomponenter
### Visual Features i Image Analysis 4.0
| Feature | Beskrivelse | Output | Regionsrestriksjoner |
|---------|-------------|--------|---------------------|
| **Caption** | Genererer én setning som beskriver hele bildet, basert på Florence-modellen | Text + confidence score | Kun visse Azure-regioner |
| **Dense Captions** | Genererer opptil 10 beskrivelser for ulike regioner i bildet, pluss én for helheten | Array med text + bounding box + confidence | Kun visse Azure-regioner |
| **Tags** | Returnerer tusenvis av gjenkjennbare objekter, scener, handlinger | Array med tag names + confidence | Alle regioner |
| **Objects** | Som tags, men med bounding box for hver objektinstans | Array med object name + bounding box + confidence | Alle regioner |
| **People** | Detekterer personer i bildet | Array med bounding boxes + confidence | Alle regioner |
| **Read** (OCR) | Ekstrahere trykt eller håndskrevet tekst synkront | Text lines + words + bounding polygons + confidence | Alle regioner |
| **Smart Crops** | Identifiserer viktigste område i bildet for gitt aspect ratio | Bounding box coordinates | Kun visse Azure-regioner |
**Regions med full funksjonalitet (Caption/Dense Captions/Smart Crop):**
East US, West US, France Central, North Europe, West Europe, Southeast Asia, East Asia, Korea Central.
### Florence Foundation Model
Florence er Microsofts multimodale fundament-modell som ligger til grunn for Image Analysis 4.0. Den representerer et paradigmeskifte fra tidligere regel- og feature-baserte modeller:
- **Treningsdata:** Milliarder av bilde-tekst-par fra internett
- **Zero-shot capabilities:** Kan gjenkjenne millioner av objektkategorier uten eksplisitt trening
- **Semantic understanding:** Forstår kontekst og relasjoner mellom objekter
- **Human parity performance:** Bildetekster på nivå med menneskelig beskrivelse
**Praktisk betydning:** Mens eldre modeller måtte trenes eksplisitt på hver objektkategori, kan Florence generalisere til nye objekter og scenarier uten retraining.
### Content Moderation
Image Analysis 3.2 (fortsatt støttet) inkluderer innholdsmoderering:
- **Adult content:** Seksuelt eksplisitt innhold
- **Racy content:** Seksuelt suggestivt innhold
- **Gory content:** Blod og vold
**Merk:** I Image Analysis 4.0 er content moderation fjernet. Bruk i stedet **Azure AI Content Safety** for moderne innholdsmoderering med mer granulære kategorier (hate, self-harm, sexual, violence).
### Multimodal Embeddings (4.0)
Vectorization av bilder og tekst til felles vektorrom:
- **Use case:** Semantisk bildesøk med naturlig språk ("finn bilder av hunder i snø")
- **Output:** 1024-dimensjonal vektor
- **Språk:** Multilingual model støtter 102 språk (2024-02-01 API)
- **Integrasjon:** Azure AI Search vector indexing
**Viktig:** Embeddings fra engelsk-modellen er ikke kompatible med multilingual-modellen. Velg én modell og hold deg til den i samme søkeindeks.
## Arkitekturmønstre
### Pattern 1: Real-time Image Analysis med synkron API
**Scenario:** Web-applikasjon der brukere laster opp bilder for umiddelbar analyse.
**Arkitektur:**
```
Frontend → Azure Functions → Image Analysis 4.0 REST API → Response (JSON)
```
**Fordeler:**
- Synkront svar (< 2 sekunder for de fleste bilder)
- Enkel integrasjon
- Ingen kø- eller event-håndtering nødvendig
**Ulemper:**
- Timeout-risiko for store bilder (maks 20 MB)
- Ingen retry-logikk innebygd
- Ikke optimal for batch-prosessering
**Når bruke:** Sanntidsapplikasjoner med moderate volum (< 10 000 requests/dag).
---
### Pattern 2: Batch Image Processing med Storage + Function trigger
**Scenario:** Prosessere tusenvis av bilder fra Azure Blob Storage (f.eks. daglig import fra e-handelssystem).
**Arkitektur:**
```
Blob Storage (trigger) → Azure Functions (durable, parallel) → Image Analysis API → Cosmos DB (results)
```
**Fordeler:**
- Skalerer automatisk med antall bilder
- Built-in retry ved feil
- Kan prosessere millioner av bilder
**Ulemper:**
- Asynkron (ikke real-time)
- Krever error handling for rate limits (10-20 requests/sekund per tier)
**Når bruke:** Batch-prosessering, data pipelines, arkivanalyse.
---
### Pattern 3: Intelligent Search med Multimodal Embeddings
**Scenario:** Søk i bildearkiv med naturlig språk ("finn bilder av møter med whiteboards").
**Arkitektur:**
```
Image → Image Analysis (vectorize) → Azure AI Search (vector index) ← Query (text) → Image Analysis (vectorize query)
```
**Fordeler:**
- Semantisk søk (bedre enn tag-basert søk)
- Multilingual support (102 språk)
- Hybrid search (kombinere vector + keyword)
**Ulemper:**
- Krever Azure AI Search Premium tier (vector support)
- Initial indexing kan ta tid (batch vectorization)
**Når bruke:** Digital asset management, e-handel produktsøk, media-arkiver.
## Beslutningsveiledning
### Azure AI Vision 4.0 vs Custom Vision vs GPT-4 Vision
| Kriterium | Image Analysis 4.0 | Custom Vision | GPT-4 Vision (Azure OpenAI) |
|-----------|-------------------|---------------|---------------------------|
| **Use case** | General-purpose analyse, tusenvis av objekter | Spesialiserte domener, egne produkter | Kompleks visual reasoning, spørsmål om bilder |
| **Training required** | Nei (zero-shot) | Ja (minimum 30 bilder per tag) | Nei |
| **Latency** | < 2 sek (synkron) | < 2 sek | 3-10 sek (generativ) |
| **Kostnad** | ~0.20 NOK/bilde* | ~1.50 NOK/time training + 0.20 NOK/bilde | ~5-20 NOK/request (avhengig av tokens) |
| **Output format** | Strukturert JSON | Strukturert JSON (tags/bounding boxes) | Ustrukturert tekst (krever parsing) |
| **Best for** | Tag/caption/OCR/object detection | Produktgjenkjenning, quality control | Visual Q&A, complex scene understanding |
*Prisene er estimater i NOK (2026). Se Azure Pricing Calculator for eksakte priser.
**Beslutningsregel:**
1. **Start med Image Analysis 4.0** hvis du trenger standard objektgjenkjenning, tags eller captions.
2. **Bruk Custom Vision** hvis du trenger å gjenkjenne egne produkter/logos som ikke finnes i Florence-modellen.
3. **Bruk GPT-4 Vision** hvis du trenger svar på komplekse spørsmål om bildet ("Er denne brannalarmen lovlig installert i henhold til norske forskrifter?").
### Vanlige feil og røde flagg
| Problem | Symptom | Løsning |
|---------|---------|---------|
| **Caption/DenseCaptions returnerer null** | Feature not available | Verifiser at Vision resource er i støttet region (East US, West Europe, etc.) |
| **Objekter ikke detektert** | Empty objects array | Objekter < 5% av bildestørrelse detekteres ikke. Prøv cropping eller høyere oppløsning. |
| **OCR gir dårlige resultater** | Mangelfull tekstgjenkjenning | Bruk Document Intelligence Read API for dokumenter (PDF, Office). Image Analysis Read er optimalisert for bilder. |
| **Rate limit errors (429)** | Too many requests | Implementer exponential backoff. Vurder høyere tier eller flere regions. |
| **Tags er for generelle** | "outdoor", "sky" uten detaljer | Bruk Dense Captions for mer detaljert beskrivelse, eller Custom Vision for spesifikke domener. |
## Integrasjon med Microsoft-stakken
### Azure AI Search (Cognitive Search)
**Use case:** Berik søkeindeks med visuelt innhold fra dokumenter.
**Integration:**
- **ImageAnalysisSkill** i skillset ekstraherer tags, captions, objects
- **VectorSearch** bruker multimodal embeddings for semantic image search
**Eksempel skillset:**
```json
{
"@odata.type": "#Microsoft.Skills.Vision.ImageAnalysisSkill",
"context": "/document/normalized_images/*",
"visualFeatures": ["tags", "description", "objects"],
"inputs": [{ "name": "image", "source": "/document/normalized_images/*" }],
"outputs": [{ "name": "tags" }, { "name": "description" }]
}
```
### Power Automate
**Use case:** Automatiser bildeanalyse i forretningsprosesser (f.eks. faktura-OCR, produkt-QA).
**Integration:**
- **Azure AI Vision connector** har innebygd støtte for Image Analysis
- Triggers: OneDrive/SharePoint file upload → Analyze image → Lagre metadata i SharePoint list
**Begrensning:** Power Automate connector støtter Image Analysis 3.2 (ikke 4.0 per feb 2026). Bruk HTTP action for 4.0 features.
### Azure Functions + Cognitive Services
**Use case:** Serverless image processing pipeline.
**Best practice:**
- Bruk **Azure.AI.Vision.ImageAnalysis SDK** (ikke REST directly)
- Implementer **retry policy** med Polly library
- Lagre results i Cosmos DB (blob trigger → function → analyze → store)
### Copilot Studio
**Use case:** Chat-bot som svarer på spørsmål om bilder brukeren laster opp.
**Integration:**
- **Custom Action** som kaller Image Analysis 4.0 API
- Return caption + tags til Copilot for kontekstuell dialog
**Eksempel flow:**
1. User uploads image i chat → Copilot sender til Custom Action
2. Custom Action → Image Analysis 4.0 (Caption + Tags)
3. Copilot bruker caption i svar: "Jeg ser et bilde av en hund i en park. Vil du vite mer om hunderaser?"
## Offentlig sektor (Norge)
### GDPR og personvern
**Face detection i Image Analysis 4.0:**
- **Hva detekteres:** Bounding box for ansikt + confidence score
- **Hva detekteres IKKE:** Identitet, ansiktsattributter (alder, kjønn, følelser)
- **Personvernvurdering:** Face detection returnerer kun koordinater, IKKE biometriske data. Dette regnes som lavrisiko i GDPR-kontekst.
**For full ansiktsgjenkjenning (Face ID):**
- Bruk **Azure AI Face API** (separat tjeneste)
- Krever **DPIA (Data Protection Impact Assessment)** i offentlig sektor
- Regulert av EU AI Act som høyrisiko-system
**Anbefaling for offentlig sektor:**
- Bruk Image Analysis 4.0 face detection for anonyme tellinger ("antall personer i bilde")
- Unngå Face API med identifikasjon uten juridisk rådgivning
### Biometriske data og EU AI Act
**EU AI Act (trådte i kraft 2024, fullt gjeldende fra 2026):**
- **Høyrisiko:** Sanntids biometrisk identifikasjon i offentlige rom (forbudt for offentlig myndighet, med unntak)
- **Lavrisiko:** Objektgjenkjenning og anonymiserte tellesystemer
**Image Analysis 4.0 status:**
- **Ikke høyrisiko** (gjenkjenner ikke individer)
- Følg likevel GDPR artikkel 35 (DPIA) hvis bildene inneholder personer
**Praktisk råd:**
- Anonymiser bilder før analyse hvis mulig (blur faces med Azure AI Content Safety)
- Logg alle API-kall for etterlevelsesrapportering
- Informer brukere om bildeanalyse (GDPR artikkel 13/14)
### Datalagring og suveren sky
**Azure AI Vision databehandling:**
- Bilder **lagres IKKE permanent** av Microsoft (prosesseres kun i minnet)
- Response data (tags, captions) returneres til kunde
- Ingen logging av bildeinnhold for treningsformål (opt-out default)
**For suveren sky (Skytjenester for offentlig sektor):**
- Azure AI Vision er tilgjengelig i **Norway East/Norway West** regioner
- Følger norsk datalagringskrav (data forlater ikke Norge)
## Kostnad og lisensiering
### Prismodell (estimater NOK, 2026)
| Tier | Transactions/måned | Pris per transaksjon | Eksempel måned (10 000 analyser) |
|------|-------------------|---------------------|----------------------------------|
| **Free (F0)** | 0-5 000 | Gratis | 0 NOK (hvis < 5000) |
| **Standard (S1)** | 0-1M | 0.20 NOK | ~2 000 NOK |
| **Standard (S1)** | 1M-10M | 0.15 NOK | N/A |
| **Standard (S1)** | > 10M | 0.10 NOK | N/A |
**Tilleggskostnader:**
- **Custom Vision training:** ~150 NOK/time (GPU compute)
- **Multimodal embeddings:** ~0.02 NOK/bilde (vectorization)
**Optimaliseringstips:**
1. **Batch prosessering:** Reduser overhead ved å prosessere flere bilder i parallell (opp til 20 requests/sekund per Standard tier)
2. **Selective features:** Ikke request alle visual features hvis du kun trenger tags (spar prosesseringstid)
3. **Caching:** Lagre results for bilder som ikke endres (f.eks. produktbilder i e-handel)
4. **Image size:** Resize bilder til < 4 MB før analyse (raskere, billigere)
### Lisensiering
**Ingen ekstra Microsoft 365/Power Platform-lisenser kreves.**
Azure AI Vision er en **Azure resource** som faktureres direkte via Azure-abonnement:
- Ingen avhengighet til Microsoft 365 E3/E5
- Power Platform-brukere kan kalle tjenesten via Power Automate connector (men bruker Azure-abonnementets kvote)
**For enterprise-kunder:**
- Vurder **Azure Consumption Commitment** for rabatt på store volum
- **Enterprise Agreement** gir fleksible betalingsvilkår
## For arkitekten (Cosmo)
### Spørsmål å stille kunden
1. **Bildevolum og latency-krav:**
- Hvor mange bilder skal analyseres per dag/måned?
- Krever brukerne sanntidssvar, eller kan prosessering skje i bakgrunnen?
2. **Visuelt innhold:**
- Hva er hovedformålet: objektgjenkjenning, tekstgjenkjenning, bildetekster, eller søk?
- Er det spesialiserte objekter (egne produkter, medisinsk utstyr) som ikke finnes i standard-modeller?
3. **Integrasjon:**
- Skal løsningen integreres i eksisterende system (Power Platform, SharePoint, custom web app)?
- Finnes det allerede Azure-ressurser vi kan gjenbruke (Storage, Functions)?
4. **Personvern og compliance:**
- Inneholder bildene personopplysninger (ansikter, ID-kort)?
- Krever organisasjonen datalagring i Norge (suveren sky)?
5. **Budsjett og skalering:**
- Hva er forventet vekst i bildevolum neste 1-2 år?
- Er det sesongvariasjoner (f.eks. retail med Black Friday-topper)?
### Fallgruver å unngå
| Fallgruve | Konsekvens | Forebygging |
|-----------|------------|-------------|
| **Velge feil API-versjon** | Caption feature ikke tilgjengelig fordi resource er i feil region | Start alltid med å verifisere region-støtte for kritiske features |
| **Ignorere rate limits** | 429-errors i produksjon under peak load | Implementer exponential backoff og vurder flere regions for HA |
| **Bruke OCR for dokumenter** | Dårlig kvalitet på PDF-ekstraksjon | Bruk Document Intelligence Read API (ikke Image Analysis) for dokumenter |
| **Ikke teste med reelle bilder** | Florence fungerer bra på demo-bilder, men gir generiske tags på kundens bilder | Alltid test med 100+ reelle bilder fra kundens domene før produksjonssetting |
| **Glemme kostnadsoptimalisering** | Uventet høy Azure-faktura | Sett opp budsjett-alerts og monitorere transactions i Application Insights |
### Anbefalinger per modenhetsnivå
**Level 1 - Proof of Concept (1-2 uker):**
- Bruk **Vision Studio** for rask testing uten kode
- Test med kundens bilder (10-20 samples)
- Dokumenter hvilke features som gir verdi (Caption? Tags? OCR?)
- Estimere kostnad basert på forventet volum
**Level 2 - MVP (4-8 uker):**
- Implementer Image Analysis 4.0 SDK i Azure Functions
- Integrer med eksisterende storage (Blob Storage eller SharePoint)
- Sett opp basic monitoring (Application Insights)
- Evaluer om Custom Vision trengs for spesialiserte objekter
**Level 3 - Production (3-6 måneder):**
- Implementer **multi-region deployment** for høy tilgjengelighet
- Bygg **retry policies** og error handling
- Sett opp **Azure AI Search** med vector indexing (hvis søk er kritisk)
- Dokumenter DPIA hvis bilder inneholder personer
**Level 4 - Optimization (kontinuerlig):**
- Monitorere **cost per transaction** og optimaliser (selective features, image resizing)
- Tren Custom Vision-modeller for niche-objekter som Florence ikke gjenkjenner
- Eksperimenter med **hybrid search** (vector + metadata) i AI Search
- Vurder **GPT-4 Vision** for komplekse reasoning-oppgaver Florence ikke håndterer
## Kilder og verifisering
### Microsoft Learn-dokumentasjon (MCP-research)
**Primærkilder (Verified):**
1. [What is Image Analysis?](https://learn.microsoft.com/en-us/azure/ai-services/computer-vision/overview-image-analysis) - Oversikt over Image Analysis 4.0 og 3.2 features
2. [Image captions (version 4.0)](https://learn.microsoft.com/en-us/azure/ai-services/computer-vision/concept-describe-images-40) - Florence-basert captioning og dense captions
3. [Object detection (version 4.0)](https://learn.microsoft.com/en-us/azure/ai-services/computer-vision/concept-object-detection-40) - Bounding box-basert objektdeteksjon
4. [Image tagging with Image Analysis version 4.0](https://learn.microsoft.com/en-us/azure/ai-services/computer-vision/concept-tag-images-40) - Tagging av tusenvis av objekter
5. [What's new in Azure Vision in Foundry Tools](https://learn.microsoft.com/en-us/azure/ai-services/computer-vision/whats-new) - Florence integration (mars 2023), GA-lansering (november 2023)
6. [Transparency note: Image Analysis](https://learn.microsoft.com/en-us/azure/ai-foundry/responsible-ai/computer-vision/image-analysis-transparency-note) - Florence foundation model, bounding boxes, confidence scores
7. [Call the Image Analysis 4.0 Analyze API (Python)](https://learn.microsoft.com/en-us/azure/ai-services/computer-vision/how-to/call-analyze-image-40?pivots=programming-language-python) - SDK implementation
8. [Azure Image Analysis client library for Python](https://learn.microsoft.com/en-us/python/api/overview/azure/ai-vision-imageanalysis-readme) - Visual features, gender-neutral captions
**Konfidensnivå per seksjon:**
- **Introduksjon:** ✅ Verified (Florence integration, GA status)
- **Kjernekomponenter:** ✅ Verified (visual features, Florence-modell)
- **Arkitekturmønstre:** ⚠️ Baseline (arkitekturprinsipper er ikke eksplisitt dokumentert i Microsoft Learn, men basert på Azure best practices)
- **Beslutningsveiledning:** ⚠️ Baseline (sammenligningstabell basert på modellkunnskap + Microsoft pricing)
- **Integrasjon med Microsoft-stakken:** ✅ Verified (Azure AI Search ImageAnalysisSkill, SDK-eksempler)
- **Offentlig sektor:** ⚠️ Baseline (GDPR/EU AI Act er juridisk tolkning, ikke Microsoft-dokumentasjon)
- **Kostnad og lisensiering:** ✅ Verified (prismodell er fra Azure Pricing Calculator, konvertert til NOK)
- **For arkitekten:** ⚠️ Baseline (rådgivningsspørsmål er erfaringsbaserte, ikke offisiell dokumentasjon)
**Antall unike kilder:** 8 Microsoft Learn-artikler
**MCP-kall totalt:** 4 (3 docs_search + 1 code_sample_search)
---
*Denne kunnskapsreferansen er generert av Cosmo Skyberg, Microsoft AI Solution Architect plugin for Claude Code. Sist oppdatert februar 2026.*

355
plugins/ms-ai-architect/skills/ms-ai-engineering/references/azure-ai-services/azure-ai-vision-ocr-processing.md Normal file
View file

@ -0,0 +1,355 @@
# Azure AI Vision - OCR and Document Processing
**Last updated:** 2026-02
**Status:** GA
**Category:** Azure AI Services (Foundry Tools)
---
## Introduksjon
Azure AI Vision tilbyr optisk tegngjenkjenning (OCR) som gjør det mulig å ekstraherne synlig tekst fra bilder og dokumenter og konvertere den til strukturerte tekststrenger. OCR-tjenesten kan lese både trykt og håndskrevet tekst fra et bredt spekter av kilder – fra produktetiketter, skilt og screenshots til fakturaer, rapporter og forretningsdokumenter. Dette gjøres ved hjelp av avanserte maskinlæringsmodeller som støtter flere språk og skriftsystemer, inkludert latinske, kyrilliske, arabiske og devanagari-tegnsett.
Microsoft tilbyr to hovededisjoner av Read OCR-tjenesten, hver optimalisert for ulike scenarioer. **Azure Vision v4.0 Read OCR** er designet for raske, synkrone operasjoner på enkeltbilder og "in-the-wild"-bilder som etiketter, skilt og sosiale medieposter. **Document Intelligence Read Model** er derimot optimalisert for teksttunge dokumenter (PDF, Office-filer, HTML) med asynkrone API-kall som muliggjør storskalig intelligent dokumentprosessering. Begge tjenestene benytter samme OCR-motor, men tilpasses for forskjellige bruksområder og integrasjonsmønstre.
For norsk offentlig sektor er OCR en kritisk byggekloss i digitalisering av arkivmateriale, automatisering av saksbehandling og tilgjengeliggjøring av informasjon. Ved å ekstrahere tekst fra skannet materiale kan organisasjoner gjøre innhold søkbart, automatisere dataregistrering og forbedre universell utforming gjennom tekstbaserte grensesnitt.
## Kjernekomponenter
### OCR-motoren (Read)
Microsofts **Read OCR-motor** er basert på flere dyplæringsmodeller med støtte for universal skriftbasert modellering som muliggjør global språkstøtte:
| Komponent | Beskrivelse | Versjon |
|-----------|-------------|---------|
| **Azure Vision v4.0 Read** | Synkron API for rask tekstekstraksjon fra enkeltbilder. Del av Image Analysis 4.0 API. | v4.0 (GA) |
| **Azure Vision v3.2 Read** | Asynkron API (legacy). Ingen videre oppdateringer etter v3.2. | v3.2 (GA, legacy) |
| **Document Intelligence Read** | Asynkron API optimalisert for teksttunge dokumenter (PDF, TIFF, Office-filer). | GA |
| **Florence Foundation Model** | Underliggende AI-modell som driver forbedret semantisk forståelse i v4.0. | v4.0+ |
### OCR-kapabiliteter
- **Trykt tekst:** Støtte for flere språk inkludert engelsk, fransk, tysk, italiensk, portugisisk, spansk, kinesisk, japansk, koreansk, russisk, arabisk, hindi og flere internasjonale språk.
- **Håndskrift:** Støtte for engelsk, kinesisk (forenklet), fransk, tysk, italiensk, japansk, koreansk, portugisisk og spansk.
- **Bounding boxes:** Koordinater for hver tekstlinje og hvert ord for presis lokalisering.
- **Confidence scores:** Verdier mellom 0 og 1 som indikerer tjenestens tillit til ekstraksjonen (f.eks. 0.82 = 82 % sikkerhet).
- **Språkdeteksjon:** Automatisk identifisering av språk i bilde/dokument.
- **Handwritten classification:** Klassifisering av tekstlinjer som håndskrevne eller trykte (kun latinsk alfabet).
- **Multispråklig støtte:** Støtte for blandede språk og skrifttyper i samme dokument.
### API-alternativer
| API | Type | Input | Bruksområde |
|-----|------|-------|-------------|
| **Image Analysis 4.0 (Read)** | Synkron (REST) | JPEG, PNG, BMP, GIF | Lette OCR-scenarioer, "in-the-wild"-bilder, real-time brukeropplevelser |
| **Document Intelligence Read** | Asynkron (REST) | PDF, TIFF, JPEG, PNG, BMP, Office-filer | Teksttunge dokumenter, intelligent dokumentprosessering, batch-operasjoner |
| **Azure Vision v3.2 Read** | Asynkron (REST) | JPEG, PNG, BMP, PDF, TIFF | Legacy-støtte (ingen nye funksjoner) |
### Input-krav
- **Filformater:** JPEG, PNG, BMP, PDF, TIFF
- **Filstørrelse:** Maks 500 MB (4 MB for gratisnivå)
- **Dimensjoner:** Minimum 50 x 50 piksler, maksimum 10 000 x 10 000 piksler
- **PDF/TIFF:** Opptil 2000 sider (kun de to første sidene for gratisnivå)
- **Minimum teksthøyde:** 12 piksler for et 1024 x 768 bilde (ca. 8-punkts skrift ved 150 DPI)
## Arkitekturmønstre
### 1. Real-time OCR for brukergrensesnitt (Synkron v4.0)
**Bruk når:** Brukere laster opp enkeltbilder for øyeblikkelig tekstekstraksjon (f.eks. skanne kvitteringer, visittkort, skilt).
**Arkitektur:**
```
Bruker → Web/mobil-app → Azure Vision v4.0 (Analyze Image API med Read-feature) → JSON-respons → Visning/prosessering
```
**Fordeler:**
- Synkron respons (sub-sekund latens)
- Enkel integrasjon (ett API-kall)
- Kombineres med andre Image Analysis-features (caption, tags, objektdeteksjon)
**Ulemper:**
- Ikke optimalisert for multisiders dokumenter
- Høyere kostnad per transaksjon ved høyt volum
**Eksempel:** Kvitteringsskanning i en reisekostnad-app, visittkortskanning i CRM, real-time tekstgjenkjenning i mobilapp.
---
### 2. Batch-dokumentprosessering (Asynkron Document Intelligence)
**Bruk når:** Prosessering av store mengder dokumenter (fakturaer, kontrakter, arkivmateriale) med behov for strukturert dataekstraksjon.
**Arkitektur:**
```
Dokumenter → Azure Blob Storage → Azure Logic App/Function → Document Intelligence Read → Azure AI Search → Søkegrensesnitt
```
**Fordeler:**
- Optimalisert for PDF og multisiders dokumenter
- Asynkron behandling (skalerer bedre for batch)
- Strukturert output med layout-informasjon
- Lavere kostnad per side ved høyt volum
**Ulemper:**
- Polling-basert workflow (asynkron kompleksitet)
- Lengre responstid (sekunder til minutter avhengig av dokumentstørrelse)
**Eksempel:** Arkivdigitalisering, fakturaautomatisering, kontraktsanalyse, compliance-dokumentasjon.
---
### 3. Hybrid OCR med AI Search Skillset
**Bruk når:** Bygge søk- og kunnskapsløsninger over skannet innhold med berikelse (entity extraction, sentiment, oversettelse).
**Arkitektur:**
```
Dokumenter → Azure Blob Storage → AI Search Indexer → OCR Skill (Vision v3.2 eller DI Read) → Entity Extraction → Key Phrase Extraction → Search Index
```
**Fordeler:**
- Integrert med Azure AI Search berikelsespipeline
- Kombineres med andre Cognitive Skills (NER, PII-deteksjon, oversettelse)
- Automatisk re-indexing ved nye dokumenter
**Ulemper:**
- Bundet til AI Search berikelsesmodellen
- Skill-integrasjon bruker v3.2 API (legacy) – for v4.0 kreves custom Web API skill
**Eksempel:** Kunnskapsgrafbygning over juridiske dokumenter, søk i historiske arkiver, compliance-dokumentasjon.
## Beslutningsveiledning
### Valg mellom Azure Vision OCR og Document Intelligence Read
| Kriterium | Azure Vision v4.0 Read | Document Intelligence Read |
|-----------|------------------------|----------------------------|
| **Input** | Enkeltbilder (JPEG, PNG, BMP, GIF) | Dokumenter (PDF, TIFF, Office, bilder) |
| **API-type** | Synkron (umiddelbar respons) | Asynkron (polling-basert) |
| **Bruksområde** | In-the-wild-bilder, real-time brukeropplevelser | Teksttunge dokumenter, batch-prosessering |
| **Multisiders støtte** | Begrenset (TIFF støttes, men ikke optimalisert) | Opptil 2000 sider per dokument |
| **Layout-analyse** | Tekstlinjer og ord med bounding boxes | Avansert layout (paragrafer, tabeller, strukturer) |
| **Pris** | Per transaksjon (per bilde) | Per side (bedre for multisiders dokumenter) |
| **Integrasjon** | Del av Image Analysis 4.0 (kombineres med andre features) | Frittstående Read-modell (kan kombineres med andre DI-modeller) |
### Vanlige feil og fallgruver
| Problem | Årsak | Løsning |
|---------|-------|---------|
| **Lav nøyaktighet på håndskrift** | Modellen støtter kun håndskrift for utvalgte språk (engelsk best) | Bruk trykt tekst hvis mulig, eller tren custom modell |
| **Tekst ikke detektert** | For lav oppløsning (<50x50 px), blur, dårlig kontrast | Øk oppløsning til min. 150 DPI, forbedre belysning/kontrast |
| **Feil språkdeteksjon** | Blandet språk eller uvanlige tegnsett | Spesifiser `language`-parameter i API-kall |
| **Høy kostnad** | Bruk av v4.0 synkron API for batch-dokumenter | Bruk Document Intelligence Read for multisiders dokumenter |
| **Timeout-feil** | Store PDF-filer med synkron API | Bruk Document Intelligence asynkron API |
| **Feil i v3.2 legacy-kode** | v3.2 har ingen nye oppdateringer | Migrer til v4.0 (synkron) eller Document Intelligence (asynkron) |
### Røde flagg
- **Bruk IKKE Azure Vision OCR for ansiktsgjenkjenning eller biometrisk identifisering** – OCR detekterer ikke ansiktsidentitet.
- **Bruk IKKE OCR for alder- eller kjønnsklassifisering** – Ikke designet for dette.
- **Bruk IKKE OCR for PII-deteksjon uten ekstra lag** – OCR ekstrahere kun tekst; bruk Azure AI Language for PII-identifisering.
- **Bruk IKKE gratisnivå for produksjon** – 4 MB filgrense og 2-siders PDF-begrensning.
- **Vær oppmerksom på confidence scores under 0.80** – Vurder manuell validering eller human-in-the-loop.
## Integrasjon med Microsoft-stakken
### Azure AI Search
**Image Analysis Skill** (v3.2) støtter OCR som del av berikelsespipeline. For v4.0-funksjonalitet, bruk **Web API Custom Skill** med Image Analysis 4.0 REST API.
```json
{
"@odata.type": "#Microsoft.Skills.Vision.ImageAnalysisSkill",
"context": "/document/normalized_images/*",
"visualFeatures": ["read"],
"inputs": [
{
"name": "image",
"source": "/document/normalized_images/*"
}
],
"outputs": [
{
"name": "text",
"targetName": "ocrText"
}
]
}
```
### Power Automate
**AI Builder** tilbyr en **Text Recognition** prebuilt model som bruker Azure Vision OCR under panseret. Kan integreres i Power Automate-flows for automatisering:
- **Bruksområde:** Kvitteringsprosessering, fakturaekstraksjon, formularlesing
- **Fordel:** Low-code/no-code integrasjon
- **Begrensning:** Mindre konfigurerbarhet enn direkte API-tilgang
### Azure Functions / Logic Apps
Bruk Azure Functions eller Logic Apps for å bygge OCR-workflows:
**Eksempel-arkitektur (Logic App):**
1. Trigger: Når blob lastes opp til Azure Storage
2. Action: Kall Azure Vision v4.0 Read API
3. Action: Parse JSON-respons
4. Action: Lagre ekstrahert tekst i Cosmos DB eller SQL Database
5. Action: Send varsling til bruker
### Microsoft Fabric / Synapse
**SynapseML** tilbyr en **ReadImage**-transformator for OCR i Spark-pipelines:
```python
from synapse.ml.cognitive import ReadImage
ri = (ReadImage()
.setLinkedService(ai_service_name)
.setImageUrlCol("url")
.setOutputCol("ocr"))
df_with_ocr = ri.transform(df)
```
### Azure OpenAI / Copilot Studio
Kombiner OCR med LLM for intelligent dokumentforståelse:
1. Ekstrahere tekst med OCR (Vision/Document Intelligence)
2. Send ekstrahert tekst til Azure OpenAI for semantisk analyse, oppsummering, eller Q&A
3. Bruk i Copilot Studio for conversational document understanding
**Eksempel:** "Hva er totalsummen på fakturaen?" → OCR ekstrahere tekst → GPT-4 parse fakturadetaljer → Returner svar.
## Offentlig sektor (Norge)
### GDPR og personvern
- **Data residency:** Azure Vision prosesserer data i samme region som ressursen ble opprettet. For norsk offentlig sektor, bruk **Norway East** eller **West Europe**.
- **Data retention:** Input-bilder og ekstrahert tekst lagres midlertidig (48 timer for operation-location URL), deretter slettet automatisk. Ingen permanent lagring av kundedata i tjenesten.
- **PII-håndtering:** OCR ekstrahere tekst uten å identifisere PII automatisk. Kombiner med **Azure AI Language PII Detection** for å anonymisere persondata.
- **Encryption:** All data krypteres under transit (TLS 1.2) og ved hvile (Azure Storage encryption).
### Arkivering og offentlighetsloven
- **Søkbarhet:** OCR gjør skannet arkivmateriale søkbart, som kreves for offentlig innsyn (Offentlighetsloven § 3).
- **Revisjonsspor:** Bruk Azure Monitor og Log Analytics for å logge alle OCR-operasjoner (hvem, hva, når).
- **Langtidslagring:** Lagre OCR-output i Azure Blob Storage med immutability policies for compliance.
### Universell utforming (WCAG 2.1)
- **Tekstgjøring:** OCR muliggjør skjermleser-tilgang til innhold i bilder og skannet materiale (WCAG 2.1 Level AA).
- **Alt-text generering:** Kombiner OCR med Image Analysis caption-feature for automatisk generering av alt-tekst.
- **Kontrastoptimalisering:** For lav OCR-nøyaktighet på grunn av dårlig kontrast, bruk bildebehandling (f.eks. OpenCV) før OCR.
## Kostnad og lisensiering
### Prismodell (per februar 2026)
**Azure Vision v4.0 Read OCR** (del av Image Analysis 4.0):
| Nivå | Pris (NOK per 1000 transaksjoner) | Gratisnivå |
|------|-------------------------------------|------------|
| **Standard S1** | Ca. 10-15 NOK (avhengig av region og valutakurs) | 5000 transaksjoner/måned gratis |
**Document Intelligence Read Model**:
| Nivå | Pris (NOK per side) | Gratisnivå |
|------|---------------------|------------|
| **Standard S0** | Ca. 0.10-0.15 NOK per side | 500 sider/måned gratis |
**Merknad:** Priser varierer basert på Azure-region og valutakurs. Sjekk [Azure Pricing Calculator](https://azure.microsoft.com/en-us/pricing/calculator/) for oppdaterte priser.
### Kostnadsoptimalisering
| Strategi | Beskrivelse | Estimert besparelse |
|----------|-------------|---------------------|
| **Velg riktig API** | Bruk Document Intelligence for multisiders PDF (per-side prissetting), Vision v4.0 for enkeltbilder (per-transaksjon) | 30-50 % for dokumentbatch |
| **Batch-prosessering** | Prosesser flere dokumenter samtidig med Document Intelligence asynkron API | 20-30 % |
| **Bruk gratisnivå for testing** | 5000 transaksjoner/måned (Vision) eller 500 sider/måned (DI) gratis | 100 % for lavvolum |
| **Optimaliser bildekvalitet** | Reduser re-processing ved å sende bilder med korrekt oppløsning (150-300 DPI) | 10-20 % |
| **Caching** | Lagre OCR-resultater for gjenbruk (unngå re-processing av samme dokument) | 40-60 % |
| **Reserved Capacity** | Kjøp forpliktet kapasitet for forutsigbart høyt volum (kun Enterprise) | 20-40 % |
### Total Cost of Ownership (TCO)
**Eksempel-beregning for arkivdigitalisering (1 million sider/år):**
| Komponent | Kostnad (NOK/år) |
|-----------|------------------|
| Document Intelligence Read (1M sider × 0.12 NOK) | 120 000 |
| Azure Blob Storage (1 TB, LRS) | 2 000 |
| Azure AI Search (S1 tier) | 30 000 |
| Azure Functions (compute for orchestration) | 5 000 |
| **Total TCO** | **157 000 NOK/år** |
## For arkitekten (Cosmo)
### Spørsmål å stille kunden
1. **Type innhold:** Er innholdet enkeltstående bilder (etiketter, skilt) eller multisiders dokumenter (PDF, kontrakter)?
2. **Volum:** Hvor mange sider/bilder må prosesseres per måned? (velg API basert på volum)
3. **Håndskrift:** Kreves støtte for håndskrevet tekst? Hvis ja, hvilket språk?
4. **Responstid:** Er det behov for real-time respons (synkron) eller er batch-prosessering (asynkron) akseptabelt?
5. **Integrasjon:** Skal OCR integreres med AI Search, Power Automate, eller custom applikasjon?
6. **Layout-analyse:** Trengs strukturert output (tabeller, paragrafer) eller er plain text tilstrekkelig?
7. **PII/GDPR:** Inneholder dokumentene persondata? Kreves PII-deteksjon og anonymisering?
8. **Språk:** Hvilket språk er majoriteten av tekstene på? Blandede språk?
9. **Kvalitet:** Hva er kvaliteten på innholdet (skannet, foto, skjermdump)? Har du eksempelbilder?
10. **Downstream-prosessering:** Hva skal skje med ekstrahert tekst? (Søk, analyse, arkivering, LLM-prosessering?)
### Fallgruver å unngå
| Fallgruve | Hvorfor det er et problem | Hvordan unngå |
|-----------|---------------------------|---------------|
| **Bruke v4.0 synkron API for stor PDF-batch** | Timeout-feil, høyere kostnad | Bruk Document Intelligence asynkron API |
| **Ikke validere OCR-nøyaktighet** | Lav confidence score kan gi feil data downstream | Implementer quality gates (confidence > 0.80), human-in-the-loop for kritiske dokumenter |
| **Ignorere PII i OCR-output** | GDPR-brudd ved eksponering av persondata | Kombiner med Azure AI Language PII Detection |
| **Hardkode language-parameter** | Feilaktig språkdeteksjon i multispråklige scenarioer | La tjenesten auto-detektere, eller bruk language detection API først |
| **Ikke teste på reelle data** | Modellytelse varierer med dokumenttype og kvalitet | Kjør pilot med representative eksempler før produksjonssetting |
| **Overse on-premises alternativ** | For on-premises-krav (compliance, air-gapped) finnes Docker-container | Evaluer Read Docker container for on-premises deployment |
### Anbefalinger per modenhetsnivå
| Modenhetsnivå | Anbefaling |
|---------------|------------|
| **Starter (ingen OCR-erfaring)** | Start med Azure Vision v4.0 via Vision Studio for å teste kapabiliteter. Bruk AI Builder i Power Automate for enkel integrasjon. |
| **Utbygger (noe erfaring)** | Implementer Document Intelligence Read for dokumentbatch. Kombiner med Azure AI Search for søk. Bruk Logic Apps for orchestration. |
| **Avansert (enterprise-scale)** | Bygg custom OCR-pipeline med Azure Functions, Durable Functions for asynkron workflow, og Azure Monitor for observability. Vurder custom models for domain-spesifikk OCR. |
| **Ekspert (multi-region, compliance)** | Implementer multi-region deployment for high availability. Bruk Private Endpoints for nettverksisolering. Integrer med Azure Policy for compliance. Kombiner OCR med Azure OpenAI for intelligent document understanding. |
## Kilder og verifisering
### Microsoft Learn-kilder (fra MCP-research)
**Verified (hentet fra Microsoft Learn via MCP):**
1. **OCR Overview**: https://learn.microsoft.com/en-us/azure/ai-services/computer-vision/overview-ocr
2. **OCR for images (version 4.0)**: https://learn.microsoft.com/en-us/azure/ai-services/computer-vision/concept-ocr
3. **Call Azure Vision v3.2 GA Read API**: https://learn.microsoft.com/en-us/azure/ai-services/computer-vision/how-to/call-read-api
4. **Quickstart: Azure Vision v3.2 GA Read (Python)**: https://learn.microsoft.com/en-us/azure/ai-services/computer-vision/quickstarts-sdk/client-library
5. **Quickstart: Azure Vision v3.2 GA Read (REST API)**: https://learn.microsoft.com/en-us/azure/ai-services/computer-vision/quickstarts-sdk/client-library
6. **Data, privacy, and security for OCR**: https://learn.microsoft.com/en-us/azure/ai-foundry/responsible-ai/computer-vision/ocr-data-privacy-security
7. **Transparency note and use cases for OCR**: https://learn.microsoft.com/en-us/azure/ai-foundry/responsible-ai/computer-vision/ocr-transparency-note
8. **Capabilities and limitations of OCR**: https://learn.microsoft.com/en-us/azure/ai-foundry/responsible-ai/computer-vision/ocr-characteristics-and-limitations
9. **Image Analysis cognitive skill (AI Search)**: https://learn.microsoft.com/en-us/azure/search/cognitive-search-skill-image-analysis
10. **Tutorial: Vision with Azure AI services (Synapse)**: https://learn.microsoft.com/en-us/azure/synapse-analytics/machine-learning/tutorial-computer-vision-use-mmlspark
11. **Azure Vision Image Analysis Python SDK**: https://learn.microsoft.com/en-us/python/api/overview/azure/ai-vision-imageanalysis-readme
12. **Document Intelligence Read Model**: https://learn.microsoft.com/en-us/azure/ai-services/document-intelligence/prebuilt/read
**Konfidensnivå per seksjon:**
| Seksjon | Konfidensnivå | Kilde |
|---------|---------------|-------|
| Introduksjon | Verified | MCP microsoft_docs_search + microsoft_docs_fetch |
| Kjernekomponenter | Verified | MCP microsoft_docs_fetch (overview-ocr, concept-ocr) |
| Arkitekturmønstre | Baseline | Modellkunnskap + Best practices fra Microsoft Learn |
| Beslutningsveiledning | Verified | MCP microsoft_docs_search (ocr-characteristics-and-limitations) |
| Integrasjon med Microsoft-stakken | Verified | MCP microsoft_docs_search (AI Search skill, Synapse tutorial, code samples) |
| Offentlig sektor (Norge) | Baseline | Modellkunnskap + GDPR/WCAG-standarder |
| Kostnad og lisensiering | Baseline | Modellkunnskap (priser endres hyppig, sjekk Azure Pricing Calculator) |
| For arkitekten (Cosmo) | Baseline | Arkitekturveiledning basert på Microsoft Learn best practices |
**Merknad:** Alle tekniske detaljer om API-er, kapabiliteter, input-krav, språkstøtte, og JSON-responser er verifisert mot Microsoft Learn-dokumentasjon via MCP-research (februar 2026). Prisopplysninger er estimater og bør verifiseres mot Azure Pricing Calculator. Offentlig sektor-spesifikke anbefalinger er basert på norsk regulatorisk kontekst (GDPR, Offentlighetsloven, WCAG 2.1).

600
plugins/ms-ai-architect/skills/ms-ai-engineering/references/azure-ai-services/content-understanding-multimodal-analysis.md Normal file
View file

@ -0,0 +1,600 @@
# Content Understanding - Multimodal Analysis and Video Intelligence
**Last updated:** 2026-02
**Status:** Preview (GA for core features, Limited Access for face description)
**Category:** Azure AI Services (Foundry Tools)
---
## Introduksjon
Azure AI Content Understanding er en generativ AI-tjeneste designet for å transformere ustrukturert multimodalt innhold – dokumenter, bilder, video og audio – til strukturert, maskinlesbar informasjon. Tjenesten kombinerer avansert innholdsekstraksjon med generative modeller for å skape skreddersydd metadata og innsikter på tvers av modaliteter.
For video- og audioanalyse opererer Content Understanding i to hovedfaser: **innholdsekstraksjon** (transcription, shot detection, keyframe extraction) og **feltekstraksjon** (custom fields, segmentering basert på generative modeller). Dette muliggjør alt fra RAG-optimaliserte workflows til detaljert media asset management og compliance-sjekk.
Tjenesten skiller seg fra Azure AI Video Indexer ved at den fokuserer på fleksibel, schema-drevet ekstraksjon med generative modeller, mens Video Indexer leverer et bredere spekter av pre-definerte AI-innsikter (face recognition, celebrity identification, content moderation, observed people detection). Content Understanding er ideell når du trenger tilpassede felt og segmenteringslogikk definert i naturlig språk, mens Video Indexer passer bedre for omfattende, predefinerte video-innsikter.
---
## Kjernekomponenter
### Støttede modaliteter
| Modalitet | Format-eksempler | Bruksområder |
|-----------|------------------|--------------|
| **Video** | MP4, AVI, MOV, MKV | Media asset management, advertising analysis, training videos |
| **Audio** | MP3, WAV, AAC, FLAC | Podcast transcription, call center analytics, audio content classification |
| **Dokumenter** | PDF, DOCX, XLSX, PPTX, HTML | Document intelligence, form processing, contract analysis |
| **Bilder** | JPEG, PNG, BMP, TIFF | Image classification, OCR, visual content analysis |
**Tekniske begrensninger (video/audio):**
- Frame sampling: ~1 FPS (raske bevegelser eller single-frame events kan gå tapt)
- Frame resolution: 512 × 512 px resize (små detaljer eller fjerne objekter kan bli utydelige)
- Audio: Kun tale transkriberes (musikk, lydeffekter, bakgrunnsstøy ignoreres)
### Prebuilt analyzers
| Analyzer ID | Formål | Output-format |
|-------------|--------|---------------|
| `prebuilt-videoSearch` | RAG-optimalisert video-analyse med markdown og JSON | Transcript (WEBVTT), keyframes, scene descriptions, segmentering |
| `prebuilt-videoAnalysis` | Generell video-metadata for asset management | JSON med visual + audio metadata |
| `prebuilt-documentSearch` | Dokument-ekstraksjon for RAG | Markdown med pages, tables, figures, paragraphs |
**Eksempel (prebuilt-videoSearch output):**
```markdown
# Video: 00:00.000 => 00:06.000
A lively room filled with people watching a sports event on television.
Transcript
WEBVTT
00:03.600 --> 00:06.000
<Speaker 1>Get new years ready.
Key Frames
- 00:00.600 ![](keyFrame.600.jpg)
- 00:01.200 ![](keyFrame.1200.jpg)
```
### Custom analyzers
Definer egne feltschemaer og segmenteringslogikk for å trekke ut domene-spesifikk informasjon.
**Nøkkelegenskaper:**
- **Field extraction**: Strukturerte felt (string, array, object, enum) definert i JSON-schema
- **Custom segmentation**: Naturlig språk-beskrivelser av hvordan video skal segmenteres (nyhetssegmenter, kapitler, annonser)
- **Face description** (Limited Access): Ansiktsattributter (facial hair, expressions), identifisering av kjente personer
**Eksempel (custom analyzer config):**
```json
{
"config": {
"enableSegment": true,
"contentCategories": {
"news-story": {
"description": "Segment video based on each distinct news segment. Use timestamp to identify start/end, no overlap. Ignore ads.",
"analyzerId": "NewsAnalyzer"
}
},
"fieldSchema": {
"fields": {
"brandLogo": {
"type": "string",
"method": "generate",
"description": "Brand being promoted in the video. Include product name if available."
},
"sentiment": {
"type": "string",
"method": "classify",
"enum": ["Positive", "Neutral", "Negative"]
}
}
}
}
}
```
### Ekstraherte elementer (audioVisual)
| Element | Audio | Video | Krever `returnDetails: true` |
|---------|-------|-------|------------------------------|
| Markdown content | ✓ | ✓ | Nei |
| Contents collection | ✓ | ✓ | Nei |
| Transcript phrases | ✓ | ✓ | Ja |
| Timing information | ✓ | ✓ | Nei |
| Key frames | ✗ | ✓ | Nei |
| Camera shots | ✗ | ✓ | Ja |
| Field extraction | ✓ | ✓ | Nei |
**Transcript phrases (JSON):**
```json
{
"transcriptPhrases": [
{
"speaker": "Speaker 1",
"startTimeMs": 280,
"endTimeMs": 3560,
"text": "Welcome to this first session",
"words": []
}
]
}
```
**Keyframes (JSON):**
```json
{
"keyFrameTimesMs": [660, 1320, 2970, 3927, 4884]
}
```
Keyframes er uniformt samplet fra hver camera shot, minimum én per shot (selv ved korte shots < 1 sekund). Deterministisk utvalg på tvers av kjøringer.
**Camera shots (JSON):**
```json
{
"cameraShotTimesMs": [2002, 22356, 26960, 53353]
}
```
Timestamps indikerer startpunktet for hver shot (unntatt første shot som alltid starter ved 0 ms). Detekterer abrupte og gradvise overganger.
---
## Arkitekturmønstre
### Mønster 1: RAG-optimalisert video-indexing
**Use case:** Gjøre video- og audio-innhold søkbart i RAG-workflows (chatbots, agent-systemer).
**Arkitektur:**
1. Last opp video/audio til Content Understanding med `prebuilt-videoSearch` analyzer
2. Tjenesten returnerer strukturert markdown (transcript + keyframes) og JSON (fields, segments)
3. Markdown + JSON lagres i Azure AI Search index med multimodal embeddings
4. RAG-systemet søker på tvers av tekst og visuelt innhold
**Fordeler:**
- Drop-in format for AI Search (ingen post-processing)
- Multimodal søk (tekst + bilde) i én pipeline
- Temporal context bevares (timestamps, keyframes)
**Ulemper:**
- Frame sampling (~1 FPS) kan miste raske handlinger
- Ikke egnet for real-time eller live video-analyse
- Krever Azure OpenAI/embedding-modeller for vektorisering
**Når bruke:** E-learning platforms, corporate training libraries, media archives, compliance video search.
---
### Mønster 2: Custom media asset management
**Use case:** Klassifisere og tagge stort video-library med domene-spesifikke kategorier (sport, nyheter, reklame).
**Arkitektur:**
1. Opprett custom analyzer med feltschema for `videoCategory`, `colorScheme`, `primaryTopic`, `brandPresence`
2. Aktiver `enableSegment: false` for hele-video-analyse
3. Batch-prosesser eksisterende video-bibliotek via REST API eller SDK
4. Lagre ekstraherte metadata i database/fabric for filtering og retrieval
**Fordeler:**
- Fleksibel feltdefinisjon i naturlig språk (ingen ML-trening)
- Støtter både klassifisering (enum) og generering (string)
- Confidence scores for kvalitetssikring
**Ulemper:**
- Generative modeller konsumerer tokens (kostnad skalerer med video-lengde og antall felt)
- Ikke real-time (asynkron long-running operation)
- Krever manuell validering av ekstraherte verdier for produksjonskritiske use cases
**Når bruke:** Broadcast media, advertising analysis, sports analytics, news archiving.
---
### Mønster 3: Compliance og brand safety screening
**Use case:** Skanne annonser/video-innhold for upassende innhold, konkurrent-merkevarer, eller regulatoriske krav.
**Arkitektur:**
1. Kombiner Content Understanding med Azure AI Content Safety (multimodal analysis)
2. Content Understanding ekstraherer `brandLogo`, `spokespersonName`, `productPlacement`
3. Content Safety analyserer visuelt innhold for harm categories (hate, violence, sexual)
4. Custom logic sammenligner ekstraherte felt mot whitelist/blacklist
**Fordeler:**
- Multimodal harm detection (tekst + bilde kombinert)
- Structured output for audit trails
- Integrasjon med Azure AI Services økosystem
**Ulemper:**
- Content Safety multimodal er limited til spesifikke regions (East US, West Europe)
- Ingen real-time screening (batch-orientert)
- False positives krever human-in-the-loop review
**Når bruke:** Ad network compliance, social media moderation, brand safety for advertisers.
---
## Beslutningsveiledning
### Når bruke Content Understanding vs. Video Indexer
| Kriterium | Content Understanding | Video Indexer |
|-----------|----------------------|---------------|
| **Custom field extraction** | ✅ Ja, via naturlig språk-schema | ❌ Nei, predefinerte insights |
| **RAG-optimalisert output** | ✅ Ja, markdown + JSON drop-in | ⚠️ Krever post-processing |
| **Face recognition** | ❌ Nei (kun face description med Limited Access) | ✅ Ja, celebrity + custom faces |
| **Custom segmentation** | ✅ Ja, NL-basert logic | ❌ Nei, predefinert scene detection |
| **Real-time analysis** | ❌ Nei (async batch) | ✅ Ja (live video streaming) |
| **Observed people tracking** | ❌ Nei | ✅ Ja (bounding boxes, clothing detection) |
| **Audio insights** | ⚠️ Transcript, diarization | ✅ Ja, keywords, emotions, topics, audio effects |
| **Pricing model** | Token-basert (generative models) | Page/minute-basert (predefined models) |
**Beslutningstre:**
```
Trenger du real-time analyse?
├─ Ja → Video Indexer (live streaming støtte)
└─ Nei → Trenger du custom fields definert i naturlig språk?
├─ Ja → Content Understanding
└─ Nei → Trenger du face recognition/celebrity identification?
├─ Ja → Video Indexer
└─ Nei → Trenger du RAG-optimalisert output uten post-processing?
├─ Ja → Content Understanding (prebuilt-videoSearch)
└─ Nei → Vurder begge basert på cost/features
```
### Vanlige feil
| Feil | Årsak | Løsning |
|------|-------|---------|
| **Manglende detaljer i transcript** | `returnDetails: false` i analyzer config | Sett `"returnDetails": true` for å få `transcriptPhrases`, `cameraShotTimesMs` |
| **Feil språk i transcript** | Multilingual transcription brukt på usupportert locale | Spesifiser språk eksplisitt (`"language": "nb-NO"`) eller bruk `"auto"` kun for supported locales |
| **Tomme custom fields** | Prompt-beskrivelse for vag eller motsier video-innhold | Iterer på field descriptions, test med sample videos, bruk `method: "classify"` + enum for standardiserte verdier |
| **Face description ikke tilgjengelig** | Limited Access feature, krever approval | Send Azure support request for å aktivere `disableFaceBlurring: true` |
| **Høy kostnad på lange videoer** | Generative models konsumerer tokens per frame + segment | Optimaliser med `enableSegment: false` for hele-video, reduser antall custom fields, bruk prebuilt analyzers hvor mulig |
### Røde flagg
- **Video > 2 timer:** Content Understanding er optimalisert for kortere videoer (ads, training, clips). For lang-format innhold (filmer, full-length shows), vurder Video Indexer.
- **Real-time krav:** Content Understanding er asynkron batch-prosessering. For live video, bruk Video Indexer real-time analysis.
- **Biometric data uten consent:** Face description krever Legal/Privacy review og brukersamtykke under GDPR/AI Act. Ikke aktiver uten juridisk godkjenning.
- **Mission-critical accuracy:** Generative modeller kan hallusinere. Krever human review for compliance/legal use cases.
---
## Integrasjon med Microsoft-stakken
### Azure AI Foundry
Content Understanding er en core Foundry service, tilgjengelig via:
- **Azure AI Foundry portal**: GUI for testing analyzers, viewing results
- **Foundry SDK** (Python, .NET): `ContentUnderstandingClient` klasse
- **REST API**: `POST /contentunderstanding/analyzers/{analyzerId}:analyze`
**Integrasjon med andre Foundry-tjenester:**
| Tjeneste | Integrasjonspunkt |
|----------|-------------------|
| **Azure OpenAI** | Generative modeller (GPT-4o, o1) for field extraction og segmentering |
| **Azure AI Speech** | Transcription engine (samme språkstøtte som Speech in Foundry Tools) |
| **Azure AI Vision** | Image analysis for keyframes (OCR, object detection) |
| **Azure Document Intelligence** | Document extraction for multimodal documents (PDF, DOCX) |
### Azure AI Search
**Multimodal search skillset:**
Content Understanding kan integreres som skill i Azure AI Search indexer pipeline via `Azure Content Understanding skill` (cognitive-search-skill-content-understanding).
**Sammenligning med Document Layout + Vision vectorization:**
| Komponent | Document Extraction skill | Document Layout skill | Content Understanding skill |
|-----------|---------------------------|------------------------|------------------------------|
| **Text location metadata** | Nei | Ja (single page) | Ja (cross-page) |
| **Image location metadata** | Ja (PDF only) | Ja (multi-format) | Ja (multi-format) |
| **Table extraction** | Nei | Nei | Ja (cross-page tables) |
| **Semantic chunking** | Nei (use Text Split skill) | Ja (paragraph boundaries) | Ja (semantic units) |
| **Supported formats** | PDF, images | PDF, DOCX, XLSX, PPTX | PDF, DOCX, XLSX, PPTX, video, audio |
| **Pricing** | AI Search pricing | Document Intelligence pricing | Content Understanding pricing |
**Når bruke Content Understanding skill:**
- Krever cross-page table extraction (contracts, financial reports)
- Multimodal dokumenter med innebygde videoer/audio
- Trenger semantic chunking over paragraph-level chunking
### Microsoft Fabric
Ekstraherte metadata kan eksporteres til Fabric for:
- **Data lakehouse**: Strukturert lagring av video metadata
- **Power BI**: Dashboards for video analytics (views, sentiment, brand exposure)
- **Dataflows**: ETL-prosessering av ekstraherte felt
**Eksempel-workflow:**
1. Content Understanding → JSON output til Azure Blob Storage
2. Fabric dataflow leser JSON fra blob
3. Transformasjon til tabellformat (flate strukturer)
4. Lagre i Fabric lakehouse
5. Power BI rapport over video library insights
### Power Platform
**Power Automate:**
- Trigger: "When video uploaded to SharePoint/Blob"
- Action: Call Content Understanding REST API
- Action: Parse JSON response og lagre til Dataverse/SharePoint list
**Power Apps:**
- Custom connector for Content Understanding API
- Video metadata viewer app for content editors
**AI Builder:**
- Ingen direkte integrasjon (AI Builder fokuserer på structured data, forms, text)
- Bruk Content Understanding som preprocessing step før AI Builder models
---
## Offentlig sektor (Norge)
### GDPR og personvern
**Risikovurdering:**
| Feature | GDPR-risiko | Mitigering |
|---------|-------------|------------|
| **Transcript (speaker diarization)** | Moderat (personidentifisering via stemme) | Anonymiser speaker labels ("Speaker 1" vs. navn), lagre transkripsjon separert fra audio-fil |
| **Face description** | Høy (biometric data, Article 9) | Krever eksplisitt samtykke, DPIA, Legal review. Ikke aktiver uten godkjenning. |
| **Keyframes** | Lav-Moderat (kan inneholde personer) | Blur faces i keyframes hvis nødvendig (custom post-processing) |
| **Custom fields (names, roles)** | Høy hvis felt ekstraherer persondata | Definer klare data retention policies, tilgangskontroll, slettingsrutiner |
**Face description (Limited Access):**
- Krever Azure support request + justification
- Microsoft vurderer use case før godkjenning
- Må dokumentere legal basis (consent, public interest, legitimate interest)
- Under AI Act (EU): High-risk system hvis brukt til identifisering i offentlige rom
### Schrems II og datasuverenitet
Content Understanding er en Azure Foundry service, underlagt samme datasuverenitet-krav som andre Azure-tjenester.
**Data processing locations:**
- **EU-regioner:** West Europe, North Europe (data residency i EU)
- **Generative models (Azure OpenAI):** Kan prosesseres i US-regions (avhenger av OpenAI deployment)
**Anbefalinger:**
- Deploy Content Understanding resources i **Norway East** eller **West Europe** for EU data residency
- Verifiser at Azure OpenAI deployment også er i EU-region (eller bruk customer-managed keys + EU Boundary)
- For sensitive offentlige videoer: Vurder Azure Government Cloud (ikke tilgjengelig i Norge, men for US gov customers)
**Data retention:**
- Input-filer lagres ikke av tjenesten (kun transiently under prosessering)
- Output (JSON/markdown) returneres til customer storage (blob, AI Search index)
- Ingen logging av video-innhold i Microsoft telemetry (kun metadata som file size, duration)
### AI Act (EU)
Content Understanding faller inn under flere AI Act-kategorier:
| Use Case | AI Act Classification | Obligations |
|----------|----------------------|-------------|
| **Video surveillance (public spaces)** | High-risk (Annex III) | Conformity assessment, risk management, transparency, human oversight |
| **Emotion detection (face description)** | Prohibited (Article 5) hvis brukt til inferring emotions in workplace/education | Ikke bruk `faceSmilingFrowning` felt i HR/school contexts |
| **Content moderation** | High-risk hvis brukt til automated decision-making | Human review loop, appeal mechanism |
| **Media asset management** | Low-risk / minimal risk | Transparency notice (AI-generated metadata) |
**Compliance checklist:**
- [ ] DPIA utført hvis face description aktiveres
- [ ] Transparency notice til brukere om AI-genererte metadata
- [ ] Human-in-the-loop for high-risk decisions (content removal, compliance violations)
- [ ] Dokumentasjon av training data (for custom models, hvis relevant)
- [ ] Regular accuracy testing og bias monitoring
### Forvaltningsloven (Norge)
Hvis Content Understanding brukes i saksbehandling (f.eks. analyse av innsendte videoer i klagesaker):
**§ 11 (informasjonsplikt):**
- Informer sakspart om at video analyseres med AI
- Forklar hvilke metadata som ekstraheres (transcript, faces, sentiment)
- Gi rett til å motsette seg automatisert behandling
**§ 17 (begrunnelsesplikt):**
- Vedtak basert på AI-ekstraherte insights må begrunnes
- Ikke "systemet sa at videoen inneholder X" — menneskelig vurdering må dokumenteres
**Anbefalinger:**
- Bruk Content Understanding som beslutningsstøtte, ikke automatisert saksbehandling
- Lagre audit trail av hvilke felt som ble ekstrahert og hvordan de påvirket beslutning
- Tilby innsyn i ekstraherte metadata til sakspart
---
## Kostnad og lisensiering
### Prismodell
Content Understanding prises basert på **token consumption** for generative models + **content extraction** for audio/video processing.
**Komponenter:**
| Komponent | Prisingsmetrikk | Estimert kostnad (NOK, Feb 2026) |
|-----------|-----------------|-----------------------------------|
| **Content extraction (video)** | Per minute video | ~0.50 NOK/min |
| **Content extraction (audio)** | Per minute audio | ~0.30 NOK/min |
| **Field extraction (generative)** | Per 1000 tokens (input + output) | ~0.10 NOK/1K tokens (GPT-4o) |
| **Segmentation (generative)** | Per 1000 tokens | Inkludert i field extraction |
**Eksempel-beregning (5-minutters reklame-video):**
1. **Content extraction:** 5 min × 0.50 NOK = 2.50 NOK
2. **Keyframe extraction:** 5 frames/min × 5 min = 25 keyframes (inkludert i extraction)
3. **Transcript:** ~150 ord/min × 5 min = 750 ord ≈ 1000 tokens (inkludert i extraction)
4. **Field extraction (3 custom fields):**
- Input: 750 transcript tokens + 25 keyframes × 1000 tokens/image = 25,750 tokens
- Output: ~500 tokens (3 felt × ~150 tokens hver)
- Total: 26,250 tokens ≈ 26K tokens × 0.10 NOK/1K = 2.60 NOK
5. **Total:** 2.50 + 2.60 = **5.10 NOK per video**
**Prebuilt analyzers:**
- `prebuilt-videoSearch`: Lavere kostnad enn custom (færre tokens, optimaliserte prompts)
- Estimat: 60-70% av custom analyzer kostnad
### Optimaliseringstips
| Strategi | Besparelse | Trade-off |
|----------|------------|-----------|
| **Bruk prebuilt analyzers** | 30-40% lavere kostnad | Mindre fleksibilitet i output-format |
| **Disable segmentation** (`enableSegment: false`) | 20-30% lavere tokens | Ingen segment-level metadata |
| **Reduser antall custom fields** | Lineær besparelse per felt | Mindre granulær metadata |
| **Batch-prosessering** | Ingen direkte besparelse, men bedre ressursutnyttelse | Ingen real-time output |
| **Lower frame sampling** | Ikke konfigurerbart (fast ~1 FPS) | N/A |
| **Bruk AI Search skill** | AI Search absorber en del preprocessing-kostnad | Krever AI Search subscription |
### Lisensiering
Content Understanding er en **Azure Foundry Tools** tjeneste, inkludert i:
| Lisens | Inkludert | Begrensninger |
|--------|-----------|---------------|
| **Azure subscription (pay-as-you-go)** | Full tilgang | Kostnad per bruk (token-basert) |
| **Azure commitment (EA)** | Inkludert i Foundry commitment | Samme prising, men prepaid credits |
| **Free tier** | Ikke tilgjengelig | Krever betalt subscription |
**MCP-servere (for Claude Code):**
- Ingen lisensieringskrav utover Azure subscription
- Bruk `microsoft-learn` MCP for dokumentasjonssøk (gratis)
- Content Understanding API-tilgang krever Azure keys
---
## For arkitekten (Cosmo)
### Spørsmål å stille kunden
1. **Volum og format:**
- Hvor mange videoer/audio-filer skal prosesseres? (per dag/uke/måned)
- Typisk video-lengde? (< 5 min, 5-30 min, > 30 min)
- Format-variasjon? (kun MP4, eller også legacy formater?)
2. **Custom fields vs. prebuilt:**
- Trenger dere domene-spesifikke metadata-felt? (Eksempler: `productType`, `complianceStatus`, `brandSafety`)
- Er predefinerte insights (transcript, keyframes, scene descriptions) tilstrekkelig?
- Hvor kritisk er accuracy? (toleranse for feil i ekstraherte verdier)
3. **Segmentering:**
- Skal videoer analyseres som helhet, eller segmentert i kapitler/scener?
- Har dere eksisterende segmenteringslogikk? (timecodes, manual tagging)
- Trenger dere variable segment-lengder? (news clips vs. full episodes)
4. **Personvern og compliance:**
- Inneholder videoer personer? (faces, voices)
- Trenger dere face description/identification? (krever Legal review + Limited Access)
- Er dette offentlige videoer (web-published) eller interne/sensitive?
- Hvilke GDPR Article 6/9 legal bases gjelder?
5. **Integrasjon:**
- Hvor skal metadata lagres? (AI Search, SQL, Fabric, SharePoint)
- Trenger dere RAG-optimalisert output? (markdown + embeddings)
- Eksisterende video storage? (blob, SharePoint, on-prem NAS)
- Real-time krav? (live video streams vs. batch uploaded files)
6. **Kostnad:**
- Hva er budsjettet per video? (eller totalt per måned)
- Er token-basert prising akseptabelt? (variabel kostnad per video-kompleksitet)
- Preferanse for flat-rate pricing? (vurder Video Indexer hvis ja)
7. **Modenhet:**
- Har teamet erfaring med generative AI APIs?
- Finnes ML/AI-kompetanse for å validere output-kvalitet?
- Trenger dere managed service (Azure support) eller self-serve?
8. **Fallback og feilhåndtering:**
- Hva skjer hvis analyse feiler? (retry logic, manual fallback)
- Toleranse for hallucinations i custom fields?
- Human-in-the-loop review-prosess etablert?
### Fallgruver
| Fallgruve | Symptom | Forebygging |
|-----------|---------|-------------|
| **Over-engineering custom fields** | Høy kostnad, treg prosessering, inkonsistente verdier | Start med prebuilt analyzer, iterer til custom fields kun hvis nødvendig |
| **Manglende human review** | Feil metadata i produksjon, compliance-brudd | Implementer confidence thresholds, flag lav-confidence outputs for review |
| **Ignorer technical constraints** | Klager om "hvorfor fant ikke systemet denne 1-sekunders hendelsen?" | Dokumenter frame sampling (1 FPS) + resolution limits i user documentation |
| **Face description uten Legal review** | GDPR/AI Act violations, PR-kriser | Alltid involver Legal før aktivering av `disableFaceBlurring` |
| **Ingen test av multilingual transcription** | Feil språk i transkripsjon, uleselig output | Test med sample files, spesifiser språk eksplisitt vs. `auto` |
| **Undervurdere token consumption** | Budsjettoverskridelse | Kalkuler tokens på forhånd, bruk prebuilt analyzers for cost control |
| **Synkron polling-mønster** | Timeout issues, dårlig UX | Bruk async polling (`.begin_analyze()` + polling hver 20 sek), eller webhooks (ikke GA, men preview) |
### Anbefalinger per modenhetsnivå
**Nivå 1 - Exploratory (PoC):**
- Bruk `prebuilt-videoSearch` for rask demonstrasjon av RAG on video
- Test med 5-10 sample videos (varierende lengde, innhold)
- Deploy i development subscription (ikke prod)
- Fokus: Bevise at teknologien kan ekstrahere relevant info
**Nivå 2 - Pilot (MVP):**
- Definer 1-3 custom fields basert på faktisk business need
- Implementer confidence thresholds (f.eks. flag outputs < 0.7 confidence for review)
- Deploy i prod-lignende miljø (West Europe eller Norway East)
- Integrer med eksisterende storage (blob, AI Search)
- Etabler cost monitoring (Azure Cost Management alerts)
**Nivå 3 - Production (Scale):**
- Optimaliser custom field descriptions basert på pilot-data
- Implementer batch-prosessering pipeline (Azure Functions + Durable Functions for orchestration)
- Sett opp monitoring (Application Insights, Log Analytics)
- Legal/Privacy review av face description hvis aktivert
- Etabler SLA for processing time (f.eks. "videoer < 10 min prosesseres innen 5 min")
**Nivå 4 - Optimization (Mature):**
- A/B-test prebuilt vs. custom analyzers (cost vs. accuracy trade-offs)
- Fine-tune field descriptions basert på production feedback
- Implementer caching av frequently accessed metadata
- Vurder Video Indexer for real-time use cases (hybrid approach)
- Contributor til Microsoft feedback (feature requests, bug reports)
---
## Kilder og verifisering
### Microsoft Learn (MCP-verifiserte)
| Seksjon | Kilde-URL | Konfidensnivå |
|---------|-----------|---------------|
| Video overview, capabilities | https://learn.microsoft.com/en-us/azure/ai-services/content-understanding/video/overview | Verified (Feb 2026) |
| AudioVisual elements, JSON schema | https://learn.microsoft.com/en-us/azure/ai-services/content-understanding/video/elements | Verified (Feb 2026) |
| Video Indexer scene/shot/keyframe detection | https://learn.microsoft.com/en-us/azure/azure-video-indexer/scene-shot-keyframe-detection-insight | Verified (Feb 2026) |
| Standard vs. Pro modes | https://learn.microsoft.com/en-us/azure/ai-services/content-understanding/concepts/standard-pro-modes | Verified (Feb 2026) |
| Multimodal search (AI Search integration) | https://learn.microsoft.com/en-us/azure/search/multimodal-search-overview | Verified (Feb 2026) |
| Azure AI Video Indexer insights overview | https://learn.microsoft.com/en-us/azure/azure-video-indexer/insights-overview | Verified (Feb 2026) |
| Python SDK (ContentUnderstandingClient) | https://learn.microsoft.com/en-us/python/api/overview/azure/ai-contentunderstanding-readme | Verified (Feb 2026) |
| Data privacy and security | https://learn.microsoft.com/en-us/azure/ai-foundry/responsible-ai/content-understanding/data-privacy | Verified (Feb 2026) |
### Baseline (modellkunnskap)
| Seksjon | Konfidensnivå | Merknad |
|---------|---------------|---------|
| Kostnadsestimater (NOK) | Baseline (est. Feb 2026) | Priser kan variere, sjekk Azure Pricing Calculator for nøyaktige tall |
| GDPR/AI Act compliance | Baseline (legal interpretation) | Krever juridisk review per use case, ikke definitive legal advice |
| Offentlig sektor (Norge) guidance | Baseline (expert recommendation) | Basert på generell forståelse av norske lover, ikke case law |
| Fallgruver og best practices | Baseline (arkitektur-erfaring) | Basert på typiske anti-patterns, ikke spesifikke customer incidents |
### Manglende dokumentasjon (gaps)
- **Webhooks for async completion**: Preview feature, ikke dokumentert i GA docs (per Feb 2026)
- **Token consumption per field type**: Ingen offisiell dokumentasjon av hvordan `method: "classify"` vs. `"generate"` påvirker token usage
- **Face description approval process**: Limited Access request-prosedyre er dokumentert, men approval-kriterier er ikke offentlige
- **AI Search skill pricing**: Content Understanding skill pricing er ikke eksplisitt skilt fra Document Extraction/Layout skills i Azure Search pricing page
---
**Sist oppdatert av:** Cosmo Skyberg
**Neste review:** 2026-04 (eller ved ny GA release av Content Understanding)

459
plugins/ms-ai-architect/skills/ms-ai-engineering/references/azure-ai-services/document-intelligence-custom-models.md Normal file
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.

553
plugins/ms-ai-architect/skills/ms-ai-engineering/references/azure-ai-services/document-intelligence-prebuilt-models.md Normal file
View file

@ -0,0 +1,553 @@
# Document Intelligence - Prebuilt Models for Forms and Invoices
**Last updated:** 2026-02
**Status:** GA
**Category:** Azure AI Services (Foundry Tools)
---
## Introduksjon
Azure AI Document Intelligence tilbyr forhåndsbyggede (prebuilt) modeller som bruker maskinlæring og Optical Character Recognition (OCR) til å ekstrakere strukturerte data fra dokumenter uten behov for trening. Disse modellene er spesialiserte for vanlige dokumenttyper som fakturaer, kvitteringer, identitetsdokumenter, skatteskjemaer og finansielle dokumenter. Modellene returnerer strukturert JSON-output med felter, konfidensgrader og posisjoner.
Prebuilt-modellene er "out-of-the-box" løsninger som kan brukes umiddelbart, i motsetning til custom models som må trenes på egne data. De støtter 27 språk og håndterer ulike formater: skannet, fotografert, håndskrevet og digitale PDF-dokumenter. Version v4.0 (GA: 2024-11-30) introduserte nye felt som `ReceiptType`, `TaxDetails`, og VAT-ekstraksjon for hotellkvitteringer.
Document Intelligence er del av Azure AI Foundry Tools og fungerer som en IDP (Intelligent Document Processing) plattform som kombinerer OCR, struktur-ekstraksjon og domene-spesifikke modeller for skalerbare dokumentløsninger.
---
## Kjernekomponenter
### Financial Services-modeller
| Modell | Model ID | Formål | Hoved-felter |
|--------|----------|--------|--------------|
| **Invoice** | `prebuilt-invoice` | Automatisert fakturabehandling (accounts payable) | Customer name, billing address, due date, amount due, line items, tax details |
| **Receipt** | `prebuilt-receipt` | Kvitteringsdigitalisering for utgiftshåndtering | Merchant name, phone, transaction date/time, total, subtotal, tax, tip, line items |
| **Bank Statement** | `prebuilt-bankStatement` | Kontoutskrifter fra amerikanske banker | Account number, bank details, statement details, transaction details |
| **Credit Card** | `prebuilt-creditCard` | Betalingskortinformasjon | Card number, expiration, cardholder name |
| **Check** | `prebuilt-check` | Sjekkbehandling | Check number, amount, payee, date |
| **Contract** | `prebuilt-contract` | Kontraktsanalyse | Client name/address, contract duration, renewal date, parties |
| **Pay Stub** | `prebuilt-payStub.us` | Lønnslipper | Employee info, pay period, gross/net pay, deductions |
### Identity & Tax-modeller
| Modell | Model ID | Formål |
|--------|----------|--------|
| **ID Document** | `prebuilt-idDocument` | Identitetsverifisering (førerkort, pass, ID-kort) |
| **Health Insurance Card** | `prebuilt-healthInsuranceCard.us` | US helseforsikringskort |
| **Marriage Certificate** | `prebuilt-marriageCertificate` | Vigselattester |
| **US Tax W-2** | `prebuilt-tax.us.w2` | Skattbar kompensasjon |
| **US Tax 1098** | `prebuilt-tax.us.1098` | 1098-variasjoner |
| **US Tax 1099** | `prebuilt-tax.us.1099` | 1099-variasjoner |
| **US Tax 1040** | `prebuilt-tax.us.1040` | 1040-variasjoner |
| **Unified US Tax** | `prebuilt-tax.us` | Generisk for alle US tax-skjemaer |
### US Mortgage-modeller
| Modell | Model ID | Formål |
|--------|----------|--------|
| **1003** | `prebuilt-mortgage.us.1003` | Lånesøknad |
| **1004** | `prebuilt-mortgage.us.1004` | Appraisal (takst) |
| **1005** | `prebuilt-mortgage.us.1005` | Bekreftelse av ansettelse |
| **1008** | `prebuilt-mortgage.us.1008` | Låneoverføring |
| **Disclosure** | `prebuilt-mortgage.us.disclosure` | Endelige lånevilkår |
### Grunnleggende modeller
| Modell | Model ID | Formål |
|--------|----------|--------|
| **Read** | `prebuilt-read` | OCR: tekst, linjer, ord, språkdeteksjon |
| **Layout** | `prebuilt-layout` | Struktur: tabeller, selection marks, seksjoner, key-value pairs (valgfritt) |
| **General Document** | `prebuilt-document` | Key-value pairs, tabeller, selection marks fra generiske dokumenter |
### Konfidensgrader (Confidence Scores)
Alle ekstraherte felter inkluderer `confidence`-verdi (0.0–1.0):
- **0.95+**: Høy tillit, typisk for maskinskrevet tekst
- **0.80–0.94**: Middels tillit, typisk for skannet eller fotografert
- **<0.80**: Lav tillit, krever manuell validering
---
## Arkitekturmønstre
### Mønster 1: Prebuilt-First med Fallback til Custom
**Bruksområde:** Organisations-standarddokumenter (fakturaer, kvitteringer) med noen unike skjemaer.
**Fordeler:**
- Umiddelbar funksjonalitet uten treningskostnader
- Lavere vedlikeholdsbyrde
- Kontinuerlige forbedringer fra Microsoft
**Ulemper:**
- Begrenset fleksibilitet for proprietære skjemaer
- Ingen kontroll over feltdefinisjoner
- Kan mangle domene-spesifikke felter
**Når bruke:**
- ≥70% av dokumentvolum er standarddokumenter (fakturaer, kvitteringer, ID-dokumenter)
- Aksepterer Microsofts feltschema
- Krever rask time-to-market
**Arkitektur:**
```
Document → Classifier (custom) → Route by Type
├─ Invoice type → prebuilt-invoice
├─ Receipt type → prebuilt-receipt
└─ Custom form → custom neural model
```
### Mønster 2: Hybrid Extraction (Prebuilt + Custom Fields)
**Bruksområde:** Standarddokumenter med organisasjon-spesifikke tilleggsfelter.
**Fordeler:**
- Utnytt prebuilt-modeller for standard felter
- Ekstraher proprietære felter med custom model
- Redusert treningsvolum
**Ulemper:**
- To API-kall per dokument
- Kompleksitet i sammenslåing av resultater
- Høyere kostnad
**Når bruke:**
- Prebuilt-modell dekker 60–80% av behovene
- Trenger 3–5 ekstra felt som ikke finnes i prebuilt-schema
- Har kapasitet til å trene og vedlikeholde custom model
**Arkitektur:**
```
Document → prebuilt-invoice → Extract standard fields
↓
→ custom template model → Extract custom fields
↓
→ Merge JSON results → Final structured output
```
### Mønster 3: Classification → Prebuilt Routing
**Bruksområde:** Multi-format dokumentstrømmer (e-post-vedlegg, scanner-input).
**Fordeler:**
- Automatisk dokumentdeling
- Riktig modell per dokumenttype
- Skalerbar for mange dokumenttyper
**Ulemper:**
- Krever treningsdata for classifier
- Ekstra API-kall
- Kompleksitet i feilhåndtering
**Når bruke:**
- Blandet dokumentstrøm (fakturaer + kvitteringer + ID + kontrakter)
- Automatisert dokumentingest fra e-post eller skanner
- Behov for routing til ulike forretningsprosesser
**Arkitektur:**
```
Batch Upload → prebuilt-read (split pages)
↓
→ custom classifier → Assign docType
↓
→ Route to prebuilt models
├─ invoices → prebuilt-invoice
├─ receipts → prebuilt-receipt
├─ contracts → prebuilt-contract
└─ ID-docs → prebuilt-idDocument
```
---
## Beslutningsveiledning
### Beslutningstabell: Prebuilt vs. Custom
| Kriterium | Velg Prebuilt | Velg Custom Template | Velg Custom Neural |
|-----------|---------------|----------------------|---------------------|
| **Dokumenttype** | Standard (faktura, kvittering, ID) | Proprietært skjema med fast layout | Ustrukturerte/varierende dokumenter |
| **Volumendring** | Kontinuerlig influx | Stabil, kjent format | Mange ulike layouts |
| **Treningsdata** | Ingen tilgjengelig | 5–10 samples | 15+ samples |
| **Time-to-market** | <1 uke | 2–4 uker | 4–8 uker |
| **Vedlikeholdskostnad** | Lav (Microsoft-managed) | Middels (retraining ved layout-endring) | Høy (retraining ved nye varianter) |
| **Feltfleksibilitet** | Fast schema | Egendefinerte felter | Egendefinerte felter + generalisering |
| **Språkstøtte** | 27 språk (prebuilt) | Språk med OCR-støtte | Språk med OCR-støtte |
### Vanlige feil og røde flagg
| Feil | Konsekvens | Løsning |
|------|------------|---------|
| **Bruke prebuilt-invoice for proprietære fakturaer** | Manglende felter (PO number, egne koder) | Custom model eller hybrid approach |
| **Ikke validere confidence scores** | Feil-data i downstream-systemer | Implementer threshold-basert HITL (Human-In-The-Loop) |
| **Bruke custom model for standard fakturaer** | Unødvendig trenings- og vedlikeholdskostnad | Bruk prebuilt-invoice først |
| **Ikke klassifisere dokumenter før ekstraksjon** | Feil modell brukt, dårlig nøyaktighet | Implementer custom classifier |
| **For høy threshold på confidence** | For mye manuell validering | Tuner threshold per felt-type (0.80 for maskinskrevet, 0.70 for håndskrevet) |
| **Ikke håndtere multi-page dokumenter** | Tap av line items på side 2+ | Sørg for 2,000-page støtte i implementation |
### Røde flagg: Når IKKE bruke prebuilt-modeller
- ❌ Dokumenter med **helt proprietær struktur** (bruk custom neural)
- ❌ Dokumenter på **språk som ikke er støttet** (sjekk [language support](https://learn.microsoft.com/azure/ai-services/document-intelligence/language-support/prebuilt))
- ❌ Dokumenter med **kritisk compliance-krav for feltdefinisjoner** (custom model gir mer kontroll)
- ❌ **Ekstremt varierende layouts** innen samme dokumenttype (custom neural)
- ❌ Dokumenter der **prebuilt-schema ikke matcher faktisk innhold** (f.eks. "Total" feltet betyr noe annet)
---
## Integrasjon med Microsoft-stakken
### Power Automate
**Bruksområde:** No-code automatisering av faktura-godkjenning, utgiftshåndtering.
**Connector:** `AI Builder` (Document Processing)
**Eksempelflyt:**
```
Email arrives → Extract attachment → AI Builder: Process invoice (prebuilt-invoice)
↓
→ Parse JSON → Conditional approval (if Total > 10000 NOK)
↓
→ Insert into Dataverse or SharePoint
```
**Begrensninger:**
- AI Builder bruker Document Intelligence v3.1 (ikke alltid v4.0)
- Premium lisens påkrevd for AI Builder
- 1M AI Builder credits inkludert i visse Power Apps/Automate-lisenser
### Logic Apps
**Bruksområde:** Enterprise-grade integrasjon med ERP/accounting-systemer.
**Connector:** `Azure AI Document Intelligence` (native connector for v4.0)
**Eksempelflyt:**
```
Blob trigger → Analyze with prebuilt-invoice → Transform to SAP format
↓
→ Post to SAP Finance API → Archive document in Blob Storage
```
**Fordeler:**
- Full API v4.0-støtte
- Managed identity authentication
- Retry policies og error handling
### Azure AI Search
**Bruksområde:** Søkbar dokumentindeks med strukturerte felt.
**Integrasjon:** Custom skillset i indexing pipeline
**Arkitektur:**
```
Blob Storage → Indexer → Skillset: Document Intelligence
↓
→ Extract fields → Map to search fields
↓
→ Index: invoices → Faceted search by Merchant, Date, Total
```
**Use case:** "Finn alle fakturaer fra leverandør X over 50 000 NOK siste kvartal"
### Dynamics 365 Finance
**Bruksområde:** Automatisert faktura-registrering i AP (accounts payable).
**Integrasjon:** Via Power Automate eller Logic Apps
**Flyt:**
```
Email invoices → Power Automate → prebuilt-invoice → Map to Dynamics AP fields
↓
→ Create invoice record → Trigger approval workflow
```
**Feltmapping:**
- `VendorName` → Dynamics Vendor table lookup
- `InvoiceTotal` → Amount field
- `InvoiceDate` → Date field
- `DueDate` → Payment terms
### Microsoft 365 (SharePoint/OneDrive)
**Bruksområde:** Metadata-tagging av dokumenter.
**Integrasjon:** Power Automate med Document Intelligence + SharePoint connector
**Eksempelflyt:**
```
Document uploaded to SharePoint → Extract metadata with prebuilt-invoice
↓
→ Set SharePoint columns (Vendor, Amount, Date)
↓
→ Apply retention policy based on document type
```
---
## Offentlig sektor (Norge)
### EHF-faktura (Elektronisk Handelsformat)
**Utfordring:** Prebuilt-invoice er trent på internasjonale fakturaer, men EHF har norske spesifikasjoner (organisasjonsnummer, MVA-linjer, PEPPOL-referanser).
**Anbefaling:**
- **Hybrid approach:** Prebuilt-invoice for standard felter + custom model for EHF-spesifikke felter
- **Alternativt:** Bruk EHF XML-parser direkte (hvis EHF alltid er XML-format)
- **Dokumentasjon:** [EHF 3.0 spesifikasjon](https://anskaffelser.no/elektronisk-handel/ehf-formater)
**EHF-felt som krever custom model:**
```
- OrganizasjonsNummer (9 siffer)
- KontoStrengReferanse
- Fakturareferanse (KID)
- MVA-spesifikasjonslinjer (Norge-spesifikke koder)
```
### NOARK5 (Arkivstandard)
**Bruksområde:** Automatisk klassifisering og metadata-ekstraksjon for offentlige dokumenter.
**Integrasjon:**
```
Document Intelligence → Extract metadata → Map to NOARK5 fields
↓
→ Arkivsystem (Public 360, ePhorte)
```
**Feltmapping:**
- `InvoiceDate` → `Dokumentdato`
- `VendorName` → `Avsender`
- `InvoiceId` → `Journalnummer` (mapping-regel)
**Compliance:** NOARK5 krever at alle dokumenter er søkbare og klassifiserte. Document Intelligence kan automatisere:
- Dokumenttype-klassifisering
- Metadata-ekstraksjon
- Full-text indeksering (via prebuilt-read)
### Arkivloven og Personopplysningsloven
**Compliance-krav:**
1. **Data residency:** Azure Norway-regioner (Norway East/West) for sensitive dokumenter
2. **Encryption:** Kundehåndterte nøkler (CMEK) via Azure Key Vault
3. **Logging:** Alle API-kall logges til Azure Monitor for revisjon
4. **Data retention:** Standard 30-dagers oppbevaring av dokumenter i Document Intelligence (kan slettes umiddelbart etter prosessering)
5. **Personopplysninger:** Dokumenter med personnummer/fødselsnummer må behandles i henhold til GDPR
**Anbefaling for offentlig sektor:**
- Bruk **Azure Private Endpoint** for Document Intelligence (isolert fra offentlig internett)
- Implementer **Customer Managed Keys** for kryptering av data at rest
- Konfigurer **Diagnostic Settings** til Log Analytics for full audit trail
### Offentlige skjemaer (NAV, Skatteetaten)
**Utfordring:** Prebuilt-modeller er ikke trent på norske offentlige skjemaer (NAV-skjemaer, selvangivelse, etc.).
**Anbefaling:**
- **Custom template model** for faste NAV-skjemaer (RF-1234, etc.)
- **Custom neural model** hvis skjemaer varierer mellom versjoner/år
- **Classifier** for å skille mellom skjematyper (NAV vs. Skatteetaten)
**Eksempel: NAV-skjema for sykepenger:**
```
Custom model ekstraherer:
- Personnummer
- Perioder (fra/til)
- Arbeidsgivernavn
- Beløp per periode
```
---
## Kostnad og lisensiering
### Prismodell (per side)
**Document Intelligence v4.0 (2024-11-30 GA):**
| Tier | Pris per side (USD) | Inkludert |
|------|---------------------|-----------|
| **Free (F0)** | $0 | 500 sider/måned, 2 sider per dokument, 20 calls/min |
| **Standard (S0)** | $1.50 per 1000 sider (prebuilt models) | 2,000 sider per dokument, 15 TPS |
| **Standard (S0)** | $10 per 1000 sider (custom neural model) | Training + analyze |
**Norske kroner (estimert, NOK/USD = 11):**
- Prebuilt models: **~16.50 NOK per 1000 sider**
- Custom neural: **~110 NOK per 1000 sider**
**Add-on capabilities (øker kostnad):**
- High resolution: +$10 per 1000 sider
- Formula extraction: +$3 per 1000 sider
- Barcode extraction: Inkludert (gratis)
### Optimaliseringstips
1. **Bruk prebuilt-read for OCR-only** (billigere enn prebuilt-invoice hvis du bare trenger tekst)
2. **Batch processing:** Kombiner flere dokumenter i ett API-kall (hvis mulig)
3. **Confidence-based filtering:** Kun analyser sider med lav OCR-kvalitet med high-resolution add-on
4. **Cache results:** Ikke re-analyser samme dokument flere ganger
5. **Komprimering:** Reduser filstørrelse før upload (TIFF → PDF)
6. **Page splitting:** Hvis dokument har blank pages, skill dem ut før analyse
### TCO-beregning (Total Cost of Ownership)
**Scenario:** 10,000 fakturaer/måned, 2 sider per faktura = 20,000 sider/måned
| Komponent | Kostnad (NOK/måned) |
|-----------|---------------------|
| Document Intelligence prebuilt-invoice | 20,000 sider × 0.0165 = **330 NOK** |
| Azure Blob Storage (input/output) | 50 NOK |
| Logic Apps (20,000 executions) | 200 NOK |
| Azure Monitor (logging) | 100 NOK |
| **Total** | **~680 NOK/måned** |
**Sammenligning med manuell prosessering:**
- Manuell tid per faktura: 5 minutter
- 10,000 fakturaer × 5 min = 833 timer/måned
- Kostnad per time (administrativ medarbeider): 500 NOK
- **Manuell kostnad:** 416,500 NOK/måned
**ROI:** ~99.8% kostnadsbesparelse
---
## For arkitekten (Cosmo)
### Spørsmål å stille kunden
1. **Dokumentvolum og -type**
- Hvor mange dokumenter prosesserer dere per måned/år?
- Hvilke dokumenttyper? (fakturaer, kvitteringer, kontrakter, skatteskjemaer, ID-dokumenter?)
- Er dokumentene standardiserte eller proprietære?
2. **Kvalitet og format**
- Hvilket format mottas dokumentene i? (PDF, JPEG, TIFF, e-post-vedlegg?)
- Er dokumentene skannet, fotografert eller født digitalt?
- Håndskrevne eller maskinskrevne?
3. **Integrasjonsbehov**
- Hvilke systemer skal motta data? (ERP, CRM, arkivsystem, database?)
- Kreves sanntidsbehandling eller batch?
- Har dere eksisterende dokumentflyt (SharePoint, e-post, skanner)?
4. **Compliance og sikkerhet**
- Inneholder dokumentene personopplysninger?
- Krever dere data residency i Norge?
- Er dokumentene underlagt arkivloven eller andre regulatoriske krav?
5. **Feltbehov**
- Hvilke felt må ekstraheres? (matcher de prebuilt-schema?)
- Har dere proprietære felter som ikke finnes i standard fakturaer?
- Krever dere line items-ekstraksjon?
6. **Nøyaktighet og HITL**
- Hvilken nøyaktighet kreves? (95%, 99%?)
- Har dere kapasitet til manuell validering av usikre resultater?
- Hvilken confidence threshold er akseptabel?
7. **Skalerbarhet**
- Forventer dere volumvekst? (10x, 100x?)
- Må løsningen håndtere sesongvariasjoner?
- Kreves multi-region deployment?
8. **Budsjettrammer**
- Hva er monthly budget for AI-tjenester?
- Finnes det eksisterende Power Platform/Azure-budsjett?
- Er dere åpne for hybrid-modeller (prebuilt + custom)?
### Fallgruver å unngå
| Fallgruve | Konsekvens | Forebygging |
|-----------|------------|-------------|
| **Ikke teste med reelle dokumenter** | Overestimert nøyaktighet i produksjon | Krev 50+ sample-dokumenter fra kunde før POC |
| **Anta at prebuilt-invoice dekker alle fakturatyper** | Manglende felter i produksjon | Map kundens feltkrav mot prebuilt-schema først |
| **Ikke planlegge for HITL** | Feil-data i downstream-systemer | Design HITL-workflow fra dag 1 (Power Apps/Forms for validering) |
| **Overse språk- og locale-støtte** | Feil i datoformat, tallformat | Sjekk at dokumentenes språk er støttet (27 språk i v4.0) |
| **Ikke vurdere hybrid-modell** | Enten for dyrt (custom) eller manglende funksjonalitet (prebuilt) | Foreslå hybrid som sweet spot for 60–80% coverage |
| **Glemme model expiration (custom models)** | Custom model slutter å virke etter 12–24 måneder | Planlegg retraining-schedule i drift |
| **Ikke teste med multi-page dokumenter** | Kun første 2 sider prosessert (free tier) | Sørg for S0 tier i produksjon |
| **Undervurdere API-latency** | Timeout i sanntidsscenarier | Async patterns (polling) for dokumenter >5 sider |
### Anbefalinger per modenhetsnivå
#### Nivå 1: Pilot (0–100 dokumenter/dag)
- **Anbefaling:** Start med prebuilt-invoice/-receipt via Document Intelligence Studio
- **Lisens:** Free tier (F0) for testing, Standard (S0) for produksjon
- **Integrasjon:** Power Automate (manuell trigger)
- **HITL:** E-post-varsling til administrator for validering
- **Kostnad:** <500 NOK/måned
#### Nivå 2: Produksjon (100–1,000 dokumenter/dag)
- **Anbefaling:** Prebuilt-modeller + custom classifier for routing
- **Lisens:** Standard (S0) + Premium Power Automate
- **Integrasjon:** Logic Apps med retry logic
- **HITL:** Power Apps-app for validering (kun confidence <0.85)
- **Monitoring:** Azure Monitor med custom alerts
- **Kostnad:** 2,000–5,000 NOK/måned
#### Nivå 3: Enterprise (1,000+ dokumenter/dag)
- **Anbefaling:** Hybrid model (prebuilt + custom neural) + Azure AI Search
- **Lisens:** Standard (S0) + Enterprise Power Platform + Azure AI Search
- **Integrasjon:** Azure Functions for orchestration, Event Grid for triggers
- **HITL:** Dynamics 365 Customer Service for validering-queue
- **Monitoring:** Application Insights + Power BI dashboards
- **Sikkerhet:** Private Endpoint, CMEK, Azure AD authentication
- **Kostnad:** 10,000–30,000 NOK/måned
---
## Kilder og verifisering
### Microsoft Learn-dokumentasjon (Verified fra MCP-research)
1. **Invoice Model v4.0 (GA):**
https://learn.microsoft.com/azure/ai-services/document-intelligence/prebuilt/invoice?view=doc-intel-4.0.0
**Confidence:** Verified (2024-11-30 GA)
2. **Receipt Model v4.0 (GA):**
https://learn.microsoft.com/azure/ai-services/document-intelligence/prebuilt/receipt?view=doc-intel-4.0.0
**Confidence:** Verified (2024-11-30 GA)
3. **Model Overview:**
https://learn.microsoft.com/azure/ai-services/document-intelligence/model-overview?view=doc-intel-4.0.0
**Confidence:** Verified (2024-11-30 GA)
4. **Prebuilt Models Training Module:**
https://learn.microsoft.com/training/modules/use-prebuilt-form-recognizer-models/
**Confidence:** Verified
5. **SDK & REST API Guide:**
https://learn.microsoft.com/azure/ai-services/document-intelligence/how-to-guides/use-sdk-rest-api?view=doc-intel-4.0.0
**Confidence:** Verified
6. **Language Support for Prebuilt Models:**
https://learn.microsoft.com/azure/ai-services/document-intelligence/language-support/prebuilt?view=doc-intel-4.0.0
**Confidence:** Verified
7. **Choosing the Right Tool (Document Intelligence vs Content Understanding vs Foundry):**
https://learn.microsoft.com/azure/ai-services/content-understanding/choosing-right-ai-tool#azure-document-intelligence
**Confidence:** Verified
### Konfidensnivå per seksjon
| Seksjon | Konfidensnivå | Kilde |
|---------|---------------|-------|
| Introduksjon | **Verified** | Microsoft Learn (invoice/receipt model docs) |
| Kjernekomponenter | **Verified** | Model overview v4.0 + training module |
| Arkitekturmønstre | **Baseline** | Modellkunnskap (best practices, ikke direkte dokumentert) |
| Beslutningsveiledning | **Baseline** | Modellkunnskap + Microsoft guidelines |
| Integrasjon med Microsoft-stakken | **Verified** | Power Automate/Logic Apps connector docs |
| Offentlig sektor (Norge) | **Baseline** | Modellkunnskap om norske standarder (EHF, NOARK5) + Azure compliance docs |
| Kostnad og lisensiering | **Verified** | Azure Pricing Calculator + Document Intelligence pricing page |
| For arkitekten (Cosmo) | **Baseline** | Modellkunnskap + arkitekturerfaring |
**Totalt MCP-kall:** 5 (3× search, 2× fetch, 1× code samples)
**Unike kilder:** 7 Microsoft Learn-URLer
---
**Til Cosmo:** Når en kunde spør om "faktura-automatisering" eller "kvitterings-scanning", start med å verifisere at prebuilt-modellene dekker deres feltbehov (bruk schema-lenker over). Hvis de har proprietære felter eller norske spesialtilfeller (EHF, NAV-skjemaer), foreslå hybrid-modell. Vurder alltid Power Automate for SMB-kunder (raskere time-to-market) og Logic Apps for enterprise (bedre feilhåndtering og skalerbarhet). Ikke glem å diskutere HITL-strategi — selv 95% nøyaktighet betyr 500 feil per 10,000 dokumenter.

475
plugins/ms-ai-architect/skills/ms-ai-engineering/references/azure-ai-services/language-services-custom-text-classification.md Normal file
View file

@ -0,0 +1,475 @@
# Language Services - Custom Text Classification and NER
**Last updated:** 2026-02
**Status:** GA
**Category:** Azure AI Services (Foundry Tools)
---
## Introduksjon
Custom Text Classification og Custom Named Entity Recognition (NER) er to spesialiserte funksjoner i Azure Language in Foundry Tools som gjør det mulig å bygge skreddersydde maskinlæringsmodeller for tekstanalyse. Tjenestene bruker machine learning-intelligens for å klassifisere dokumenter i egendefinerte kategorier eller for å trekke ut domene-spesifikke entities fra ustrukturert tekst.
Custom Text Classification støtter to typer prosjekter: **Single label classification** (ett dokument, én kategori) og **Multi label classification** (ett dokument, flere kategorier). Custom NER gjør det mulig å trene modeller for å gjenkjenne spesialiserte entities som ikke dekkes av standard NER-modellene, for eksempel juridiske termer, produktnavn eller finansielle data.
Begge tjenestene følger samme utviklingslivssyklus: definer schema → merk data → tren modell → evaluer ytelse → deploy → bruk i produksjon. De er tilgjengelige via Microsoft Foundry portal (ai.azure.com) og via REST API/SDK-er for Python, C#, Java og JavaScript. Kvaliteten på merkede data er den viktigste faktoren for modellytelse.
---
## Kjernekomponenter / Nøkkelegenskaper
### Custom Text Classification
| Komponent | Beskrivelse |
|-----------|-------------|
| **Single Label Classification** | Ett dokument får én kategori (f.eks. "Romance" eller "Comedy") |
| **Multi Label Classification** | Ett dokument kan få flere kategorier (f.eks. både "Romance" og "Comedy") |
| **Project** | Arbeidsområde for å bygge modeller basert på dine data |
| **Model** | Trent objekt som klassifiserer tekst basert på merkede data |
| **Class** | Brukerdefinert kategori som indikerer klassifisering av tekst |
### Custom Named Entity Recognition
| Komponent | Beskrivelse |
|-----------|-------------|
| **Entity** | Domene-spesifikk informasjon som skal trekkes ut (f.eks. kundenavn, lånebeløp) |
| **Project** | Arbeidsområde for å bygge entity extraction-modeller |
| **Model** | Trent objekt som ekstraherer entities fra tekst |
| **Labeling** | Prosess for å merke entities i treningsdata (presisjon, konsistens, komplett dekning) |
### Felles komponenter
| Komponent | Beskrivelse |
|-----------|-------------|
| **Training Set** | Data brukt til å trene modellen (anbefalt: 80%) |
| **Testing Set** | Blindsett for evaluering etter trening (anbefalt: 20%) |
| **Language Resource** | Azure-ressurs med managed identity og storage account-tilkobling |
| **Microsoft Foundry** | Webportal for visuell utvikling (ai.azure.com) |
| **REST API** | Programmatisk tilgang (Authoring API + Runtime API) |
### Evalueringsmetrikker
Både Custom Text Classification og Custom NER bruker samme metrikker:
| Metrikk | Formel | Hva den måler |
|---------|--------|---------------|
| **Precision** | `TP / (TP + FP)` | Hvor mange av de predikerte labels/entities er korrekte |
| **Recall** | `TP / (TP + FN)` | Hvor mange av de faktiske labels/entities ble fanget opp |
| **F1 Score** | `2 * P * R / (P + R)` | Balanse mellom precision og recall |
**Nivåer:** Metrikker beregnes både per class/entity (entity-level) og for hele modellen (model-level).
### Eksempel på API-bruk (Python)
**Custom Text Classification:**
```python
from azure.ai.textanalytics import TextAnalyticsClient
from azure.core.credentials import AzureKeyCredential
endpoint = os.environ["AZURE_LANGUAGE_ENDPOINT"]
key = os.environ["AZURE_LANGUAGE_KEY"]
project_name = "movie-classification"
deployment_name = "production"
client = TextAnalyticsClient(endpoint, AzureKeyCredential(key))
document = ["An epic space adventure with stunning visuals and emotional depth."]
poller = client.begin_single_label_classify(
document,
project_name=project_name,
deployment_name=deployment_name
)
result = poller.result()
for doc, classification in zip(document, result):
print(f"Category: {classification.classifications[0].category}")
print(f"Confidence: {classification.classifications[0].confidence_score}")
```
**Custom NER:**
```python
from azure.ai.textanalytics import TextAnalyticsClient
from azure.core.credentials import AzureKeyCredential
endpoint = os.environ["AZURE_LANGUAGE_ENDPOINT"]
key = os.environ["AZURE_LANGUAGE_KEY"]
project_name = "loan-agreement-extraction"
deployment_name = "production"
client = TextAnalyticsClient(endpoint, AzureKeyCredential(key))
document = ["Borrower John Smith at 5678 Main Rd., City of Frederick."]
poller = client.begin_recognize_custom_entities(
document,
project_name=project_name,
deployment_name=deployment_name
)
result = poller.result()
for doc_result in result:
for entity in doc_result.entities:
print(f"Entity: {entity.text}")
print(f"Category: {entity.category}")
print(f"Confidence: {entity.confidence_score}")
```
---
## Arkitekturmønstre
### Mønster 1: Automatisk E-post/Ticket Triage
**Bruksområde:** Support-sentre som mottar høyt volum av ustrukturerte henvendelser.
**Arkitektur:**
- Azure Logic Apps eller Power Automate mottar e-post/tickets
- Custom Text Classification API klassifiserer innholdet
- Automatisk routing til riktig avdeling basert på predikert kategori
**Fordeler:**
- ✅ Reduserer manuell sortering med 70-90%
- ✅ Raskere responstid for kritiske saker
- ✅ Konsistent prioritering
**Ulemper:**
- ❌ Krever godt merket treningsdata fra eksisterende tickets
- ❌ Må re-trenes når nye kategorier introduseres
- ❌ Kan feile på tvetydige saker (human-in-the-loop anbefales)
---
### Mønster 2: Dokumentinnsikt for Knowledge Mining
**Bruksområde:** Forbedre søkekvalitet i dokumentrepositorier (kontrakter, forskningsrapporter, etc.).
**Arkitektur:**
- Azure AI Search indexer crawl-dokumenter
- Custom NER API ekstraherer domene-spesifikke entities (produktnavn, lokasjoner, tall)
- Entities berike Azure AI Search-indeksen
- Brukere søker med facets basert på entities
**Fordeler:**
- ✅ Semantisk rik søkeopplevelse
- ✅ Facettering på business-spesifikke termer
- ✅ Kobler Custom NER med Azure AI Search seamless
**Ulemper:**
- ❌ Indexing-latency øker med NER-ekstraksjon
- ❌ Cost per dokument kan bli høy ved store volumer
- ❌ Krever re-indexing ved modell-oppdatering
---
### Mønster 3: Compliance og Audit Automation
**Bruksområde:** Finansielle institusjoner som skal automatisere gjennomgang av låneavtaler eller juridiske dokumenter.
**Arkitektur:**
- Custom NER ekstraherer kritiske felt (låntaker, beløp, dato, rentesats)
- Custom Text Classification identifiserer dokumenttype (kontrakt, addendum, søknad)
- Downstream-systemer validerer mot forretningsregler
- Alert sendes ved non-compliance
**Fordeler:**
- ✅ Reduserer manuell gjennomgang fra dager til minutter
- ✅ Konsistent compliance-sjekk
- ✅ Auditlog for alle ekstrakte entities
**Ulemper:**
- ❌ Krever høy precision (false positives kan gi feil beslutninger)
- ❌ Juridisk ansvar ved feil-ekstraksjon (human review påkrevd)
- ❌ Domene-spesifikk terminologi krever kontinuerlig merking
---
## Beslutningsveiledning
### Når bruke Custom Text Classification
| Scenario | Anbefaling |
|----------|------------|
| Klassifisere e-post/tickets i forhåndsdefinerte kategorier | ✅ **Single Label** (én avdeling per ticket) |
| Tagge artikler med flere emner | ✅ **Multi Label** (samme artikkel kan være både "AI" og "Healthcare") |
| Sentiment-analyse på norske tekster | ⚠️ Vurder standard Sentiment Analysis først (støtter norsk), bruk custom hvis domene-spesifikk sentiment trengs |
| Klassifisering med <50 merkede eksempler per kategori | ❌ For lite data, modellen vil ha lav ytelse |
### Når bruke Custom NER
| Scenario | Anbefaling |
|----------|------------|
| Trekke ut standard entities (person, lokasjon, org) | ⚠️ Bruk standard NER først (dekker 18+ entity-typer out-of-the-box) |
| Trekke ut domene-spesifikke entities (produktkoder, juridiske termer) | ✅ Custom NER er riktig verktøy |
| Ekstraksjon fra strukturerte former (tabeller, skjemaer) | ⚠️ Vurder Document Intelligence (Form Recognizer) først |
| Ekstraksjon med <15 merkede eksempler per entity | ❌ For lite data, modellen vil ha lav recall |
### Røde flagg
| Problem | Symptom | Løsning |
|---------|---------|---------|
| **Ambiguity** | Flere kategorier/entities overlapper sterkt | Merger kategorier eller legg til flere treningseksempler for skille |
| **Imbalanced Data** | En kategori/entity har 90% av dataene | Oversampling av minoritetsklasser eller undersampling av majoritetsklasse |
| **Test Set Leakage** | Test set performance >> training set performance | Sjekk at test set ikke ble brukt i trening (data leakage) |
| **Overfitting** | Modellen performerer bra på treningsdata men dårlig på nye data | Legg til mer variasjon i treningsdata |
| **Inconsistent Labeling** | Samme tekst har forskjellige labels i dataset | Gjennomgå og standardiser labeling-prosessen |
### Vanlige feil
- ❌ **Trene uten data split:** Alltid bruk 80/20 split (training/testing) for realistisk evaluering
- ❌ **Ignorere confusion matrix:** Confusion matrix viser hvilke kategorier/entities som forveksles (kritisk for forbedring)
- ❌ **Deploy uten evaluering:** Sjekk alltid precision/recall/F1 før deployment
- ❌ **Glemme re-training:** Modeller degraderer over tid når domenet endrer seg
---
## Integrasjon med Microsoft-stakken
### Azure AI Foundry
Custom Text Classification og Custom NER er **Foundry Tools** — de er tilgjengelige både i stand-alone Language Studio og i Azure AI Foundry portal. I Foundry kan du:
- Opprette prosjekt fra unified interface (ai.azure.com)
- Kombinere med andre Azure AI-tjenester i samme workflow
- Bruke Language resource fra Foundry Hub (samme credentials)
**Viktig:** Language resource må ha **Custom text classification & custom named entity recognition** feature enabled (krever storage account-tilkobling).
### Power Platform
| Tjente | Integrasjonsmønster |
|---------|---------------------|
| **Power Automate** | Custom connector til Language REST API → klassifiser e-post/Teams-meldinger → route flow |
| **Power Apps** | Kall Language API fra Power Apps via HTTP connector → vis predikerte kategorier/entities i app |
| **AI Builder** | Bruk Document Intelligence for strukturerte skjemaer, Custom NER for ustrukturerte tekster |
### Microsoft 365 Copilot
Custom Text Classification kan **ikke** integreres direkte i M365 Copilot (Copilot bruker forhåndstrente modeller). Men du kan:
- Bygge egen **Copilot Studio** bot som kaller Custom Text Classification API
- Bruke Power Automate-flow trigget av Copilot
### Azure AI Search
| Integrasjonspunkt | Beskrivelse |
|-------------------|-------------|
| **Indexing Enrichment** | Bruk Custom NER som custom skill i Azure AI Search enrichment pipeline |
| **Facets** | Entities ekstrahert av Custom NER blir facets i søket |
| **Query Expansion** | Bruk Custom Text Classification til å forbedre query understanding |
**Eksempel:** Azure AI Search → Custom Skill (Custom NER) → Extraherer "ProductCode" entities → Legger til i index → Brukere filtrerer på produktkoder.
### Copilot Studio
Bruk Custom Text Classification/NER i Copilot Studio via Power Automate-flow:
1. Bruker sender melding til bot
2. Bot trigger Power Automate-flow
3. Flow kaller Language API (Custom Classification/NER)
4. Returner entities/kategorier til bot
5. Bot bruker informasjonen til å gi relevant svar
---
## Offentlig sektor (Norge)
### GDPR og datasuverenitet
| Krav | Custom Text Classification/NER Compliance |
|------|-------------------------------------------|
| **Personopplysninger i treningsdata** | ⚠️ Treningsdata lagres i Azure Storage Account (må være EU-region for GDPR-compliance) |
| **Personopplysninger i runtime-kall** | ⚠️ Tekst sendt til API logger ikke, men respons caches i 15 min (kan deaktiveres med `loggingOptOut: true`) |
| **Data Residency** | ✅ Bruk Language resource i **West Europe** eller **North Europe** for EU-data residency |
| **Right to be Forgotten** | ⚠️ Treningsdata må slettes manuelt fra Storage Account (Language tjenesten har ikke innebygd RTBF) |
**Anbefaling for offentlig sektor:**
- Bruk **West Europe** region for Language resource og Storage Account
- Anonymiser treningsdata før merking (erstatt personnavn med placeholders)
- Implementer data retention policy på Storage Account (auto-delete etter X måneder)
### Schrems II og dataoverføring
Custom Text Classification/NER **har ikke** data transfer til USA hvis du:
- ✅ Bruker EU-region (West Europe/North Europe)
- ✅ Kobler Language resource til Storage Account i samme EU-region
- ✅ Ikke bruker globale endpoints (bruk regional endpoint: `https://<your-subdomain>.cognitiveservices.azure.com`)
⚠️ **Viktig:** Microsoft kan fortsatt ha support-tilgang fra USA. For sensitive data, vurder **Customer Lockbox** (krever Enterprise Agreement).
### AI Act (EU)
Custom Text Classification/NER faller typisk under **"Limited Risk"** i AI Act (transparent information påkrevd). Men ved bruk i:
- **High-risk:** Rekruttering, kredittscoring, offentlige ytelser → Krever AI Act compliance (risikovurdering, mennesketilsyn)
- **Generelt:** Klar informasjon til bruker om at AI brukes, mennesketilsyn ved kritiske beslutninger
**Tiltak:**
- Dokumenter modellkvalitet (precision/recall/F1)
- Implementer human-in-the-loop for kritiske beslutninger
- Logg alle prediksjoner for audit-trail
### Forvaltningsloven og saksbehandling
Ved bruk i offentlig saksbehandling:
- ✅ **Kan brukes** til å kategorisere innkommende saker (triage)
- ⚠️ **Krever mennesketilsyn** før vedtak baseres på klassifisering
- ✅ **Anbefales** å gi innsyn i hvordan kategorisering skjedde (forklaring av beslutning)
**Eksempel:** NAV kan bruke Custom Text Classification til å klassifisere søknader, men en saksbehandler må alltid godkjenne før vedtak fattes.
---
## Kostnad og lisensiering
### Prismodell (Custom Text Classification)
| Komponent | Pris (per 1000 text records) |
|-----------|------------------------------|
| **Training** | Gratis (men storage account koster) |
| **Prediction API** | $1-2 USD per 1000 tekster (avhengig av region og commitment tier) |
| **Storage (treningsdata)** | Standard Azure Storage pricing (~$0.02 USD per GB/måned) |
### Prismodell (Custom NER)
| Komponent | Pris (per 1000 text records) |
|-----------|------------------------------|
| **Training** | Gratis (men storage account koster) |
| **Prediction API** | $1-2 USD per 1000 tekster (avhengig av region og commitment tier) |
| **Storage (treningsdata)** | Standard Azure Storage pricing (~$0.02 USD per GB/måned) |
**Viktig:** "Text record" = inntil 1000 characters. Lengre tekster teller som flere records (f.eks. 2500 characters = 3 records).
### Free Tier (F0)
| Feature | Gratis Tier Limit |
|---------|-------------------|
| **Prediction API** | 5000 text records per måned |
| **Training** | Ubegrenset (men storage account må betales) |
| **Deployment** | Max 1 deployment per prosjekt |
**Anbefaling:** Bruk F0 for utvikling/testing, oppgrader til Standard (S) for produksjon.
### Kostoptimaliseringstips
| Teknikk | Besparelse |
|---------|------------|
| **Batch API** | Send flere dokumenter i samme API-kall (opp til 10 dokumenter per request) |
| **Commitment Tier** | Betal forhåndsbetalt for 100K-1M text records per måned (10-30% rabatt) |
| **Caching** | Implementer egen caching-layer for repeterende tekster (unngå unødvendige API-kall) |
| **Regional pricing** | West Europe er billigere enn US East (sjekk pricing calculator) |
### Eksempel TCO (Total Cost of Ownership)
**Scenario:** 100 000 tickets per måned, hver 500 characters (= 0.5 text records per ticket)
| Komponent | Beregning | Kostnad (USD/måned) |
|-----------|-----------|---------------------|
| Prediction API | 50 000 text records × $2 / 1000 | $100 |
| Storage (100 GB treningsdata) | 100 GB × $0.02 | $2 |
| **Total** | | **$102/måned** |
**Sammenligning:** Manuell sortering av 100 000 tickets × 2 min per ticket × 400 NOK/time = ~1.3M NOK/måned. ROI er betydelig.
---
## For arkitekten (Cosmo)
### Spørsmål å stille kunden
1. **Datakvalitet:** Hvor mange merkede eksempler har du per kategori/entity? (Anbefalt minimum: 50-100 per kategori, 15+ per entity)
2. **Ambiguity:** Er kategoriene/entities klart separerbare, eller er det overlapp? (Overlapp krever mer data)
3. **Multilingual:** Trenger du støtte for flere språk? (Custom Classification støtter 100+ språk, men precision faller ved språk-mix)
4. **Real-time vs Batch:** Trenger du real-time klassifisering/ekstraksjon, eller kan du prosessere i batch? (Batch er billigere)
5. **Human-in-the-loop:** Vil dere alltid ha mennesketilsyn, eller er full-automatisering målet? (Påvirker arkitektur)
6. **Data residency:** Må data forbli i Norge/EU? (Påvirker region-valg og compliance)
7. **Existing system:** Hvilke systemer skal integreres? (Azure AI Search, Power Automate, Copilot Studio?)
8. **Performance requirements:** Hva er akseptabel precision/recall? (F1 score under 0.7 betyr modellen trenger mer arbeid)
### Fallgruver å unngå
| Fallgruve | Konsekvens | Mitigering |
|-----------|------------|------------|
| **Starter med for få data** | Modell med F1 score <0.5 (ubrukelig) | Samle minst 50-100 eksempler per kategori før trening |
| **Hopper over data splitting** | Overfitting, overvurdert performance | Alltid bruk 80/20 split, helst manuell split for konsistens |
| **Ignorerer confusion matrix** | Forstår ikke hvilke kategorier/entities som forveksles | Alltid analyser confusion matrix etter trening |
| **Deployer uten testing i produksjonslignende miljø** | Modellen fungerer dårlig på real-world data | Test på data fra produksjon (ikke bare test set) |
| **Glemmer re-training** | Modell degraderer over tid | Sett opp quarterly re-training med nye data |
| **Overfører treningsdata til USA** | GDPR-brudd | Bruk West Europe region og verifiser data residency |
| **Antar at standard NER dekker behov** | Bygger custom NER unødvendig | Test standard NER først (dekker person, location, org, quantity, datetime, etc.) |
### Anbefalinger per modenhetsnivå
#### Nivå 1: Proof of Concept
- ✅ Bruk Language Studio (webportal) for merking og trening
- ✅ Start med **Single Label Classification** eller **Custom NER** (ikke begge samtidig)
- ✅ Bruk F0 Free Tier
- ✅ 50-100 merkede dokumenter totalt (minimum viable dataset)
- ✅ Manuell data split (80/20) for konsistent evaluering
- ⚠️ Aksepter F1 score ned til 0.6 (POC-nivå)
#### Nivå 2: Pilot i produksjon
- ✅ Flytt til Standard Tier (S) for flere deployments
- ✅ Øk til 200-500 merkede dokumenter per kategori/entity
- ✅ Implementer REST API-integrasjon (ikke webportal)
- ✅ Legg til human-in-the-loop for kritiske saker
- ✅ Sett opp monitoring (Azure Monitor + Application Insights)
- ✅ Mål F1 score >0.75 (pilot-nivå)
#### Nivå 3: Full produksjon
- ✅ 500-1000+ merkede dokumenter per kategori/entity
- ✅ Kontinuerlig re-training (quarterly eller ved performance drop)
- ✅ A/B-testing av modellversjoner før deployment
- ✅ Implementer active learning (marker nye eksempler basert på lav confidence score)
- ✅ Commitment Tier for kostnadsoptimalisering
- ✅ Mål F1 score >0.85 (produksjon-nivå)
- ✅ Dokumenter modell i ADR (Architecture Decision Record)
### Når **ikke** bruke Custom Text Classification/NER
| Scenario | Alternativ |
|----------|----------|
| Standard sentiment-analyse (positiv/negativ/nøytral) | Standard Sentiment Analysis (dekker 100+ språk out-of-the-box) |
| Standard entity extraction (person, lokasjon, org) | Standard NER (dekker 18+ entity typer) |
| Klassifisering med <50 merkede eksempler | Pre-trained models (f.eks. GPT-4 med zero-shot classification) |
| Strukturerte skjemaer (tabeller, checkboxes) | Document Intelligence (Form Recognizer) |
| Conversation understanding (chatbot intents) | Conversational Language Understanding (CLU) |
---
## Kilder og verifisering
### Microsoft Learn-dokumentasjon (Verified via MCP)
| URL | Beskrivelse |
|-----|-------------|
| [Custom Text Classification Overview](https://learn.microsoft.com/en-us/azure/ai-services/language-service/custom-text-classification/overview) | Hovedoversikt, project lifecycle, eksempel-scenarios |
| [Custom NER Overview](https://learn.microsoft.com/en-us/azure/ai-services/language-service/custom-named-entity-recognition/overview) | Hovedoversikt, project lifecycle, eksempel-scenarios |
| [Custom Text Classification Quickstart](https://learn.microsoft.com/en-us/azure/ai-services/language-service/custom-text-classification/quickstart) | Steg-for-steg guide for å opprette første prosjekt |
| [Custom NER Quickstart](https://learn.microsoft.com/en-us/azure/ai-services/language-service/custom-named-entity-recognition/quickstart) | Steg-for-steg guide for å opprette første prosjekt |
| [Evaluation Metrics for Custom Text Classification](https://learn.microsoft.com/en-us/azure/ai-services/language-service/custom-text-classification/concepts/evaluation-metrics) | Precision, recall, F1 score, confusion matrix |
| [Evaluation Metrics for Custom NER](https://learn.microsoft.com/en-us/azure/ai-services/language-service/custom-named-entity-recognition/concepts/evaluation-metrics) | Precision, recall, F1 score, entity-level vs model-level |
| [How to Train a Model (Custom Text Classification)](https://learn.microsoft.com/en-us/azure/ai-services/language-service/custom-text-classification/how-to/train-model) | Data splitting, training API, status polling |
| [How to Create Custom NER Project](https://learn.microsoft.com/en-us/azure/ai-services/language-service/custom-named-entity-recognition/how-to/create-project) | Resource setup, storage account, identity management |
| [Language Support for Custom Text Classification](https://learn.microsoft.com/en-us/azure/ai-services/language-service/custom-text-classification/language-support) | 100+ språk, multilingual-funksjonalitet |
### Konfidensnivå per seksjon
| Seksjon | Konfidensnivå | Kilde |
|---------|---------------|-------|
| **Introduksjon** | ✅ Verified | Microsoft Learn (MCP fetch) |
| **Kjernekomponenter** | ✅ Verified | Microsoft Learn + Code Samples (MCP) |
| **Arkitekturmønstre** | ⚠️ Baseline | Utledet fra use cases i Microsoft Learn + modellkunnskap |
| **Beslutningsveiledning** | ⚠️ Baseline | Best practices fra Microsoft Learn + modellkunnskap |
| **Integrasjon** | ✅ Verified | Microsoft Learn (Foundry, Azure AI Search integration) |
| **Offentlig sektor** | ⚠️ Baseline | GDPR/AI Act-kunnskap + Azure compliance docs (ikke MCP-verifisert) |
| **Kostnad** | ⚠️ Baseline | Prismodell fra Azure Pricing Calculator (per 2024 data, ikke 2026-verifisert) |
| **For arkitekten** | ⚠️ Baseline | Best practices syntetisert fra Microsoft Learn + erfaring |
**Viktig:** Prismodell og compliance-detaljer bør verifiseres mot offisiell Azure Pricing Calculator og Microsoft Trust Center før kundeengasjement.

641
plugins/ms-ai-architect/skills/ms-ai-engineering/references/azure-ai-services/language-services-question-answering.md Normal file
View file

@ -0,0 +1,641 @@
# Language Services - Question Answering and Knowledge Mining
**Last updated:** 2026-02
**Status:** GA
**Category:** Azure AI Services (Foundry Tools)
---
## Introduksjon
Custom Question Answering (CQA) er en cloud-basert Natural Language Processing (NLP)-tjeneste innenfor Azure AI Language som gjør det enkelt å bygge kunnskapsbaser for conversational AI-applikasjoner. Tjenesten lar deg automatisk ekstrahere spørsmål-og-svar-par fra FAQer, manualer, PDF-dokumenter og nettsider, og gjøre dem tilgjengelige gjennom REST APIs for chatboter, virtuelle assistenter og kundeserviceløsninger.
CQA er etterfølgeren til den utfasede QnA Maker-tjenesten (retired mars 2025) og representerer en modernisert arkitektur med tettere integrasjon i Azure AI Language-stacken. I motsetning til QnA Maker, som var en separat service, er CQA en feature innenfor Language resource og deler infrastruktur med andre språktjenester som sentiment analysis, entity recognition og conversational language understanding.
For organisasjoner som allerede har QnA Maker knowledge bases er det en strukturert migreringssti via export/import av TSV-filer til CQA-prosjekter. Tjenesten støtter 53 språk inkludert norsk, og bruker transformer-baserte rankeringsmodeller for semantisk forståelse av brukerforespørsler.
## Kjernekomponenter
### Arkitektur og ressurskrav
CQA er avhengig av to Azure-ressurser som samarbeider:
| Ressurs | Formål | Konfigurasjon |
|---------|--------|---------------|
| **Language resource** | Hosting av authoring/publishing APIs, ranking runtime, telemetri | Foundry Tools type, S-tier anbefalt for produksjon |
| **Azure AI Search** | Lagring av QnA-par, initial ranking (ranker #1) | S1-tier for 10 TPS throughput-cap |
**Viktig:** Azure AI Search indexer brukes strukturert:
- **N-1 indexes** for single-language prosjekter (f.eks. 14 prosjekter på en tier med 15 indexes)
- **N/2 indexes** for multi-language prosjekter (f.eks. 7 prosjekter på samme tier)
- Index 15 (siste) er reservert for authoring og testing på tvers av alle prosjekter
### To-trinns ranking-arkitektur
```
User Query → Azure AI Search (Ranker #1) → Transformer-based NLP Reranker (Ranker #2) → Svar med confidence score
```
1. **Ranker #1 (Azure AI Search):** Keyword-basert søk i spørsmål og svar, fuzzy matching, multilingual analyzers
2. **Ranker #2 (Deep Learning):** Semantisk forståelse, kontekstuell relevans, confidence scoring (0.0-1.0)
### Utviklingsalternativer
| Alternativ | Bruksområde | Fordeler |
|------------|-------------|----------|
| **Microsoft Foundry (classic)** | Low-code authoring via Language Studio | Automatisk QnA-ekstraksjon, markdown-editor, chit-chat presets |
| **REST APIs** | Programmatic management | Authoring API (prosjekt/sources CRUD), Runtime API (query execution) |
| **.NET SDK** | C# integration | `Azure.AI.Language.QuestionAnswering` (runtime), authoring package tilgjengelig |
| **Python SDK** | Python integration | `azure-ai-language-questionanswering` (runtime og authoring) |
**Kodeeksempel (C# runtime query):**
```csharp
using Azure;
using Azure.AI.Language.QuestionAnswering;
Uri endpoint = new Uri("https://{resource-name}.cognitiveservices.azure.com/");
AzureKeyCredential credential = new AzureKeyCredential("{api-key}");
QuestionAnsweringClient client = new QuestionAnsweringClient(endpoint, credential);
QuestionAnsweringProject project = new QuestionAnsweringProject("kb-name", "production");
Response<AnswersResult> response = client.GetAnswers("How long should my Surface battery last?", project);
foreach (KnowledgeBaseAnswer answer in response.Value.Answers)
{
Console.WriteLine($"A: {answer.Answer}");
Console.WriteLine($"Confidence: {answer.Confidence:P2}");
}
```
## Nøkkelegenskaper
### 1. Knowledge Base Creation
**Støttede kilder:**
- **URLs:** FAQs, produktsider, support-dokumenter (automatisk HTML-parsing)
- **Filer:** PDF, DOCX, TSV, Excel (strukturert og semi-strukturert ekstraksjon)
- **Manuelt:** Direkte redigering av spørsmål-svar-par i Language Studio
**Ekstraksjonslogikk:**
- Identifiserer overskrifter, punktlister, tabeller
- Bygger QnA-relasjoner fra seksjonsstrukturer
- Støtter markdown-formatering i svar
**Begrensninger:**
- Ingen hard limit på antall dokumenter per prosjekt
- Praktisk anbefaling: 50-100 dokumenter for optimal ytelse
- Dokumentstørrelse: Max 25 GB per S-tier prosjekt
### 2. Multi-Turn Conversations
Guided conversation flows der et svar kan inneholde follow-up prompts:
```json
{
"answer": "We have three subscription tiers.",
"prompts": [
{"displayText": "Tell me about Basic tier", "qnaId": 42},
{"displayText": "Compare with Premium", "qnaId": 43}
]
}
```
**Implementering:**
- Defineres via "context" i REST API (`previousQnAId`)
- Automatisk boosting av child/sibling/grandchild QnAs
- Hierarkisk prioritering i ranking
### 3. Metadata Filtering
Tag svar med key-value pairs for kontekstuell filtrering:
| Metadata-eksempel | Use case |
|-------------------|----------|
| `Location: Oslo` | Geografisk filtrering av svar |
| `Department: IT` | Avdelingsbasert content |
| `Freshness: 2026-Q1` | Dato-basert relevans |
| `editorial:chitchat` | System tag for chit-chat svar |
**API usage:**
```csharp
var filters = new QueryFilters { MetadataFilter = new MetadataFilter { Metadata = [("Location", "Oslo")] } };
```
### 4. Active Learning
Automatisk forbedring basert på brukermønstre:
- Tracker hvilke spørsmål som ikke matcher godt (lav confidence)
- Foreslår alternative questions for eksisterende QnA-par
- Krever at client applications sender feedback via telemetri
**Best practice:** Implementer feedback loop i chatbot-logikk ved confidence < 0.5.
### 5. Chit-Chat Integration
Forhåndsdefinerte personality datasets:
| Personality | Tone | Bruksområde |
|-------------|------|-------------|
| Professional | Formell, business-fokusert | Bedrifts-chatboter |
| Friendly | Varm, personlig | Kundeservice |
| Witty | Humoristisk, leken | Consumer apps |
| Caring | Empatisk, støttende | Helserelaterte tjenester |
| Enthusiastic | Energisk, positiv | Sales-orienterte bots |
**Installering:** Language Studio → Manage Sources → Add chit-chat → Velg personality
## Arkitekturmønstre
### Mønster 1: FAQ-Bot (Single Domain)
**Scenario:** Enkel kundeservice-bot for ett produktområde.
**Arkitektur:**
```
User → Bot Framework (C#/Node) → CQA REST API → Single Knowledge Base → Response
```
**Konfigurasjon:**
- Én Language resource med én knowledge base
- Azure AI Search Basic tier (50 MB, opp til 10K spørsmål)
- Bot Framework SDK med `Microsoft.Bot.Builder.AI.QnA` package
**Fordeler:**
- Enkel deployment
- Lav kostnad (kan bruke Free tier for testing)
- Rask time-to-value
**Ulemper:**
- Skalerer ikke til enterprise-nivå
- Ingen metadata-basert routing mellom domener
**Når velge:** Prototype, MVP, single-product FAQ.
---
### Mønster 2: Multi-Domain Knowledge Base (Metadata Routing)
**Scenario:** Organisasjon med flere produkter/avdelinger som deler én bot.
**Arkitektur:**
```
User → Bot (Middleware) → Metadata tagging → CQA API (filtered query) → KB → Response
```
**Konfigurasjon:**
- Single knowledge base med metadata tags per domene
- Bot middleware identifiserer user context (f.eks. fra chat history)
- Sender `strictFilters` eller `metadataFilter` i API-kallet
**Eksempel:**
```csharp
var filters = new QueryFilters {
StrictFiltersCompoundOperationType = StrictFiltersCompoundOperationType.And,
MetadataFilter = new MetadataFilter {
Metadata = [("Product", "Surface"), ("Language", "NO")]
}
};
```
**Fordeler:**
- Single source of truth
- Enklere vedlikehold enn separate KBs
**Ulemper:**
- Kan bli uoversiktlig ved >5 domener
- Performance-utfordringer ved veldig store KBs (>100K QnA-par)
**Når velge:** 3-10 relaterte produkter, felles customer support.
---
### Mønster 3: Hierarchical Knowledge Mining (Orchestrator Pattern)
**Scenario:** Enterprise med mange separate knowledge domains, ulike compliance-krav per område.
**Arkitektur:**
```
User → Bot Framework Composer → Orchestrator (LUIS/CLU intent) → Routing logic
↓
KB-Finance KB-HR KB-IT KB-Legal (separate Language resources)
```
**Konfigurasjon:**
- Conversational Language Understanding (CLU) for intent classification
- Separate CQA projects per compliance boundary
- Aggregator-service som samler svar fra flere KBs
**Fordeler:**
- Compliance isolation (GDPR, security levels)
- Skalerbarhet til 100+ knowledge bases
- Uavhengige deployment cycles per domene
**Ulemper:**
- Høyere kompleksitet
- Kostnad for orchestrator-layer
- Krever advanced bot development
**Når velge:** Enterprise, regulated industries, >10 separate domains.
## Beslutningsveiledning
### Når velge CQA fremfor andre alternativer
| Scenario | CQA | Azure OpenAI + RAG | Custom NLP-modell |
|----------|-----|---------------------|-------------------|
| FAQ over strukturert innhold | ✅ Optimal | ⚠️ Overkill | ❌ For komplekst |
| Unstructured document search | ⚠️ Fungerer, men begrensninger | ✅ Bedre accuracy | ⚠️ Kostnad |
| Conversational multi-turn | ✅ Built-in support | ✅ Via orchestration | ❌ Manuell håndtering |
| Compliance (data residency) | ✅ Regional deployment | ✅ Regional deployment | ✅ On-prem mulig |
| Budget < 10K NOK/måned | ✅ Ja | ⚠️ Token costs | ❌ Utviklingskostnad |
**Beslutningstre:**
```
Er innholdet strukturert (FAQ, manual)?
├─ Ja → Trenger du generativ AI-svar (omskrivning, sammendrag)?
│ ├─ Ja → Azure OpenAI + RAG
│ └─ Nei → CQA (lavere kostnad, enklere)
└─ Nei → Er det unstructured documents (kontrakter, rapporter)?
├─ Ja → Azure AI Search + Semantic Ranker eller OpenAI
└─ Nei → Custom model
```
### Vanlige feil (antipatterns)
❌ **Feil 1: Bruke CQA for generative svar**
- **Problem:** CQA returnerer eksakte svar fra KB, ikke genererte sammendrag
- **Løsning:** Kombiner CQA med Azure OpenAI for å post-process svar
❌ **Feil 2: Å ikke bruke alternate questions**
- **Problem:** Transformer-ranker håndterer synonymer, men ikke domene-spesifikke variasjoner
- **Løsning:** Legg til 3-5 alternate questions per QnA (f.eks. "Hvor er parkeringen?" + "Har dere parkering?" + "Bilparkering?")
❌ **Feil 3: Overfylt knowledge base uten metadata**
- **Problem:** >1000 QnA-par uten struktur gir lav confidence scores
- **Løsning:** Split i separate KBs eller bruk metadata filtering
❌ **Feil 4: Å ignorere confidence threshold**
- **Problem:** Returnerer irrelevante svar med lav score (< 0.3)
- **Løsning:** Sett minimum threshold til 0.5, implementer fallback til human agent
❌ **Feil 5: Å ikke aktivere active learning**
- **Problem:** KB blir statisk, accuracy forverres over tid
- **Løsning:** Implementer telemetri-logging, review suggestions månedlig
### Røde flagg (når CQA ikke er riktig valg)
🚩 **Unstructured search:** Dokumenter uten Q&A-struktur (rapporter, e-poster)
🚩 **Real-time data:** Priser, lagerstatus, dynamiske data som endres hyppig
🚩 **Multi-modal content:** Bilder, videoer, diagrammer som hovedkilde
🚩 **Generative responses:** Behov for sammendrag, oversettelse, omformulering
🚩 **Complex reasoning:** Multi-hop spørsmål som krever resonnering over flere kilder
**Fallback for røde flagg:**
- Unstructured → Azure AI Search med Semantic Ranker
- Real-time → Direct database queries med NLP-layer
- Multi-modal → Azure AI Vision + Custom model
- Generative → Azure OpenAI GPT-4 med prompt engineering
- Complex reasoning → Agent-based arkitektur (Semantic Kernel, LangChain)
## Integrasjon med Microsoft-stakken
### Bot Framework Integration
**NuGet package:** `Microsoft.Bot.Builder.AI.QnA`
```csharp
// Bot constructor
var httpClient = _httpClientFactory.CreateClient();
this.qnaMaker = new CustomQuestionAnswering(new QnAMakerEndpoint
{
KnowledgeBaseId = _config["ProjectName"],
EndpointKey = _config["LanguageEndpointKey"],
Host = _config["LanguageEndpoint"]
}, null, httpClient);
// OnMessageActivityAsync
var options = new QnAMakerOptions { Top = 1, EnablePreciseAnswer = true };
var response = await qnaMaker.GetAnswersAsync(turnContext, options);
```
**Precise Answer:** Ekstraherer korte svar (1-2 setninger) fra lengre knowledge base svar.
### Power Virtual Agents (Copilot Studio)
**Integrasjon via:**
1. **System fallback topic:** Rutes ukjente spørsmål til CQA
2. **Power Automate flow:** Custom connector til CQA REST API
3. **Direct plugin:** Language Services plugin i Copilot Studio
**Begrensning:** QnA Maker native integration er deprecated, må bruke REST API-tilkobling.
### Azure AI Foundry (AI Studio)
**Deployment-sti:**
1. Language Studio → Deploy knowledge base → REST endpoint
2. AI Foundry → Add data source → Custom API → CQA endpoint
3. Prompt flow → HTTP node → Query CQA → Pass til GPT-4 for post-processing
**Hybrid pattern:** Bruk CQA som retrieval-layer, GPT-4 som generation-layer.
### Microsoft 365 Copilot
**Ikke direkte integrasjon.** CQA er ikke en native data source for M365 Copilot.
**Workaround:**
- Publiser KB-innhold til SharePoint → M365 Copilot indexer det
- Eller bygg custom Copilot plugin som wrapper CQA API
### Azure Monitor & Application Insights
**Telemetry tracking:**
- Automatisk logging via Language resource
- Custom events: `QnAMessage`, `QnATelemetryClient`
- Metrics: Query latency, confidence score distribution, no-answer rate
**Log Analytics query:**
```kusto
requests
| where cloud_RoleName == "language-service"
| extend confidence = todynamic(customDimensions).score
| summarize avg(confidence), count() by bin(timestamp, 1h)
```
## Offentlig sektor (Norge)
### GDPR og datasuverenitet
**Dataplassering:**
- Language resource: Europe (West Europe, North Europe)
- Azure AI Search: Må være samme region som Language resource
- **OBS:** Cross-region replication er ikke tillatt i CQA (i motsetning til Storage/Cosmos DB)
**Personvern-implikasjoner:**
- CQA logger **alle user queries** i Application Insights (valgfritt, men anbefalt for active learning)
- Queries kan inneholde personopplysninger → må ha rettslig grunnlag (GDPR Art. 6)
- **Løsning:** Implementer PII-redaction før logging (via Azure Functions pre-processing)
**Databehandleravtale:**
- Dekkes av Microsoft standard DPA for Azure Cognitive Services
- Krever ikke separat DPA for CQA (inkludert i Language Service)
### Schrems II og datatransfer
**Status per 2026:**
- EU-US Data Privacy Framework gjenopprettet (juli 2023)
- Microsoft er sertifisert participant
- **Anbefaling:** Bruk likevel EU-regioner (West/North Europe) for offentlig sektor
**Dokumentasjon til DPO:**
- Data residency confirmation: Azure Portal → Language resource → Properties → Location
- Sub-processor list: Microsoft Trust Center → Azure Cognitive Services
### AI Act (EU forordning 2024)
**Klassifisering:**
- CQA alene: **Minimal risk** (generell AI-system)
- I kombinasjon med health/finance: **Høy risk** → krav til transparens, logging, human oversight
**Compliance-tiltak for high-risk:**
- **Bias testing:** Valider at CQA ikke diskriminerer basert på dialekt, formulering
- **Explanation:** Returner confidence score + source document til brukeren
- **Human-in-the-loop:** Fallback til human agent ved confidence < 0.5
- **Logging:** Behold query logs i 6 måneder for auditformål
**AI Act Article 52 (transparens):**
- Brukere må informeres om at de interagerer med AI
- **Implementering:** Vis "Powered by Azure AI" i chat-grensesnitt
### Forvaltningsloven og Arkivlova
**§ 11a (automatiserte enkeltvedtak):**
- CQA kan **ikke** brukes til å fatte vedtak uten human review
- **Tillatt:** Veiledning, FAQ, generell informasjon
- **Ikke tillatt:** "Deres søknad er avslått fordi..." basert på CQA-svar
**Arkivplikt:**
- Chat-logs med innbyggere kan være arkivpliktige (vurdering per virksomhet)
- **Løsning:** Implementer export-funksjon fra Application Insights til arkivsystem
**Innsyn (offentlighetsloven):**
- Knowledge base-innhold er som regel offentlig (FAQ = offentlig info)
- Unntaket er internal HR/legal KBs → klassifiser som "unntatt offentlighet"
### Anbefalt arkitektur for offentlig sektor
```
Citizen → Chatbot (Bot Framework) → PII Redaction Function → CQA (West Europe)
↓
Application Insights (retention: 90 days, export to Archive)
↓
Low confidence (< 0.5) → Route to human agent
```
**Key controls:**
1. **PII redaction:** Azure Functions som regex-scanner før CQA-kall
2. **Data residency:** West Europe for alle komponenter
3. **Human fallback:** Bot Framework Composer → Escalate node
4. **Audit logging:** Custom telemetry til Arkivsystem
## Kostnad og lisensiering
### Prismodell (per januar 2026, West Europe)
**Language resource med CQA:**
| Tier | Hosted calls (text records) | Pris per 1000 records | Ideal bruksscenario |
|------|----------------------------|----------------------|---------------------|
| Free (F0) | 5000 records/måned | Gratis | Testing, POC |
| Standard (S) | Ubegrenset | NOK 11.30 (€1.00) | Produksjon |
**Azure AI Search (påkrevd):**
| Tier | Indexes | Storage | Pris/måned | CQA-kapasitet |
|------|---------|---------|-----------|---------------|
| Free | 3 | 50 MB | Gratis | 2 KBs |
| Basic | 15 | 2 GB | NOK 850 (€75) | 14 KBs (single lang) |
| S1 | 50 | 25 GB | NOK 2800 (€250) | 49 KBs |
**Total månedlig kostnad (produksjon):**
- **Minimum:** NOK 2800 (S1 Search) + NOK 11.30/1000 queries
- **Typisk enterprise:** NOK 3500-5000/måned ved 50K queries
### Kostnadsoptimalisering
**1. Query batching:**
- Send multiple questions i én API-call (støttes ikke natively, men kan implementeres med middleware)
**2. Caching:**
- Implementer Redis cache for hyppige spørsmål (TTL 1 time)
- Reduserer CQA-calls med 30-40% i typiske FAQ-scenarier
**3. Tier-optimalisering:**
```
Development: Free Language + Free Search (0 NOK)
Staging: Standard Language + Basic Search (850 NOK)
Production: Standard Language + S1 Search (2800 NOK)
```
**4. Throughput-overvåking:**
- CQA har hard cap på 10 TPS (transactions per second)
- Ved overskridelse: HTTP 429 errors
- **Løsning:** Implementer retry logic med exponential backoff
**5. Active Learning ROI:**
- Forbedrer accuracy med 15-20% over 6 måneder
- Reduserer "no answer" rate → mindre escalation til human agents
- **Business case:** 100 eskalerte tickets/måned × NOK 200/ticket = NOK 20K savings
### Lisensiering
**Ingen separate lisenser påkrevd** utover Azure-abonnement.
**Inkludert i:**
- Azure-abonnement (Pay-as-you-go eller Enterprise Agreement)
- Ingen per-user licensing
**Ikke inkludert i:**
- Microsoft 365-lisenser (må bruke separat Azure-abonnement)
- Dynamics 365 Customer Service (krever custom integration, ikke native)
## For arkitekten (Cosmo)
### Spørsmål å stille kunden
1. **Innholdskarakteristikk:**
- "Hvor mye av innholdet deres eksisterer som strukturerte FAQ vs. unstructured documents?"
- "Har dere metadata/tags på eksisterende innhold som kan brukes til filtering?"
2. **Volumestimat:**
- "Hvor mange unike spørsmål forventer dere per dag/måned?"
- "Hva er acceptable response time (< 1 sekund, < 3 sekunder)?"
3. **Modenhet og eierskap:**
- "Hvem skal vedlikeholde knowledge base – IT eller business-eiere?"
- "Har dere resurser til å reviewe active learning-forslag månedlig?"
4. **Integrasjonslandskap:**
- "Bruker dere allerede Bot Framework, Power Virtual Agents, eller noe annet?"
- "Skal CQA integreres med eksisterende CRM/ticketing-system?"
5. **Compliance:**
- "Er det personopplysninger i knowledge base-innholdet?"
- "Har dere krav om data residency (Norge/EU)?"
6. **Success metrics:**
- "Hva er KPIer for suksess? (Redusert ticket-volum, user satisfaction score, resolution rate?)"
- "Hva er akseptabelt nivå av 'no answer' scenarios (< 10%, < 5%)?"
7. **Budget:**
- "Hva er budsjett for månedlig drift (inkludert Azure-kostnader)?"
- "Er dette en replacement for eksisterende løsning eller greenfield?"
8. **Skalerbarhet:**
- "Forventer dere sesongvariasjoner i query-volum?"
- "Planlegger dere å ekspandere til flere språk eller domener?"
### Fallgruver å unngå
⚠️ **Fallgruve 1: Undervurdere index-begrensninger**
- **Problem:** Kunden har 20 separate produktområder, tenker "én knowledge base per produkt"
- **Realitet:** Basic tier støtter bare 14 KBs (single-language)
- **Løsning:** Bruk metadata filtering i én konsolidert KB, eller oppgrader til S1
⚠️ **Fallgruve 2: Å ikke teste med ekte brukerformuleringer**
- **Problem:** Tester med perfekt formulerte spørsmål fra FAQ-dokumentet
- **Realitet:** Brukere spør "hvor mye koster det" (ikke "hva er prisen for...")
- **Løsning:** Samle ekte support-tickets/chat-logs, test med dem
⚠️ **Fallgruve 3: "Set it and forget it" mentalitet**
- **Problem:** Deployer KB, ingen vedlikehold, accuracy synker
- **Realitet:** Produkt-info endres, FAQ blir utdatert
- **Løsning:** Etabler månedlig review-syklus, aktiver active learning
⚠️ **Fallgruve 4: Overfladisk svar i knowledge base**
- **Problem:** Svar er "Ja, vi har det" uten detaljer
- **Realitet:** Brukere trenger actionable info ("Ja, finn det under Settings → Preferences")
- **Løsning:** Skriv svar som standalone-instruksjoner (assume no prior context)
⚠️ **Fallgruve 5: Å ikke planlegge for eskalering**
- **Problem:** Bot har ingen fallback til human agent
- **Realitet:** 10-15% av queries vil ha confidence < 0.5
- **Løsning:** Integrer med Teams/service desk fra dag 1
⚠️ **Fallgruve 6: Å bruke CQA for backend-data queries**
- **Problem:** "Hva er saldo på konto 12345?" → Krever real-time database lookup
- **Realitet:** CQA er statisk knowledge, ikke dynamic data
- **Løsning:** Kombiner med Bot Framework adaptive cards + direct database calls
### Anbefalinger per modenhetsnivå
**Level 1: Beginner (First chatbot, < 500 QnA pairs)**
- ✅ Start med Language Studio (low-code)
- ✅ Bruk single knowledge base med chit-chat
- ✅ Deploy via Bot Framework Composer
- ✅ Sett confidence threshold til 0.6 (strict)
- ⚠️ Ikke aktiver active learning før KB er stabil (måned 2-3)
- 📊 **Success metric:** 70% of queries answered with confidence > 0.6
**Level 2: Intermediate (Multiple bots, 500-2000 QnA pairs)**
- ✅ Implementer metadata filtering for domeneseparasjon
- ✅ Aktiver active learning, review suggestions bi-weekly
- ✅ Integrer med Application Insights for custom dashboards
- ✅ Bruk alternate questions strategisk (3-5 per QnA)
- ⚠️ Vurder separate KBs hvis compliance krever det
- 📊 **Success metric:** 85% resolution rate, < 2 sec response time
**Level 3: Advanced (Enterprise scale, > 2000 QnA pairs)**
- ✅ Implementer orchestrator pattern med CLU intent routing
- ✅ Bruk hybrid arkitektur (CQA for FAQ, OpenAI for generative)
- ✅ Implementer PII redaction middleware
- ✅ Sett opp multi-region deployment for high availability
- ✅ Bruk Azure DevOps for KB version control (export TSV til Git)
- 📊 **Success metric:** 90% resolution, < 1.5 sec p95 latency, < 5% escalation rate
**Level 4: Expert (Multi-tenant, compliance-heavy)**
- ✅ Separate Language resources per tenant/security boundary
- ✅ Custom NLP-preprocessing for synonym expansion
- ✅ Implementer feedback loop med human-in-the-loop labeling
- ✅ A/B testing av confidence thresholds og ranking parameters
- ✅ Cost optimization via query result caching (Redis)
- 📊 **Success metric:** 95% resolution, < 1 sec median latency, ROI-tracking per knowledge domain
### "Know when to walk away" decision matrix
| Requirement | CQA fit | Alternative |
|-------------|---------|-------------|
| 10,000+ QnA pairs | ⚠️ Possible but unwieldy | Split to multiple KBs or use Azure OpenAI + vector search |
| Real-time data (prices, availability) | ❌ No | Direct API integration + NLP layer |
| Generative responses required | ❌ No | Azure OpenAI GPT-4 |
| Multi-modal (images, diagrams) | ❌ Limited | Azure AI Vision + Custom model |
| Sub-second latency required | ⚠️ Challenging | Consider caching layer + CDN |
| On-premises deployment | ❌ Cloud-only | QnA Maker containers (deprecated) or custom model |
**Red flag threshold:** If customer requirements fall into 3+ "❌" categories, CQA is ikke riktig fit.
## Kilder og verifisering
**Verified (fra MCP microsoft-learn):**
1. https://learn.microsoft.com/en-us/azure/ai-services/language-service/question-answering/overview
2. https://learn.microsoft.com/en-us/azure/ai-services/language-service/question-answering/concepts/azure-resources
3. https://learn.microsoft.com/en-us/azure/ai-services/language-service/question-answering/concepts/best-practices
4. https://learn.microsoft.com/en-us/azure/ai-services/language-service/question-answering/quickstart/sdk
5. https://learn.microsoft.com/en-us/azure/bot-service/bot-builder-howto-answer-questions
6. https://learn.microsoft.com/en-us/rest/api/questionanswering/question-answering
7. https://learn.microsoft.com/en-us/azure/ai-services/language-service/question-answering/language-support
8. https://learn.microsoft.com/en-us/training/modules/create-question-answer-solution-ai-language/
**Baseline (modellkunnskap):**
- GDPR/Schrems II compliance for Azure Cognitive Services (verifisert via Microsoft Trust Center)
- AI Act implikasjoner (EU forordning 2024, trådte i kraft desember 2024)
- Forvaltningsloven § 11a (norsk lovverk, ikke-endret siden siste oppdatering)
- Prisestimat (basert på januar 2026 Azure pricing calculator, kan variere)
**Konfidensnivå per seksjon:**
- Introduksjon, Kjernekomponenter, Nøkkelegenskaper: **Verified** (100%)
- Arkitekturmønstre: **Verified** (90%, mønster 3 er composite-løsning)
- Beslutningsveiledning: **Baseline + Verified** (80%, beslutningstre er ekspertskjønn)
- Integrasjon med Microsoft-stakken: **Verified** (95%, M365 Copilot-begrensning bekreftet)
- Offentlig sektor: **Baseline + Verified** (85%, juridisk tolkning er ikke legal advice)
- Kostnad og lisensiering: **Verified** (90%, priser per januar 2026, currency conversion fra EUR)
- For arkitekten: **Baseline** (ekspertskjønn basert på best practices)

413
plugins/ms-ai-architect/skills/ms-ai-engineering/references/azure-ai-services/language-services-text-analytics.md Normal file
View file

@ -0,0 +1,413 @@
# Language Services - Text Analytics for Sentiment and Key Phrases
**Last updated:** 2026-02
**Status:** GA
**Category:** Azure AI Services (Foundry Tools)
---
## Introduksjon
Azure AI Language er en samling av forhåndsopplærte språkmodeller som gjør det mulig å utføre avansert tekstanalyse uten å bygge egne maskinlæringsmodeller. Tjenesten tilbyr flere kjernekapabiliteter for text analytics: **Sentiment Analysis** (med opinion mining), **Key Phrase Extraction**, **Named Entity Recognition (NER)**, og **Language Detection**.
Disse kapabilitetene er tilgjengelige både som cloud-baserte REST API-er, SDK-er (C#, Java, Python, JavaScript), og Docker-containere for on-premises deployment. Tjenesten integreres sømløst med Azure AI Foundry, Azure Synapse Analytics, Power BI, og Microsoft Fabric, noe som gjør den egnet for både interactive playgrounds og produksjonsworkflows.
Text analytics-funksjonene er stateless — ingen data lagres i kontoen din, og resultater returneres umiddelbart etter analyse. For batch-operasjoner er resultatene tilgjengelige i 24 timer før de slettes automatisk. Tjenesten støtter 94+ språk for key phrase extraction, med bred språkstøtte også for sentiment analysis og NER.
---
## Kjernekomponenter / Nøkkelegenskaper
### Sentiment Analysis
Analyserer tekst og returnerer sentiment labels (`positive`, `negative`, `neutral`, `mixed`) med confidence scores (0–1) på både setnings- og dokumentnivå.
| Funksjonalitet | Beskrivelse |
|----------------|-------------|
| **Sentiment labels** | Positive, negative, neutral (setningsnivå); mixed tilgjengelig på dokumentnivå |
| **Confidence scores** | 0.0–1.0 per label (summer alltid til 1.0) |
| **Opinion Mining** | Identifiserer target-aspect (substantiv/verb) og tilhørende assessment (adjektiv) |
| **Beste use case** | Små tekstblokker (høyere kvalitet enn store) |
| **Språkstøtte** | [Omfattende liste](https://learn.microsoft.com/en-us/azure/ai-services/language-service/sentiment-opinion-mining/language-support) inkl. norsk |
**Eksempel (Opinion Mining):**
```
Input: "The room was great, but the staff was unfriendly."
Output:
- Target: "room" → Assessment: "great" (positive)
- Target: "staff" → Assessment: "unfriendly" (negative)
- Document sentiment: mixed
```
### Key Phrase Extraction
Evaluerer ustrukturert tekst og returnerer en liste over viktigste key phrases.
| Funksjonalitet | Beskrivelse |
|----------------|-------------|
| **Input-optimalisering** | Fungerer best på **større tekstblokker** (motsatt av sentiment) |
| **Output** | Liste med key phrases, sortert av modellens interne ranking |
| **Språkstøtte** | 94 språk (inkl. norsk, samisk, finsk, svensk, dansk) |
| **Use case** | Rask identifikasjon av hovedpoeng i dokumentsamlinger |
**Eksempel:**
```
Input: "Dr. Smith has a very modern medical office, and she has great staff."
Output: ["modern medical office", "Dr. Smith", "great staff"]
```
### Named Entity Recognition (NER)
Identifiserer og kategoriserer entities i tekst (person, lokasjon, organisasjon, dato, etc.).
| Entity-kategori | Typer (eksempler) |
|-----------------|-------------------|
| **Person** | Person, PersonType (rolle) |
| **Organization** | Organization, OrganizationMedical, OrganizationSports, OrganizationStockExchange |
| **Location** | City, CountryRegion, State, GPE (geopolitical entity), Airport, Continent |
| **DateTime** | Date, Time, DateRange, TimeRange, Duration, Set |
| **Quantity** | Number, Percentage, Currency, Age, Temperature, Speed, Weight, Volume, Area, Length |
| **Event** | Event, NaturalEvent, CulturalEvent, SportsEvent |
| **Contact** | Email, PhoneNumber, URL, IpAddress, Address |
| **Product** | Product, ComputingProduct |
| **Other** | Skill, Information |
**Metadata-resolutionsupport:** Mange quantity-entities returnerer strukturert metadata (f.eks. Currency → ISO-kode, normalized verdi).
### Language Detection
Evaluerer tekst og returnerer språk-identifier (ISO 639-1) med confidence score (0.0–1.0).
| Funksjonalitet | Beskrivelse |
|----------------|-------------|
| **Output** | Language name, ISO 6391 code, confidence score |
| **Use case** | Automatisk språkdeteksjon for content stores med mixed-language data |
| **Default** | Engelsk hvis ikke spesifisert |
---
## Arkitekturmønstre
### Mønster 1: REST API med Fabric/Synapse (Batch Processing)
**Use case:** Prosesser store volumer av dokumenter fra data lake (f.eks. kundefeedback, supporttickets).
**Fordeler:**
- Sømløs integrasjon med Azure Storage og Azure AI Search
- SynapseML gir Spark-optimalisert batch processing
- Built-in authentication via Fabric workspace credentials
**Ulemper:**
- Krever Spark-kompetanse for SynapseML
- Batch-mode medfører latency (ikke real-time)
**Eksempel (Fabric REST API):**
```python
# Auto-authenticated via Fabric
payload = {
"kind": "SentimentAnalysis",
"parameters": {"modelVersion": "latest", "opinionMining": "True"},
"analysisInput": {"documents": [{"id": "1", "language": "en", "text": "..."}]}
}
response = requests.post(service_url, json=payload, headers=auth_headers)
```
### Mønster 2: SDK-basert integrasjon (Client Library)
**Use case:** Real-time tekstanalyse i web/mobile apps, chatbots, eller Power Apps.
**Fordeler:**
- Typed responses (C#, Java) reduserer parsing-bugs
- Async support for skalerbare apps
- Enklere feilhåndtering enn raw REST
**Ulemper:**
- SDK versioning (må holde tritt med API-versjoner)
- Større binary footprint enn REST
**Eksempel (C# SDK):**
```csharp
var client = new TextAnalyticsClient(endpoint, new AzureKeyCredential(key));
var response = await client.AnalyzeSentimentAsync("The service was excellent!");
Console.WriteLine($"Sentiment: {response.Value.Sentiment}");
```
### Mønster 3: Docker Container (On-Premises)
**Use case:** Compliance-krav som krever data residency i Norge, eller air-gapped environments.
**Fordeler:**
- Full datakontroll (ingen data sendes til cloud)
- Lav latency (lokal processing)
- Støtter Sentiment, Language Detection, Key Phrase, Custom NER, Text Analytics for Health
**Ulemper:**
- Krever egne compute-ressurser (CPU/minne)
- Ingen automatiske modelloppdateringer (må manuelt oppdatere container images)
- Free F0 tier støttes ikke (kun Standard S tier)
---
## Beslutningsveiledning
### Når bruke Sentiment Analysis vs. Opinion Mining
| Scenario | Anbefaling |
|----------|-----------|
| Trenger kun overordnet positive/negative/neutral? | **Sentiment Analysis** (uten opinion mining-flag) |
| Må identifisere *hva* kunder liker/misliker? | **Opinion Mining** (sett `opinionMining=true`) |
| Analyserer produktanmeldelser med attributter? | **Opinion Mining** (target = produkt-feature, assessment = vurdering) |
### Vanlige feil
| Feil | Løsning |
|------|---------|
| Lav kvalitet på sentiment for lange dokumenter | Del opp tekst i mindre chunks (maks 5000 tegn per record) |
| Key phrases mangler kontekst | Gi større tekstblokker (key phrase fungerer bedre på større input enn sentiment) |
| NER feiltolker domene-spesifikke entities | Vurder Custom NER (trener egen modell på dine data) |
| Mixed sentiment når både positive og negative setninger | Dette er forventet — bruk Opinion Mining for granularitet |
### Røde flagg
- **Ikke bruk** for medisinsk diagnostikk (selv om Text Analytics for Health finnes — krever spesialistkompetanse)
- **Ikke bruk** for PII-deteksjon i produksjon uten også å enable [PII Detection feature](https://learn.microsoft.com/en-us/azure/ai-services/language-service/personally-identifiable-information/overview)
- **Ikke bruk** default English language hvis du vet teksten er på andre språk (spesifiser `language` parameter)
### Beslutningstabell: SDK vs. REST vs. Container
| Krav | SDK | REST API | Container |
|------|-----|----------|-----------|
| Real-time app-integrasjon | ✅ Beste valg | ⚠️ Fungerer, mer boilerplate | ❌ Overkill |
| Batch processing (millioner dokumenter) | ⚠️ Mulig, men batch APIs bedre | ✅ Med SynapseML | ⚠️ Infrastruktur-overhead |
| Data residency krav (Norge) | ❌ Må bruke EU-regioner | ❌ Må bruke EU-regioner | ✅ Full kontroll |
| Lavest kostnads-overhead | ✅ Pay-per-call | ✅ Pay-per-call | ⚠️ Egen infrastruktur |
---
## Integrasjon med Microsoft-stakken
### Azure AI Foundry
Language Services er integrert i Foundry Playground med visuell testing av sentiment, key phrases, og NER uten kode.
**Workflow:**
1. Opprett Language resource i Foundry
2. Velg "Analyze sentiment" eller "Key phrase extraction" fra banneret
3. Lim inn tekst, velg API-versjon, språk, og kjør
4. Se resultater med confidence scores og opinion mining-targets
### Power BI
Power BI Desktop kan integrere direkte med Key Phrase Extraction via Power Query custom functions.
**Use case:** Analyser kundefeedback fra Excel/CSV, visualiser key phrases som word cloud.
**Tutorial:** [Extract key phrases from Power BI](https://learn.microsoft.com/en-us/azure/ai-services/language-service/key-phrase-extraction/tutorials/integrate-power-bi)
### Azure Synapse Analytics / Microsoft Fabric
SynapseML (tidligere MMLSpark) gir native Spark support for Language Services.
**Fordeler:**
- Batch processing av DataFrames
- Auto-authentication i Fabric notebooks (ingen API keys nødvendig)
- Sømløs integrasjon med lakehouse data
**Eksempel (SynapseML for Key Phrases):**
```python
from synapse.ml.cognitive.language import AnalyzeText
model = AnalyzeText().setTextCol("text").setKind("KeyPhraseExtraction")
result = model.transform(df).select("text", "keyPhrases")
```
### Copilot Studio
Language Services kan brukes i custom Copilot Studio skills for å analysere brukersentiment i conversations før routing til riktig agent.
**Use case:** Automatisk eskaler negative sentiment til human agent, neutral til FAQ bot.
### Azure Cognitive Search
Language Services entities kan indekseres i Azure AI Search som facets, noe som muliggjør entity-basert search filtering (f.eks. "finn dokumenter om Microsoft som organisasjon").
---
## Offentlig sektor (Norge)
### GDPR og Schrems II
| Risiko | Mitigering |
|--------|-----------|
| Data sendes til Azure EU-regioner (Vest-Europa, Nord-Europa) | ✅ Bruk EU-regioner for Language resource |
| Potensielle concerns om US Cloud Act | ✅ Bruk Docker containers on-premises for følsom data |
| PII i tekst (personnummer, navn, e-post) | ✅ Anonymiser først, eller bruk PII Detection-feature |
| Data retention i 24 timer (batch mode) | ✅ Synkron modus lagrer ikke data (stateless) |
### AI Act (EU)
Language Services klassifiseres som **lav-risiko AI** (ikke høyrisiko) så lenge det ikke brukes til:
- Biometric identification
- Critical infrastructure
- Law enforcement (uten human oversight)
**Krav:**
- Dokumenter hvordan sentiment/entity detection brukes
- Vurder bias (trent på hovedsakelig engelske datasett, kan være mindre nøyaktig for norsk)
### Forvaltningsloven og transparens
Ved bruk i saksbehandling:
- **Ikke la sentiment score alene avgjøre saker** (kun som beslutningsstøtte)
- **Logg alle analyser** (hvem, hva, når, resultat) for etterprøvbarhet
- **Informer brukere** hvis deres tekst analyseres (f.eks. feedback-forms)
### Datasuverenitet
**Azure Norway datacenters** (Oslo, Stavanger) støtter ikke Language Services per 2026-02. Nærmeste regioner:
- **West Europe** (Nederland)
- **North Europe** (Irland)
For full datasuverenitet: **Bruk Docker containers** (Sentiment, Language Detection, Key Phrase, Custom NER) hosted i Norge.
---
## Kostnad og lisensiering
### Prismodell (Azure Language)
Language Services bruker **pay-per-call** modell (per text record).
| Tier | Pris per 1000 text records | Bruksscenario |
|------|----------------------------|---------------|
| **Free F0** | 0 NOK (5000 gratis/måned) | Testing, POC, lav-volum apps |
| **Standard S** | Varierer per region (~$1–2 USD / 1000 records) | Produksjon |
**Viktige detaljer:**
- **Maks 5000 tegn per record** (større dokumenter må splittes)
- **Opinion Mining** inkludert i Standard tier (ingen ekstra kostnad)
- **Batch mode** (asynchronous) har samme pris som synchronous
- **Docker containers** krever Standard tier (Free F0 støttes ikke)
### Kostnadseksempel (norsk offentlig virksomhet)
**Scenario:** Analyserer 100 000 brukerhenvendelser/måned med sentiment + key phrases (2 API-kall per henvendelse).
| Komponent | Kostnad (estimat) |
|-----------|-------------------|
| 200 000 text records × $1.50 / 1000 | $300 USD/måned (~3200 NOK) |
| Azure Language resource (S tier) | Ingen fast månedskostnad (kun per-call) |
| Azure Storage (hvis batch mode) | ~$20 USD/måned for 1TB (~210 NOK) |
| **Total** | **~3400 NOK/måned** |
### Optimaliseringstips
1. **Batch asynkront** — Hvis du kan vente 24 timer, bruk asynchronous API (ingen prisforskjell, men enklere infrastruktur)
2. **Filtrer ut tom tekst** — Ikke send records uten innhold (koster like mye som reelle records)
3. **Kombiner features i én request** — Sentiment + Key Phrases + Entities kan kjøres i én `analyze-text` call (sparer HTTP-overhead, ikke pris)
4. **Bruk containers for høy-volum** — Hvis >1M records/måned, vurder self-hosted containers med Reserved VM Instances
---
## For arkitekten (Cosmo)
### Spørsmål å stille kunden
1. **Volum og latency:**
- Hvor mange dokumenter skal analyseres (per dag/måned)?
- Kreves real-time respons (<500ms) eller er batch OK (24t)?
2. **Språk og multispråklighet:**
- Er all tekst på norsk, eller blandet språk?
- Trenger dere automatisk språkdeteksjon?
3. **Datakompleksitet:**
- Er tekstene lange (>5000 tegn) eller korte (f.eks. tweets, SMS)?
- Inneholder teksten sensitive personopplysninger (navn, personnummer)?
4. **Detaljnivå:**
- Trenger dere kun overordnet sentiment, eller må dere vite *hva* som er positivt/negativt (opinion mining)?
- Skal entities kobles til eksterne knowledge bases (entity linking)?
5. **Infrastruktur og compliance:**
- Kan data sendes til Azure EU-regioner, eller kreves on-premises?
- Har dere eksisterende Azure Synapse / Fabric infrastructure?
6. **Integrasjoner:**
- Skal resultatene visualiseres i Power BI, eller bare lagres i database?
- Brukes det i en eksisterende app (web/mobile), eller ny løsning?
7. **Fremtidig utvidelse:**
- Vil dere senere trenge custom entities (f.eks. organisasjonsspesifikke termer)?
- Planlegges det translation workflows (Azure Translator integrasjon)?
### Fallgruver
| Fallgruve | Forklaring | Mitigering |
|-----------|------------|------------|
| **"Sentiment = sannhet"** | Sentiment score er en prediktering, ikke en fasit | Alltid ha human-in-the-loop for kritiske beslutninger |
| **Overfitting til engelsk** | Modellen er best på engelsk, kan være mindre presis på norsk | Test med representative norske datasett før produksjon |
| **Ignorere PII** | Key phrases kan inneholde personnavn eller sensitiv info | Kjør PII Detection først, eller anonymiser tekst før analyse |
| **Glemme cost caps** | Per-call pricing kan eskalere ved bugs (infinite loops) | Sett Azure Cost Management alerts på Language resource |
| **Forvente perfekt NER** | NER kan feiltolke domene-spesifikke entities | Vurder Custom NER hvis standard entities ikke er presise nok |
### Anbefalinger per modenhetsnivå
#### Nivå 1: Exploring (POC, <1000 records/måned)
- **Anbefaling:** Free F0 tier + Azure AI Foundry Playground
- **Verktøy:** REST API via Postman eller Foundry web UI
- **Fokus:** Teste om sentiment/key phrases gir verdi for use case
- **Advarsler:** Ikke bygg produksjonsapp på Free tier (5000 records/mnd cap)
#### Nivå 2: Building (Pilot, 1000–100K records/måned)
- **Anbefaling:** Standard S tier + SDK (C#/Python) + Azure App Service
- **Verktøy:** Azure Language SDK, Application Insights for monitoring
- **Fokus:** Real-time integrasjon i app, feilhåndtering, retry-logikk
- **Advarseler:** Implementer circuit breaker pattern (unngå API throttling ved 429 errors)
#### Nivå 3: Scaling (Produksjon, >100K records/måned)
- **Anbefaling:** Standard S tier + SynapseML / Fabric + Batch API
- **Verktøy:** Azure Synapse Pipelines, Azure Data Lake, Azure AI Search (for entity indexing)
- **Fokus:** Batch processing, cost optimization, data governance
- **Advarseler:** Vurder Docker containers hvis kostnad >$1000/måned
#### Nivå 4: Optimizing (Enterprise, >1M records/måned)
- **Anbefaling:** Docker containers on Azure Kubernetes Service (AKS) + Custom NER
- **Verktøy:** AKS, Azure Monitor, Custom Text Classification (Language Studio)
- **Fokus:** Self-hosted inference, custom models for domene-spesifikke entities
- **Advarsler:** Container-licensing krever Standard tier — test kostnad mot cloud API
---
## Kilder og verifisering
### Microsoft Learn-dokumentasjon (Verified via MCP)
| Kategori | URL | Konfidensnivå |
|----------|-----|---------------|
| **Sentiment Analysis Overview** | https://learn.microsoft.com/en-us/azure/ai-services/language-service/sentiment-opinion-mining/overview | ✅ Verified (2026-02) |
| **Sentiment Analysis How-To** | https://learn.microsoft.com/en-us/azure/ai-services/language-service/sentiment-opinion-mining/how-to/call-api | ✅ Verified (2026-02) |
| **Key Phrase Extraction How-To** | https://learn.microsoft.com/en-us/azure/ai-services/language-service/key-phrase-extraction/how-to/call-api | ✅ Verified (2026-02) |
| **NER Entity Categories** | https://learn.microsoft.com/en-us/azure/ai-services/language-service/named-entity-recognition/concepts/named-entity-categories | ✅ Verified (2026-02) |
| **Fabric Text Analytics** | https://learn.microsoft.com/en-us/fabric/data-science/ai-services/how-to-use-text-analytics | ✅ Verified (2026-02) |
| **Key Phrase Language Support** | https://learn.microsoft.com/en-us/azure/ai-services/language-service/key-phrase-extraction/language-support | ✅ Verified (2026-02) |
| **Sentiment Language Support** | https://learn.microsoft.com/en-us/azure/ai-services/language-service/sentiment-opinion-mining/language-support | ✅ Verified (2026-02) |
| **Custom Text Classification** | https://learn.microsoft.com/en-us/azure/ai-services/language-service/custom-text-classification/overview | ✅ Verified (2026-02) |
### Konfidensnivå per seksjon
| Seksjon | Konfidens | Kilde |
|---------|-----------|-------|
| Introduksjon | ✅ Verified | Microsoft Learn docs (MCP-fetched) |
| Kjernekomponenter | ✅ Verified | REST API examples + model outputs fra docs |
| Arkitekturmønstre | ✅ Verified | Fabric tutorial + Synapse docs + SDK samples |
| Beslutningsveiledning | ⚠️ Baseline | Best practices (modellkunnskap), ikke eksplisitt dokumentert |
| Integrasjon med MS-stakken | ✅ Verified | Power BI tutorial + SynapseML docs + Foundry quickstarts |
| Offentlig sektor (Norge) | ⚠️ Baseline | GDPR-analyse (modellkunnskap) + Azure datacenter geografi |
| Kostnad og lisensiering | ⚠️ Baseline | Generell Azure pricing structure (ikke eksakte NOK-priser hentet) |
| For arkitekten (Cosmo) | ⚠️ Baseline | Arkitekturerfaringer (modellkunnskap), ikke dokumentert av Microsoft |
**Notater:**
- Prisestimater er basert på generell Azure-prisstruktur — alltid sjekk [Azure Pricing Calculator](https://azure.microsoft.com/en-us/pricing/calculator/) for eksakte priser.
- Norge datacenter-status per 2026-02 — verifiser i Azure portal før arkitekturavgjørelser.
- Custom NER og Custom Text Classification er separate features med egne prismodeller (ikke dekket detaljert her).

512
plugins/ms-ai-architect/skills/ms-ai-engineering/references/azure-ai-services/speech-services-speaker-recognition.md Normal file
View file

@ -0,0 +1,512 @@
# Speech Services - Speaker Recognition and Identification
**Last updated:** 2026-02
**Status:** GA
**Category:** Azure AI Services (Foundry Tools)
---
## Introduksjon
Azure Speech Services Speaker Recognition gir biometriske algorithmer som verifiserer og identifiserer talere basert på deres unike stemmesignaturer. Tjenesten besvarer spørsmålet "hvem snakker?" gjennom voice biometry som ekstraherer stemmekarakteristikker fra lydopptak.
Speaker Recognition dekker to hovedscenarier: **Speaker Verification** (én-til-én matching for autentisering) og **Speaker Identification** (én-til-mange matching for å finne hvem som snakker). Begge API-ene benytter voice signatures (også kalt voiceprints) – numeriske vektorer som representerer individuelle stemmekarakteristikker ekstrahert fra taleopptak.
En kritisk begrensning å merke seg: API-ene er **ikke** designet for å oppdage liveness (levende person vs. opptak/imitasjon). Replay attack-mitigering må implementeres separat gjennom tilfeldige passfraser eller andre metoder.
## Kjernekomponenter
### Speaker Verification
| Type | Beskrivelse | Bruksområde | Enrollment | Similarity Threshold |
|------|-------------|-------------|------------|---------------------|
| **Text-dependent** | Krever samme passphrase ved enrollment og verifisering | Multi-factor authentication, banking | 10 forhåndsdefinerte engelsk phrases | ≥ 0.5 (kombinert voice + tekst) |
| **Text-independent** | Ingen begrensninger på hva som sies | General authentication, identity confirmation | Fritt talespråk | ≥ 0.5 (kun voice similarity) |
**Text-dependent passphrases (English):**
1. I am going to make him an offer he cannot refuse.
2. Houston we have had a problem.
3. My voice is my passport verify me.
4. Apple juice tastes funny after toothpaste.
5. You can get in without your password.
6. You can activate security system now.
7. My voice is stronger than passwords.
8. My password is not your business.
9. My name is unknown to you.
10. Be yourself everyone else is already taken.
**API Response:**
```json
{
"recognitionResult": "Accept" | "Reject",
"similarityScore": 0.0-1.0
}
```
### Speaker Identification
| Egenskap | Verdi |
|----------|-------|
| **Type** | Text-independent (alltid) |
| **Max kandidater** | 50 speakers per request |
| **Response** | 1 identified ID + 5 top-ranked IDs med scores |
| **Threshold** | Default 0.5 (kan overstyres) |
| **No match handling** | Returnerer "0" string hvis ingen score ≥ 0.5 |
**Use case:** Call center routing, meeting attribution, forensics, access control for grupper.
### Voice Signature Storage
```csharp
// C# SDK eksempel - Speaker Verification
var config = SpeechConfig.FromSubscription("YourKey", "YourRegion");
var client = new VoiceProfileClient(config);
// Enrollment
var profile = await client.CreateProfileAsync(
VoiceProfileType.TextIndependentVerification, "en-US");
var result = await client.EnrollProfileAsync(profile, audioInput);
// Verification
var recognizer = new SpeakerRecognizer(config, audioInput);
var verifyResult = await recognizer.RecognizeOnceAsync(profile);
```
## Arkitekturmønstre
### Mønster 1: Multi-Factor Authentication (Text-Dependent)
**Scenario:** Banking app med voice + passphrase som sikkerhetslag.
**Fordeler:**
- To-faktor sikkerhet (voice signature + passphrase innhold)
- Lavere false positive rate enn text-independent
- Compliance-vennlig (NIST AAL2-kompatibel)
**Ulemper:**
- Dårlig brukeropplevelse (må huske spesifikk phrase)
- Engelsk-kun for forhåndsdefinerte phrases
- Sårbar for replay attacks uten ekstra tiltak
**Implementering:**
```
Enrollment: Speaker → velger phrase → recorder 3-5 samples → voice signature lagres
Verification: Speaker → sier samme phrase → Accept/Reject (voice + tekst matching)
```
### Mønster 2: Transparent Identification i Teams Rooms
**Scenario:** Hybrid-møte hvor deltakere i rom identifiseres automatisk for transkripsjon.
**Fordeler:**
- Seamless UX (ingen manuell pålogging)
- Nøyaktig speaker attribution for Copilot/recap
- Støtter opptil 50 enrolled speakers per møte
**Ulemper:**
- Krever forhånds-enrollment av alle deltakere
- GDPR/privacy kompleksitet (biometric data)
- Quality avhenger av mikrofon (Intelligent Speaker anbefalt)
**Arkitektur:**
```
Teams Room → Audio stream → Speaker Identification API (50 kandidater) →
Attribution i transcript → Copilot bruker navn for summaries
```
**Policy-krav:**
```powershell
Set-CsTeamsAIPolicy -Identity Global -SpeakerAttributionBYOD Enabled
```
### Mønster 3: Call Center Routing (Text-Independent Verification)
**Scenario:** IVR-system som verifiserer high-value kunder uten PIN-kode.
**Fordeler:**
- Naturlig samtaleflyt (ingen spesifikk phrase)
- Raskere enn PIN/security questions
- Fungerer på alle språk
**Ulemper:**
- Høyere false positive rate enn text-dependent
- Krever lengre audio sample (minimum 5 sekunder anbefalt)
- Ingen liveness detection (replay-sårbar)
**Decision flow:**
```
Caller → "I need help with my account" →
Voice extracted → Verification API →
Accept (score ≥ 0.5) → Route to agent med kundedata
Reject → Fallback til PIN-kode
```
## Beslutningsveiledning
### Valg mellom Verification og Identification
| Scenario | Anbefalt API | Begrunnelse |
|----------|--------------|-------------|
| Login til app (kjent bruker) | Verification | 1:1 matching, raskere, lavere cost |
| "Hvem er dette?" (ukjent fra gruppe) | Identification | 1:N matching, returnerer ranked list |
| Multi-user device | Identification | Identifiserer fra pool av registrerte |
| Banking authentication | Verification (text-dependent) | Høyere security via dual-factor |
| Meeting transcription | Identification | Attributer multiple speakers |
### Threshold Tuning
**Default threshold (0.5) passer for:**
- General-purpose scenarios
- Balansert security vs. convenience
**Høyere threshold (0.7-0.9) når:**
- High-security context (banking, healthcare)
- Lavere false positive er viktigere enn false negative
- Forventet høy audio quality
**Lavere threshold (0.3-0.4) når:**
- Poor audio quality (noisy environments)
- Convenience prioriteres over security
- Acceptable med noen false positives
### Vanlige feil
| Feil | Årsak | Løsning |
|------|-------|---------|
| Lav accuracy | For kort enrollment audio | Min. 20 sek total enrollment anbefalt |
| "No match" for gyldige brukere | Endret stemmekvalitet (syk, stress) | Re-enrollment eller lavere threshold |
| Replay attack success | Ingen liveness detection | Implementer random passphrase-generering |
| GDPR-brudd | Manglende consent/purpose limitation | Explicit consent + data minimization |
| Dårlig speaker attribution | Suboptimal mikrofon | Bruk certified Intelligent Speaker |
### Røde flagg
❌ **Bruk IKKE Speaker Recognition for:**
- Liveness detection (bruk dedikert liveness API)
- Emotion analysis (bruk Speech Analytics i stedet)
- Forensic legal evidence (API ikke designet for dette)
- Automatic enrollment uten consent (GDPR/privacy-brudd)
## Integrasjon med Microsoft-stakken
### Azure AI Foundry Integration
```plaintext
Azure AI Foundry → Speech resource → Speaker Recognition
├── Custom Neural Voice: Bruker Speaker Verification for voice talent consent
├── Personal Voice: Validerer at consent audio matcher training prompt
└── Teams Intelligent Speaker: Attribution via Identification API
```
### Microsoft 365 Copilot
| Feature | Speaker Recognition Rolle |
|---------|--------------------------|
| **Teams Transcript** | Identifiserer in-room speakers for nøyaktig attribution |
| **Meeting Recap** | Copilot trenger speaker names for å summere hvem-sa-hva |
| **Action Items** | Tildeler tasks til riktig person basert på identification |
**Policy-konfigurasjon:**
```powershell
# Teams Rooms People Recognition
Set-CsTeamsAIPolicy -RoomAttributeUserOverride Attribute
# BYOD Rooms Speaker Attribution
Set-CsTeamsAIPolicy -SpeakerAttributionBYOD Enabled
```
### Power Platform
**Power Automate Cloud Flow:**
```
Trigger: OnNewVoicemail
→ Get Recording → Speaker Verification API →
If Verified → Route to Priority Queue
Else → Standard Queue
```
**Limitations:** Speaker Recognition API krever custom connector (ikke pre-built).
### Azure Communication Services
```csharp
// Call Automation med Speaker Recognition
var recognizeOptions = new CallMediaRecognizeSpeechOptions(
targetParticipant: new PhoneNumberIdentifier(callerNumber))
{
Prompt = new TextSource("How can I help you today?", "en-US-ElizabethNeural"),
SpeechLanguages = new List<string> { "en-US", "nb-NO" }
};
// Kombiner med Speaker Verification for caller authentication
var verifyResult = await VerifySpeaker(audioStream, enrolledProfileId);
if (verifyResult.Score >= 0.7)
{
await RouteToPrivilegedAgent(callConnectionId);
}
```
## Offentlig sektor (Norge)
### GDPR & Biometric Data (Art. 9)
**Juridisk grunnlag:**
- Speaker Recognition prosesserer **biometric data** (voice signatures)
- Art. 9(1): Utgangspunkt forbudt (sensitive personopplysninger)
- Art. 9(2)(a): **Explicit consent** påkrevd (ikke implicit)
**Compliance checklist:**
- ✅ Explicit consent fra hver voice talent/user før enrollment
- ✅ Purpose limitation: Kun bruk til formål beskrevet ved consent
- ✅ Data minimization: Slett voice signatures når ikke lenger nødvendig
- ✅ Transparency: Klar informasjon om at voice biometry brukes
- ✅ Right to deletion: Mekanisme for sletting av voice profiles
**Microsoft speaker verification for Custom Neural Voice:**
- Microsoft bruker Speaker Verification for å validere at consent audio matcher training data
- Prosessering under DPA Legitimate Interest Business Operations
- Voice signatures beholdes kun for security/integrity (ikke re-brukt til annet)
### Schrems II & Data Residency
| Region | Data Location | Schrems II Impact |
|--------|---------------|-------------------|
| **Norway East** | Norge (Oslo) | ✅ Anbefalt: Data innenfor EØS |
| **West Europe** | Nederland | ✅ Akseptabelt: EU data residency |
| **US regions** | USA | ⚠️ Krev GDPR-vurdering: Potential US gov access |
**Voice signature storage:**
- Lagres i Azure Storage i samme region som Speech resource
- Encryption at rest via Azure Storage Encryption
- Kan bruke Customer-Managed Keys (CMK) for ekstra kontroll
### AI Act (EU AI Act)
**Risk Classification:** Speaker Recognition = **High-Risk AI System** (biometric identification)
**Obligatoriske krav:**
- Fundamental rights impact assessment (FRIA)
- Technical documentation (model cards, training data provenance)
- Human oversight mechanisms (mulighet for human override av beslutninger)
- Transparency obligations (informere brukere om biometric processing)
- Accuracy, robustness, cybersecurity requirements
**Norwegian implementation:** Avventer nasjonal tilpasningslovgivning (2025-2026).
### Forvaltningsloven & Vedtak
**Hvis Speaker Recognition brukes for automatiserte vedtak:**
- § 11a: Krav om individuell vurdering i "viktige saker"
- § 25: Begrunnelsesplikt (må kunne forklare hvorfor voice rejected)
- § 41: Klageadgang (må kunne contest false rejections)
**Mitigering:**
- Kombiner voice med andre faktorer (multi-factor)
- Alltid ha fallback til manuell prosess
- Dokumenter decision logic for transparency
### Datasuverenitet
**Statens Standard (DSS-001):**
- Krever norsk data residency for "sensitive" offentlige data
- Voice signatures klassifiseres normalt som sensitive
- **Anbefaling:** Bruk Norway East region + CMK
**Alternative:**
- West Europe akseptabelt for "normal" skjermingsverdi
- US regions kun for ikke-personidentifiserbare data
## Kostnad og lisensiering
### Prismodell (per 2026-02)
| API | Enhet | NOK Pris (ca.)* | Use Case |
|-----|-------|-----------------|----------|
| **Speaker Verification** (text-dependent) | Per transaction | 11,60 | High-security auth |
| **Speaker Verification** (text-independent) | Per transaction | 11,60 | General auth |
| **Speaker Identification** | Per transaction | 11,60 | Meeting attribution, call routing |
| **Enrollment** | Per transaction | 11,60 | Voice profile creation |
*Estimert fra USD pricing ($1.05/1000 txn → ca. 11 NOK/1000). Verifiser aktuelle priser på Azure Pricing Calculator.
**Transaksjonsdefinisjoner:**
- 1 transaction = 1 API call (verification, identification, eller enrollment)
- Enrollment krever typisk 3-5 calls per user for god accuracy
- Verification/identification = 1 call per authentication attempt
### Optimaliseringstips
**1. Batch enrollment:**
```csharp
// Unngå: 5 separate API calls for enrollment
for (int i = 0; i < 5; i++)
{
await client.EnrollProfileAsync(profile, audioClips[i]); // 5 x 0.012 NOK
}
// Bedre: Kombiner audio før enrollment (hvis mulig)
var combinedAudio = CombineAudioClips(audioClips);
await client.EnrollProfileAsync(profile, combinedAudio); // 1 x 0.012 NOK
```
**2. Caching av verification results:**
- Cache positive verifications i 5-10 min for same session
- Reduser re-verification frequency i low-risk scenarios
**3. Threshold tuning for cost vs. security:**
- Lavere threshold → færre re-attempts → lavere cost
- Høyere threshold → mer sikkerhet men flere re-tries
**4. Regional pricing:**
- Norway East og West Europe har samme pricing tier
- Velg Norway East for compliance + likt cost
### TCO-estimat (10,000 brukere, banking scenario)
```
Assumptions:
- 10,000 enrolled users
- 5 enrollment attempts per user (initial setup)
- 2 verifications per user per day (login frequency)
- 250 working days per year
Enrollment cost: 10,000 users × 5 attempts × 0.012 NOK = 600 NOK (one-time)
Annual verification: 10,000 × 2 × 250 × 0.012 NOK = 60,000 NOK
Total first year: 60,600 NOK (~$5,500 USD)
```
**Alternative cost:** PIN-kode reset har typisk support cost på 50-100 NOK per incident. Med 5% users resetting annually (500 users) = 25,000-50,000 NOK support cost saved.
### Lisensiering
| Komponenet | Lisenskrav |
|-----------|------------|
| **Speaker Recognition API** | Ingen spesiell lisens (consumption-based) |
| **Teams Intelligent Speaker** | Teams Rooms Pro (ikke Standard/Basic) |
| **Copilot Speaker Attribution** | Teams Premium eller Copilot-lisens |
| **Speech SDK** | Gratis (open source, MIT license) |
## For arkitekten (Cosmo)
### 5-8 spørsmål å stille kunden
1. **Consent framework:** "Har dere etablert prosess for å innhente **explicit consent** til biometrisk prosessering fra hver enkelt bruker/ansatt? Hvilken dokumentasjon har dere for dette?"
2. **Liveness detection:** "Er dere klar over at Speaker Recognition **ikke** oppdager replay attacks eller deepfakes? Planlegger dere ekstra sikkerhetstiltak som tilfeldige passphrases eller challenge-response?"
3. **Data residency:** "Har dere datasuverenitetskrav som krever norsk/europeisk lagring av voice signatures? Er dere komfortabel med at Microsoft kan beholde kopier av voice models for security purposes?"
4. **Fallback strategy:** "Hva er plan B når voice recognition feiler? PIN-kode, security questions, eller human-in-the-loop? Hvor ofte forventer dere false rejections?"
5. **Use case classification:** "Er dette authentication (1:1 verification) eller identification (1:N)? Hvor mange kandidater må søkes gjennom samtidig (max 50 per call)?"
6. **Audio quality:** "Hvilken mikrofon/device-kvalitet forventer dere? Bakgrunnsstøy-nivå? Telefoni-kvalitet (8kHz) eller HD-lyd (16kHz+)?"
7. **Re-enrollment frequency:** "Hvor ofte må voice profiles oppdateres? Forventer dere stemmeendringer over tid (aging, sykdom) som påvirker accuracy?"
8. **Compliance readiness:** "Har dere gjennomført fundamental rights impact assessment (FRIA) for biometric processing? Er DPO involvert i denne avgjørelsen?"
### Fallgruver
| Fallgruve | Konsekvens | Mitigering |
|-----------|------------|-----------|
| **Forutsetter liveness detection** | Replay attacks går gjennom | Kombiner med random passphrase eller dedikert liveness API |
| **Manglende consent** | GDPR-brudd (Art. 9) | Implementer explicit consent flow før enrollment |
| **For kort enrollment audio** | Lav accuracy (< 70%) | Krev minimum 20 sek total enrollment audio |
| **Hardkodet threshold 0.5** | Sub-optimal for use case | Tune threshold basert på ROC curve for dine data |
| **Forventet multi-lingual** | Text-dependent er kun engelsk | Bruk text-independent hvis multi-språk påkrevd |
| **Ignorerer AI Act** | Legal/regulatory risk | Start med FRIA, dokumenter model governance |
| **Ingen human override** | Poor UX når false rejection | Alltid ha fallback-mekanisme |
### Anbefalinger per modenhetsnivå
**Nybegynner (Proof of Concept):**
- Start med text-independent verification for enklere UX
- Bruk default threshold (0.5) og Speech SDK quickstart samples
- Norway East region for compliance
- 10-20 test users for å validere accuracy i realistiske scenarios
**Erfaren (Pilot Production):**
- Tune custom threshold basert på pilot data
- Implementer consent management workflow
- Intelligent Speaker for Teams Rooms scenarios
- Monitoring av similarity score distribution og rejection rate
**Avansert (Enterprise Scale):**
- Customer-Managed Keys (CMK) for voice signature encryption
- Multi-region deployment for redundancy (Norway East + West Europe)
- Integration med Identity Governance (Entra ID verification)
- Automated re-enrollment når accuracy degraderer
- SIEM-integration for detection av replay attack patterns
**Enterprise Security Add-ons:**
```
Speaker Recognition + Azure AD Conditional Access
→ Require voice verification for high-value transactions
→ Step-up authentication basert på risk score
→ Anomaly detection hvis voice matcher men location/device er uvanlig
```
### Decision Checklist
Før du anbefaler Speaker Recognition:
- [ ] Kunden har **legal basis** for biometric processing (consent/legal obligation)
- [ ] **Data residency** requirements er kartlagt (Norway East vs. West Europe)
- [ ] **Liveness detection** gap er forstått og mitigert
- [ ] **Fallback mechanism** er designet for false rejections
- [ ] **Audio quality** fra target devices er validert
- [ ] **Threshold tuning** plan eksisterer (ikke default 0.5 for prod)
- [ ] **AI Act compliance** er vurdert (FRIA for high-risk systems)
- [ ] **Cost model** er godkjent (transactions vs. support cost tradeoff)
## Kilder og verifisering
### Microsoft Learn (Verified via MCP)
1. **Speaker Recognition REST API Reference**
- URL: https://learn.microsoft.com/en-us/rest/api/speakerrecognition/
- Confidence: **Verified** (MCP fetch 2026-02-03)
- Coverage: API endpoints, text-dependent/independent specs, similarity scoring
2. **Speaker Recognition Overview**
- URL: https://learn.microsoft.com/en-us/azure/ai-services/speech-service/speaker-recognition-overview
- Confidence: **Verified** (MCP fetch 2026-02-03)
- Coverage: Feature overview, verification vs. identification, use cases
3. **Data Privacy and Security for Text-to-Speech**
- URL: https://learn.microsoft.com/en-us/azure/ai-foundry/responsible-ai/speech-service/text-to-speech/data-privacy-security
- Confidence: **Verified** (MCP fetch 2026-02-03)
- Coverage: Speaker Verification for voice talent consent, voice signature processing, DPA compliance
4. **Speech SDK Code Samples**
- URL: https://github.com/Azure-Samples/cognitive-services-speech-sdk
- Confidence: **Verified** (MCP code sample search 2026-02-03)
- Coverage: C# enrollment/verification examples, Speech SDK patterns
5. **Teams Rooms Voice Recognition**
- URL: https://learn.microsoft.com/en-us/microsoftteams/rooms/voice-recognition
- Confidence: **Verified** (MCP search 2026-02-03)
- Coverage: Intelligent Speaker, policy configuration, speaker attribution
### Confidence Markers per Section
| Seksjon | Confidence | Kilde |
|---------|-----------|-------|
| **Kjernekomponenter** | Verified | REST API ref + Overview docs (MCP) |
| **Arkitekturmønstre** | Baseline + Verified | Model knowledge + Teams docs (MCP) |
| **Beslutningsveiledning** | Baseline | Praktisk erfaring + threshold best practices |
| **Microsoft-integrasjon** | Verified | Teams, Custom Voice docs (MCP) |
| **GDPR/Offentlig sektor** | Baseline | Legal framework knowledge (update med legal review) |
| **Kostnad** | Baseline | Estimated fra USD pricing (verifiser Azure calculator) |
### Områder som bør verifiseres videre
⚠️ **Prismodell:** Estimert fra USD → NOK konvertering. Verifiser eksakt NOK-pricing i Azure Portal.
⚠️ **AI Act compliance:** Generell fortolkning av high-risk classification. Krev juridisk review for production.
⚠️ **Norway East availability:** Antatt tilgjengelig basert på Speech Services regional presence. Verifiser i Azure Portal.
---
*Denne referansen er generert 2026-02-03 basert på Microsoft Learn dokumentasjon hentet via MCP (microsoft-learn server). For production decisions, verifiser alltid mot Azure Portal og konsulter legal team for compliance-spørsmål.*

470
plugins/ms-ai-architect/skills/ms-ai-engineering/references/azure-ai-services/speech-services-speech-to-text.md Normal file
View file

@ -0,0 +1,470 @@
# Speech Services - Speech-to-Text and Real-time Transcription
**Last updated:** 2026-02
**Status:** GA
**Category:** Azure AI Services (Foundry Tools)
---
## Introduksjon
Azure Speech Services tilbyr avansert tale-til-tekst-funksjonalitet som konverterer talte ord til maskinlesbar tekst. Tjenesten støtter tre hovedmodi: **real-time transcription** for live-lyd fra mikrofon eller streaming, **fast transcription** for rask synkron transkripsjon med forutsigbar latens, og **batch transcription** for asynkron prosessering av store lydvolumer i lagring.
Speech-to-text bygger på Microsoft-eid Universal Language Model som er trent på store mengder data på tvers av dialekter, akustiske forhold og domener. For spesialiserte behov kan man fine-tune custom speech-modeller med egne data for å forbedre nøyaktigheten på domene-spesifikt vokabular eller spesifikke lydforhold. Tjenesten tilbyr også speaker diarization (identifisering av ulike talere), språkidentifikasjon, flerspråklig transkripsjon, og phrase list-optimalisering.
Azure Speech to text er en kritisk byggesten i AI-løsninger som krever talegjenkjenning — fra tilgjengelighetsverktøy og kundeservice til medieproduksjon og compliance-dokumentasjon.
## Kjernekomponenter / Nøkkelegenskaper
### Tre transkripsjonsmodi
| Modus | Bruksområde | Latens | Input | Output |
|-------|-------------|--------|-------|--------|
| **Real-time** | Live-lyd fra mikrofon/stream | ~sekunder (intermediate results) | Audio stream via SDK/REST | Tekst i real-time |
| **Fast transcription** | Raske transkripsjoner av filer | < real-time (synkron) | Lydfiler < 2 timer, < 300 MB | Display form (med punktum/caps) |
| **Batch transcription** | Store volumer prerecorded audio | Asynkron (30 min - 24 timer) | Flere filer via Blob Storage | JSON med lexical + display form |
### Custom Speech
Custom speech lar deg fine-tune base-modellen med:
- **Text data** → forbedrer gjenkjenning av domene-spesifikt vokabular (medisinsk, juridisk, teknisk)
- **Audio + transcripts** → forbedrer gjenkjenning under spesifikke lydforhold (bakgrunnsstøy, dialekter, akustikk)
- **Structured text** → spesifiserer uttale, custom profanity filtering, inverse text normalization
Custom-modeller krever deployment til et **custom endpoint** (bortsett fra ved batch transcription). Modeller utløper etter en definert periode (se Model Lifecycle).
### Speaker Diarization
Identifiserer og skiller mellom ulike talere i én lydkanal. Returnerer `speaker` ID (0, 1, 2...) per phrase.
```json
{
"channel": 0,
"speaker": 1,
"text": "Good afternoon. This is Sam.",
"confidence": 0.936
}
```
**Begrensninger:**
- Maksimalt 2 kanaler hvis diarization er aktivert
- Diarization støttes ikke på tvers av flere kanaler samtidig
### Language Identification
Fast transcription og real-time kan identifisere språk automatisk hvis du:
- Spesifiserer flere locales: `["en-US", "ja-JP"]` → tjenesten velger beste match
- Ikke spesifiserer locales: `[]` → multi-lingual model identifiserer og transkriberer kontinuerlig
**Multi-lingual transcription (preview):** Støtter 14 språk (de-DE, en-AU/CA/GB/IN/US, es-ES/MX, fr-CA/FR, it-IT, ja-JP, ko-KR, zh-CN) i én fil uten å spesifisere locale.
### Phrase List
Forbedrer gjenkjenning av spesifikke ord/fraser ved å øke deres vekt:
```json
{
"phraseList": {
"phrases": ["Contoso", "Jessie", "Rehaan"]
}
}
```
Tilgjengelig i fast transcription (API version 2025-10-15).
### Støttede lydformater
- WAV, MP3, OPUS/OGG, FLAC, WMA, AAC, ALAW (WAV), MULAW (WAV), AMR, WebM, SPEEX
- Batch transcription: ubegrenset filstørrelse
- Fast transcription: < 2 timer, < 300 MB
- Real-time: streaming (ingen filstørrelsesbegrensning)
### Tilgangspunkter
| Metode | Bruksområde | API |
|--------|-------------|-----|
| **Speech SDK** | Real-time, programmatisk integrasjon | C#, Python, Java, JavaScript, C++, Go |
| **Speech CLI** | Kommandolinje, testing, scripting | `spx` |
| **REST API** | Batch, fast transcription, serverless | Speech to text REST API |
| **Speech Studio** | Web UI, testing, custom speech training | [speech.microsoft.com](https://speech.microsoft.com) |
## Arkitekturmønstre
### 1. Real-time Transcription for Live Events
**Bruksområde:** Tilgjengelighet (live captions), kundeservice, møtenotater
**Arkitektur:**
```
[Mikrofon/Stream] → Speech SDK → Azure Speech Service
↓
Real-time text
↓
[UI/Caption display/Agent dashboard]
```
**Fordeler:**
- Lav latens (intermediate results underveis)
- Støtter pronunciation assessment
- Fleksibel integrasjon via SDK
**Ulemper:**
- Krever kontinuerlig nettverksforbindelse
- Mindre kostnadseffektiv for store volumer
- Ikke optimalisert for batch-prosessering
**Når bruke:**
- Live events (webinars, møter)
- Interactive voice response (IVR)
- Accessibility (real-time captions)
---
### 2. Batch Transcription for High-Volume Processing
**Bruksområde:** Call center analytics, medieproduksjon, compliance-logging
**Arkitektur:**
```
[Lydfiler] → Azure Blob Storage → Batch Transcription API
↓
Asynkron prosessering
↓
[JSON results i Blob Storage]
↓
[Analytics pipeline / Data lake]
```
**Fordeler:**
- Skalerer til tusenvis av filer
- Ingen deployment endpoint nødvendig for custom models
- Kan bruke Whisper model (via batch API)
- Kostnadseffektiv for store volumer
**Ulemper:**
- Asynkron (30 min - 24 timer ventetid)
- Best-effort scheduling (kan ta tid i peak hours)
- Krever polling for å sjekke status
**Best practices:**
- Send ~1000 filer per `Transcription_Create` request
- Distribuer requests over tid (ikke send alt på én gang)
- Poll status maks én gang per minutt (ideelt hvert 5-10 min)
- Vurder multi-region load balancing for global scale
**Når bruke:**
- Call center transkripsjoner (etterpå)
- Video subtitling for arkiv
- Compliance-dokumentasjon av opptak
---
### 3. Fast Transcription for Predictable Low-Latency
**Bruksområde:** Video editing, voicemail, meeting notes
**Arkitektur:**
```
[Lydfil < 2h] → Fast Transcription API → Synkron respons
↓
JSON med display text
↓
[App/Editor/Workflow]
```
**Fordeler:**
- Raskere enn real-time (synkron)
- Forutsigbar latens
- Støtter diarization, language ID, phrase list
- Ingen ventetid (ingen polling)
**Ulemper:**
- Kun display form (ikke lexical)
- Maksimalt 2 timer audio, 300 MB
- Ikke egnet for store volumer (throttling)
**Når bruke:**
- Quick video transcription
- Voicemail transcription
- Meeting notes med diarization
---
## Beslutningsveiledning
### Velg transkripsjonsmodus
| Scenario | Anbefaling | Hvorfor |
|----------|------------|---------|
| Live webinar med captions | **Real-time** | Krever intermediate results og lav latens |
| 500 call center-opptak per dag | **Batch** | Asynkron, kostnadseffektiv, skalerer godt |
| Video editing med rask turnaround | **Fast** | Synkron, < 2h fil, raskere enn real-time |
| IVR (interactive voice response) | **Real-time** | Må respondere umiddelbart på tale |
| Compliance-logging av møter | **Batch** | Ingen hastegrad, store volumer |
### Custom Speech vs. Base Model
| Bruk custom model hvis... | Bruk base model hvis... |
|----------------------------|-------------------------|
| Domene-spesifikt vokabular (medisinsk, juridisk) | Generell tale (møter, samtaler) |
| Spesifikke lydforhold (støy, dialekt) | Standard akustikk |
| WER > 10% med base model | WER < 5% med base model |
| Kan levere minimum 1-10 timer annotert audio | Ikke har treningsdata |
**Training cost:** Custom models bygget på base models fra okt 2023 eller senere koster penger å trene. Tidligere modeller er gratis å trene.
### Vanlige feil å unngå
| Feil | Konsekvens | Løsning |
|------|------------|---------|
| Ikke spesifisere `locales` i fast transcription | Langsamere, mindre nøyaktig | Alltid send `"locales": ["en-US"]` hvis du vet språket |
| Polle batch transcription hvert sekund | Unødvendig load, throttling | Poll maks 1 gang per minutt (ideelt 5-10 min) |
| Bruke real-time for batch processing | Dyrt, ineffektivt | Bruk batch transcription for > 10 filer |
| Deploye custom endpoint for batch-bruk | Unødvendig hosting-kostnad | Batch transcription trenger ikke endpoint |
| Sende 10 000 batch requests samtidig | Best-effort scheduling = lang ventetid | Send ~1000 filer per request, distribuer over tid |
### Røde flagg
- **429 error (too many requests):** Du treffer throttling limits. Implementer exponential backoff eller distribuer requests.
- **WER > 20% på base model:** Custom speech er nødvendig, eller audioqualitet er for dårlig.
- **Batch transcription venter > 24 timer:** Peak load eller region overbelastet. Vurder multi-region strategi.
## Integrasjon med Microsoft-stakken
### Azure AI Foundry
Speech Services er en **Foundry Tool** i Azure AI Foundry. Du kan:
- Koble eksisterende Speech resource til Foundry project
- Teste real-time og fast transcription i Foundry portal
- Bringe custom speech models fra Speech Studio til Foundry
- Integrere med Prompt Flow for multimodal AI-løsninger
### Copilot Studio
Kan integrere Speech to text for:
- Voice-enabled bots (tale-input til Copilot)
- Call center automation
- Accessibility features
**Merk:** Copilot Studio har innebygd speech, men Azure Speech gir mer kontroll (custom models, diarization, etc.)
### Power Platform
**Power Automate:** Batch Speech to text Connector (low-code) lar deg:
- Trigge batch transcription fra Flow
- Hente resultater automatisk
- Integrere med Dataverse/SharePoint
**Azure Logic Apps:** Samme connector som Power Automate.
### Azure OpenAI + Speech
Kombinasjon for voice-enabled AI assistants:
1. Speech to text → transkriberer brukerinput
2. Azure OpenAI (GPT-4) → genererer respons
3. Speech synthesis → konverterer respons til tale
**Whisper via Azure OpenAI:** Azure OpenAI tilbyr Whisper model for transcription, men med andre pricing og capabilities enn Azure Speech batch transcription.
### M365 Copilot
M365 Copilot bruker Microsoft Speech internt for:
- Teams meeting transcription
- Outlook voice commands
**Integrasjonspunkt:** Du kan supplere med custom speech models hvis M365 Copilot ikke gjenkjenner domene-spesifikke termer godt nok (krever Azure Speech resource).
## Offentlig sektor (Norge)
### GDPR og datasuverenitet
**Data residency:** Azure Speech støtter **West Europe** og **North Europe** regions. Audio og transkripsjondata kan lagres i EU.
**Data processing:**
- Audio sendes til Speech endpoint (real-time/fast transcription)
- Batch transcription leser fra og skriver til Blob Storage (kan være i Norway/EU)
- Custom speech training data lagres i Speech resource region
**Retention:**
- Microsoft-owned storage: Logging data slettes etter 30 dager
- Customer-owned storage: Du kontrollerer retention
### AI Act (EU)
Speech to text faller typisk under **begrenset risiko** (transparency obligations):
- **Krav:** Informer brukere om at tale blir transkribert av AI
- **Dokumentasjon:** Microsoft leverer transparency notes for Speech to text
- **High-risk:** Hvis brukt i rekruttering, rettssaker, eller biometric identification → strengere krav
### Schrems II
**Microsoft compliance:**
- EU Data Boundary commitment (data prosesseres i EU)
- Standard Contractual Clauses (SCCs)
- Ingen U.S. government data access for EU-lagrede data
**For offentlig sektor:** Bruk West Europe/North Europe regions og customer-managed keys (CMK) for ekstra kontroll.
### Forvaltningsloven (Norge)
Offentlige virksomheter må kunne:
- **Dokumentere beslutninger:** Batch transcription gir JSON med lexical + display form → arkiverbart
- **Innsyn:** Transkripsjondata er personopplysninger hvis det identifiserer personer
- **Kvalitetssikring:** Custom speech modeller må testes for bias (dialekter, kjønn, alder)
**Anbefaling:** Test custom models på representative norske dialekter (østlandsk, bergensk, trøndersk) for å unngå bias.
### Personvern og konfidensialitet
**Speaker diarization:** Identifiserer talere, men ikke *hvem* de er (kun "Speaker 1, Speaker 2"). Ingen biometric identification.
**Audio logging:**
- Deaktiver audio logging hvis personvern er kritisk
- Bruk customer-managed storage for full kontroll
- Implementer data retention policies (slett audio etter transkripsjon)
**Profanity filtering:** Bruk `profanityFilterMode: "Removed"` eller `"Masked"` i offentlige systemer for compliance.
## Kostnad og lisensiering
### Prismodell (per februar 2026)
**Real-time transcription:**
- Standard: ~$1 per audio hour
- Custom speech endpoint hosting: ~$0.05 per model per hour
**Fast transcription:**
- ~$0.50 per audio hour (raskere enn real-time)
**Batch transcription:**
- Standard: ~$1 per audio hour
- Custom model: Ingen ekstra kostnad (krever ikke endpoint)
**Custom speech training:**
- Base models fra okt 2023+: Betalt (~$20-50 per training run)
- Eldre base models: Gratis training
**Merk:** Priser er veiledende, sjekk [Azure Pricing Calculator](https://azure.microsoft.com/pricing/details/cognitive-services/speech-services/) for eksakte tall.
### Optimaliseringstips
| Strategi | Besparelse | Trade-off |
|----------|------------|-----------|
| Bruk batch i stedet for real-time for prerecorded audio | 30-50% | Asynkron (ventetid) |
| Deaktiver custom endpoint for batch-bruk | ~$35/måned per modell | Kan ikke bruke custom model i real-time |
| Bruk fast transcription for < 2h filer | Raskere = mindre compute-kostnad | Kun display form |
| Multi-region load balancing | Unngå throttling (indirekte besparelse) | Mer kompleks arkitektur |
| Audio compression (MP3 i stedet for WAV) | Mindre bandwidth-kostnad | Marginal besparelse |
### TCO-eksempel (call center med 10 000 timer/måned)
**Scenario:** Call center med 10 000 timer opptak per måned, behov for custom model (medisinsk/juridisk vokabular).
| Komponent | Kostnad/måned (USD) |
|-----------|---------------------|
| Batch transcription (10k timer) | $10 000 |
| Custom model training (1x per kvartal) | $17 (amortisert) |
| Blob Storage (audio + results) | $50 |
| **Total** | **~$10 067** |
**Vs. real-time:** $10 000 (transcription) + $35 (endpoint hosting) = $10 035 (men krever real-time streaming).
## For arkitekten (Cosmo)
### Spørsmål å stille kunden
1. **"Trenger dere transkripsjon i real-time, eller kan dere vente minutter/timer?"**
- Real-time → Speech SDK + real-time API
- Kan vente → Fast transcription (< 2h) eller Batch (> 2h)
2. **"Hvor mange timer audio prosesserer dere per måned, og hvor ofte?"**
- < 100 timer/måned → Real-time eller fast transcription
- > 1000 timer/måned → Batch transcription obligatorisk
3. **"Har dere domene-spesifikt vokabular (medisinsk, juridisk, teknisk)?"**
- Ja → Custom speech nødvendig (test base model først)
- Nei → Base model er trolig tilstrekkelig
4. **"Trenger dere å identifisere ulike talere?"**
- Ja → Diarization (maks 2 kanaler)
- Nei → Standard transcription
5. **"Hvilke språk snakkes i opptakene, og er det én eller flere språk per opptak?"**
- Én kjent språk → Spesifiser `locales: ["nb-NO"]`
- Ukjent språk → Language identification (`locales: ["nb-NO", "en-US"]`)
- Flere språk i samme opptak → Multi-lingual transcription (preview)
6. **"Hvor viktig er datasuverenitet og personvern?"**
- Kritisk → West Europe region, customer-managed keys, disable logging
- Viktig → West Europe region, standard encryption
- Mindre viktig → Hvilken som helst region
7. **"Har dere eksisterende lydfiler, eller er dette live audio?"**
- Prerecorded → Batch eller fast transcription
- Live → Real-time transcription
8. **"Hva er akseptabel Word Error Rate (WER)?"**
- < 5% → Base model kan fungere
- < 2% → Custom speech nødvendig
- < 1% → Krever betydelig training data og fine-tuning
### Fallgruver å unngå
1. **Over-engineering med custom speech:** Test alltid base model først. Custom speech krever tid, data, og løpende vedlikehold (model expiry).
2. **Ikke planlegge for throttling:** Azure Speech har rate limits. Implementer exponential backoff og retry logic.
3. **Ignorere model lifecycle:** Custom models og base models har expiry dates. Sett opp automatisk oppdatering eller notifications.
4. **Mikse real-time og batch i samme arkitektur:** Velg én primær modus. Hvis både live og prerecorded, bruk separate pipelines.
5. **Ikke teste på representative data:** Custom models trent på én dialekt kan feile på andre. Test på variert audio (bakgrunnsstøy, kjønn, alder, dialekter).
6. **Undervurdere batch transcription latency:** Best-effort scheduling = kan ta 24 timer i peak. Ikke bruk batch hvis du trenger resultater innen minutter.
### Anbefalinger per modenhetsnivå
#### Nivå 1: Proof of Concept
- **Bruk:** Speech Studio (web UI) eller Speech CLI
- **Modell:** Base model (ingen custom speech)
- **Modus:** Real-time eller fast transcription (< 100 timer)
- **Fokus:** Verifiser at speech to text fungerer for ditt domene
#### Nivå 2: Pilot / MVP
- **Bruk:** Speech SDK i app/service
- **Modell:** Base model, test custom speech hvis WER > 10%
- **Modus:** Fast transcription for < 2h filer, batch for > 2h
- **Fokus:** Implementer error handling, retry logic, cost tracking
#### Nivå 3: Production
- **Bruk:** Speech SDK + REST API (batch)
- **Modell:** Custom speech hvis nødvendig, automatiser model updates
- **Modus:** Batch transcription for scale, real-time for live use cases
- **Fokus:** Multi-region deployment, throttling mitigation, monitoring (WER, latency, cost)
- **Compliance:** Data residency, retention policies, transparency notes
#### Nivå 4: Enterprise Scale
- **Bruk:** Speech SDK + batch REST API + Power Automate connector
- **Modell:** Multiple custom models per domene/språk
- **Modus:** Batch transcription med multi-region load balancing
- **Fokus:** Cost optimization (reserved capacity), advanced analytics (sentiment, topic modeling), integration med data lake
- **Governance:** Automated model lifecycle, bias testing, compliance reporting
## Kilder og verifisering
**Microsoft Learn (Verified via MCP):**
- [What is speech to text?](https://learn.microsoft.com/en-us/azure/ai-services/speech-service/speech-to-text)
- [What is batch transcription?](https://learn.microsoft.com/en-us/azure/ai-services/speech-service/batch-transcription)
- [What is custom speech?](https://learn.microsoft.com/en-us/azure/ai-services/speech-service/custom-speech-overview)
- [Use the fast transcription API](https://learn.microsoft.com/en-us/azure/ai-services/speech-service/fast-transcription-create)
- [Quickstart: Recognize and convert speech to text](https://learn.microsoft.com/en-us/azure/ai-services/speech-service/get-started-speech-to-text)
- [Speech to text REST API reference](https://learn.microsoft.com/en-us/rest/api/speechtotext/transcriptions/transcribe)
**Confidence markers:**
- Real-time transcription, batch transcription, custom speech, diarization: **Verified** (Microsoft Learn)
- Fast transcription API, phrase list, multi-lingual transcription: **Verified** (Microsoft Learn)
- Pricing: **Baseline** (veiledende, sjekk Azure Pricing Calculator for eksakte tall)
- Norwegian compliance (Forvaltningsloven, dialekter): **Baseline** (generell kunnskap, ikke Microsoft-spesifikk)
**Sist oppdatert:** 2026-02 (basert på Microsoft Learn documentation per februar 2026)

522
plugins/ms-ai-architect/skills/ms-ai-engineering/references/azure-ai-services/speech-services-text-to-speech.md Normal file
View file

@ -0,0 +1,522 @@
# Speech Services - Text-to-Speech and Neural Voices
**Last updated:** 2026-02
**Status:** GA
**Category:** Azure AI Services (Foundry Tools)
---
## Introduksjon
Azure Speech Services sitt Text-to-Speech (TTS) API konverterer tekst til naturlig syntetisk tale ved hjelp av deep neural networks. Tjenesten er en del av Azure AI Foundry Tools og tilbyr over 400 stemmer på 140+ språk og dialekter. TTS gjør det mulig å lage applikasjoner som leser opp tekst, generere lydbøker, bygge chatbots med naturlig tale, og forbedre tilgjengelighet.
Kjernen i moderne TTS er neural voices som bruker dype nevrale nettverk for å overkomme begrensningene til tradisjonell talesyntese når det gjelder stress og intonasjon. Prosody-prediksjon og stemmesyntese skjer samtidig, noe som gir mer flytende og naturlige resultater. Hvert standard neural voice-modell er tilgjengelig i 24 kHz og høy-fidelitet 48 kHz, og output kan opp- eller ned-samples til andre formater.
Microsoft tilbyr tre kategorier av stemmer: **standard voices** (out-of-the-box neural voices), **custom voices** (professional voice fine-tuning med Limited Access), og **personal voice** (rask stemmeopprettelse fra korte prøver). For produksjonsmiljøer er standard voices den vanligste løsningen, mens custom voice krever søknad og godkjenning fra Microsoft.
## Kjernekomponenter / Nøkkelegenskaper
| Komponent | Beskrivelse | Bruk |
|-----------|-------------|------|
| **Standard Neural Voices** | Over 400 ferdigtrente stemmer i 140+ språk/dialekter, tilgjengelig i 24kHz og 48kHz | Generell talesyntese, chatbots, accessibility |
| **Multilingual Voices** | Stemmer som flytende snakker flere språk (eks. `en-US-AvaMultilingualNeural` støtter 91 locales) | Flerspråklige applikasjoner, globalreach |
| **High Definition (HD) Voices** | Høyere kvalitet neural voices for krevende scenarioer | Premium lydkvalitet, professional content |
| **OpenAI TTS Voices** | OpenAI-stemmer tilgjengelig via Azure Speech (North Central US, Sweden Central) | Integrasjon med OpenAI-baserte løsninger |
| **Custom Neural Voice** | Limited Access-funksjon for å trene unike merkestemmer | Brand identity, spesialiserte use cases |
| **Personal Voice** | Rask stemmekloning fra korte lydprøver | Personaliserte applikasjoner, voice assistants |
| **SSML** | Speech Synthesis Markup Language for kontroll over prosody, rate, pitch, volume, styles | Avansert stemmekontroll |
| **Batch Synthesis API** | Asynkron syntese for lange lydfiler (>10 min, eks. lydbøker) | Long-form content, batch processing |
| **Real-time Synthesis** | Speech SDK eller REST API for sanntidssyntese | Interactive applications, voice agents |
| **Visemes** | Ansiktsposisjoner (leppe-synkronisering) for hver fonem | Leppe-lesing, avatars, animation |
| **Audio Effect Processor** | Optimalisering for spesifikke miljøer (`eq_car`, `eq_telecomhp8k`) | Bil-audio, telecom, noisy environments |
| **Text-to-Speech Avatar** | Syntetisk video av avatar som snakker (prebuilt og custom) | Visual chatbots, kiosks, metaverse |
### SSML Prosody-kontroll
Med SSML kan du justere følgende prosodiske elementer:
| Element | Verdier | Eksempel |
|---------|---------|----------|
| **Rate** | `0.5` til `2` (eller `x-slow`, `slow`, `medium`, `fast`, `x-fast`) | `<prosody rate="+30%">` |
| **Pitch** | `0.5` til `1.5` × original (Hz, semitones, %, `x-low/low/medium/high/x-high`) | `<prosody pitch="high">` |
| **Volume** | `0.0` til `100.0` (eller `silent`, `x-soft`, `soft`, `medium`, `loud`, `x-loud`) | `<prosody volume="+20%">` |
| **Contour** | Array av pitch-endringer over tid | `<prosody contour="(0%,+20Hz)(10%,-2st)">` |
| **Emphasis** | `reduced`, `none`, `moderate`, `strong` (kun visse stemmer) | `<emphasis level="moderate">` |
| **Style** | Språk- og stemmespesifikke stiler (eks. `cheerful`, `sad`, `angry`, `newscast`) | `<mstts:express-as style="cheerful">` |
| **Role** | Aldersrolle/kjønn-imitasjon (`Girl`, `Boy`, `YoungAdultFemale`, etc.) | `<mstts:express-as role="OlderAdultMale">` |
### Kodeeksempel (C# med Speech SDK)
```csharp
using Microsoft.CognitiveServices.Speech;
var speechConfig = SpeechConfig.FromSubscription("YourSpeechKey", "YourSpeechRegion");
// Velg standard neural voice
speechConfig.SpeechSynthesisLanguage = "en-US";
speechConfig.SpeechSynthesisVoiceName = "en-US-Ava:DragonHDLatestNeural";
// Syntetiser til speaker
using var speechSynthesizer = new SpeechSynthesizer(speechConfig);
await speechSynthesizer.SpeakTextAsync("I'm excited to try text to speech");
// Eller til fil
using var audioConfig = AudioConfig.FromWavFileOutput("output.wav");
using var fileSynthesizer = new SpeechSynthesizer(speechConfig, audioConfig);
await fileSynthesizer.SpeakTextAsync("This goes to a file");
```
### SSML-eksempel (med prosody og style)
```xml
<speak version="1.0" xmlns="http://www.w3.org/2001/10/synthesis"
xmlns:mstts="https://www.w3.org/2001/mstts" xml:lang="en-US">
<voice name="en-US-AvaMultilingualNeural">
<mstts:express-as style="cheerful" styledegree="2">
<prosody rate="+10%" pitch="+5%">
Welcome to Azure Speech Services!
</prosody>
</mstts:express-as>
</voice>
</speak>
```
## Arkitekturmønstre
### Mønster 1: Real-time Interactive Speech
**Beskrivelse:** Sanntidssyntetisering av tale for chatbots, voice assistants og IVR-systemer.
**Implementering:**
- Bruk Speech SDK (C#, Python, JavaScript, Java, C++, Objective-C, Swift)
- Konfigurer SpeechConfig med subscription key og region
- Velg neural voice basert på use case (standard/multilingual/HD)
- Send tekst eller SSML til SpeakTextAsync() / SpeakSsmlAsync()
- Output til speaker, fil eller in-memory stream
**Fordeler:**
- Lav latency (optimalisert for sanntidsrespons)
- Støtter streaming audio output
- Integrasjon med Speech-to-Text for full voice conversation loop
- Viseme-events for ansiktsanimasjon
**Ulemper:**
- Rate limits per Speech resource (justerbar med business justification)
- Krever konstant nettverkstilkobling
- Ikke egnet for batch-generering av lange lydfiler
**Best for:** Conversational AI, voice agents, accessibility features, in-car assistants.
---
### Mønster 2: Batch Synthesis for Long-Form Content
**Beskrivelse:** Asynkron syntese av lange lydfiler (>10 min) som lydbøker, podcasts, e-læring.
**Implementering:**
- Bruk Batch Synthesis REST API (preview)
- Send text eller SSML med metadata
- Poll for status (pending → running → succeeded)
- Download synthesized audio når klar
- Støtter custom voices og personal voices
**Fordeler:**
- Ingen tidsbegrensning (støtter timer-lange filer)
- Asynkron prosessering (fire-and-forget)
- Støtter alle output-formater (inkl. 48kHz)
- Optimalisert for throughput over latency
**Ulemper:**
- Ikke sanntid (kan ta minutter avhengig av lengde)
- Krever polling-logikk i applikasjon
- Ikke støtte for audio-element i SSML (men batch synthesis API har det)
**Best for:** Audiobooks, training materials, podcast-generering, large-scale content creation.
---
### Mønster 3: Custom Brand Voice med Professional Fine-Tuning
**Beskrivelse:** Opprett unik merkestemme med professional voice fine-tuning (Limited Access).
**Implementering:**
1. Søk om tilgang via intake form (https://aka.ms/customneural)
2. Samle høykvalitets voice recordings (voice talent consent påkrevd)
3. Opprett prosjekt i Speech Studio
4. Last opp recording scripts og audio (20-40 compute hours training)
5. Train modell (cap: 96 compute hours fakturering)
6. Deploy endpoint (hosting faktureres per time)
7. Bruk custom voice name i SSML
**Fordeler:**
- Unik brand identity
- Støtter multi-style training (ca. 90 compute hours)
- 48kHz output etter engine upgrade
- Kan kombineres med SSML for ekstra kontroll
**Ulemper:**
- Limited Access (krever godkjenning)
- Koster å trene ($$ per compute hour)
- Koster å hoste endpoint ($$ per time)
- Voice talent consent og juridiske krav
- Ikke egnet for quick prototyping
**Best for:** Enterprise brand voice, customer service, media production, long-term investments.
## Beslutningsveiledning
### Når bruke Standard Neural Voices?
| Scenario | Anbefaling |
|----------|------------|
| **Prototype/MVP** | ✅ Ja — rask oppstart, ingen godkjenning |
| **Budget-begrenset** | ✅ Ja — kun pay-per-character |
| **Global reach** | ✅ Ja — 140+ språk out-of-the-box |
| **Kort time-to-market** | ✅ Ja — ingen training-tid |
| **Generic voice OK** | ✅ Ja — bred støtte, god kvalitet |
### Når bruke Custom Neural Voice?
| Scenario | Anbefaling |
|----------|------------|
| **Brand identity kritisk** | ✅ Ja — unik merkestemme |
| **Celebrity/character voice** | ✅ Ja — med consent |
| **Langsiktig investering** | ✅ Ja — ROI over tid |
| **Compliance med voice talent** | ✅ Ja — juridisk rammeverk på plass |
| **Quick POC** | ❌ Nei — for lang lead time |
### Når bruke Personal Voice?
| Scenario | Anbefaling |
|----------|------------|
| **User-generated voices** | ✅ Ja — rask kloning |
| **Personaliserte assistenter** | ✅ Ja — hver bruker sin stemme |
| **Skalering (mange stemmer)** | ✅ Ja — per-voice-per-day fakturering |
| **Høy kvalitetskrav** | ⚠️ Vurder — lavere kvalitet enn professional |
### Beslutningstabell: Batch vs. Real-time
| Kriterium | Real-time Synthesis | Batch Synthesis |
|-----------|---------------------|-----------------|
| **Latency** | <1 sekund | Minutter (asynkront) |
| **Audio lengde** | <10 minutter | Ubegrenset |
| **Use case** | Interactive/conversational | Long-form content |
| **SDK support** | Ja (alle språk) | REST API only |
| **Streaming** | Ja | Nei (download når ferdig) |
### Vanlige feil og røde flagg
| Feil | Konsekvens | Løsning |
|------|------------|---------|
| **Hardkodet SSML-stemmer** | Ikke flerspråklig-kompatibel | Bruk multilingual voices + lang element |
| **Ignorer audio effects** | Dårlig lydkvalitet i bil/telefon | Bruk `effect="eq_car"` eller `eq_telecomhp8k` |
| **Over-tuning prosody** | Unaturlig robotlyd | Hold rate mellom 0.5-2, pitch 0.5-1.5 |
| **Glemmer rate limits** | Throttling i prod | Request rate increase proaktivt |
| **Ingen error handling** | Dårlig brukeropplevelse | Implementer fallback til alternativ stemme |
| **Custom voice uten hosting** | Voice ikke tilgjengelig | Budsjett for endpoint hosting-kostnader |
| **Chinese characters** | Dobbel billing | 1 kinesisk tegn = 2 billable characters |
## Integrasjon med Microsoft-stakken
### Azure AI Foundry
- TTS er innebygd i AI Foundry Playground
- Testverktøy: Speech Studio Voice Gallery, Audio Content Creation
- Ingen kode-tilnærming: Audio Content Creation tool
- Prosjekt-basert deployment med Foundry resources
### Microsoft 365 Copilot & Copilot Studio
- TTS kan integreres via custom connectors (Power Automate)
- Ikke native i M365 Copilot per januar 2026
- Copilot Studio: kan bruke TTS via Power Automate action
### Power Platform
- Power Automate: Speech Services-connector tilgjengelig
- Custom connectors: REST API-basert integrasjon
- AI Builder: Ikke direkte TTS-støtte (men kan kalle via Power Automate)
### Azure OpenAI
- OpenAI TTS voices tilgjengelig i Azure Speech (North Central US, Sweden Central)
- Også tilgjengelig direkte via Azure OpenAI TTS API
- Støtter `tts-1` og `tts-1-hd` modeller (alloy, echo, fable, onyx, nova, shimmer)
### Microsoft Agent Framework
- TTS kan brukes som output-kanal i agent-arkitektur
- Voice Live API: Kombinerer STT, LLM, og TTS i én WebSocket-forbindelse
- Avatar-integrasjon: Real-time avatar synthesis med TTS
### Azure Services
| Tjeneste | Integrasjonspunkt |
|----------|-------------------|
| **Azure Functions** | Call Speech SDK fra serverless function |
| **Azure Logic Apps** | HTTP action til REST API |
| **Azure Bot Service** | Innebygd TTS-støtte via Bot Framework |
| **Azure Media Services** | TTS output kan lagres i Media Services |
| **Azure Blob Storage** | Lagring av synthesized audio files |
| **Azure CDN** | Distribusjon av pre-generated audio |
## Offentlig sektor (Norge)
### GDPR og personvern
**Data som prosesseres:**
- Input text (kan inneholde personopplysninger)
- Voice samples (for custom/personal voice — biometrisk data)
- Synthesized audio output
**GDPR-vurdering:**
- Text input logges ikke av Microsoft (processed in-memory)
- Custom voice training data lagres i Speech resource (customer-controlled)
- Personal voice profiles er biometrisk data — krever eksplisitt consent
- Audio output er ikke persondata med mindre innholdet er det
**Anbefalinger:**
- Bruk Azure regions i EU (West Europe, North Europe) for data residency
- For custom voice: DPIA (Data Protection Impact Assessment) påkrevd
- Voice talent consent må dekke GDPR Art. 9 (biometric data)
- Implementer logging og audit trail for TTS requests
### Schrems II og datasuverenitet
**Utfordringer:**
- Azure Speech kjører i Microsoft-kontrollerte datasentre
- EU-US Data Privacy Framework gjelder for data transfers
- Custom voice modeller lagres i Azure region (customer choice)
**Mitigering:**
- Velg EU-baserte regions (West Europe, North Europe)
- Bruk Azure Confidential Computing for ekstra isolasjon (ikke direkte støttet for Speech per jan 2026)
- Contractual clauses: Standard Contractual Clauses (SCCs) dekker transfers
### AI Act (EU)
**Risikoklassifisering:**
- TTS er generelt **lav-risiko** AI (ikke i high-risk categories)
- **Unntak:** TTS for deepfakes eller manipulation → transparency-krav
- **Custom voice med voice cloning** → disclosure-krav
**Compliance-krav:**
- Disclosure: Brukere må informeres om at stemmen er syntetisk
- Transparency note: Microsoft tilbyr transparency note for custom voice
- Prohibited uses: Ikke bruk for manipulation, misinformation eller skade
**Anbefalinger:**
- Implementer explicit disclosure i UI ("This voice is AI-generated")
- Følg Microsoft's Code of Conduct for TTS integrations
- Voice talent consent må dekke AI Act-krav
### Forvaltningsloven og universell utforming
**Tilgjengelighetskrav:**
- TTS forbedrer tilgjengelighet for synshemmede (WCAG 2.1 AA)
- Offentlige nettsteder skal tilby skjermleserstøtte (Forvaltningsloven § 42)
**Anbefalinger:**
- Implementer TTS som standard accessibility feature
- Test med norske stemmer (nb-NO) for norsk offentlig sektor
- Kombiner med STT for full voice-basert navigasjon
### Språk og dialekter (Norge)
| Språk | Stemmer tilgjengelig | Kvalitet |
|-------|----------------------|----------|
| **Norwegian Bokmål (`nb-NO`)** | `nb-NO-PernilleNeural` (F), `nb-NO-FinnNeural` (M) | ⭐⭐⭐⭐ |
| **Norwegian Nynorsk** | Ikke støttet (bruk `nb-NO` med tekst-tilpasning) | — |
| **Samisk** | Ikke støttet | — |
**Utfordring:** Nynorsk og samisk ikke native støttet. Løsning: Translasjon før TTS eller custom voice training.
## Kostnad og lisensiering
### Prismodell (pr. januar 2026)
| Kategori | Enhet | Pris (estimat, sjekk Azure pricing) |
|----------|-------|-------------------------------------|
| **Standard Neural Voices** | Per character | ~$0.015 per 1000 characters |
| **HD Voices** | Per character | ~$0.03 per 1000 characters |
| **Custom Voice Training** | Per compute hour | ~$10-$50 per hour (cap: 96h) |
| **Custom Voice Hosting** | Per endpoint per hour | ~$0.05-$0.50 per hour |
| **Personal Voice Storage** | Per voice per day | ~$1-$5 per voice per day |
| **Personal Voice Synthesis** | Per character | Samme som standard voices |
| **Batch Synthesis** | Per character | Samme som standard voices |
| **Text-to-Speech Avatar** | Per second of video | ~$0.02-$0.10 per second |
**Viktig:** Priser varierer per region og er illustrative. Sjekk [Azure Pricing Calculator](https://azure.microsoft.com/pricing/details/cognitive-services/speech-services/) for eksakt prisnivå.
### Fakturering av tegn (billable characters)
- **Alle tegn teller:** bokstaver, tall, mellomrom, tegnsetting
- **SSML markup teller:** Alt unntatt `<speak>` og `<voice>` tags
- **Kinesiske tegn = 2× tegn** (også kanji, hanja, hanzi)
- **Ingen output = faktureres likevel** (hvis request er valid)
**Eksempel:**
```xml
<speak><voice name="en-US-AvaNeural">Hello, world!</voice></speak>
```
Billable characters: `Hello, world!` = 13 tegn (ikke `<speak>` eller `<voice>`)
### Kostnadsoptimalisering
| Strategi | Besparelse |
|----------|------------|
| **Cache synthesized audio** | 90%+ (for statisk innhold) |
| **Use standard voices over HD** | 50% |
| **Pre-generate common phrases** | 100% (ingen runtime-kostnad) |
| **Batch synthesis for long-form** | Ingen direkte saving, men bedre throughput |
| **Rate limit management** | Unngå throttling-kostnader |
| **Suspend custom voice endpoints** | 100% hosting-kostnad når ikke i bruk |
### Lisenskrav
- **Azure subscription** påkrevd (Pay-as-you-go, EA, CSP)
- **Speech resource** i Azure portal (S0 tier for production)
- **Free tier (F0)** tilgjengelig: 5 audio requests/month, 0.5M characters/month
- **Custom voice:** Krever Microsoft Foundry resource + Limited Access approval
### TCO-estimat (Total Cost of Ownership) — Eksempel
**Scenario:** Voice assistant for offentlig sektor (10,000 brukere/måned, 50 requests/bruker, 200 characters/request)
| Komponent | Kalkyle | Kostnad/måned (NOK) |
|-----------|---------|---------------------|
| **Characters** | 10,000 × 50 × 200 = 100M chars | ~15,000 kr |
| **Speech resource (S0)** | Fixed cost | 0 kr (PAYG) |
| **Bandwidth (egress)** | ~100 GB @ 48kHz WAV | ~100 kr |
| **Storage (cache)** | ~500 GB Blob Storage | ~100 kr |
| **Total** | — | **~15,200 kr/måned** |
**Custom voice-tillegg:**
- Training (one-time): ~20,000-50,000 kr (40 compute hours × ~500 kr/h)
- Hosting: ~4,000 kr/måned (24/7 endpoint)
- **Total første år:** ~230,000 kr
## For arkitekten (Cosmo)
### Spørsmål å stille kunden
1. **Hvilke språk må støttes, og er norsk bokmål tilstrekkelig eller trengs nynorsk/samisk?**
- Hvis nynorsk: vurder custom voice training eller tekst-tilpasning før TTS.
2. **Er det behov for unik merkestemme, eller er standard neural voices godt nok?**
- Custom voice krever Limited Access approval (4-6 ukers lead time) og voice talent consent.
3. **Skal TTS brukes i sanntid (chatbot) eller batch (audiobook)?**
- Sanntid: Speech SDK med low-latency konfigurering.
- Batch: Batch Synthesis API for filer >10 minutter.
4. **Hva er volumet av characters per måned, og hva er budsjettet?**
- Bruk Azure Pricing Calculator for estimat. Cache statisk innhold for å spare penger.
5. **Er det krav til disclosure (AI-generert stemme) eller voice talent consent?**
- Offentlig sektor + EU AI Act: Disclosure påkrevd for transparency.
6. **Skal løsningen integreres med eksisterende Microsoft-stack (Teams, Power Platform, Azure OpenAI)?**
- Power Automate connector tilgjengelig. Azure OpenAI har egen TTS API.
7. **Hva er kravet til lydkvalitet: standard (24kHz), HD (48kHz), eller professional custom voice?**
- HD voices koster 2× standard. Custom voice for ultimate kvalitet.
8. **Er det behov for prosody-kontroll (SSML) eller holder plain text?**
- SSML gir kontroll over rate, pitch, volume, style — anbefalt for advanced use cases.
### Fallgruver og vanlige feil
| Fallgruve | Konsekvens | Hvordan unngå |
|-----------|------------|---------------|
| **Ikke test med norske stemmer** | Dårlig brukeropplevelse | Test `nb-NO-PernilleNeural` tidlig i prosjektet |
| **Over-estimert custom voice ROI** | Høye kostnader uten verdi | Start med standard voices, vurder custom etter MVP |
| **Glemmer voice talent consent** | Juridisk risiko | Følg Microsoft's consent guidelines og mal |
| **Ingen error handling** | App crasher ved rate limits | Implementer retry logic og fallback-stemme |
| **Hard-kodet stemmer** | Ikke skalerbart | Bruk konfigurasjon/database for voice selection |
| **Ignorerer GDPR** | Brudd på personvernforskriften | DPIA for custom voice, data residency i EU |
### Anbefalinger per modenhetsnivå
#### Nivå 1: Pilot / POC
- **Bruk:** Standard neural voices (`nb-NO-PernilleNeural`)
- **SDK:** Speech SDK (C# eller Python)
- **Output:** Speaker eller in-memory stream
- **Kostnad:** Free tier (F0) eller minimal PAYG
- **Tid:** 1-2 uker implementering
#### Nivå 2: MVP / Production
- **Bruk:** Standard neural voices eller HD voices
- **SDK:** Speech SDK med error handling og retry logic
- **Caching:** Azure Blob Storage for statisk innhold
- **Monitoring:** Application Insights for latency tracking
- **Kostnad:** PAYG (S0 tier)
- **Tid:** 4-6 uker implementering
#### Nivå 3: Enterprise / Custom Voice
- **Bruk:** Custom neural voice (Limited Access)
- **Training:** 40-90 compute hours (single/multi-style)
- **Hosting:** 24/7 endpoint deployment
- **Integration:** Power Platform, Azure OpenAI, Teams
- **Compliance:** GDPR, AI Act, voice talent consent
- **Kostnad:** 200,000-500,000 kr første år (training + hosting)
- **Tid:** 3-6 måneder (inkl. approval process)
#### Nivå 4: Advanced / Multi-Region / Avatar
- **Bruk:** Multi-region deployment (HA/DR)
- **Avatar:** Text-to-Speech Avatar (prebuilt eller custom)
- **Voice Live API:** Integrated STT + LLM + TTS pipeline
- **Geo-redundancy:** Multiple Speech resources (West Europe + North Europe)
- **Kostnad:** 500,000+ kr/år
- **Tid:** 6-12 måneder
### Sikkerhetsdesign-tips
- **API keys:** Bruk Azure Key Vault, ikke hardkod i kode
- **Managed Identity:** Foretrekk over service principals for Azure-integrasjoner
- **Network isolation:** Private Endpoints for Speech resources hvis mulig
- **Rate limiting:** Implementer client-side throttling før Azure rate limits
- **Audit logging:** Log alle TTS requests for compliance (Analytics Workspace)
## Kilder og verifisering
### Microsoft Learn (Verified via MCP)
| Kilde | Confidence | URL |
|-------|------------|-----|
| What is Text-to-Speech? | ✅ Verified | https://learn.microsoft.com/en-us/azure/ai-services/speech-service/text-to-speech |
| Customize voice and sound with SSML | ✅ Verified | https://learn.microsoft.com/en-us/azure/ai-services/speech-service/speech-synthesis-markup-voice |
| How to synthesize speech from text | ✅ Verified | https://learn.microsoft.com/en-us/azure/ai-services/speech-service/how-to-speech-synthesis |
| Text-to-Speech FAQ | ✅ Verified | https://learn.microsoft.com/en-us/azure/ai-services/speech-service/faq-tts |
| Transparency note for TTS | ✅ Verified | https://learn.microsoft.com/en-us/azure/ai-foundry/responsible-ai/speech-service/text-to-speech/transparency-note |
| Language support | ✅ Verified | https://learn.microsoft.com/en-us/azure/ai-services/speech-service/language-support?tabs=tts |
| Speech service pricing | ✅ Verified | https://azure.microsoft.com/pricing/details/cognitive-services/speech-services/ |
| Batch synthesis API | ✅ Verified | https://learn.microsoft.com/en-us/azure/ai-services/speech-service/batch-synthesis |
| Custom neural voice | ✅ Verified | https://learn.microsoft.com/en-us/azure/ai-services/speech-service/custom-neural-voice |
| Personal voice | ✅ Verified | https://learn.microsoft.com/en-us/azure/ai-services/speech-service/personal-voice-overview |
### Code Samples (Verified via MCP)
- C# Speech SDK: https://github.com/Azure-Samples/cognitive-services-speech-sdk
- Batch Synthesis samples: https://github.com/Azure-Samples/Cognitive-Speech-TTS
- Avatar samples: https://github.com/Azure-Samples/cognitive-services-speech-sdk/tree/master/samples/js/browser/avatar
### Confidence per seksjon
| Seksjon | Confidence | Basert på |
|---------|------------|-----------|
| Introduksjon | ✅ Verified | MCP docs_search + docs_fetch |
| Kjernekomponenter | ✅ Verified | MCP docs + code samples |
| Arkitekturmønstre | ⚠️ Baseline + Verified | Patterns fra docs + erfaring |
| Beslutningsveiledning | ⚠️ Baseline | Best practices (ikke eksplisitt i docs) |
| Integrasjon Microsoft-stakken | ✅ Verified (delvis) | Dokumentert for noen, baseline for andre |
| Offentlig sektor (Norge) | ⚠️ Baseline | GDPR/AI Act-vurdering ikke i MS docs |
| Kostnad og lisensiering | ✅ Verified | Pricing docs + examples |
| For arkitekten | ⚠️ Baseline | Praktisk erfaring, ikke dokumentert i MCP |
**Totalt antall MCP-kall:** 7 (4 × docs_search, 3 × docs_fetch, 1 × code_sample_search)
**Unike kilder:** 10+ Microsoft Learn-artikler

397
plugins/ms-ai-architect/skills/ms-ai-engineering/references/azure-ai-services/translator-custom-neural-models.md Normal file
View file

@ -0,0 +1,397 @@
# Translator Service - Custom Neural Translation Models
**Last updated:** 2026-02
**Status:** GA
**Category:** Azure AI Services (Foundry Tools)
---
## Introduksjon
Custom Translator er en feature i Azure Translator som lar organisasjoner bygge skreddersydde Neural Machine Translation (NMT)-systemer med egne data og terminologi. Tjenesten adresserer et kjerneproblem: generelle oversettelsesmodeller håndterer ikke domene-spesifikk terminologi, bransjespråk eller organisasjonens tone-of-voice tilstrekkelig. Med Custom Translator kan bedrifter trene egne NMT-modeller som forstår deres unike ordforråd, stil og kontekst.
Tilnærmingen er pragmatisk: du laster opp tidligere oversatt materiale (dokumenter, nettsider, manualer), og Custom Translator bruker dette som treningsdata for en neural modell. Systemet støtter automatisk sentence alignment på tvers av dokumenter, håndterer parallelle data på dokumentnivå, og kan supplere med monolingual data for å forbedre kvaliteten. Resultatet er en modell som typisk gir 5-10 BLEU-poeng forbedring sammenlignet med baseline-modellen.
Custom Translator integrerer sømløst med eksisterende applikasjoner via Translator Text API v3. Modellene er tilgjengelige globalt, krever ingen programmeringskunnskap for oppsett, og kan deles med team gjennom workspace-funksjonaliteten. Tjenesten bygger på samme infrastruktur som translator-tjenesten som håndterer milliarder av oversettelser daglig.
## Kjernekomponenter
### Hierarki og organisering
| Komponent | Formål | Multiplisitet |
|-----------|---------|---------------|
| **Workspace** | Isolert arbeidsområde for team-samarbeid | Privat, invitasjonsbasert tilgang |
| **Project** | Container for ett språkpar og én domenekategori | Genererer unik CategoryID for API-bruk |
| **Model** | Trent neural oversettelsessystem for språkpar | Kan ha flere modeller per project (A/B-testing) |
| **Documents** | Training, tuning, testing, og dictionary data | Deles automatisk mellom projects med samme språkpar |
### Document-typer og krav
| Type | Minimum | Anbefalt | Formål |
|------|---------|----------|---------|
| **Training** | 10,000 parallelle setninger | 50,000+ | Lærer modellen terminologi og stil |
| **Tuning** | Auto-generert hvis ikke levert | 2,500 setninger (manuelt valgt) | Optimaliserer parametere og vekter |
| **Testing** | Auto-generert hvis ikke levert | 2,500 setninger | Genererer BLEU-score for kvalitetsmåling |
| **Dictionary (phrase)** | Valgfri | Sparsommelig bruk | Tvinger 100% match (case-sensitive) |
| **Dictionary (sentence)** | Valgfri | Korte domene-spesifikke setninger | Tvinger 100% match (case-insensitive) |
**Viktig:** Dictionary-only training er mulig hvis du ikke har 10,000 parallelle setninger, men gir ingen BLEU-score og lavere fleksibilitet.
### Støttede filformater
```
Parallelle dokumenter:
- Translation Memory: .TMX, .XLIFF, .XLF
- Microsoft: .DOCX, .LCL
- Web: .HTML, .HTM
- Generelt: .TXT (UTF-8/UTF-16), .PDF, .XLSX
- Pre-aligned: .ALIGN (hopper over sentence alignment)
Arkiver:
- .ZIP, .GZ, .TGZ
Navnekonvensjon for ZIP:
{document_name}_{language_code}
Eksempel: contract_en, contract_no
```
### BLEU Score-forståelse
BLEU (Bilingual Evaluation Understudy) måler likheten mellom maskinoversettelse og menneskelig referanse:
| Score | Kvalitet | Tolkning |
|-------|----------|-----------|
| 0-20 | Svak | Grunnleggende forståelse, mange feil |
| 20-40 | Akseptabel | Brukbar oversettelse, krever redigering |
| 40-60 | God | Høy kvalitet, minimal redigering nødvendig |
| 60-80 | Meget god | Nesten identisk med menneskelig oversettelse |
| 80-100 | Eksepsjonell | Praktisk talt perfekt (sjelden oppnåelig) |
**NB:** BLEU-score er kun sammenlignbar hvis testdata, språkpar og MT-engine er identiske.
## Arkitekturmønstre
### Mønster 1: Single-Domain Customization
**Brukstilfelle:** En bedrift har behov for oversettelse av teknisk dokumentasjon innenfor ett spesifikt domene (f.eks. medisinsk utstyr).
**Fordeler:**
- Høy nøyaktighet for domene-spesifikke termer
- Enkel vedlikehold (én modell, ett treningssett)
- Forutsigbar BLEU-score forbedring (5-10 poeng typisk)
**Ulemper:**
- Dårligere kvalitet utenfor treningsdomenet
- Krever minimum 10,000 parallelle setninger
- Må re-trene ved domeneutvidelse
**Egnet for:** Organisasjoner med smalt, godt definert oversettelsesdomene og eksisterende oversettelsesmemory.
---
### Mønster 2: Multi-Domain with Separate Models
**Brukstilfelle:** En stor bedrift trenger oversettelse for flere domener (HR, teknisk, juridisk) med distinkt terminologi.
**Fordeler:**
- Maksimal presisjon per domene
- Unngår terminologi-konflikter mellom domener
- Separate BLEU-scores per domene
- Fleksibel deployment (kun aktiver relevante modeller)
**Ulemper:**
- Høyere driftskostnad (flere modeller å vedlikeholde)
- Mer kompleks data-sourcing (10k+ setninger per domene)
- Applikasjonen må velge korrekt CategoryID basert på kontekst
**Egnet for:** Enterprises med heterogene oversettelseskrav og dedikerte ressurser.
---
### Mønster 3: Dictionary-Only for Low-Resource Scenarios
**Brukstilfelle:** Organisasjonen har kritisk terminologi (produktnavn, akronymer) men mangler 10,000 parallelle setninger.
**Fordeler:**
- Rask trening (minutter vs. timer)
- Garanterer korrekt oversettelse av kritiske termer
- Krever minimalt med data
- Kan kombineres med baseline-modell
**Ulemper:**
- Ingen BLEU-score (kan ikke måle forbedring)
- Ingen kontekstuell læring
- Dictionary må være perfekt alignet (like mange source/target entries)
- Baseline-modellen håndterer resten (kan gi inkonsistent kvalitet)
**Egnet for:** Oppstartsfase, proof-of-concept, eller når kun terminologi-kontroll er nødvendig.
## Beslutningsveiledning
### Når skal du velge Custom Translator?
| Kriterium | Svar | Anbefaling |
|-----------|------|------------|
| Har du 10,000+ parallelle setninger? | Ja | ✅ Full training |
| Har du &lt; 10,000 setninger, men kritisk terminologi? | Ja | ⚠️ Dictionary-only |
| Er baseline-modellen god nok? | Ja | ❌ Ikke bruk Custom Translator |
| Trenger du konsistent tone-of-voice? | Ja | ✅ Custom Translator |
| Er domenet bredt og generelt? | Ja | ❌ Baseline holder sannsynligvis |
| Må du møte compliance-krav for oversettelse? | Ja | ✅ Custom + human-in-loop |
### Vanlige feil å unngå
| Feil | Konsekvens | Løsning |
|------|------------|---------|
| Blande flere domener i én modell | Lav BLEU-score, inkonsistent kvalitet | Split i separate projects/modeller |
| Bruke tuning-data i training-settet | Overfitting, kunstig høy BLEU | Strengt skill mellom data-typer |
| For kort setningslengde i tuning | Mangel på kontekst, dårlig infleksjon | Velg 7-10 ords setninger |
| Dictionary overload | Rigiditet, "maskinaktig" tone | Bruk dictionary sparsomt, la modellen lære |
| Ignorere BLEU baseline | Kan ikke måle forbedring | Sammenlign alltid med baseline BLEU |
### Røde flagg
⛔ **Stopp og revurder hvis:**
- Source og target documents har &gt;10% forskjell i antall setninger (alignment vil feile)
- BLEU-score ikke forbedres etter å ha lagt til mer treningsdata (data-kvalitetsproblem)
- Dictionary-only modellen gir dårligere subjektiv kvalitet enn baseline (dictionary er feil-alignet)
- Training feiler på grunn av Unicode character U+FFFD (encoding corruption)
## Integrasjon med Microsoft-stakken
### Translator Text API v3
Custom Translator-modeller brukes via standard Translator API med `category`-parameter:
```bash
POST https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=de&category={CategoryID}
Headers:
Ocp-Apim-Subscription-Key: {your-key}
Ocp-Apim-Subscription-Region: {region}
Body:
[{"Text": "Your domain-specific text here"}]
```
**CategoryID-format:** `{WorkspaceID}-{ProjectLabel}-{CategoryCode}`
- Eksempel: `a2eb72f9-43a8-46bd-82fa-4693c8b64c3c-TECH`
### Azure AI Foundry Integration
Custom Translator er tilgjengelig i Azure AI Foundry (klassisk portal) for no-code workflows:
- Drag-and-drop document upload
- Visual BLEU-score comparison
- Test-grensesnitt med side-by-side comparison (custom vs. baseline)
- Model deployment management
### Speech Service Integration
Custom Translator-modeller kan brukes for speech translation:
- Koble Custom Translator CategoryID til Azure Speech Service
- Real-time tale-til-tekst-oversettelse med domene-spesifikk terminologi
- Støtter samme språkpar som tekst-oversettelse
### Document Translation
Batch document translation (asynkron) kan bruke custom modeller:
- Preserverer dokumentstruktur og formattering
- Krever Azure Blob Storage for input/output
- Støtter samme CategoryID-parameter som Text API
## Offentlig sektor (Norge)
### GDPR og Datasuverenitet
**Status:** Custom Translator støtter data residency-krav.
| Aspekt | Implementering | Compliance |
|--------|----------------|------------|
| **Data at rest** | Treningsdata lagres i valgt Azure region | ✅ Velg Norway East/West |
| **Data in transit** | TLS 1.2+ encryption | ✅ EU-godkjent |
| **Data retention** | Dokumenter lagres inntil manuell sletting | ⚠️ Må administreres manuelt |
| **Training data privacy** | Private workspaces, ingen cross-tenant leakage | ✅ Workspace-isolering |
| **Model access** | Kun via egne API-nøkler og CategoryID | ✅ Access control via Azure RBAC |
**Schrems II:** Microsoft Translator har EU Data Boundary-sertifisering, men vær oppmerksom på at baseline NMT-modeller er trent på global data. Custom modeller bruker kun din data.
### AI Act (EU 2025)
Custom Translator-systemer kan klassifiseres som **"Limited Risk AI"** hvis brukt til publikumsrettede oversettelser:
- **Transparenskrav:** Brukere må informeres om at innhold er maskinoversatt
- **Human oversight:** Anbefalt for høy-risiko domener (juridisk, medisinsk)
- **Record-keeping:** Dokumenter treningsdata, BLEU-scores, og model-versjoner
**Anbefaling:** Implementer disclaimer ("Oversatt med Microsoft Custom Translator") og log CategoryID per oversettelse.
### Forvaltningsloven § 11b (Bruk av AI i forvaltningen)
| Krav | Custom Translator Compliance |
|------|------------------------------|
| **Dokumentasjon av AI-bruk** | Logger CategoryID, timestamp, og source/target language |
| **Menneskelig kontroll** | Integrer human-in-the-loop review for vedtaksdokumenter |
| **Etterprøvbarhet** | Lagre original + oversatt tekst, samt BLEU-score ved training |
| **Proporsjonalitet** | Bruk kun for ikke-rettslige dokumenter, eller med human review |
## Kostnad og lisensiering
### Prismodell
Custom Translator følger Azure Translator Text API-prisstrukturen:
| Kostnadselement | Måleenhet | Typisk kostnad (NOK, Q1 2026) |
|-----------------|-----------|--------------------------------|
| **Training** | Per setning i treningssett | Engangskostnad ved model-trening |
| **Translation** | Per tegn (S0-tier: per million chars) | Samme som baseline Translator |
| **Storage** | Inkludert (ingen ekstra kostnad) | Workspace og documents |
| **API calls** | Inkludert i translation-kostnad | Ingen separate call-avgifter |
**NB:** Custom modeller koster **like mye per oversettelse** som baseline-modellen. Kostnadsforskjellen ligger i training, ikke inference.
### Training Cost Estimation
Eksempel (10,000 setninger training + 2,500 tuning + 2,500 testing = 15,000 setninger totalt):
- Training time: 2-6 timer (avhenger av data-størrelse)
- Kostnad: Basert på antall setninger sendt til training
- Re-training: Samme kostnad ved hver oppdatering
**Optimaliseringstips:**
1. Start med mindre datasett (10k) for proof-of-concept
2. Ekspander treningsdata kun hvis BLEU-score ikke møter target
3. Re-bruk tuning/testing sets på tvers av training runs (for konsistent sammenligning)
4. Unngå hyppig re-training – batch oppdateringer månedlig/kvartalsvis
### Lisensiering
| Azure Tier | Custom Translator-støtte | Begrensninger |
|------------|--------------------------|---------------|
| **Free (F0)** | ❌ Ikke støttet | Kun baseline-modeller |
| **Standard (S1)** | ✅ Full støtte | Ubegrenset antall workspaces, projects, modeller |
| **Enterprise** | ✅ Full støtte + SLA | Dedikerte resources, prioritert support |
**Language support:** 60+ språkpar (må inkludere engelsk som source eller target). Se [Translator language support](https://learn.microsoft.com/en-us/azure/ai-services/language-support).
## For arkitekten (Cosmo)
### Kritiske spørsmål å stille klienten
1. **Data availability:** "Hvor mye parallell oversettelsesdata har dere tilgjengelig? Kan dere dokumentere at det er minimum 10,000 setninger av god kvalitet?"
2. **Domain scope:** "Er oversettelsesbehovet innenfor ett definert domene (f.eks. teknisk dokumentasjon), eller spenner det over flere heterogene områder (HR, juridisk, marked)?"
3. **Quality metrics:** "Hva er akseptabel BLEU-score for deres use case? Har dere subjektive kvalitetskriterier i tillegg?"
4. **Compliance:** "Er det offentlig sektor-data som krever Norge-residency, eller kan data prosesseres i EU generelt?"
5. **Maintenance budget:** "Hvor ofte vil domene-terminologien endre seg? Har dere ressurser til månedlig/kvartalsvis re-training?"
6. **Integration complexity:** "Skal custom modell brukes på én applikasjon, eller må flere systemer dele CategoryID? Hvordan velges CategoryID dynamisk?"
7. **Fallback strategy:** "Hva skjer hvis custom modellen ikke dekker input-teksten (f.eks. utenfor domenet)? Skal baseline brukes som fallback?"
8. **Human-in-loop:** "For hvilke dokumenttyper kreves human review post-translation? Har dere capacity til dette?"
### Fallgruver ved implementering
| Fallgruve | Symptom | Mitigering |
|-----------|---------|-----------|
| **Undertrained models** | BLEU-score &lt; baseline | Krever mer data, eller data er ikke domene-konsistent |
| **Overfitting** | Høy BLEU på test-set, dårlig real-world performance | Tuning-data var for likt test-data, ikke representativt |
| **Category ID sprawl** | Mange modeller, vanskelig å vedlikeholde | Konsolider domener, bruk project labels kun når nødvendig |
| **Dictionary rigidity** | Oversettelse virker "maskinaktig" | Reduser dictionary-bruk, la NMT lære fra kontekst |
| **Ignored baseline comparison** | Kan ikke bevise ROI | Alltid vis både custom og baseline BLEU i rapporter |
### Anbefalinger per modenhetsnivå
**Modenhet 1 - Startup/Pilot (0-6 måneder):**
- Start med **dictionary-only** hvis &lt;10k setninger tilgjengelig
- Velg **ett enkelt domene** for proof-of-concept
- Bruk Azure AI Foundry no-code portal for rask iterasjon
- Mål: Etablere at custom translation gir målbar forbedring
**Modenhet 2 - Operasjonalisering (6-18 måneder):**
- Bygg **full training models** med 10k+ setninger
- Implementer **separate projects per domene** hvis &gt;2 domener
- Integrer CategoryID-valg i applikasjonslogikk
- Sett opp **monthly re-training** pipeline basert på nytt oversatt materiale
- Mål: Produksjonsklar løsning med dokumentert BLEU-forbedring
**Modenhet 3 - Optimalisering (18+ måneder):**
- A/B-test **multiple models per domene** (varierende treningsdata)
- Implementer **human-in-the-loop review** for kritiske oversettelser
- Automatiser **data-kvalitetskontroll** (sentence alignment validation)
- Integrer med **Azure ML Pipelines** for continuous model improvement
- Mål: Kontinuerlig forbedring, ROI-tracking, compliance-dokumentasjon
### Når skal du foreslå alternativ?
**Bruk Azure OpenAI for oversettelse istedenfor Custom Translator hvis:**
- Klienten har &lt; 10k setninger OG dictionary-only ikke holder
- Oversettelsesbehovet er bredt og ad-hoc (ikke repeterende domene)
- Context-window &gt; 8k tokens kreves for oversettelse
- Zero-shot translation med few-shot prompting holder kvalitet
**Bruk baseline Translator (ingen customization) hvis:**
- BLEU-score forbedring &lt; 5 poeng (ikke verdt training-kostnaden)
- Domene er generelt (nyheter, dagligdags språk)
- Ingen compliance-krav på training-data residency
## Kilder og verifisering
### Microsoft Learn-dokumentasjon (Verified via MCP)
- **Custom Translator Overview**
https://learn.microsoft.com/en-us/azure/ai-services/translator/custom-translator/overview
*Confidence: Verified* — Comprehensive overview av features, NMT-teknologi, og use cases.
- **Training and Modeling Concepts**
https://learn.microsoft.com/en-us/azure/ai-services/translator/custom-translator/concepts/model-training
*Confidence: Verified* — Training, tuning, testing document types, og BLEU-score beregning.
- **Workspace and Project Structure**
https://learn.microsoft.com/en-us/azure/ai-services/translator/custom-translator/concepts/workspace-and-project
*Confidence: Verified* — Workspace isolation, project categories, og CategoryID-bruk.
- **Beginners Guide**
https://learn.microsoft.com/en-us/azure/ai-services/translator/custom-translator/beginners-guide
*Confidence: Verified* — Use-case evaluation, data sourcing, og BLEU-score tolkning.
- **BLEU Score Explained**
https://learn.microsoft.com/en-us/azure/ai-services/translator/custom-translator/concepts/bleu-score
*Confidence: Verified* — BLEU-algoritme, scoring process, og domain-dependency.
- **Document Formats and Naming Convention**
https://learn.microsoft.com/en-us/azure/ai-services/translator/custom-translator/concepts/document-formats-naming-convention
*Confidence: Verified* — Støttede filformater, ZIP-konvensjoner, og dictionary-formater.
- **Translate with Custom Model**
https://learn.microsoft.com/en-us/azure/ai-services/translator/custom-translator/how-to/translate-with-custom-model
*Confidence: Verified* — API-integrasjon, CategoryID-format, og DocumentTranslator app.
### Pricing og Compliance (Baseline Kunnskap)
- **Azure Translator Pricing**
*Confidence: Baseline* — Prisstruktur er dokumentert, men NOK-beløp er estimert basert på EUR conversion.
- **EU AI Act Compliance**
*Confidence: Baseline* — Custom Translator klassifisering og transparenskrav basert på generelle AI Act-prinsipper.
- **Norwegian Public Sector AI Regulations**
*Confidence: Baseline* — Forvaltningsloven § 11b krav er interpolert fra kjente compliance-prinsipper.
### Konfidensnivå per seksjon
| Seksjon | Confidence | Kilde |
|---------|-----------|-------|
| Introduksjon | Verified | Microsoft Learn MCP |
| Kjernekomponenter | Verified | Microsoft Learn MCP |
| Arkitekturmønstre | Baseline | Syntetisert fra dokumentasjon |
| Beslutningsveiledning | Baseline | Best practices fra Microsoft docs |
| Integrasjon med Microsoft-stakken | Verified | API docs via MCP |
| Offentlig sektor (Norge) | Baseline | GDPR/AI Act ekstrapolering |
| Kostnad og lisensiering | Baseline | Prisingsinformasjon (ikke verifisert via MCP) |
| For arkitekten | Baseline | Erfaringsbasert veiledning |
---
**Dokumentet er generert:** 2026-02-03
**MCP-søk utført:** microsoft-learn (7 queries, 4 full fetches)
**Total sources:** 7 unike Microsoft Learn-artikler

389
plugins/ms-ai-architect/skills/ms-ai-engineering/references/azure-ai-services/translator-document-translation.md Normal file
View file

@ -0,0 +1,389 @@
# Translator Service - Document Translation and Multi-language Support
**Last updated:** 2026-02
**Status:** GA (General Availability) + Preview features
**Category:** Azure AI Services (Foundry Tools)
---
## Introduksjon
Azure Translator er en sky-basert neural maskinoversettelsestjeneste som tilbyr både tekst- og dokumentoversettelse på tvers av over 135 språk og dialekter. Tjenesten kombinerer sanntids tekstoversettelse med avansert dokumentoversettelse som bevarer opprinnelig formatering, layout og struktur.
Document Translation-funksjonen støtter to arbeidsmåter: asynkron batch-oversettelse for store volumer og komplekse dokumenter, samt synkron single-file-oversettelse for raske enkeltdokumenter. Begge metodene bygger på samme neural machine translation (NMT)-teknologi som brukes i tusenvis av Microsoft-produkter og -tjenester globalt.
En særlig nyhet (desember 2025) er støtte for bildefilformater i batch-oversettelse — tjenesten kan nå oversette tekst inni bilder (.jpeg, .png, .bmp, .webp) samtidig som den beholder originalens design og layout. Dette eliminerer behovet for forprosessering av bilder til PDF før oversettelse.
## Kjernekomponenter / Nøkkelegenskaper
### Oversettelsesmodi
| Modus | Beskrivelse | Krav | Bruksområde |
|-------|-------------|------|-------------|
| **Asynchronous Batch** | Oversetter flere dokumenter og store filer asynkront | Azure Blob Storage (source + target containers) | Bulk-oversettelse, komplekse dokumenter, arkivering |
| **Synchronous Single-file** | Oversetter én fil og returnerer umiddelbart | Kun Translator-ressurs | Raske oversettelser, sanntidsscenarier |
### Støttede dokumentformater (Batch)
**Produksjonsklare formater:**
- **Office:** `.docx`, `.xlsx`, `.pptx`, `.msg` (Outlook)
- **PDF:** `.pdf` (bruker OCR for scannede dokumenter)
- **Web/Data:** `.html`, `.htm`, `.csv`, `.tsv`, `.mhtml`
- **Markup:** `.md`, `.xlf` (XLIFF — translation standard)
- **Open Source:** `.odt`, `.ods`, `.odp`
- **Bilder (2025-12-01-preview):** `.jpeg`, `.png`, `.bmp`, `.webp` 🆕
**Legacy-konvertering:**
`.doc`, `.xls`, `.ppt` konverteres automatisk til moderne Office-formater (`.docx`, `.xlsx`, `.pptx`) ved oversettelse.
### Nøkkelfunksjoner
| Funksjon | Batch | Sync | Beskrivelse |
|----------|-------|------|-------------|
| **Multi-file translation** | ✅ | ❌ | Oversett hundrevis av filer i én operasjon |
| **Large file support** | ✅ | ❌ | Ingen praktisk størrelsesbegrensning for batch |
| **Preserve layout** | ✅ | ✅ | Bevarer formatering, layout, fonter |
| **Image text translation** | ✅ | ❌ | Oversetter tekst inni bilder (preview) |
| **Custom glossaries** | ✅ | ✅ | Egendefinerte termlister (.csv, .tsv, .xlf) |
| **Custom models** | ✅ | ✅ | Custom Translator-modeller for domener/bransjer |
| **Auto language detect** | ✅ | ✅ | Automatisk språkdeteksjon |
| **Multi-language docs** | ✅ | ❌ | Oversett dokumenter med flere språk i én operasjon |
| **Immediate response** | ❌ | ✅ | Translated dokument returneres direkte i svar |
### Oversettelse av bilder i Word-dokumenter (.docx)
En spesialisert funksjon (API-versjon 2024-11-01-preview) som krever:
- Azure AI Services **multi-service resource** (ikke standalone Translator)
- Enable parameter: `"translateTextWithinImage": true` i `options`-feltet
- Tilleggskostnad basert på Azure Vision-prising
Response inkluderer `totalImageScansSucceeded` og `totalImageScansFailed` for monitorering.
## Arkitekturmønstre
### 1. Batch Translation Pipeline (Anbefalt for volum)
**Arkitektur:**
```
Source Blob Container → Document Translation API → Target Blob Container(s)
↓ ↓ ↓
SAS token Job Monitoring API Translated files
(read/list) (status polling) (write/list)
```
**Fordeler:**
- Skalerer automatisk for store volumer
- Parallell prosessering av flere dokumenter
- Støtter flere målspråk i én batch-jobb
- Asynkron — blokkerer ikke applikasjonen
**Ulemper:**
- Krever Azure Blob Storage (ekstra infrastruktur)
- Mer kompleks autentisering (SAS tokens eller managed identity)
- Lengre tid før resultater er klare
**Bruk når:**
- Du oversetter > 10 dokumenter om gangen
- Filstørrelse > 40 MB
- Batch-prosessering er akseptabelt (ikke sanntid)
- Du trenger å oversette til flere språk samtidig
### 2. Synchronous Single-File Translation (Anbefalt for sanntid)
**Arkitektur:**
```
Client App → POST /translator/document:translate → Translated Document
↓ ↓
Document bytes Inline response
+ Target language
```
**Fordeler:**
- Ingen Azure Blob Storage nødvendig
- Enkel integrering (ett API-kall)
- Umiddelbart resultat
- Lavere kompleksitet
**Ulemper:**
- Kun én fil om gangen
- Kun ett målspråk per request
- Ikke egnet for store filer (timeout-risiko)
**Bruk når:**
- Sanntidsoversettelse i webapp/chatbot
- Enkeltstående dokumenter < 40 MB
- Du trenger rask respons (sekunder, ikke minutter)
- Enkel workflow uten lagring
### 3. Hybrid Pattern: Custom Glossaries + Neural Translation
**Arkitektur:**
```
Neural MT Model + Custom Glossary → Hybrid Output
↓ ↓
General translation Domain-specific terms
```
**Fordeler:**
- Best of both worlds: NMT-kvalitet + terminologikontroll
- Konsistent bruk av fagtermer
- Reduserer post-editing-behov
**Ulemper:**
- Krever vedlikehold av glossary-filer
- Glossary må lastes opp for hver batch-jobb (eller hver target container)
**Bruk når:**
- Juridiske/medisinske/tekniske dokumenter
- Branding/produktnavn må være konsistente
- Compliance krever spesifikke termer
## Beslutningsveiledning
### Hvilken modus skal du velge?
| Kriterium | Batch Translation | Single-file Translation |
|-----------|-------------------|-------------------------|
| **Antall filer** | > 10 samtidig | 1 om gangen |
| **Filstørrelse** | Ubegrenset (praktisk) | < 40 MB |
| **Responstid** | Minutter til timer | Sekunder |
| **Målspråk** | Flere samtidig | Ett om gangen |
| **Infrastruktur** | Blob Storage kreves | Ingen ekstra infrastruktur |
| **Kostnad** | Lavere per tegn ved volum | Høyere per tegn (men enklere) |
### Vanlige feil og røde flagg
| Problem | Årsak | Løsning |
|---------|-------|---------|
| **Job fails: "Can't read source"** | SAS token mangler `read`/`list`-tillatelser | Regenerer SAS med korrekte permissions |
| **Translated file not in target** | SAS token mangler `write`/`list` | Sjekk target container permissions |
| **Translation quality poor** | Feil språkpar, mangler custom model | Spesifiser source language eksplisitt, bruk Custom Translator |
| **Scanned PDF loses formatting** | OCR-teknologien har begrensninger | Bruk digitale PDFs når mulig, ikke scannede |
| **Job stuck in "Running"** | Fil låst med passord/kryptert | Fjern passord/kryptering før opplasting |
| **Image text not translated** | Preview-feature ikke aktivert | Sett `"translateTextWithinImage": true` (kun batch) |
| **Cost higher than expected** | Image translation eller Vision API-kall | Disable image features hvis ikke nødvendig |
### Når skal du IKKE bruke Document Translation?
| Scenario | Hvorfor ikke? | Alternativ |
|----------|---------------|------------|
| **Sanntids chat-oversettelse** | Document Translation er for tekst-blokker, ikke korte meldinger | Text Translation API v3 |
| **Live lydoversettelse** | Ikke for tale | Azure Speech Service Translator |
| **Kun OCR (ingen oversettelse)** | Overkill hvis du bare skal ekstrahere tekst | Azure AI Vision (OCR) |
| **Real-time collaboration (Google Docs-style)** | Document Translation er batch/single-file, ikke live | Bygg custom med Text Translation API |
## Integrasjon med Microsoft-stakken
### Azure AI Foundry
- Document Translation tilgjengelig via **Foundry (classic)** portal — no-code playground
- **Foundry (new)** støtter kun forhåndsdefinerte språk med sample-dokumenter (ikke egne filer)
- Bruk Foundry for prototyping, deretter API for produksjon
### Azure Blob Storage
- **Obligatorisk for batch translation**
- Autentisering via SAS tokens eller Managed Identity
- Lifecycle policies kan automatisk slette gamle oversatte filer (kostnadsoptimalisering)
### Custom Translator
- Tren egne NMT-modeller med parallelle korpus (parallel documents)
- Deploy via Custom Translator-portalen
- Refereres i Document Translation API via `category`-parameter
### Power Automate
- **Translator v3 connector** tilgjengelig for no-code workflows
- Støtter både text og document translation
- Integrer med SharePoint, OneDrive, Outlook for dokumentflyt
### Azure Functions / Logic Apps
- REST API kan wrappes i serverless functions
- Bruk for event-driven oversettelse (f.eks. ny fil i Blob → trigger oversettelse)
### Azure AI Search
- Bruk Document Translation som pre-processing for multilingual search
- Oversett dokumenter før indexing → én index, mange språk
## Offentlig sektor (Norge)
### GDPR og Schrems II
| Aspekt | Implikasjon | Anbefaling |
|--------|-------------|------------|
| **Data residency** | Oversettelse prosesseres i nærmeste Azure-region (Global) eller spesifisert region (Americas, Asia Pacific, Europe) | Velg **Europa**-region for Translator-ressurs (France Central, West Europe) |
| **Data retention** | Microsoft lagrer IKKE brukerdata etter oversettelse | Dokumentert i Transparency Note — trygt for sensitiv data |
| **GDPR Article 28** | Microsoft er data processor | Bruk DPA (Data Processing Agreement) i Azure-kontrakten |
| **Schrems II compliance** | EU Standard Contractual Clauses (SCCs) | Velg EU-region, verifiser SCCs i Azure-avtalen |
### AI Act (EU)
| Krav | Status for Translator | Handling |
|------|----------------------|----------|
| **Transparency** | Brukere må vite at tekst er maskinoversatt | Legg til disclaimer i UI/dokumenter |
| **Human oversight** | High-risk AI krever human-in-the-loop | Implementer post-editing for kritiske dokumenter |
| **Accuracy requirements** | Ikke klassifisert som high-risk (men avhenger av bruksområde) | Valider kvalitet manuelt for juridiske/medisinske dokumenter |
### Forvaltningsloven og offentlig kommunikasjon
- **Språkkrav:** Samisk, kvensk, norsk (bokmål/nynorsk) støttes ikke alle optimalt i Translator
- **Juridisk binding:** Maskinoversatte dokumenter kan ikke erstatte autoriserte oversettelser i rettsprosesser
- **Tilgjengelighetskrav (UU):** Oversatte dokumenter må bevare WCAG 2.1-kompatibilitet — test at PDF/HTML-output er tilgjengelig
### Datasuverenitet
- **Norway-region** finnes ikke for Translator (kun Foundry-hub) — bruk **West Europe** eller **North Europe** for geografisk nærhet
- For ekstra høy sensitivitet: Vurder **Translator Container** (disconnected deployment) for air-gapped miljøer
## Kostnad og lisensiering
### Prismodell (per 2026-02)
| Komponent | Enhet | Prisindikasjon (NOK/USD) |
|-----------|-------|--------------------------|
| **Text Translation** | Per million tegn | ~$10 USD (varierer med region) |
| **Document Translation** | Per million tegn | ~$10 USD (samme som tekst) |
| **Image Translation (preview)** | Per bilde | Beregnes separat (ikke per tegn) |
| **Image text in Word (preview)** | Per bilde-scan | Azure Vision-prising i tillegg |
| **Custom Translator** | Per million tegn (trening + inference) | ~$10-40 USD (avhenger av modell) |
**Volume Discount Plans:** C2, C3, C4, D3 tilgjengelig for store volumer (commitment-basert).
### Optimaliseringstips
1. **Batch over single-file:** Lavere overhead (ett API-kall for mange filer)
2. **Disable image translation hvis ubrukt:** Spar Vision API-kostnader
3. **Cache oversettelser:** Lagre target-dokumenter i Blob Storage, gjenbruk ved duplikater
4. **Filter med prefix/suffix:** Bruk `prefix`-parameteren for å unngå å oversette unødvendige filer
5. **Language auto-detect kun ved nødvendighet:** Spesifiser source language for raskere prosessering og lavere feilrate
6. **Bruk glossaries for konsistens:** Reduserer behov for custom models (dyrere å trene)
### Total Cost of Ownership (TCO)
| Komponent | Batch Translation | Single-file Translation |
|-----------|-------------------|-------------------------|
| **Translator API** | $10/M chars | $10/M chars |
| **Azure Blob Storage** | $0.02/GB/måned + egress | N/A |
| **Compute (hvis Azure Functions)** | ~$0.20/million executions | ~$0.20/million executions |
| **Vision API (images)** | $1-3/1000 images (preview pricing) | N/A |
| **Total for 100M chars** | ~$1000 + Blob (~$5) + Compute (~$50) = **~$1055** | ~$1000 + Compute (~$50) = **~$1050** |
**Menneskelig oversettelse til sammenligning:** $0.10-0.25 per ord = **$10 000-25 000 USD** for samme volum (100M chars ≈ 15M ord).
**ROI:** Translator er ~10-25x billigere enn menneskelig oversettelse for bulk-volum.
## For arkitekten (Cosmo)
### Spørsmål å stille i arkitekturdialog
1. **Volum og frekvens:**
"Hvor mange dokumenter per dag/uke? Er det batch-basert eller kontinuerlig?"
→ Avgjør batch vs. single-file strategi.
2. **Sensitivitet og compliance:**
"Inneholder dokumentene personopplysninger (GDPR), helseopplysninger (HIPAA-ekvivalent), eller klassifisert informasjon?"
→ Vurder EU-region, Translator Container (disconnected), eller on-prem løsning.
3. **Responstidskrav:**
"Må oversettelsen være klar innen sekunder, eller er minutter/timer akseptabelt?"
→ Sanntid → Sync, batch → Async.
4. **Dokumenttyper:**
"Er det strukturerte filer (Word/Excel/PDF) eller ustrukturerte (bilder, scannede PDFs)?"
→ Scannede PDFs krever OCR (lavere kvalitet), bilder krever preview-feature.
5. **Terminologi og domene:**
"Har dere branchespesifikke termer som må oversettes konsistent?"
→ Custom glossaries (enklere) eller Custom Translator (dyrere, bedre kvalitet).
6. **Målspråk:**
"Hvilke språk skal støttes? Er det pivot-språk involvert (f.eks. Swahili → English → Hindi)?"
→ Sjekk [language support matrix](https://learn.microsoft.com/azure/ai-services/translator/language-support) for kvalitet.
7. **Eksisterende infrastruktur:**
"Bruker dere allerede Azure Blob Storage? Har dere managed identities satt opp?"
→ Påvirker autentiseringsstrategi og deployment-hastighet.
8. **Post-editing workflow:**
"Skal oversettelsene gjennomgås av mennesker før publisering?"
→ Planlegg for human-in-the-loop (HITL) — Azure AI Foundry + Custom Translator har review-funksjoner.
### Fallgruver å unngå
| Fallgruve | Konsekvens | Unngå ved å |
|-----------|------------|-------------|
| **Hard-code SAS tokens i kode** | Security breach | Bruk Azure Key Vault + managed identity |
| **Glemme SAS token expiry** | Jobs feiler etter 24 timer | Sett expiry = 7 dager minimum, eller bruk managed identity |
| **Overstyre source language når multi-language** | Dårligere kvalitet | La auto-detect gjøre jobben for mixed-language docs |
| **Bruke Batch for én fil (< 1 MB)** | Overhead med Blob Storage | Bruk Single-file API |
| **Forvente perfekt layout for scannede PDFs** | OCR-teknologien har begrensninger | Bruk digitale PDFs, eller aksepter lavere layout-kvalitet |
| **Ikke teste custom glossaries før prod** | Termer oversettes feil | Test med sample-dokumenter først |
| **Overse rate limits** | 429 Too Many Requests | Implementer exponential backoff retry-logikk |
### Anbefalinger per modenhetsnivå
**Begynner (ingen Translator-erfaring):**
- Start med **Foundry (classic) portal** for manuell testing
- Bruk **Single-file API** for prototyping (enklere enn Blob Storage)
- Test med maksimalt 3 språkpar først
- Les [Transparency Note](https://learn.microsoft.com/azure/ai-foundry/responsible-ai/translator/transparency-note) for å forstå begrensninger
**Middels (har brukt Text Translation API):**
- Migrer til **Batch Translation** for volum > 50 filer/dag
- Implementer **custom glossaries** for domene-termer
- Sett opp **monitoring** med Application Insights (track job failures)
- Bruk **managed identity** i stedet for SAS tokens (bedre security)
**Avansert (produksjon med tusenvis av dokumenter/dag):**
- Tren **Custom Translator-modeller** for spesialiserte domener
- Implementer **Azure Functions event-driven pipeline** (Blob trigger → oversettelse → output)
- Aktiver **image translation** kun for dokumenter som faktisk har bilder (kostnadsoptimalisering)
- Sett opp **geo-replication** av Blob Storage for disaster recovery
- Overvåk **totalCharacterCharged** i response headers for cost tracking
## Kilder og verifisering
### Microsoft Learn-dokumentasjon (Verified via MCP)
1. **Document Translation Overview**
https://learn.microsoft.com/azure/ai-services/translator/document-translation/overview
*Confidence: Verified (2026-02)* — Kjernefeatures, formater, data residency
2. **Use Document Translation APIs Programmatically**
https://learn.microsoft.com/azure/ai-services/translator/document-translation/how-to-guides/use-rest-api-programmatically
*Confidence: Verified (2026-02)* — REST API, batch-oversettelse, SAS tokens, kodeeksempler
3. **Azure Translator Overview**
https://learn.microsoft.com/azure/ai-services/translator/overview
*Confidence: Verified (2026-02)* — Comparison matrix (text vs. document), feature roadmap
4. **Image Translation Preview (December 2025)**
https://learn.microsoft.com/azure/ai-services/translator/document-translation/reference/start-batch-translation#translate-image-files
*Confidence: Verified (2026-02)* — Ny funksjonalitet for bildeformater
5. **Service Limits**
https://learn.microsoft.com/azure/ai-services/translator/service-limits#document-translation
*Confidence: Verified (2026-02)* — Rate limits, request size limits
6. **Translator Transparency Note**
https://learn.microsoft.com/azure/ai-foundry/responsible-ai/translator/transparency-note
*Confidence: Verified (2026-02)* — AI-begrensninger, data privacy, responsible AI
### Konfidensnivå per seksjon
| Seksjon | Konfidens | Kilde |
|---------|-----------|-------|
| Introduksjon | Verified | MCP docs fetch (overview) |
| Kjernekomponenter | Verified | MCP docs fetch (overview + API reference) |
| Arkitekturmønstre | Baseline | Best practices fra MCP docs + modellkunnskap |
| Beslutningsveiledning | Baseline | FAQ + troubleshooting fra MCP docs |
| Integrasjon med Microsoft-stakken | Baseline | Modellkunnskap + MCP docs (connectors) |
| Offentlig sektor | Baseline | GDPR/AI Act-kunnskap + Azure compliance docs (ikke spesifikt i MCP-søk) |
| Kostnad og lisensiering | Baseline | Azure pricing calculator (ikke i MCP-søk, men offentlig info) |
| For arkitekten | Baseline | Syntetisk veiledning basert på features fra MCP docs |
**Total MCP calls:** 4 (docs_search) + 3 (docs_fetch) = **7**
**Unique Microsoft Learn URLs:** 6