ms-ai-architect/skills/ms-ai-engineering/references/api-management/apim-ai-gateway-overview.md

# APIM as AI Gateway: Architecture & Concepts

**Last updated:** 2026-02
**Status:** GA
**Category:** API Management & AI Gateway
**Type:** reference
**Source:** https://learn.microsoft.com/azure/api-management/genai-gateway-capabilities

---

## Innhold

- [Introduksjon](#introduksjon)
- [Kjernekonsepter i Azure API Management](#kjernekonsepter-i-azure-api-management)
- [AI Gateway-kapabiliteter](#ai-gateway-kapabiliteter)
- [Arkitekturmønstre for AI Gateway](#arkitekturmønstre-for-ai-gateway)
- [Governance og organisatorisk styring](#governance-og-organisatorisk-styring)
- [Bicep-deployment: AI Gateway](#bicep-deployment-ai-gateway)
- [Policy-pipeline for AI Gateway](#policy-pipeline-for-ai-gateway)
- [Relevante referansearkitekturer](#relevante-referansearkitekturer)
- [Hensyn for norsk offentlig sektor](#hensyn-for-norsk-offentlig-sektor)
- [For Cosmo](#for-cosmo)

## Introduksjon

Azure API Management (APIM) har utviklet seg fra en tradisjonell API-gateway til en fullverdig AI-gateway som gir organisasjoner sentral kontroll over alle generative AI-tjenester. For norsk offentlig sektor, der mange etater deler Azure OpenAI-instanser på tvers av avdelinger og prosjekter, er APIM den anbefalte tilnærmingen for å sikre styring, kostnadsfordeling og sikkerhet.

APIM som AI-gateway kombinerer tradisjonelle API Management-funksjoner (autentisering, rate limiting, logging) med spesialiserte AI-kapabiliteter som token-basert kvoteregulering, semantisk caching, multi-modell backend routing og innholdssikkerhet. Microsoft anbefaler APIM som den foretrukne PaaS-løsningen for å bygge og drifte en AI-gateway, fremfor egenutviklede løsninger.

I en typisk enterprise-arkitektur sitter APIM mellom klientapplikasjoner (chatbots, agentrammeverk, RAG-pipelines) og backend AI-tjenester (Azure OpenAI, Microsoft Foundry, tredjepartsmodeller). Dette gir ett enkelt endepunkt for alle konsumenter, uavhengig av hvor mange backend-instanser som finnes bak gatewayen.

---

## Kjernekonsepter i Azure API Management

### APIM-arkitektur

Azure API Management består av tre hovedkomponenter:

| Komponent | Rolle | Beskrivelse |
|-----------|-------|-------------|
| **API Gateway** | Data plane / runtime | Mottar API-kall, håndhever policies, videresender til backends |
| **Management Plane** | Kontrollplan | Konfigurering av APIs, policies, backends, produkter |
| **Developer Portal** | Selvbetjening | API-dokumentasjon, testing, onboarding av utviklere |

### APIM Service Tiers for AI

| Tier | AI Gateway-støtte | Circuit Breaker | Semantic Caching | Token Policies | Anbefaling |
|------|-------------------|-----------------|-------------------|----------------|------------|
| **Consumption** | Begrenset | Nei | Ja | Nei (ingen token limit by key) | Ikke anbefalt for AI |
| **Developer** | Full | Ja | Ja | Ja | Dev/test |
| **Basic v2** | Full | Ja | Ja | Ja | Små workloads |
| **Standard v2** | Full | Ja | Ja | Ja | Produksjon |
| **Premium** | Full + multi-region | Ja | Ja | Ja | Enterprise / offentlig sektor |

**Anbefaling for norsk offentlig sektor:** Standard v2 eller Premium, avhengig av krav til multi-region og VNet-integrasjon.

---

## AI Gateway-kapabiliteter

APIM tilbyr fem hovedkategorier av AI-spesifikke funksjoner:

### 1. Token Rate Limiting og Kvoter

Kontroller token-forbruk per konsument med dedikerte policies:

```xml
<!-- Begrens tokens per minutt per subscription -->
<llm-token-limit
    counter-key="@(context.Subscription.Id)"
    tokens-per-minute="10000"
    estimate-prompt-tokens="true"
    remaining-tokens-variable-name="remainingTokens">
</llm-token-limit>
```

Policies for Azure OpenAI-spesifikke og generelle LLM-scenarier:

| Policy | Scope | Beskrivelse |
|--------|-------|-------------|
| `azure-openai-token-limit` | Azure OpenAI | Token-begrensning spesifikt for Azure OpenAI-endepunkter |
| `llm-token-limit` | Alle LLM-er | Generell token-begrensning for alle LLM APIs |
| `azure-openai-emit-token-metric` | Azure OpenAI | Emit token-metrikk til Application Insights |
| `llm-emit-token-metric` | Alle LLM-er | Generell token-metrikk for alle LLM APIs |

### 2. Load Balancing

Backend pools med round-robin, weighted og priority-basert lastbalansering:

```xml
<!-- Rut trafikk til backend pool -->
<set-backend-service backend-id="openai-pool" />
```

Load balancing-alternativer:

| Modus | Beskrivelse | Typisk bruk |
|-------|-------------|-------------|
| **Round-robin** | Jevn fordeling mellom backends | Standard, like instanser |
| **Weighted** | Vektet fordeling basert på kapasitet | Blue-green deployments |
| **Priority-based** | Prioritetsgrupper, fallback ved feil | PTU + Pay-as-you-go spillover |
| **Session-aware** | Sesjonsaffinitet via cookie | Chat-assistenter, Assistants API |

### 3. Circuit Breaker

Beskytter backend-tjenester mot overbelastning med automatisk feilhåndtering:

| Egenskap | Beskrivelse |
|----------|-------------|
| **Failure threshold** | Antall feil som utløser circuit breaker |
| **Trip duration** | Varighet circuit breaker er åpen |
| **Retry-After header** | Dynamisk trip duration basert på backend-respons |
| **Status code range** | Hvilke HTTP-koder som teller som feil (f.eks. 429, 5xx) |

### 4. Semantic Caching

Gjenbruk av LLM-svar basert på semantisk likhet:

```xml
<!-- Inbound: Sjekk cache -->
<azure-openai-semantic-cache-lookup
    score-threshold="0.15"
    embeddings-backend-id="embeddings-backend"
    embeddings-backend-auth="system-assigned"
    ignore-system-messages="true"
    max-message-count="10">
    <vary-by>@(context.Subscription.Id)</vary-by>
</azure-openai-semantic-cache-lookup>

<!-- Outbound: Lagre i cache -->
<azure-openai-semantic-cache-store duration="3600" />
```

**Krav:** Azure Managed Redis med RediSearch-modul.

### 5. Sikkerhet og Content Safety

| Funksjon | Policy/Mekanisme | Beskrivelse |
|----------|-------------------|-------------|
| **Autentisering** | Managed Identity | Eliminerer API-nøkler, bruker system- eller user-assigned identity |
| **Content Safety** | `llm-content-safety` | Automatisk moderering via Azure AI Content Safety |
| **OAuth** | Credential Manager | OAuth-autorisasjon for AI-apper og agenter |
| **MCP-sikkerhet** | Secure MCP servers | Sikrer tilgang til MCP-servere via APIM |

---

## Arkitekturmønstre for AI Gateway

### Mønster 1: Sentralisert AI Gateway (anbefalt)

```
                        ┌─────────────────────┐
                        │   Azure API Mgmt    │
                        │   (AI Gateway)      │
  Chatbot ─────────────►│                     │──► Azure OpenAI (Norway East)
  RAG Pipeline ────────►│  - Token limiting   │──► Azure OpenAI (Sweden Central)
  Copilot Studio ─────►│  - Load balancing   │──► Microsoft Foundry
  Power Automate ─────►│  - Circuit breaker  │──► Third-party LLMs
                        │  - Caching          │
                        │  - Content safety   │
                        └─────────────────────┘
                                 │
                          ┌──────┴──────┐
                          │  Monitoring  │
                          │  App Insights│
                          │  Log Analyt. │
                          └─────────────┘
```

**Fordeler:**
- Ett endepunkt for alle konsumenter
- Sentralisert styring og kostnadskontroll
- Konsistent sikkerhetspolitikk
- Full observabilitet av token-forbruk

### Mønster 2: Multi-Region AI Gateway

```
  Client ──► DNS/Traffic Manager
                    │
           ┌────────┴────────┐
           ▼                 ▼
  APIM Gateway          APIM Gateway
  (Norway East)         (Sweden Central)
       │                     │
       ▼                     ▼
  Azure OpenAI          Azure OpenAI
  (Norway East)         (Sweden Central)
```

For norsk offentlig sektor med krav til datasuverenitet:
- Deploy APIM Premium med multi-region
- Regionalt avgrensede backends via policy-logikk
- Innebygd FQDN-routing basert på laveste latens

### Mønster 3: Hub-and-Spoke for offentlig sektor

```
              Central IT (Hub)
        ┌──────────────────────────┐
        │  APIM (Premium)          │
        │  - Sentral policy        │
        │  - Kostnadsallokering    │
        │  - Compliance monitoring │
        └──────┬───────┬───────────┘
               │       │
    ┌──────────┘       └──────────┐
    ▼                             ▼
  Etat A (Spoke)            Etat B (Spoke)
  - Subscription A          - Subscription B
  - TPM: 50 000             - TPM: 30 000
  - Egne produkter          - Egne produkter
```

---

## Governance og organisatorisk styring

### Kostnadsfordeling med APIM

APIM muliggjør presis kostnadsfordeling gjennom:

| Mekanisme | Hvordan | Eksempel |
|-----------|---------|---------|
| **Subscription keys** | Hvert team/prosjekt får egen subscription | Team A: 50k TPM, Team B: 30k TPM |
| **Products** | Grupperer APIer med ulike kvoter | "Standard AI" (10k TPM), "Premium AI" (100k TPM) |
| **Custom headers** | Spor forbruk per bruker/applikasjon | `x-cost-center: 12345` |
| **Token metrics** | Emit til Application Insights per dimensjon | Dashboard per team, API, bruker |

### Eksempel: Token-metrikk med dimensjoner

```xml
<llm-emit-token-metric namespace="ai-gateway-metrics">
    <dimension name="Etat" value="@(context.Request.Headers.GetValueOrDefault("x-etat", "ukjent"))" />
    <dimension name="Prosjekt" value="@(context.Request.Headers.GetValueOrDefault("x-prosjekt", "ukjent"))" />
    <dimension name="API" value="@(context.Api.Id)" />
    <dimension name="Modell" value="@(context.Request.Headers.GetValueOrDefault("x-model-id", "default"))" />
</llm-emit-token-metric>
```

### Observabilitet

APIM integreres med Azure Monitor for full oversikt:

| Datakilde | Hva den gir | Verktøy |
|-----------|-------------|---------|
| **Token metrics** | TPM/RPM per konsument, API, modell | Application Insights, Azure Monitor |
| **Request logs** | Prompts, completions, latens | App Insights, Log Analytics |
| **Built-in dashboard** | Visuell oversikt over AI API-forbruk | APIM portal |
| **Custom alerts** | Varsling ved kvote-overskridelse | Azure Monitor Alerts |

---

## Bicep-deployment: AI Gateway

### Grunnleggende APIM-instans for AI Gateway

```bicep
@description('Azure API Management instance for AI Gateway')
resource apim 'Microsoft.ApiManagement/service@2023-09-01-preview' = {
  name: 'apim-ai-gateway-${environment}'
  location: location
  sku: {
    name: 'StandardV2'
    capacity: 1
  }
  identity: {
    type: 'SystemAssigned'
  }
  properties: {
    publisherEmail: 'admin@example.no'
    publisherName: 'Statens AI Gateway'
  }
}
```

### Backend for Azure OpenAI

```bicep
resource openaiBackend 'Microsoft.ApiManagement/service/backends@2023-09-01-preview' = {
  parent: apim
  name: 'openai-norwayeast'
  properties: {
    url: 'https://my-aoai-norwayeast.openai.azure.com/openai'
    protocol: 'http'
    credentials: {
      header: {}
      query: {}
    }
    tls: {
      validateCertificateChain: true
      validateCertificateName: true
    }
  }
}
```

### Rolletildeling for Managed Identity

```bicep
@description('Grant APIM Managed Identity access to Azure OpenAI')
resource roleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  scope: openaiResource
  name: guid(apim.id, openaiResource.id, cognitiveServicesUserRole)
  properties: {
    roleDefinitionId: cognitiveServicesUserRole
    principalId: apim.identity.principalId
    principalType: 'ServicePrincipal'
  }
}
```

---

## Policy-pipeline for AI Gateway

En komplett AI gateway-policy kombinerer flere policies i riktig rekkefølge:

```xml
<policies>
    <inbound>
        <base />

        <!-- 1. Autentisering mot backend via Managed Identity -->
        <authentication-managed-identity resource="https://cognitiveservices.azure.com/" />

        <!-- 2. Token rate limiting per subscription -->
        <llm-token-limit
            counter-key="@(context.Subscription.Id)"
            tokens-per-minute="10000"
            estimate-prompt-tokens="true"
            remaining-tokens-variable-name="remainingTokens" />

        <!-- 3. Semantic cache lookup -->
        <azure-openai-semantic-cache-lookup
            score-threshold="0.15"
            embeddings-backend-id="embeddings-backend"
            embeddings-backend-auth="system-assigned"
            ignore-system-messages="true"
            max-message-count="10">
            <vary-by>@(context.Subscription.Id)</vary-by>
        </azure-openai-semantic-cache-lookup>

        <!-- 4. Content safety sjekk -->
        <llm-content-safety backend-id="content-safety-backend">
            <categories output-type="EightSeverityLevels">
                <category name="Hate" threshold="4" />
                <category name="Violence" threshold="4" />
            </categories>
        </llm-content-safety>

        <!-- 5. Ruting til backend pool -->
        <set-backend-service backend-id="openai-backend-pool" />
    </inbound>

    <outbound>
        <base />

        <!-- 6. Lagre i semantic cache -->
        <azure-openai-semantic-cache-store duration="3600" />

        <!-- 7. Emit token metrikk -->
        <llm-emit-token-metric namespace="ai-gateway">
            <dimension name="SubscriptionId"
                       value="@(context.Subscription.Id)" />
            <dimension name="ApiId"
                       value="@(context.Api.Id)" />
        </llm-emit-token-metric>
    </outbound>

    <on-error>
        <base />
    </on-error>
</policies>
```

---

## Relevante referansearkitekturer

| Ressurs | Beskrivelse | URL |
|---------|-------------|-----|
| **GenAI Gateway Capabilities** | Oversikt over AI gateway i APIM | learn.microsoft.com/azure/api-management/genai-gateway-capabilities |
| **GenAI Gateway Reference Architecture** | Referansearkitektur med APIM | learn.microsoft.com/ai/playbook/technology-guidance/generative-ai/dev-starters/genai-gateway/reference-architectures/apim-based |
| **Multi-backend Gateway** | Gateway foran flere Azure OpenAI-instanser | learn.microsoft.com/azure/architecture/ai-ml/guide/azure-openai-gateway-multi-backend |
| **GenAI Gateway Toolkit** | Sample policies og lasttesting | github.com/Azure-Samples/apim-genai-gateway-toolkit |
| **AI Hub Gateway Accelerator** | Landing zone accelerator | github.com/Azure-Samples/ai-hub-gateway-solution-accelerator |
| **Well-Architected Guide for APIM** | WAF service guide | learn.microsoft.com/azure/well-architected/service-guides/api-management/reliability |

---

## Hensyn for norsk offentlig sektor

| Krav | APIM-løsning |
|------|---------------|
| **Datasuverenitet** | Deploy i Norway East / Sweden Central, private endpoints |
| **Schrems II** | Managed Identity eliminerer API-nøkler, data forblir i EU |
| **Kostnadsfordeling** | Token metrics per etat/prosjekt via subscriptions og custom headers |
| **Tilgangsstyring** | Entra ID-integrasjon, RBAC på APIM-nivå |
| **Logging/revisjon** | Diagnostic settings til Log Analytics, retention per regelverk |
| **NSM-krav** | VNet-integrasjon, private endpoints, WAF foran APIM |

---

## For Cosmo

- APIM som AI Gateway er den anbefalte PaaS-tilnærmingen for organisasjoner som trenger sentralisert styring over Azure OpenAI og andre LLM-backends -- spesielt relevant for offentlig sektor med krav til kostnadsfordeling og compliance.
- De fem hovdkapabilitetene (token limiting, load balancing, circuit breaker, semantic caching, content safety) dekker de fleste enterprise-behov uten egenutviklet kode.
- For norsk offentlig sektor: anbefal Standard v2 eller Premium tier, Managed Identity for autentisering, private endpoints, og token-metrikk med dimensjoner per etat/prosjekt for kostnadsallokering.
- Policy-pipeline-rekkefølgen er kritisk: autentisering -> token limit -> cache lookup -> content safety -> backend routing (inbound), cache store -> emit metrics (outbound).
- Multi-region deployment med APIM Premium gir active-active gateway med innebygd FQDN-routing, men vær oppmerksom på datasuverenitet ved cross-region trafikk.