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

View file

@ -0,0 +1,419 @@
# RAG Core Patterns and Architecture
**Last updated:** 2026-02
**Status:** GA
**Category:** RAG Architecture & Semantic Search
---
## Introduksjon
Retrieval-Augmented Generation (RAG) er en arkitektonisk tilnærming som kombinerer informasjonshenting med generativ AI for å produsere faktagrunnede, domene-spesifikke svar. I stedet for å stole utelukkende på en language models forhåndstrente kunnskap, henter RAG-systemer relevant kontekst fra eksterne kunnskapsbaser i sanntid og bruker denne som grunnlag for generering. Dette reduserer hallusinasjoner, tillater kontinuerlig oppdatering av kunnskap uten retrening, og muliggjør svar basert på proprietær eller fersk data.
For enterprise-organisasjoner representerer RAG en praktisk vei til produksjon av AI-løsninger som er både presise og etterprøvbare. Microsoft-økosystemet tilbyr en komplett stack for RAG: Azure AI Search for indeksering og søk, Azure OpenAI Service for generering, Azure AI Foundry for orkestrering, og Copilot Studio for low-code RAG-agenter. RAG brukes i alt fra kunnskapssøk og dokumentanalyse til kundeservice og beslutningsstøtte.
Det finnes tre hovedarkitekturer: **Naive RAG** (enkel retrieve-then-generate), **Advanced RAG** (med pre/post-processing og reranking), og **Agentic RAG** (autonome agenter som planlegger og itererer). Valg av mønster avhenger av use case-kompleksitet, krav til presisjon, og tilgjengelig modenhet.
---
## Kjernekomponenter i RAG-arkitektur
En RAG-pipeline består av følgende byggeklosser:
| Komponent | Ansvar | Microsoft-tjenester |
|-----------|--------|---------------------|
| **Document Ingestion** | Laste inn, parse og chunke dokumenter | Azure AI Document Intelligence, Azure Functions |
| **Embedding Generation** | Konvertere tekst til vektorer | Azure OpenAI (text-embedding-3-large, text-embedding-ada-002) |
| **Vector Store** | Lagre og indeksere embeddings | Azure AI Search, Azure Cosmos DB (MongoDB vCore) |
| **Retrieval** | Søke etter relevante chunks basert på query | Azure AI Search (vector, hybrid, semantic search) |
| **Reranking** | Sortere resultater etter relevans | Azure AI Search Semantic Ranker, custom models |
| **Context Assembly** | Bygge prompt med retrieved chunks | Semantic Kernel, LangChain, Prompt flow |
| **Generation** | Generere svar basert på context | Azure OpenAI Service (GPT-4, GPT-4o) |
| **Citation Tracking** | Spore kilder og gi referanser | Custom logic, Azure AI Search metadata |
**Typisk RAG-flyt:**
1. **Indexing (offline):** Dokumenter lastes inn → chunkes → embeddes → lagres i vector store
2. **Query (runtime):** User query → embedding → vector search → reranking → top-k chunks
3. **Generation:** Chunks + query → prompt template → LLM → response + citations
**Eksempel: Enkel RAG-flyt i Python (Semantic Kernel)**
```python
from semantic_kernel import Kernel
from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion, AzureTextEmbedding
from semantic_kernel.connectors.memory.azure_cognitive_search import AzureCognitiveSearchMemoryStore
# Setup
kernel = Kernel()
kernel.add_chat_service("chat", AzureChatCompletion(...))
kernel.add_text_embedding_generation_service("embedding", AzureTextEmbedding(...))
memory = AzureCognitiveSearchMemoryStore(...)
# Index (offline)
await memory.save_information_async("docs", id="1", text="Microsoft Copilot Studio allows...")
# Retrieve + Generate (runtime)
results = await memory.search_async("docs", "What is Copilot Studio?", limit=3)
context = "\n".join([r.text for r in results])
prompt = f"Context:\n{context}\n\nQuestion: What is Copilot Studio?\nAnswer:"
response = await kernel.invoke_semantic_async(prompt)
```
---
## Arkitekturmønstre
### 1. Naive RAG
**Beskrivelse:** Enkel retrieve-then-generate pipeline uten pre/post-processing.
**Flyt:**
1. Embed user query
2. Vector search → top-k chunks
3. Inject chunks i prompt
4. Generate response
**Når bruke:**
- MVP/proof-of-concept
- Enkle kunnskapssøk med begrenset datamengde
- Lavt krav til presisjon
**Fordeler:**
- Rask implementering (dager)
- Lav kompleksitet
- Enkel feilsøking
**Ulemper:**
- Dårlig håndtering av komplekse queries
- Ingen optimalisering av chunk-relevans
- Begrensede citation capabilities
**Typisk bruk:** Intern FAQ-bot, proof-of-concept for ledelse, enkel dokumentsøk.
---
### 2. Advanced RAG
**Beskrivelse:** Forbedret pipeline med query processing, hybrid search, reranking, og post-processing.
**Flyt:**
1. **Pre-retrieval:** Query expansion, intent detection, filter inference
2. **Retrieval:** Hybrid search (vector + BM25) + metadata filtering
3. **Post-retrieval:** Reranking (semantic ranker), deduplication, chunk selection
4. **Generation:** Context-optimized prompt + citation tracking
**Når bruke:**
- Produksjonsløsninger med krav til presisjon
- Store kunnskapsbaser (>10,000 dokumenter)
- Behov for verifiable citations
**Fordeler:**
- Høyere relevans (20-40% forbedring vs naive)
- Bedre håndtering av komplekse queries
- Citation tracking og source attribution
- Robusthet mot ambiguity
**Ulemper:**
- Høyere latency (2-5x vs naive)
- Mer kompleks pipeline å vedlikeholde
- Høyere kostnader (reranking, query expansion)
**Typisk bruk:** Enterprise kunnskapssøk, regulatory compliance bots, kundeservice med SLA-krav.
---
### 3. Agentic RAG
**Beskrivelse:** Autonome agenter som planlegger, itererer, og velger retrieval-strategi dynamisk.
**Flyt:**
1. **Planning:** Agent analyserer query → dekomponerer i sub-tasks
2. **Tool Selection:** Agent velger search-strategi (vector, keyword, multi-index, web)
3. **Iterative Retrieval:** Agent henter data → evaluerer relevans → henter mer hvis nødvendig
4. **Self-Reflection:** Agent vurderer om nok kontekst er samlet
5. **Generation:** Syntetiserer svar basert på aggregert kontekst
**Når bruke:**
- Komplekse, multi-hop reasoning tasks
- Cross-domain queries (søk i flere databaser)
- Research-assistenter og analytical agents
**Fordeler:**
- Høyest presisjon for komplekse queries
- Selvkorrigerende (kan omformulere og re-query)
- Kan kombinere multiple sources (docs, web, APIs)
**Ulemper:**
- Høy latency (10-60 sekunder)
- Høy token-kostnad (multiple LLM calls)
- Kompleks debugging og observability
**Typisk bruk:** Research assistants, regulatory analysis, cross-domain intelligence.
**Eksempel: Agentic RAG med Microsoft Agent Framework**
```python
from semantic_kernel.agents import ChatCompletionAgent
from semantic_kernel.agents.strategies import TerminationStrategy
# Define retrieval tool
@kernel_function(name="search_docs", description="Search knowledge base")
async def search_docs(query: str) -> str:
results = await memory.search_async("docs", query, limit=5)
return "\n".join([r.text for r in results])
# Create agent with tools
agent = ChatCompletionAgent(
kernel=kernel,
name="ResearchAgent",
instructions="You are a research assistant. Use search_docs to find information, then synthesize.",
tools=[search_docs]
)
# Run
result = await agent.invoke_async("What are the compliance requirements for AI in Norwegian public sector?")
```
---
## Beslutningsveiledning
### Mønster-valg: Når bruke hva?
| Kriterium | Naive RAG | Advanced RAG | Agentic RAG |
|-----------|-----------|--------------|-------------|
| **Use case-kompleksitet** | Enkel FAQ, direktesøk | Enterprise kunnskapssøk, compliance | Multi-hop reasoning, research |
| **Datamengde** | <1,000 dokumenter | 1,000-100,000+ | Ubegrenset (multi-source) |
| **Latency-krav** | <1s | 1-3s | 10-60s |
| **Presisjonskrav** | Lav (70-80% recall) | Høy (90%+ recall) | Kritisk (95%+ recall) |
| **Citation-krav** | Valgfri | Påkrevd | Påkrevd + traceability |
| **Kostnadssensitivitet** | Lav (få tokens) | Moderat | Høy (mange LLM calls) |
| **Modenhet i org** | MVP-fase | Produksjon | Advanced AI-team |
### Vanlige feil og misforståelser
| Misforståelse | Realitet |
|---------------|----------|
| "RAG eliminerer hallusinasjoner" | RAG reduserer, men eliminerer ikke hallusinasjoner. LLM kan fortsatt generere feil basert på dårlig kontekst. |
| "Større chunks gir bedre svar" | Større chunks gir mer kontekst, men reduserer presisjon. Optimal chunk size: 512-1024 tokens med 10-20% overlap. |
| "Vector search er nok" | Vector search alene misser keyword matches. Hybrid search (vector + BM25) gir 15-30% bedre recall. |
| "RAG fungerer out-of-the-box" | RAG krever tuning: chunk size, embedding model, retrieval-k, reranking, prompt engineering. |
| "Long-context models erstatter RAG" | Long-context (128K tokens) er dyrt og tregere. RAG er mer kostnadseffektivt for store kunnskapsbaser. |
### Røde flagg
- **Ingen metadata-strategi:** Uten metadata (source, date, category) er filtrering og citation umulig.
- **Hardkodet chunk size:** Ulike dokumenttyper (tabeller, prosatekst, kode) krever ulike chunk-strategier.
- **Manglende reranking:** Vector search alene gir ofte irrelevante chunks i top-3. Reranking er kritisk.
- **Ingen evaluation metrics:** Uten retrieval recall/precision og generation fidelity er tuning blindflyvning.
- **Token overflow:** Uten context window management risikerer du truncation og tap av relevante chunks.
---
## In-Context Learning vs RAG
**In-Context Learning (ICL):** Gi LLM all kontekst i prompten (few-shot examples, dokumenter, data).
**Når bruke ICL:**
- Liten kunnskapsbase (<10 dokumenter, <50K tokens)
- Statisk data som sjeldent endres
- Behov for rask prototyping uten infrastruktur
**Når bruke RAG:**
- Stor kunnskapsbase (>50K tokens)
- Dynamisk data som oppdateres hyppig
- Behov for citation og source tracking
- Kostnadsoptimalisering (vector search er billigere enn å sende 100K tokens per query)
**Long-Context Models (GPT-4 Turbo 128K):**
- Tillater større ICL-windows
- **Men:** Høyere latency, høyere kostnad, "lost-in-the-middle" problem (LLM prioriterer start/slutt av context)
- **Hybrid-tilnærming:** Bruk RAG for retrieval → inject top-k chunks i long-context model
---
## Integrasjon med Microsoft-stakken
### Azure AI Search (kjernen i RAG)
| Funksjon | Bruk i RAG |
|----------|-----------|
| **Vector search** | Embedding-basert retrieval (cosine similarity, HNSW indexing) |
| **Hybrid search** | Kombinerer vector + BM25 for bedre recall |
| **Semantic Ranker** | L2 reranking basert på cross-encoder (20-30% relevance boost) |
| **Metadata filtering** | Filtrering på dato, category, access control |
| **Skillset API** | Document cracking, OCR, entity extraction pre-indexing |
**Eksempel: Hybrid search query**
```python
from azure.search.documents import SearchClient
results = search_client.search(
search_text="What is Copilot Studio?", # BM25
vector_queries=[VectorQuery(
vector=query_embedding, # Vector
k_nearest_neighbors=50,
fields="contentVector"
)],
select=["id", "content", "sourcePage", "category"],
top=10
)
```
### Azure AI Foundry
- **Prompt flow:** Visuell orkestrasjon av RAG-pipelines (indexing → retrieval → generation)
- **Evaluation:** Built-in metrics (groundedness, relevance, coherence)
- **Tracing:** End-to-end observability av RAG-calls
### Semantic Kernel
- **Memory connectors:** Abstraksjon over Azure AI Search, Cosmos DB, Qdrant
- **Plugins:** Modulær arkitektur for retrieval functions
- **Planner:** Agent-basert orkestrering for Agentic RAG
### Copilot Studio
- **Generative answers:** Low-code RAG med Azure AI Search + SharePoint
- **Knowledge sources:** Drag-and-drop indexing av docs, websites
- **Conversation boosting:** Automatisk faller tilbake på RAG hvis intent ikke matches
---
## Offentlig sektor (Norge)
### Datasuverenitet og residency
| Krav | RAG-implikasjon |
|------|-----------------|
| **GDPR Art. 32 (sikkerhet)** | Embeddings kan inneholde PII. Krypter vector store, bruk Managed Identity for autentisering. |
| **Schrems II (dataoverføring)** | Bruk Azure Norway regions (Norway East/West). Sjekk at embeddings ikke sendes utenfor EU. |
| **Forvaltningsloven § 11a (innsyn)** | RAG må kunne vise kilder for svar. Citation tracking er obligatorisk. |
| **AI Act (høyrisiko-AI)** | Hvis RAG brukes i forvaltningsvedtak, krev menneske-i-loop og dokumentasjon av retrieval-logikk. |
### Compliance-sjekkliste
- [ ] **Document-level RBAC:** Filtrer søkeresultater basert på brukers AD-gruppe.
- [ ] **Audit logging:** Logg alle queries, retrieved chunks, og genererte svar (Azure Monitor).
- [ ] **PII detection:** Skann og rediger PII i indexing og output (Azure AI Content Safety).
- [ ] **Data retention:** Definer retention policy for embeddings og logs (6 måneder standard).
- [ ] **Explainability:** Vis alltid kilder, confidence score, og retrieval-logikk.
### Typetilfeller for offentlig sektor
| Use case | RAG-mønster | Compliance-fokus |
|----------|-------------|------------------|
| **Regelverksøk** (lovdata, forskrifter) | Advanced RAG + metadata filtering | Citation, audit logging |
| **Saksbehandler-assistent** | Agentic RAG + document-level RBAC | GDPR, Forvaltningsloven § 11a |
| **Kundeservice chatbot** | Naive RAG (FAQ) | PII redaction, data residency |
| **Policy-analyse** | Agentic RAG + multi-index | AI Act transparency krav |
---
## Kostnad og lisensiering
### Prismodell (per 1,000 brukere/måned, Norge, 2026)
| Komponent | Kostnad (NOK) | Merk |
|-----------|---------------|------|
| **Azure AI Search (S1, 10M vectors)** | 15,000 | Semantic Ranker: +5,000 NOK |
| **Azure OpenAI embeddings (text-embedding-3-large, 1B tokens)** | 1,500 | Batching reduserer kostnad 50% |
| **Azure OpenAI generation (GPT-4o, 10M tokens output)** | 60,000 | Input tokens: 20,000 NOK |
| **Azure AI Document Intelligence (10K pages)** | 1,200 | For document cracking |
| **Azure Monitor (logging)** | 2,000 | For audit trails |
| **Total (Advanced RAG)** | ~83,700 NOK/mnd | Naive RAG: ~50,000 (uten reranking/DI) |
### Kostnadsoptimaliseringstips
1. **Caching:** Cache embeddings for repeterte queries (50-70% kostnadskutt).
2. **Batching:** Batch embedding-generering (50% rabatt via Azure OpenAI batch API).
3. **Chunk reuse:** Generer embeddings én gang, ikke per user session.
4. **Model downgrade:** Bruk text-embedding-ada-002 (10x billigere) for non-critical use cases.
5. **Semantic Ranker on-demand:** Aktiver kun for complex queries (identifiser via query length/complexity).
6. **Hybrid caching:** Cache både retrieval results og generated responses (LLM cache hit = gratis).
---
## For arkitekten (Cosmo)
### Nøkkelspørsmål å stille kunden
1. **Datakilde:** Hvor ligger kunnskapsbasen? (SharePoint, Dataverse, SQL, filshare, ekstern API?)
2. **Data-dynamikk:** Hvor ofte endres dataen? (Sanntid, daglig, månedlig, statisk?)
3. **Query-kompleksitet:** Enkle spørsmål ("Hva er...") eller multi-hop reasoning ("Sammenlign X og Y basert på Z")?
4. **Citation-krav:** Må systemet vise kilder? Hvor granulært (dokument, side, paragraf)?
5. **Latency-toleranse:** Akseptabel responstid? (<1s, 1-3s, >5s?)
6. **Compliance:** GDPR, Schrems II, AI Act? Offentlig sektor?
7. **Volum:** Hvor mange dokumenter? Hvor mange queries per dag?
8. **Tilgangskontroll:** Trenger brukere ulik tilgang til dokumenter? (RBAC, document-level filtering?)
### Vanlige fallgruver
| Fallgruve | Hvordan unngå |
|-----------|---------------|
| **For store chunks** | Test chunk sizes (256, 512, 1024 tokens). Mål retrieval recall. |
| **Manglende metadata** | Alltid legg til source, date, category, access_control ved indexing. |
| **Ingen reranking** | Semantic Ranker gir 20-30% bedre relevans. Alltid inkluder i prod. |
| **Hardkodet prompts** | Bruk parametriserte prompt templates. Test med ulike query-typer. |
| **Token overflow** | Monitor context window usage. Implementer chunk truncation-logikk. |
| **Ingen evaluation** | Definer retrieval recall/precision targets. Bruk Azure AI Foundry evaluation. |
### Anbefalinger per modenhetsnivå
| Modenhet | RAG-mønster | Tooling | Tidsestimat |
|----------|-------------|---------|-------------|
| **Pilot** (MVP) | Naive RAG | Copilot Studio generative answers | 1-2 uker |
| **Produksjon** (scale) | Advanced RAG | Azure AI Foundry Prompt flow + Semantic Kernel | 6-8 uker |
| **Advanced** (complex) | Agentic RAG | Microsoft Agent Framework + custom agents | 12-16 uker |
### Quick-start playbook
**Uke 1-2: Indexing**
1. Document cracking (Azure AI Document Intelligence)
2. Chunking (512 tokens, 10% overlap)
3. Embedding generation (text-embedding-3-large)
4. Indexing i Azure AI Search
**Uke 3-4: Retrieval**
1. Hybrid search setup (vector + BM25)
2. Semantic Ranker aktivering
3. Metadata filtering (source, date, category)
4. Retrieval evaluation (recall@10)
**Uke 5-6: Generation**
1. Prompt engineering (system prompt + context injection)
2. Citation tracking (source attribution i output)
3. Hallucination mitigation (grounding prompts)
4. Output evaluation (groundedness, relevance)
**Uke 7-8: Produksjonisering**
1. Caching (query results + LLM responses)
2. Observability (Azure Monitor + Application Insights)
3. RBAC enforcement (document-level filtering)
4. Load testing (concurrent users, latency targets)
---
## Kilder og verifisering
### Microsoft Learn-referanser
- [What is Retrieval Augmented Generation with Azure AI Search?](https://learn.microsoft.com/en-us/azure/search/retrieval-augmented-generation-overview) (GA)
- [Hybrid search in Azure AI Search](https://learn.microsoft.com/en-us/azure/search/hybrid-search-overview) (GA)
- [Semantic ranking in Azure AI Search](https://learn.microsoft.com/en-us/azure/search/semantic-search-overview) (GA)
- [Integrate Azure OpenAI with Azure AI Search](https://learn.microsoft.com/en-us/azure/search/vector-search-integrated-vectorization-ai-studio) (GA)
- [Use generative answers in Copilot Studio](https://learn.microsoft.com/en-us/microsoft-copilot-studio/nlu-boost-conversations) (GA)
- [Semantic Kernel memory and embeddings](https://learn.microsoft.com/en-us/semantic-kernel/memories/) (GA)
- [Azure AI Foundry prompt flow for RAG](https://learn.microsoft.com/en-us/azure/ai-studio/how-to/flow-develop) (GA)
### Konfidensnivå
- **Verified:** Arkitekturmønstre, Azure AI Search features, Azure OpenAI embeddings, Semantic Kernel patterns (basert på Microsoft Learn + GA-tjenester)
- **Baseline:** Kostnadsestimater (basert på Azure pricing januar 2026, kan variere per region)
- **Assumed:** Agentic RAG adoption timeline (basert på current preview status i Microsoft Agent Framework)
---
**For Cosmo:** Når kunde spør om RAG, start med "Naive vs Advanced vs Agentic"-beslutningstreet. Identifiser data source, query complexity, og latency-krav først. Hvis offentlig sektor: alltid spør om GDPR/Schrems II/AI Act compliance før du foreslår arkitektur. Hvis customer mangler evaluation strategy: stopp og definer retrieval recall/precision targets før du går videre med implementation.