open/ms-ai-architect
1
0
Fork 0
Code Issues Releases 1 Activity

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

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

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

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

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

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

379
skills/ms-ai-engineering/references/api-management/versioning-ai-api-endpoints.md Normal file
View file

@ -0,0 +1,379 @@
# API Versioning Strategies for AI Endpoints
**Last updated:** 2026-02
**Status:** GA
**Category:** API Management & AI Gateway
---
## Introduksjon
API-versjonering er kritisk for AI-tjenester der underliggende modeller endres hyppig, nye kapabiliteter legges til og eldre versjoner fases ut. Azure API Management tilbyr tre versjoneringsstrategier (URL-path, header og query string) samt revisjonsstyring for ikke-brytende endringer. For AI-API-er er dette spesielt utfordrende fordi modellversjoner, API-schemaer og responsformater kan endres uavhengig av hverandre.
For norsk offentlig sektor er kontrollert versjonering essensielt. Offentlige virksomheter har ofte integrerte systemer som er avhengige av stabile API-grensesnitt, og et modellbytte kan gi annerledes output for samme prompt. En robust versjoneringssstrategi sikrer at eksisterende integrasjoner fortsetter a fungere nar nye modeller eller kapabiliteter innfores, og gir forbrukere tid til a migrere kontrollert.
APIM skiller mellom versjoner (for brytende endringer) og revisjoner (for ikke-brytende endringer). Denne referansen dekker begge konseptene i konteksten av AI-API-er, med praktiske monstre for modellversjonsmapping, migrasjon og avvikling.
---
## Versjoneringsstrategier i APIM
### Tre tilgjengelige skjemaer
| Skjema | Format | Eksempel |
|--------|--------|---------|
| **URL Path** | `/{api-path}/v1/...` | `https://api.virksomhet.no/ai/v1/chat/completions` |
| **Header** | Custom header | `Api-Version: 2024-08-01` |
| **Query String** | URL-parameter | `https://api.virksomhet.no/ai/chat/completions?api-version=2024-08-01` |
### Anbefaling for AI-API-er
| Strategi | Fordeler | Ulemper | Anbefalt for |
|----------|---------|---------|-------------|
| URL Path | Tydelig, selvdokumenterende, lett a route | Mer tungvint a migrere | Offentlige API-er med stabile versjoner |
| Header | Ren URL, fleksibelt | Ikke synlig i URL | Interne API-er, programmatisk tilgang |
| Query String | Kompatibelt med Azure OpenAI-konvensjon | Kan bli rotete med mange params | Direkte kompatibilitet med Azure OpenAI |
**Anbefaling:** For AI gateway som wrapper rundt Azure OpenAI, bruk **query string** med `api-version` for a folge Microsofts eksisterende konvensjon. For egne AI-fasade-API-er, bruk **URL path** for tydelighet.
### Konfigurere versjonering i APIM
#### URL Path-versjonering
```bicep
resource apiVersionSet 'Microsoft.ApiManagement/service/apiVersionSets@2023-09-01-preview' = {
parent: apiManagement
name: 'ai-gateway-version-set'
properties: {
displayName: 'AI Gateway API'
versioningScheme: 'Segment' // URL path
description: 'AI Gateway API versjonert med URL-path'
}
}
resource aiApiV1 'Microsoft.ApiManagement/service/apis@2023-09-01-preview' = {
parent: apiManagement
name: 'ai-gateway-v1'
properties: {
displayName: 'AI Gateway API v1'
apiVersion: 'v1'
apiVersionSetId: apiVersionSet.id
path: 'ai'
protocols: [ 'https' ]
subscriptionRequired: true
}
}
resource aiApiV2 'Microsoft.ApiManagement/service/apis@2023-09-01-preview' = {
parent: apiManagement
name: 'ai-gateway-v2'
properties: {
displayName: 'AI Gateway API v2'
apiVersion: 'v2'
apiVersionSetId: apiVersionSet.id
path: 'ai'
protocols: [ 'https' ]
subscriptionRequired: true
}
}
```
#### Header-basert versjonering
```bicep
resource apiVersionSetHeader 'Microsoft.ApiManagement/service/apiVersionSets@2023-09-01-preview' = {
parent: apiManagement
name: 'ai-gateway-header-version-set'
properties: {
displayName: 'AI Gateway API (Header Versioned)'
versioningScheme: 'Header'
versionHeaderName: 'Api-Version'
}
}
```
#### Query String-versjonering
```bicep
resource apiVersionSetQuery 'Microsoft.ApiManagement/service/apiVersionSets@2023-09-01-preview' = {
parent: apiManagement
name: 'ai-gateway-query-version-set'
properties: {
displayName: 'AI Gateway API (Query Versioned)'
versioningScheme: 'Query'
versionQueryName: 'api-version'
}
}
```
---
## Avviklingsfrister (Deprecation Timelines)
### Livssyklusmodell for AI-API-versjoner
```
[Preview] --> [GA] --> [Deprecated] --> [Retired]
| | | |
| 6-12 mnd | 6-12 mnd| 3-6 mnd |
| | | |
Flagg: Flagg: Flagg: Fjernet
beta stable deprecated fra gateway
```
### Fasestyring med policies
```xml
<policies>
<outbound>
<base />
<!-- Add deprecation headers based on API version -->
<choose>
<!-- Deprecated version -->
<when condition="@(context.Api.Version == "v1")">
<set-header name="Deprecation" exists-action="override">
<value>true</value>
</set-header>
<set-header name="Sunset" exists-action="override">
<value>Sat, 30 Jun 2026 00:00:00 GMT</value>
</set-header>
<set-header name="Link" exists-action="override">
<value><https://api.virksomhet.no/ai/v2/docs>; rel="successor-version"</value>
</set-header>
<!-- Log deprecation usage for tracking -->
<trace source="api-versioning" severity="warning">
<message>@($"Deprecated API v1 called by {context.Subscription.Name}")</message>
</trace>
</when>
<!-- Preview version -->
<when condition="@(context.Api.Version == "v3-preview")">
<set-header name="x-api-status" exists-action="override">
<value>preview</value>
</set-header>
<set-header name="x-api-warning" exists-action="override">
<value>This API version is in preview and may change without notice.</value>
</set-header>
</when>
</choose>
</outbound>
</policies>
```
### Standard HTTP-headere for versjonsstyring
| Header | Verdi | RFC |
|--------|-------|-----|
| `Deprecation` | `true` | RFC 8594 |
| `Sunset` | ISO 8601 dato | RFC 8594 |
| `Link` | URL til ny versjon | RFC 8288 |
| `x-api-status` | `preview` / `ga` / `deprecated` | Custom |
---
## Modellversjonsmapping
### Utfordringen med AI-modellversjoner
AI-modeller oppdateres uavhengig av API-versjoner:
| API-versjon | Modellnavn | Faktisk modellversjon | Endring |
|-------------|-----------|----------------------|---------|
| v1 | gpt-4o | 2024-05-13 | Opprinnelig |
| v1 | gpt-4o | 2024-08-06 | Modelloppgradering (transparent) |
| v2 | gpt-4o | 2024-11-20 | Ny API + ny modell |
| v2 | gpt-4o-mini | 2024-07-18 | Ny modelltype i v2 |
### Policy: Modellversjonsmapping
```xml
<policies>
<inbound>
<base />
<!-- Map API version to specific model deployment -->
<set-variable name="apiVersion" value="@(context.Api.Version)" />
<set-variable name="requestedModel"
value="@(context.Request.Body.As<JObject>(preserveContent: true)?["model"]?.ToString())" />
<choose>
<!-- v1: Map to stable, older model deployments -->
<when condition="@((string)context.Variables["apiVersion"] == "v1")">
<set-variable name="deployment" value="@{
var model = (string)context.Variables["requestedModel"];
return model switch {
"gpt-4o" => "gpt-4o-2024-05-13-stable",
"gpt-4" => "gpt-4-0613-stable",
_ => "gpt-4o-2024-05-13-stable"
};
}" />
</when>
<!-- v2: Map to latest model deployments -->
<when condition="@((string)context.Variables["apiVersion"] == "v2")">
<set-variable name="deployment" value="@{
var model = (string)context.Variables["requestedModel"];
return model switch {
"gpt-4o" => "gpt-4o-2024-11-20-latest",
"gpt-4o-mini" => "gpt-4o-mini-2024-07-18",
_ => "gpt-4o-2024-11-20-latest"
};
}" />
</when>
</choose>
<!-- Route to correct deployment -->
<rewrite-uri template="@($"/openai/deployments/{context.Variables["deployment"]}/chat/completions")" />
</inbound>
</policies>
```
---
## Migreringsstrategier
### Parallellkjoring av versjoner
Kjor gammel og ny versjon side om side med gradvis migrering:
```xml
<policies>
<inbound>
<base />
<!-- Canary: Route percentage of v1 traffic to v2 backend -->
<choose>
<when condition="@(context.Api.Version == "v1" && new Random().Next(100) < 10)">
<!-- 10% of v1 traffic gets v2 backend for shadow testing -->
<set-variable name="shadowTest" value="true" />
<set-backend-service backend-id="ai-backend-v2" />
<set-header name="x-shadow-test" exists-action="override">
<value>true</value>
</set-header>
</when>
</choose>
</inbound>
</policies>
```
### Migreringssjekkliste
| Fase | Handling | Varighet |
|------|---------|----------|
| 1. Announce | Publiser ny versjon, dokumenter endringer | Uke 0 |
| 2. Parallel | Kjor begge versjoner, monitor bruk | Uke 1-12 |
| 3. Deprecate | Merk gammel versjon som deprecated | Uke 8 |
| 4. Notify | Send varsler til aktive brukere | Uke 8, 16, 22 |
| 5. Restrict | Reduser rate limits pa gammel versjon | Uke 20 |
| 6. Sunset | Fjern gammel versjon | Uke 24 |
### KQL: Overvak versjonsbruk
```kusto
ApiManagementGatewayLogs
| where TimeGenerated > ago(30d)
| extend ApiVersion = tostring(split(ApiId, "-")[-1])
| summarize
RequestCount = count(),
UniqueSubscriptions = dcount(SubscriptionId)
by ApiVersion, bin(TimeGenerated, 1d)
| order by TimeGenerated desc, ApiVersion asc
```
---
## Revisjonsstyring for ikke-brytende endringer
### Revisjoner vs. Versjoner
| Egenskap | Revisjon | Versjon |
|----------|----------|---------|
| Type endring | Ikke-brytende | Brytende |
| URL-endring | Nei (`;rev=N` valgfri) | Ja (ny versjon i path/header/query) |
| Eksempel | Legge til valgfritt felt | Endre responsstruktur |
| Klientpavirkning | Ingen (bakoverkompatibelt) | Krever klientoppdatering |
| Publisering | Gjor revisjon "current" | Ny API-versjon |
| Change log | Valgfri endringslogg | Egen dokumentasjon |
### Bruke revisjoner for modelloppgraderinger
Nar en modell oppdateres uten API-endringer (f.eks. GPT-4o far ny snapshot):
1. Opprett ny revisjon av API-et
2. Endre backend-deployment i den nye revisjonen
3. Test grundig med nye revisjon
4. Gjor revisjon "current" nar validert
5. Publiser endringslogg
```xml
<!-- Revision-specific backend for testing -->
<policies>
<inbound>
<base />
<!-- Non-current revisions can use different backends for testing -->
<choose>
<when condition="@(context.Api.Revision == "3")">
<set-backend-service backend-id="ai-backend-new-model" />
</when>
</choose>
</inbound>
</policies>
```
---
## Handtering av brytende endringer
### Hva er en brytende endring for AI-API-er?
| Endring | Brytende? | Strategi |
|---------|-----------|---------|
| Legge til nytt valgfritt felt i response | Nei | Revisjon |
| Endre modellnavn | Ja | Ny versjon |
| Fjerne felt fra response | Ja | Ny versjon |
| Endre feilformat | Ja | Ny versjon |
| Endre token-tellemekanisme | Ja | Ny versjon |
| Legge til ny operasjon | Nei | Revisjon |
| Endre autentiseringsmetode | Ja | Ny versjon |
| Oppdatere underliggende modell (samme API) | Avhenger* | Revisjon eller versjon |
\* Modelloppgraderinger som gir vesentlig annerledes output bor behandles som brytende.
### Versjonering av OpenAPI-spesifikasjon
```yaml
openapi: 3.0.3
info:
title: AI Gateway API
version: '2.0'
description: |
## Endringslogg
### v2.0 (2026-02)
- Ny modell: gpt-4o-mini
- Endret responsformat for token_usage
- Fjernet deprecated 'prompt' field (bruk 'messages')
### v1.0 (2025-06) - DEPRECATED
- Opprinnelig versjon
- Sunset: 2026-06-30
contact:
name: AI Platform Team
email: ai-platform@virksomhet.no
```
---
## Referanser
- [Versions in Azure API Management](https://learn.microsoft.com/en-us/azure/api-management/api-management-versions) -- versjoneringsguide
- [Tutorial: Publish multiple versions of your API](https://learn.microsoft.com/en-us/azure/api-management/api-management-get-started-publish-versions) -- hands-on tutorial
- [Revisions in Azure API Management](https://learn.microsoft.com/en-us/azure/api-management/api-management-revisions) -- revisjonsstyring
- [Tutorial: Use revisions to make nonbreaking changes](https://learn.microsoft.com/en-us/azure/api-management/api-management-get-started-revise-api) -- revisjon-tutorial
- [API design - Versioning (Azure Architecture)](https://learn.microsoft.com/en-us/azure/architecture/microservices/design/api-design#api-versioning) -- designprinsipper
- [OWASP: Improper inventory management](https://learn.microsoft.com/en-us/azure/api-management/mitigate-owasp-api-threats#improper-inventory-management) -- sikkerhetsanbefalinger
- [AI gateway in Azure API Management](https://learn.microsoft.com/en-us/azure/api-management/genai-gateway-capabilities) -- AI gateway-oversikt
## For Cosmo
- **Bruk denne referansen** nar kunden planlegger versjonering av sine AI-API-er, trenger a migrere mellom modellversjoner, eller vil etablere en livssyklusmodell for sine API-endepunkter.
- For AI gateway som wrapper rundt Azure OpenAI, anbefal query string-versjonering med `api-version` for kompatibilitet med Microsofts eksisterende konvensjon.
- Skill alltid mellom modellversjoner og API-versjoner -- en modelloppgradering er ikke nodvendigvis en API-versjon. Bruk revisjoner for transparente modelloppgraderinger og versjoner for brytende API-endringer.
- Anbefal minimum 6 maneders deprecation-periode for norsk offentlig sektor, der integrerte systemer ofte har lange endringssykluser.
- Bruk alltid `Deprecation` og `Sunset` HTTP-headere (RFC 8594) for a gi maskinlesbare signaler til klienter om kommende avvikling -- dette lar automatiserte systemer varsle forvaltere.