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

Add /ultraresearch-local for structured research combining local codebase analysis with external knowledge via parallel agent swarms. Produces research briefs with triangulation, confidence ratings, and source quality assessment. New command: /ultraresearch-local with modes --quick, --local, --external, --fg. New agents: research-orchestrator (opus), docs-researcher, community-researcher, security-researcher, contrarian-researcher, gemini-bridge (all sonnet). New template: research-brief-template.md. Integration: --research flag in /ultraplan-local accepts pre-built research briefs (up to 3), enriches the interview and exploration phases. Planning orchestrator cross-references brief findings during synthesis. Design principle: Context Engineering — right information to right agent at right time. Research briefs are structured artifacts in the pipeline: ultraresearch → brief → ultraplan --research → plan → ultraexecute. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-04-08 08:58:35 +02:00 · 2026-04-08 08:58:35 +02:00 · baa2d0220b
commit baa2d0220b
488 changed files with 213221 additions and 0 deletions
--- a/skills/ms-ai-engineering/references/api-management/apim-vs-direct-access-comparison.md
+++ b/skills/ms-ai-engineering/references/api-management/apim-vs-direct-access-comparison.md
@ -0,0 +1,399 @@
+# APIM vs Direct Access: Trade-offs & Decision Matrix
+
+**Last updated:** 2026-02
+**Status:** GA
+**Category:** API Management & AI Gateway
+
+---
+
+## Introduksjon
+
+En av de første arkitekturbeslutningene ved implementering av Azure OpenAI er om applikasjoner skal koble seg direkte til Azure OpenAI-endepunktene, eller om trafikken skal gå gjennom en gateway som Azure API Management. Svaret avhenger av organisasjonens størrelse, sikkerhetskrav, antall applikasjoner og modelldeployments, samt behovet for sentral styring og observerbarhet.
+
+For norsk offentlig sektor, der sikkerhet, governance, transparens og kostnadseffektivitet er sentrale verdier, er gateway-tilnærmingen typisk å foretrekke. Men for enklere piloter og enkelt-applikasjon-scenarier kan direkte tilgang være tilstrekkelig. Denne referansen gir en systematisk sammenligning for å hjelpe med beslutningen.
+
+Azure Well-Architected Framework identifiserer utfordringer ved direkte tilgang på tvers av alle fem pilarer: sikkerhet, pålitelighet, ytelse, kostnadseffektivitet og operasjonell dyktighet. En gateway adresserer de fleste av disse, men introduserer også ny kompleksitet og kostnader. Riktig valg krever en helhetsvurdering.
+
+---
+
+## Gateway Overhead Analysis
+
+### Latensoverhead
+
+APIM legger til en liten latens for policy-kjøring og nettverkshopping:
+
+| Scenario | Direkte tilgang | Via APIM | Overhead |
+|----------|----------------|----------|----------|
+| Enkel chat completion | ~200ms | ~210-230ms | +10-30ms |
+| Med autentisering + rate limiting | N/A | ~220-250ms | +20-50ms |
+| Med content safety | N/A | ~300-500ms | +100-300ms |
+| Med semantic caching (hit) | ~200ms | ~50-100ms | -100-150ms (raskere!) |
+| Streaming (time-to-first-token) | ~100ms | ~110-130ms | +10-30ms |
+
+**Merk:** Semantic caching kan redusere latens betydelig ved gjentatte lignende spørsmål.
+
+### Throughput
+
+| APIM Tier | Scale Units | Estimert RPS | Kostnad/mnd (NOK) |
+|-----------|------------|-------------|-------------------|
+| Standard v2 | 1 | ~1000 | ~2,500 |
+| Premium | 1 | ~2500 | ~25,000 |
+| Premium | 2 (multi-region) | ~5000 | ~50,000 |
+
+### Ressursforbruk
+
+| Ressurs | Direkte | Via APIM |
+|---------|---------|----------|
+| Nettverkshopp | 1 (klient→AOAI) | 2 (klient→APIM→AOAI) |
+| DNS-oppslag | 1 | 2 |
+| TLS-handshake | 1 | 2 (med connection pooling: ~1.1) |
+| CPU (gateway) | 0 | APIM policy-kjøring |
+| Minne | 0 | APIM caching, policy state |
+
+---
+
+## Security Posture Comparison
+
+### Sikkerhetsfunksjoner
+
+| Sikkerhetsfunksjon | Direkte tilgang | Via APIM |
+|-------------------|----------------|----------|
+| API-nøkkelhåndtering | Klient har nøkkel | Nøkkel skjult i APIM |
+| Managed identity | Klient trenger MI | APIM MI (sentralisert) |
+| OAuth 2.0 validering | Custom kode | Innebygd policy |
+| Rate limiting | Kun AOAI-kvoter | Granulær per bruker/app |
+| IP-filtrering | NSG/Firewall | APIM policy + NSG |
+| Content Safety | Custom integrasjon | Innebygd policy |
+| Prompt Shield | Custom integrasjon | Innebygd policy |
+| mTLS | Custom oppsett | Innebygd støtte |
+| Audit logging | Custom logging | Innebygd diagnostikk |
+| Key rotation | Manuell per app | Sentralisert via Key Vault |
+
+### Angrepsflate
+
+```
+Direkte tilgang:
+  Klient ←→ Azure OpenAI
+  - API-nøkkel eksponert i klientkonfigurasjon
+  - Ingen sentral policy-håndhevelse
+  - Vanskelig å rotere nøkler på tvers av applikasjoner
+  - Ingen prompt-validering
+
+Via APIM:
+  Klient ←→ APIM Gateway ←→ Azure OpenAI
+  - API-nøkkel kun i APIM (eller managed identity)
+  - Sentral autentisering og autorisering
+  - Enkel nøkkelrotasjon
+  - Content Safety og Prompt Shield integrert
+  - Full audit trail
+```
+
+### NSM Grunnprinsipper-mapping
+
+| NSM Prinsipp | Direkte | APIM |
+|-------------|---------|------|
+| Identifisere og kartlegge | Manuell per app | Sentralt API-register |
+| Beskytte og opprettholde | Per-app sikkerhet | Sentrale policyer |
+| Oppdage | Custom logging | Innebygd observerbarhet |
+| Håndtere og gjenopprette | Per-app | Sentralt med circuit breaker |
+
+---
+
+## Governance Requirements
+
+### Governance-kapabiliteter
+
+| Kapabilitet | Direkte tilgang | Via APIM |
+|------------|----------------|----------|
+| API-versjonering | Manuelt per app | Sentralisert |
+| Policy enforcement | Ingen | Innebygd |
+| Token-kvoter per team | Ikke mulig | llm-token-limit policy |
+| Modell-tilgangskontroll | RBAC per AOAI | APIM Products + subscriptions |
+| Usage tracking | AOAI-metriker | Detaljerte APIM-metriker |
+| Chargeback | Ikke mulig | Innebygde dimensjoner |
+| Compliance reporting | Custom | Innebygd dashboard |
+| Developer portal | Ikke aktuelt | Innebygd self-service |
+
+### Governance-scenario: Multi-Team AI Platform
+
+```
+Uten APIM:
+  Team A → AOAI Endpoint 1 (egne nøkler, egen logging)
+  Team B → AOAI Endpoint 1 (egne nøkler, egen logging)
+  Team C → AOAI Endpoint 2 (egne nøkler, egen logging)
+  → Ingen sentral oversikt, ingen policy-kontroll
+
+Med APIM:
+  Team A → APIM (Subscription A, Product: AI-Standard)
+  Team B → APIM (Subscription B, Product: AI-Premium)
+  Team C → APIM (Subscription C, Product: AI-Standard)
+  → Sentral token-kvote, logging, chargeback, content safety
+```
+
+---
+
+## Cost per Request
+
+### Total Cost of Ownership
+
+| Kostnadspost | Direkte | Via APIM (Standard v2) | Via APIM (Premium) |
+|-------------|---------|----------------------|-------------------|
+| APIM-infrastruktur | 0 | ~2,500 NOK/mnd | ~25,000 NOK/mnd |
+| Azure OpenAI tokens | Samme | Samme | Samme |
+| Utviklingskostnad | Høy (per app) | Lav (sentral) | Lav (sentral) |
+| Drift og vedlikehold | Høy (per app) | Lav (sentral) | Lav (sentral) |
+| Sikkerhetsimplementasjon | Per app | Inkludert | Inkludert |
+| Logging-infrastruktur | Custom | Inkludert | Inkludert |
+| Nøkkelrotasjon | Manuell | Automatisert | Automatisert |
+
+### Break-even Analyse
+
+```
+APIM Standard v2 kost: ~2,500 NOK/mnd
+
+Estimert besparelse per applikasjon:
+  - Eliminert custom auth-kode: ~2,000 NOK/mnd (drift)
+  - Eliminert custom logging: ~1,000 NOK/mnd (drift)
+  - Redusert sikkerhetsinnsats: ~1,500 NOK/mnd
+  - Semantic caching token-besparelse: variabel
+
+Break-even: ~1 applikasjon for Standard v2
+            ~6 applikasjoner for Premium
+```
+
+### Kostnad ved Semantic Caching
+
+Semantic caching kan redusere Azure OpenAI-kostnader betydelig:
+
+| Cache Hit Rate | Token-besparelse | Typisk ROI |
+|---------------|-----------------|-----------|
+| 10% | ~10% reduksjon | Moderat |
+| 30% | ~30% reduksjon | God |
+| 50%+ | ~50%+ reduksjon | Utmerket |
+
+**Eksempel:** 1M tokens/dag × 0.10 NOK/1K tokens = 100 NOK/dag.
+Med 30% cache hit: 70 NOK/dag → ~900 NOK besparelse/mnd (dekker Standard v2-kostnad).
+
+---
+
+## Organizational Scale Factors
+
+### Decision Matrix
+
+| Faktor | Score: Direkte | Score: APIM | Vekt |
+|--------|---------------|-------------|------|
+| 1 applikasjon | 5 | 2 | Høy |
+| 2-5 applikasjoner | 3 | 4 | Høy |
+| 6+ applikasjoner | 1 | 5 | Høy |
+| Sikkerhetskrav (standard) | 3 | 4 | Medium |
+| Sikkerhetskrav (strengt) | 1 | 5 | Høy |
+| Chargeback-behov | 0 | 5 | Medium |
+| Multi-team | 1 | 5 | Høy |
+| Content Safety-krav | 1 | 5 | Høy |
+| Enkel pilot/POC | 5 | 2 | Lav |
+| Produksjon | 2 | 5 | Høy |
+| Compliance-rapportering | 1 | 5 | Medium |
+
+**Scoring:** 1 = Dårlig egnet, 5 = Svært godt egnet
+
+### Beslutningstre
+
+```
+Spørsmål 1: Kun én applikasjon med lav trafikk?
+  JA → Spørsmål 2: Strenge sikkerhetskrav (offentlig sektor)?
+    JA → APIM (sikkerhet trumfer enkelhet)
+    NEI → Direkte tilgang (POC/pilot)
+
+  NEI → Spørsmål 3: Flere team/avdelinger deler AI?
+    JA → APIM Premium (governance, chargeback)
+    NEI → Spørsmål 4: Behov for multi-region eller failover?
+      JA → APIM Premium (multi-region)
+      NEI → APIM Standard v2 (sentral gateway)
+```
+
+### Anbefaling per Organisasjonstype
+
+| Organisasjon | Anbefaling | Tier | Begrunnelse |
+|-------------|-----------|------|------------|
+| Enkelt team, pilot | Direkte tilgang | N/A | Minst friksjon |
+| Enkelt team, produksjon | APIM Standard v2 | Standard v2 | Sikkerhet + logging |
+| Flere team, felles AI | APIM Premium | Premium | Governance + chargeback |
+| Offentlig sektor, produksjon | APIM Premium | Premium | Compliance + multi-region |
+| Enterprise, multi-region | APIM Premium | Premium | Full kapabilitet |
+
+---
+
+## Migrasjonsvei: Direkte → APIM
+
+### Gradvis Migrasjon
+
+```
+Fase 1: Deploy APIM med proxy-modus
+  - Import AOAI API til APIM
+  - Konfigurer managed identity
+  - APIM viderekobler til eksisterende AOAI
+  - Ingen endring i AOAI-konfigurasjon
+
+Fase 2: Omdirigér applikasjoner
+  - Oppdater endepunkt fra AOAI → APIM
+  - Legg til subscription key
+  - Test per applikasjon
+  - Gradvis utrulling
+
+Fase 3: Aktiver APIM-policyer
+  - Rate limiting
+  - Authentication (OAuth 2.0)
+  - Token-metriker
+  - Content Safety
+
+Fase 4: Fjern direkte tilgang
+  - Fjern public endpoint på AOAI
+  - Konfigurer private endpoints
+  - APIM som eneste inngang
+```
+
+### Minimal-Endring Policy
+
+For å starte med minimal påvirkning på eksisterende applikasjoner:
+
+```xml
+<policies>
+    <inbound>
+        <base />
+        <!-- Pass-through: Videresend API-nøkkel fra klient -->
+        <set-backend-service backend-id="aoai-backend" />
+    </inbound>
+    <backend>
+        <forward-request buffer-response="false" />
+    </backend>
+    <outbound>
+        <base />
+        <!-- Start med kun logging -->
+        <llm-emit-token-metric namespace="ai-metrics">
+            <dimension name="API" value="@(context.Api.Name)" />
+            <dimension name="Subscription" value="@(context.Subscription.Name)" />
+        </llm-emit-token-metric>
+    </outbound>
+</policies>
+```
+
+---
+
+## Hybrid-tilnærminger
+
+### APIM for Governance + Direkte for Latens-kritisk
+
+```
+Batch-operasjoner → APIM → Azure OpenAI (full policy-stack)
+Real-time chatbot → APIM → Azure OpenAI (minimal policy)
+Embedding-pipeline → Direkte → Azure OpenAI (ingen gateway)
+```
+
+### Global Standard + APIM
+
+Azure OpenAI Global Standard deployment med APIM for governance:
+
+```
+APIM håndterer: Autentisering, rate limiting, logging
+AOAI håndterer: Global routing, kapasitetsallokering
+```
+
+**Merk:** Global Standard deployments ruter automatisk til regioner med kapasitet — dette er en annen form for load balancing enn APIM backend pools.
+
+---
+
+## Well-Architected Framework Perspektiv
+
+### Sammenligning per WAF-pilar
+
+| WAF-pilar | Direkte tilgang | Via APIM |
+|-----------|----------------|----------|
+| **Reliability** | Failover må implementeres i klientkode | Innebygd backend pools, circuit breaker, multi-region |
+| **Security** | API-nøkler i klientkonfig, ingen sentral policy | Managed identity, OAuth, Content Safety, sentral policy |
+| **Cost Optimization** | Ingen synlighet i forbruk per team | Token-metriker, chargeback, semantic caching |
+| **Operational Excellence** | Logging per applikasjon | Sentralisert diagnostikk, innebygd dashboard |
+| **Performance Efficiency** | Ingen caching-lag | Semantic caching, regional routing |
+
+### Utfordringer ved Direkte Tilgang (fra Azure Architecture Center)
+
+Microsoft identifiserer følgende utfordringer ved direkte tilgang:
+
+1. **Sikkerhet**: API-nøkler hardkodet eller lagret i klientkonfigurasjon. Ingen sentral mekanisme for nøkkelrotasjon.
+2. **Pålitelighet**: Klientkode må håndtere throttling (429), failover, og retry-logikk. Ingen automatisk load balancing.
+3. **Kostnader**: Ingen synlighet i token-forbruk per team/avdeling. Umulig å implementere chargeback.
+4. **Observerbarhet**: Ingen sentral logging. Vanskelig å spore hvem som bruker hva.
+5. **Governance**: Ingen policy-håndhevelse. Klienter kan sende vilkårlig innhold til modellen.
+
+### Scenario-vurdering
+
+**Scenario 1: Intern chatbot for én avdeling**
+```
+Direkte tilgang: Akseptabelt for POC
+APIM: Anbefalt for produksjon (logging, content safety)
+Vurdering: Start direkte, migrer til APIM før prod
+```
+
+**Scenario 2: AI-plattform for hele organisasjonen**
+```
+Direkte tilgang: Ikke anbefalt (ingen governance)
+APIM: Obligatorisk (chargeback, rate limiting, content safety)
+Vurdering: APIM Premium fra start
+```
+
+**Scenario 3: RAG-pipeline (batch-orientert)**
+```
+Direkte tilgang: Akseptabelt (lav latens-krav, enkel arkitektur)
+APIM: Valgfritt (logging og rate limiting er nyttig)
+Vurdering: Vurder basert på compliance-krav
+```
+
+**Scenario 4: Multi-region med DR-krav**
+```
+Direkte tilgang: Svært kompleks (klientbasert failover)
+APIM: Sterkt anbefalt (innebygd multi-region, FQDN routing)
+Vurdering: APIM Premium med multi-region deployment
+```
+
+### Når Direkte Tilgang er Riktig
+
+Direkte tilgang kan være riktig valg i følgende scenarier:
+
+| Scenario | Begrunnelse |
+|----------|-------------|
+| POC/Prototype (< 1 mnd) | Minst mulig overhead |
+| Enkeltapplikasjon, lavt volum | Gateway-overhead urettferdiggjort |
+| Embedding-pipeline (intern batch) | Ingen brukerinteraksjon, lav risiko |
+| Dev/test-miljø | Unødvendig å gateway-beskytte testdata |
+| Global Standard deployment | Innebygd global routing, begrenset APIM-verdi |
+
+### Når APIM er Obligatorisk
+
+APIM bør alltid brukes i følgende scenarier:
+
+| Scenario | Begrunnelse |
+|----------|-------------|
+| Offentlig sektor (produksjon) | Compliance, audit, content safety |
+| Multi-team AI-plattform | Governance, chargeback, rate limiting |
+| Brukervendte AI-tjenester | Content Safety, prompt shield |
+| Multi-region deployment | Failover, latency routing |
+| SLA-krav > 99.9% | Multi-region, circuit breaker |
+
+---
+
+## Referanser
+
+- [Access Azure OpenAI and other language models through a gateway](https://learn.microsoft.com/en-us/azure/architecture/ai-ml/guide/azure-openai-gateway-guide) — Well-Architected Framework gateway-guide
+- [AI gateway in Azure API Management](https://learn.microsoft.com/en-us/azure/api-management/genai-gateway-capabilities) — AI gateway-kapabiliteter
+- [Architecture best practices for Azure API Management](https://learn.microsoft.com/en-us/azure/well-architected/service-guides/azure-api-management) — WAF-guide for APIM
+- [Use a gateway in front of multiple Azure OpenAI deployments](https://learn.microsoft.com/en-us/azure/architecture/ai-ml/guide/azure-openai-gateway-multi-backend) — Multi-backend arkitekturmønstre
+- [Scale OpenAI for Python with Azure API Management](https://learn.microsoft.com/en-us/azure/developer/python/get-started-app-chat-scaling-with-azure-api-management) — Praktisk implementasjonsguide
+
+---
+
+## For Cosmo
+
+- **Bruk denne referansen** når kunder spør om de trenger APIM eller kan koble direkte til Azure OpenAI. Beslutningsmatrisen gir et strukturert svar.
+- Tommelfingerregel: Hvis kunden har mer enn én applikasjon ELLER strenge sikkerhetskrav (som offentlig sektor typisk har) → anbefal APIM.
+- For POC og piloter: Direkte tilgang er OK, men planlegg for gateway fra start — refaktorering fra direkte til APIM er arbeid som kan unngås.
+- Husk at APIM med semantic caching kan faktisk redusere total kostnad og latens — gateway er ikke bare overhead, det er også ytelsesoptimalisering.
+- For norsk offentlig sektor er APIM nesten alltid riktig valg: compliance, audit logging, content safety og chargeback er typisk påkrevd.