Kjell Tore Guttormsen 6a7632146e feat(ms-ai-architect): add plugin to open marketplace (v1.5.0 baseline)

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>

2026-04-07 17:17:17 +02:00

15 KiB

Raw Blame History

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:

<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:

Sikkerhet: API-nøkler hardkodet eller lagret i klientkonfigurasjon. Ingen sentral mekanisme for nøkkelrotasjon.
Pålitelighet: Klientkode må håndtere throttling (429), failover, og retry-logikk. Ingen automatisk load balancing.
Kostnader: Ingen synlighet i token-forbruk per team/avdeling. Umulig å implementere chargeback.
Observerbarhet: Ingen sentral logging. Vanskelig å spore hvem som bruker hva.
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 — Well-Architected Framework gateway-guide
AI gateway in Azure API Management — AI gateway-kapabiliteter
Architecture best practices for Azure API Management — WAF-guide for APIM
Use a gateway in front of multiple Azure OpenAI deployments — Multi-backend arkitekturmønstre
Scale OpenAI for Python 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.

15 KiB Raw Blame History Unescape Escape