open/ms-ai-architect
1
0
Fork 0
Code Issues Releases 4 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

464
skills/ms-ai-engineering/references/rag-architecture/azure-ai-search-setup.md Normal file
View file

@ -0,0 +1,464 @@
# Azure AI Search - Configuration and Deployment
**Last updated:** 2026-02
**Status:** GA
**Category:** RAG Architecture & Semantic Search
---
## Introduksjon
Azure AI Search (tidligere Azure Cognitive Search) er Microsofts managed search-plattform for å bygge enterprise-ready søkeløsninger med AI-beriket innhold. For RAG-arkitektur er den det dominerende valget i Microsoft-stakken — den støtter hybrid search (full-text + vector), semantic ranker, og integrerer direkte med Azure OpenAI, AI Foundry, og Copilot Studio.
Korrekt konfigurasjon av Azure AI Search avgjør om RAG-systemet ditt er kostnadseffektivt, performant, og skalerbart. Feilvalg av SKU, indekseringsstrategi, eller replika-konfigurasjon kan føre til unødvendig høye kostnader eller dårlig brukeropplevelse. Denne referansen dekker de kritiske valgene arkitekten må ta: SKU-seleksjon, indekseringsstrategier, skalering, og prisingmodeller.
For offentlig sektor er Azure AI Search spesielt relevant fordi den støtter data residency (Norway East/West regioner), GDPR-compliance, og kan konfigureres med Private Link for å holde trafikk innenfor Azure-nettverket. Den er en nøkkelkomponent i norske AI-løsninger som må følge Schrems II og Forvaltningslovens krav til informasjonssikkerhet.
## Kjernekomponenter
### Azure AI Search Service Tiers
| Tier | Bruksområde | Maks dokumenter | Maks indekser | Semantic Ranker | Vector Search | Estimert kostnad (NOK/mnd) |
|------|-------------|-----------------|---------------|-----------------|---------------|----------------------------|
| **Free** | Prototyping | 10 000 | 3 | Nei | Begrenset | Gratis (0) |
| **Basic** | Små prod-miljøer | 15M | 15 | Nei | Ja | ~800 |
| **Standard (S1)** | Mid-tier prod | 60M per partition | 50 | Ja | Ja | ~4 000 |
| **Standard (S2)** | Høy-volum prod | 120M per partition | 200 | Ja | Ja | ~8 000 |
| **Standard (S3)** | Enterprise-scale | 240M per partition | 200 | Ja | Ja | ~16 000 |
| **Storage Optimized (L1/L2)** | Arkivering, cold search | 120M/240M per partition | 10 | Nei | Ja | ~11 000 / ~22 000 |
**Viktige egenskaper:**
- **Partitions:** Øker lagringskapasitet og parallellitet (horizontal scaling)
- **Replicas:** Øker throughput og tilgjengelighet (query load balancing)
- **SLA:** 99.9% for 2+ replicas (query), 99.9% for 3+ replicas (indexing + query)
- **Semantic Ranker:** Kun Standard og høyere (S1+)
- **Private Link:** Standard (S1+), Storage Optimized
### Indekseringsstrategier
Azure AI Search støtter tre indekseringsmodeller:
1. **Push API** — Applikasjonen sender dokumenter direkte til indexing API
- Best for: Real-time updates, custom pipelines, event-driven indexing
- Kompleksitet: Høy (må bygge egen orchestration)
- Use case: Chat-applikasjoner som krever øyeblikkelig synkronisering
2. **Pull (Indexers)** — Azure AI Search henter data fra datakilde på schedule
- Best for: Bulk indexing, batch processing, scheduled updates
- Støttede kilder: Azure Blob Storage, Cosmos DB, SQL Database, SharePoint Online
- Use case: Bulk-indeksering av SharePoint-dokumenter, nightly sync
3. **Hybrid (Debug Sessions + Skillsets)** — Indexer + AI enrichment pipeline
- Best for: OCR, entity extraction, key phrase extraction før indexing
- Koster: Både AI Search indexer-tid OG Azure AI Services API-kall
- Use case: Søk i scannede PDF-er, bildeanalyse, custom skills
### Search Service Configuration
**Kritiske konfigurasjonsparametre:**
```json
{
"name": "search-service-name",
"location": "norwayeast",
"sku": {
"name": "standard"
},
"replicaCount": 2,
"partitionCount": 1,
"hostingMode": "default",
"publicNetworkAccess": "disabled",
"privateEndpointConnections": [...],
"semanticSearch": "standard"
}
```
**Replica vs Partition trade-offs:**
| Scenario | Replicas | Partitions | Begrunnelse |
|----------|----------|------------|-------------|
| Høy query load, moderat data | 3+ | 1 | Prioriter throughput, unngå partition-overhead |
| Stor datamengde, lav trafikk | 1-2 | 3+ | Prioriter lagring, spar på replica-kostnad |
| Enterprise prod (SLA) | 3+ | 2+ | SLA krever 3 replicas, partitions for skalering |
| Dev/test | 1 | 1 | Minimal kostnad |
## Arkitekturmønstre
### Mønster 1: Single-Index RAG (enkleste)
```
[Azure OpenAI] --> [AI Search (1 index)] --> [Storage Account]
↑
[Indexer pipeline]
```
**Når bruke:**
- Én domene/datakilde (f.eks. kun produktdokumentasjon)
- Homogene dokumenter (samme format, metadata)
- Enkelt RBAC-krav (alle brukere ser alt)
**Fordeler:**
- Lavest kompleksitet
- Enkleste kostnadsmodell
- Best latency (én søkeoperasjon)
**Ulemper:**
- Kan ikke skille tilgang per bruker uten custom filtering
- Blander alle dokumenttyper i samme index
- Vanskelig å optimere for ulike query-mønstre
### Mønster 2: Multi-Index Federation (enterprise)
```
[Azure OpenAI] --> [Search Client Logic]
↓
┌─────────────────┼─────────────────┐
↓ ↓ ↓
[Index: HR] [Index: Legal] [Index: Public]
↑ ↑ ↑
[Indexer 1] [Indexer 2] [Indexer 3]
```
**Når bruke:**
- Multi-tenant scenarios (per kunde/avdeling)
- Ulike RBAC-krav per datasett
- Ulike refresh-frekvenser (HR daglig, Legal hourly)
**Fordeler:**
- Granulær sikkerhetskontroll
- Optimert per use case (ulike analyzers, scoring profiles)
- Isolert feilhåndtering (én index nede påvirker ikke andre)
**Ulemper:**
- Høyere kostnad (multiple indexes)
- Kompleks query-orchestration (må merge resultater)
- Vanskelig å ranke på tvers
### Mønster 3: Hybrid Search + Semantic Ranker (anbefalt for RAG)
```
[User Query] --> [AI Search]
↓
┌──────────┴──────────┐
↓ ↓
[BM25 Full-Text] [Vector Search]
↓ ↓
└──────────┬──────────┘
↓
[Semantic Ranker] (rerank top 50)
↓
[Top K til LLM]
```
**Når bruke:**
- RAG-arkitektur med Azure OpenAI
- Trenger både keyword precision og semantic recall
- Budsjett for Standard tier (S1+)
**Fordeler:**
- Best relevance for RAG (kombinerer begge verdener)
- Semantic Ranker forbedrer top-K dramatisk
- Støtter både "exact match" og "conceptual match"
**Ulemper:**
- Krever S1+ tier (dyrere)
- Semantic Ranker koster ekstra per 1000 queries
- Høyere latency (3 steg: BM25, vector, rerank)
## Beslutningsveiledning
### Velg SKU basert på bruksområde
| Krav | Anbefalt SKU | Begrunnelse |
|------|--------------|-------------|
| Prototype, POC, demo | Free eller Basic | Gratis/billig, tilstrekkelig for <15M docs |
| Prod, <10M docs, moderate queries | S1 | Best value, semantic ranker inkludert |
| Prod, 10-50M docs | S1 (multi-partition) eller S2 | Øk partitions etter behov |
| Prod, >50M docs | S2 eller S3 | S3 for høy throughput + stor data |
| Compliance: Private Link | S1+ | Free/Basic støtter ikke Private Link |
| Arkivering, cold storage | L1 eller L2 | Billigere per GB, men tregere queries |
### Vanlige feil og misforståelser
| Feil | Konsekvens | Riktig tilnærming |
|------|------------|-------------------|
| "Vi trenger S3 for å være sikre" | 4x kostnad vs. S1 uten reell gevinst | Start med S1, skaler opp ved faktisk behov |
| Bruke 1 replica i prod | Ingen SLA, downtime ved maintenance | Alltid 2+ replicas for prod (query SLA) |
| Bruke Basic tier for RAG | Ingen semantic ranker → dårlig relevance | S1 minimum for RAG med semantic ranker |
| Ignorere partition-grense | Query-timeout ved >60M docs på S1 | Øk partitions, ikke bare replicas |
| Push API uten rate limiting | Throttling (429 errors) | Bruk batch indexing eller indexer-pipeline |
### Røde flagg arkitekten bør se etter
1. **Kunden krever <100ms latency for RAG:** Urealistisk med hybrid search + semantic ranker (typisk 200-500ms). Vurder caching eller pre-retrieval.
2. **"Vi skal indeksere 500M dokumenter":** S3 HD (high density) eller vurder sharding til flere services.
3. **"Vi vil ha vector search uten full-text":** Mulig, men dårlig idé — hybrid search er nesten alltid bedre.
4. **"Vi trenger real-time sync (<1 sek)":** Push API mulig, men komplekst. Vurder om eventual consistency (5-10 sek) er akseptabelt.
5. **"Kan vi bruke Free tier i prod?":** Nei. Ingen SLA, maksimalt 10K docs, ingen semantic ranker.
## Integrasjon med Microsoft-stakken
### Azure OpenAI + AI Search (RAG)
```python
from azure.search.documents import SearchClient
from openai import AzureOpenAI
# 1. Retrieve via AI Search
search_client = SearchClient(endpoint, index_name, credential)
results = search_client.search(
search_text=user_query,
vector_queries=[VectorizedQuery(vector=query_embedding, k_nearest_neighbors=5)],
select=["content", "title", "url"],
top=5
)
# 2. Ground OpenAI with retrieved context
context = "\n\n".join([doc["content"] for doc in results])
openai_client = AzureOpenAI(...)
response = openai_client.chat.completions.create(
model="gpt-4o",
messages=[
{"role": "system", "content": f"Use this context: {context}"},
{"role": "user", "content": user_query}
]
)
```
### Copilot Studio + AI Search (Declarative Agent)
Copilot Studio kan bruke AI Search som "knowledge base" via **Declarative Agent**-manifest:
```json
{
"capabilities": [
{
"name": "OneDriveAndSharePoint",
"items_by_url": [
{
"url": "https://search-service.search.windows.net/indexes/my-index"
}
]
}
]
}
```
**Krav:**
- AI Search må ha Public Network Access eller Managed Identity-konfigurasjon
- Index må ha semantic configuration
- Copilot Studio kjører automatisk hybrid search + semantic ranker
### AI Foundry + AI Search (Prompt Flow)
AI Foundry (tidligere AI Studio) har innebygget **Vector Index**-node i Prompt Flow:
```yaml
inputs:
query: ${inputs.question}
index_type: "Azure AI Search"
endpoint: "https://search-service.search.windows.net"
index_name: "my-index"
top_k: 5
```
**Best practice:**
- Bruk Managed Identity (ikke API keys) mellom AI Foundry og AI Search
- Konfigurer Private Link hvis begge er i samme VNET
### Power Platform + AI Search (Custom Connector)
Power Automate/Power Apps kan kalle AI Search via **Custom Connector**:
- Bruk OpenAPI-spec for Azure AI Search REST API
- Bruk Service Principal for autentisering
- Typisk use case: "Search company docs" action i Power Virtual Agents
## Offentlig sektor (Norge)
### GDPR og data residency
Azure AI Search støtter **Norway East** og **Norway West** regioner:
- Data lagres kun i Norge (ingen geo-replication utenfor EU/EEA)
- Metadata (index schema, konfiguration) lagres i Azure Control Plane (EU)
- Oppfyller GDPR Article 28 (processor agreement)
### Schrems II og Forvaltningsloven
**Schrems II-relevans:**
- Microsoft er amerikansk selskap → potensielt CLOUD Act-scope
- **Mitigerende tiltak:**
- Bruk Norway regions (ikke US/Global)
- Konfigurer Private Link (ingen trafikk over internet)
- Krypter data med Customer Managed Keys (CMK) i Azure Key Vault
**Forvaltningsloven § 13b (informasjonssikkerhet):**
- Krav om tilgangskontroll: Bruk Azure RBAC + document-level security filters
- Krav om logging: Aktiver Diagnostic Settings (Log Analytics)
- Krav om risikovurdering: Dokumenter SKU-valg, encryption, network isolation
### AI Act (fra 2026)
**Relevans for AI Search:**
- Ikke en "høyrisiko AI-system" i seg selv (er infrastruktur)
- Men hvis brukt i RAG for høyrisiko use case (f.eks. saksbehandling), må systemet dokumentere:
- Data provenance (hvor kom dokumentene fra?)
- Citation tracking (hvilke dokumenter ble brukt i svar?)
- Bias testing (er søkeresultater skjeve?)
**Anbefaling:** Implementer metadata-tagging for data lineage (kilde, dato, versjon).
## Kostnad og lisensiering
### Prismodell (2026)
Azure AI Search prises per **search unit** (SU = 1 partition × 1 replica).
| Tier | Kostnad per SU (NOK/mnd) | Ekstrakostnader |
|------|---------------------------|-----------------|
| Basic | ~800 | N/A |
| S1 | ~2 000 | Semantic Ranker: ~70 NOK per 1000 queries |
| S2 | ~4 000 | Semantic Ranker: ~70 NOK per 1000 queries |
| S3 | ~8 000 | Semantic Ranker: ~70 NOK per 1000 queries |
| L1 | ~5 500 | N/A |
**Eksempel:**
- S1 med 2 replicas, 1 partition = 2 SU = 4 000 NOK/mnd
- S1 med 3 replicas, 2 partitions = 6 SU = 12 000 NOK/mnd
- Semantic Ranker: 100 000 queries/mnd = ~7 000 NOK ekstra
### Kostnadsoptimaliseringstips
1. **Start med 1 partition, 2 replicas (ikke omvendt):**
- 2 replicas gir SLA og throughput
- Legg til partitions kun når du treffer lagringsgrense
2. **Bruk indexer-schedule, ikke continuous:**
- Continuous indexing koster mer (konstant polling)
- Scheduled indexing (f.eks. hver 6. time) er billigere
3. **Deaktiver semantic ranker i dev/test:**
- Semantic ranker koster per query
- Aktiver kun i prod-miljø
4. **Bruk Free tier for prototyping:**
- Gratis, men maks 10K docs og 3 indekser
- Bytt til Basic/S1 kun når du deployer til prod
5. **Vurder Storage Optimized (L1/L2) for arkivering:**
- Hvis <100 queries/dag, men stor datamengde (100M+ docs)
- 50% billigere per GB vs. Standard
6. **Unngå over-replication:**
- 2 replicas er nok for de fleste use cases
- 3+ replicas kun hvis >1000 queries per sekund eller 99.9% SLA-krav
### Sammenligning med alternativer
| Løsning | Kostnad (NOK/mnd) | Når bruke |
|---------|-------------------|-----------|
| Azure AI Search (S1, 2 replicas) | ~4 000 | Standard for RAG i Microsoft-stakk |
| Pinecone (1M vectors, standard) | ~6 000 | Kun vector search, ingen hybrid |
| Weaviate (self-hosted, Azure VM) | ~3 000 (VM) | Open source, full kontroll, men ops-kostnad |
| Azure Cosmos DB (vector search) | ~8 000+ | Hvis du allerede bruker Cosmos, ellers overkill |
**Anbefaling:** Azure AI Search er best value for RAG i Microsoft-stakken pga. native integrasjon og semantic ranker.
## For arkitekten (Cosmo)
### Nøkkelspørsmål å stille kunden
1. **"Hvor mange dokumenter skal indekseres totalt? Hvor stor er gjennomsnitts-dokumentet?"**
- Avgjør om Basic/S1/S2/S3 er tilstrekkelig (partition-sizing)
2. **"Hvor ofte må dataene oppdateres? Real-time, hourly, eller daily?"**
- Real-time → Push API (komplekst, dyrt)
- Hourly/daily → Indexer (enklere, billigere)
3. **"Hva er forventet query-volum? Queries per sekund i peak?"**
- <10 QPS: 2 replicas
- 10-50 QPS: 3 replicas
- >50 QPS: 4+ replicas eller vurder caching
4. **"Trenger dere document-level security (RBAC per dokument)?"**
- Ja → Implementer security filters (øker query-kompleksitet)
- Nei → Enklere, men alle brukere ser alt
5. **"Er dette et POC, pilot, eller prod-deployment?"**
- POC: Free/Basic
- Pilot: S1 (1 partition, 2 replicas)
- Prod: S1+ (3 replicas for SLA)
6. **"Hva er compliance-kravene? Schrems II, GDPR, AI Act?"**
- Schrems II → Norway regions + Private Link + CMK
- AI Act → Metadata tagging, citation tracking
7. **"Trenger dere hybrid search (keyword + vector) eller kun vector?"**
- Hybrid → S1+ (anbefalt for RAG)
- Kun vector → Vurder alternativer (Pinecone, Qdrant)
8. **"Hva er budsjettet for search-infrastruktur per måned?"**
- <5 000 NOK: Basic eller S1 (1 partition, 2 replicas)
- 5 000-15 000 NOK: S1 (multi-partition) eller S2
- >15 000 NOK: S2/S3 eller multi-index architecture
### Vanlige fallgruver
1. **Over-provisioning fra dag 1:**
- Kunder ber ofte om S3 "for å være sikre"
- Start med S1, skaler opp basert på faktisk bruk
2. **Glemme SLA-krav:**
- 1 replica = ingen SLA (maintenance = downtime)
- Prod krever minimum 2 replicas (query) eller 3 replicas (indexing + query)
3. **Bruke Basic tier med semantic ranker-forventning:**
- Basic støtter ikke semantic ranker
- S1 er minimum for RAG med god relevance
4. **Push API uten retry logic:**
- AI Search throttler ved >1000 docs/batch
- Implementer exponential backoff
5. **Ignorere partition-grense:**
- S1 = 60M docs per partition
- Hvis du har 100M docs, trenger du 2 partitions (ikke 10 replicas)
### Anbefalinger per modenhetsnivå
| Modenhetsnivå | Anbefaling |
|---------------|------------|
| **Pilot (ingen prod-bruk)** | Free eller Basic tier, 1 partition, 1 replica. Bruk Indexer med Azure Blob Storage. Ingen Private Link. |
| **Prod (lav trafikk, <1000 users)** | S1, 1 partition, 2 replicas. Aktiver semantic ranker. Vurder Private Link hvis sensitive data. |
| **Prod (moderat trafikk, enterprise)** | S1 eller S2, 2 partitions, 3 replicas. Private Link, Diagnostic Logging, Managed Identity. |
| **Prod (høy trafikk, >10 000 users)** | S2 eller S3, 3+ partitions, 4+ replicas. Multi-index architecture, caching-lag (Redis), CDN for static content. |
## Kilder og verifisering
### Microsoft Learn-referanser
- [Azure AI Search pricing](https://azure.microsoft.com/en-us/pricing/details/search/)
- [Choose a tier for Azure AI Search](https://learn.microsoft.com/en-us/azure/search/search-sku-tier)
- [Scale for performance in Azure AI Search](https://learn.microsoft.com/en-us/azure/search/search-performance-optimization)
- [Semantic ranking in Azure AI Search](https://learn.microsoft.com/en-us/azure/search/semantic-search-overview)
- [Indexers in Azure AI Search](https://learn.microsoft.com/en-us/azure/search/search-indexer-overview)
- [Hybrid search in Azure AI Search](https://learn.microsoft.com/en-us/azure/search/hybrid-search-overview)
### Konfidensnivå
**Verified (90%+ confidence):**
- SKU-pricing, partition/replica limits, semantic ranker availability
- Norway region support, Private Link requirements
- Hybrid search architecture, indexer support
**Baseline (70-89% confidence):**
- Semantic Ranker pricing per query (varierer noe per region)
- Exact QPS limits per tier (Microsoft dokumenterer ikke eksakte tall)
- AI Act-implikasjoner (ennå ikke fullt enforceret)
**Assumed (<70% confidence):**
- Kostnadssammenligning med Pinecone/Weaviate (priser endres ofte)
- Optimal chunk size for RAG (avhenger av use case)
---
**For Cosmo:** Denne referansen brukes når kunden snakker om "RAG-implementasjon", "søkeløsning", "Azure AI Search setup", eller spør om SKU-valg. Kombiner med **RAG Core Patterns** for arkitekturveiledning og **Hybrid Search - Full-Text and Vector Combined** for query-optimalisering.