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,440 @@
# RAG Context Windows and Long-Context Models
**Last updated:** 2026-02
**Status:** GA
**Category:** RAG Architecture & Semantic Search
---
## Introduksjon
Context window-størrelse er en av de mest kritiske faktorene som bestemmer kvaliteten og kostnaden for en RAG-løsning. En language model har en begrenset kapasitet for tokens den kan prosessere i en enkelt request — dette omtales som modellens context window. For RAG-implementasjoner må man balansere mellom å gi modellen nok kontekst til å generere gode svar, uten å overbelaste context window eller sløse med tokens (som koster penger).
Med innføringen av long-context models som GPT-4 Turbo (128k tokens) og GPT-4.1 (context windows opp til 200k+ tokens), har arkitekter fått nye muligheter: skal man fortsatt bruke klassisk RAG med retrieval av små, relevante chunks, eller kan man nå sende hele dokumenter direkte til modellen? Svaret avhenger av use case, kostnad, latency-krav og modellens faktiske evne til å utnytte store context windows — kjent som "lost-in-the-middle"-problemet.
I denne kunnskapsreferansen dekkes token budgeting, context window management, og når man skal velge RAG-basert chunking versus long-context direct prompting, med fokus på Azure OpenAI-modeller og integrasjon i Microsoft-stakken.
---
## Kjernekomponenter
### Context Window vs. Token Limit
| Begrep | Definisjon |
|--------|-----------|
| **Context Window** | Totalt antall tokens modellen kan prosessere (input + output) i én request |
| **Max Prompt Tokens** | Maksimalt antall input tokens (brukermelding + system prompt + retrieved documents + conversation history) |
| **Max Completion Tokens** | Maksimalt antall output tokens modellen kan generere som svar |
| **Token Budget** | Planlagt fordeling av tokens mellom ulike komponenter (system prompt, history, grounding data, buffer) |
**Verified (Azure OpenAI):**
- GPT-4 Turbo: 128k tokens context window
- GPT-4.1 series: Opp til 200k+ tokens context window
- GPT-4o: 128k tokens
- o1-series: Varierende (o1: 200k, o3-mini: 128k)
### Token Budget Allocation
En RAG-prompt består typisk av:
1. **System message** (50500 tokens): Instruksjoner om oppførsel og svarformat
2. **Conversation history** (02000 tokens): Tidligere brukerforespørsler og svar
3. **Retrieved context** (50010,000 tokens): Dokumenter/chunks hentet fra vektordatabase
4. **User query** (10200 tokens): Brukerens nåværende spørsmål
5. **Response buffer** (2004000 tokens): Reservert plass til modellens genererte svar
**Best practice:**
For GPT-4 Turbo (128k context):
- Reserved for system/history/query: ~5-10k tokens
- Retrieved context: Max 30-50k tokens (ikke hele window)
- Response buffer: 2-4k tokens
For GPT-4.1 (200k context):
- Retrieved context: Kan økes til 100k tokens, men kvalitet avtar (lost-in-the-middle)
- Reserved: 10-15k tokens
### Prompt Compression Techniques
Når man nærmer seg token limit, kan man bruke:
| Teknikk | Beskrivelse | Trade-off |
|---------|-------------|-----------|
| **Semantic truncation** | Fjern minst relevante chunks fra retrieved context | Risiko for tap av relevant informasjon |
| **History summarization** | Komprimer tidligere conversation history til sammendrag | Reduserer kontekstuell forståelse |
| **Token-aware chunking** | Del dokumenter i chunks som passer innenfor token budget | Økt kompleksitet i indexing pipeline |
| **Retrieval limiting** | Reduser antall chunks hentet (top-k parameter) | Lavere recall, kan misse relevante kilder |
**Baseline (generell kunnskap):**
Azure OpenAI Assistants API støtter automatisk truncation via `max_prompt_tokens` og `truncation_strategy` parameters.
### Lost-in-the-Middle Effect
**Verified (Research):**
Studier viser at LLMs har svakere performance når relevant informasjon er plassert midt i en lang context — de presterer best når viktig info er i starten eller slutten av prompten.
**RAG-implikasjoner:**
- Ikke anta at større context window = bedre svar
- Bruk semantic ranking for å sikre at de mest relevante chunks plasseres først
- For long-context models: overvei map-reduce eller sliding window pattern
### Long-Context LLMs
| Modell | Context Window | Anbefalt RAG-strategi |
|--------|---------------|----------------------|
| GPT-4 Turbo | 128k | Klassisk RAG (top-10 til top-50 chunks) |
| GPT-4.1 | 200k+ | Hybrid: RAG for precision queries, long-context for exploratory |
| GPT-4o | 128k | Klassisk RAG med hybrid search |
| o1-series | 200k | Long-context for reasoning tasks, RAG for factual grounding |
**Baseline:**
Long-context models reduserer behovet for aggressive chunking, men øker token cost og latency.
---
## Arkitekturmønstre
### Mønster 1: Klassisk RAG med Token-Aware Retrieval
**Beskrivelse:**
Hent et begrenset antall høyt relevante chunks (f.eks. top-10), og pass dem inn i en prompt som holder seg godt under context window limit.
**Fordeler:**
- Lavere token cost (kun relevante chunks sendes)
- Raskere inference (mindre input å prosessere)
- Bedre kontroll over token budget
- Fungerer godt med modeller som har mindre context windows (32k128k)
**Ulemper:**
- Avhenger av retrieval-kvalitet (dårlig ranking = dårlige svar)
- Kan misse informasjon som ligger spredt i flere dokumenter
**Når bruke:**
Standard for de fleste RAG-implementasjoner, spesielt når kostnad og latency er prioritert.
**Verified (Azure AI Search):**
Azure AI Search støtter hybrid queries (keyword + vector) med semantic ranking for å finne de mest relevante chunks innenfor et token budget.
---
### Mønster 2: Long-Context Direct Prompting
**Beskrivelse:**
Send hele dokumenter (eller store seksjoner) direkte til en long-context model uten chunking eller retrieval-prosess.
**Fordeler:**
- Ingen tap av informasjon fra aggressive chunking
- Enklere arkitektur (ikke behov for vektor-database eller embeddings)
- Fungerer godt for summarization, analyse av hele dokumenter
**Ulemper:**
- Høyere token cost (sender alt, ikke bare relevant)
- Tregere inference (modellen må prosessere hele dokumentet)
- Lost-in-the-middle effekt kan redusere accuracy
- Ikke skalerbart for store dokumentsamlinger (100+ dokumenter)
**Når bruke:**
- Dokumentsamlinger er små (<10 dokumenter)
- Brukerforespørsler krever bred kontekst (f.eks. "sammenlign alle seksjonene i denne policyen")
- Budget tillater høyere token cost
**Baseline:**
Passende for ad-hoc analyser, men ikke for produksjons-RAG-løsninger med mange brukere.
---
### Mønster 3: Sliding Window (Incremental Context)
**Beskrivelse:**
Del et stort dokument i overlappende vinduer (chunks med 1020% overlap), og kjør modellen på hvert vindu sekvensielt. Aggreger svarene.
**Fordeler:**
- Håndterer ekstremt store dokumenter (over 200k tokens)
- Unngår lost-in-the-middle problemet
- Kan paralleliseres for raskere prosessering
**Ulemper:**
- Kompleks aggregeringslogikk (hvordan kombinere delsvar?)
- Ikke egnet for spørsmål som krever sammenheng på tvers av hele dokumentet
**Når bruke:**
- Legal document analysis (lange kontrakter, lover)
- Scientific papers med streng struktur
- Når brukerspørsmål kan besvares fra én seksjon om gangen
**Baseline:**
Sjeldnere brukt, men effektiv for spesialiserte domener.
---
## Beslutningsveiledning
### Når bruke RAG vs. Long-Context
| Kriterium | Bruk RAG (chunked retrieval) | Bruk Long-Context (hele dokumenter) |
|-----------|------------------------------|--------------------------------------|
| **Dokumentsamling** | Store (100+ dokumenter) | Små (<10 dokumenter) |
| **Query type** | Faktaspørsmål, lookup | Analyse, sammenligning, summarization |
| **Kostnad** | Lav til medium (kun relevante tokens) | Høy (sender alt) |
| **Latency** | Lav (mindre tokens å prosessere) | Høyere (modellen må lese alt) |
| **Retrieval kvalitet** | Avhenger av embeddings og ranking | Ikke relevant (sender alt) |
| **Modenhetsnivå** | Alle nivåer | Medium til høy (krever token-kostnadskontroll) |
### Vanlige Feil
| Feil | Konsekvens | Rettelse |
|------|-----------|----------|
| **Sender for mye context** | Høy token cost, lost-in-the-middle effekt | Bruk semantic ranking, reduser top-k |
| **Ignorerer token budget** | Requests feiler med 400 (exceeded context limit) | Implementer token counting (tiktoken) før API call |
| **Glemmer response buffer** | Modellen trunkerer svar midt i setning | Reserver 1520% av context window for output |
| **Bruker long-context for alle queries** | Unødvendig høy kostnad | Implementer query classification (enkel query → RAG, kompleks → long-context) |
### Røde Flagg
- **Token cost øker plutselig**: Sjekk om conversation history ikke blir trunked
- **Svarkvalitet synker**: Lost-in-the-middle — flytt viktigste chunks til start av prompt
- **Rate limit errors (429)**: Du overskrider Tokens-Per-Minute (TPM) quota
---
## Integrasjon med Microsoft-stakken
### Azure OpenAI Context Limits (Verified)
| Modell | Context Window | TPM (Default tier) | TPM (Enterprise tier) |
|--------|---------------|-------------------|----------------------|
| gpt-4 (turbo-2024-04-09) | 128k | 450k | 2M |
| gpt-4.1 | 200k+ | 1M | 5M |
| gpt-4o | 128k | 450k | 30M |
| gpt-4o-mini | 128k | 2M | 150M |
| o1 | 200k | 3M | 30M |
| o3-mini | 128k | 5M | 50M |
**Viktig:**
TPM (Tokens Per Minute) = Max tokens som kan prosesseres per minutt på deployment-nivå. Hvis du sender én request med 50k input tokens + 2k output tokens = 52k tokens → teller mot TPM.
### Azure OpenAI Assistants API (Verified)
**Max Prompt/Completion Tokens:**
Når du oppretter en Run i Assistants API, kan du sette:
```python
# Python example (Verified from Microsoft Learn)
run = client.beta.threads.runs.create(
thread_id=thread.id,
assistant_id=assistant.id,
max_prompt_tokens=20000, # Recommended minimum for File Search
max_completion_tokens=4000
)
```
**Truncation Strategy:**
- `auto`: Standard (OpenAI bestemmer hva som trunkeres)
- `last_messages`: Beholder kun N siste meldinger i conversation history
**Best practice (Verified):**
For File Search tool: Sett `max_prompt_tokens` til minimum 20,000. For lengre samtaler: 50,000 eller fjern limit helt.
### Semantic Kernel
**Token Management:**
Semantic Kernel (C#/.NET) har innebygd token counting via `PromptSection.Tokens`:
```csharp
// C# (Baseline — generell Semantic Kernel pattern)
var section = new PromptSection
{
Content = retrievedContext,
Tokens = maxTokens, // Request token budget for this section
Required = true
};
```
Semantic Kernel vil automatisk trunkere seksjoner hvis total token count overskrider modellens context window.
### Prompt Flow (Azure AI Foundry)
**Token Estimation:**
Prompt Flow viser estimert token count per node i flyten. Bruk dette for å debugge context window issues før deployment.
**Baseline (generell kjennskap):**
Du kan også bruke `tiktoken` Python library direkte i Prompt Flow nodes for mer presis token counting.
---
## Offentlig sektor (Norge)
### Token-Kostnader i Offentlige Budsjetter
**Context:**
Offentlige virksomheter må ofte forsvare AI-kostnader i budsjettprosesser. Token-forbruk er en operasjonell kostnad som skalerer med bruk.
**Anbefaling:**
- Implementer token logging per bruker/avdeling for å spore kostnad
- Bruk `max_prompt_tokens` og `max_completion_tokens` for å hindre "runaway cost" (f.eks. hvis en bruker sender ekstremt lange dokumenter)
- Vurder GPT-4o-mini eller GPT-4.1-mini for ikke-kritiske use cases (10x billigere enn GPT-4)
**Verified (Azure OpenAI Pricing):**
- GPT-4 Turbo input: ~$0.01 per 1k tokens
- GPT-4o input: ~$0.005 per 1k tokens
- GPT-4.1-mini input: ~$0.0001 per 1k tokens
(Husk å konvertere til NOK og inkluder output token cost, som ofte er 2-3x input cost.)
### Dataminimering (GDPR)
**Relevant for:**
Personvern-forskriften krever dataminimering — ikke send mer data til modellen enn nødvendig.
**RAG-fordel:**
Ved å bruke retrieval (ikke long-context direct prompting) sender du kun relevante chunks, som reduserer risikoen for å eksponere sensitiv informasjon utilsiktet i context.
**Best practice:**
Kombiner RAG med security trimming (Azure AI Search + Entra ID permissions) for å sikre at kun autoriserte dokumenter blir retrievet.
---
## Kostnad og lisensiering
### Prismodell per Token (Verified fra Azure OpenAI Pricing)
| Modell | Input (per 1k tokens) | Output (per 1k tokens) | Optimal RAG context size |
|--------|----------------------|------------------------|--------------------------|
| gpt-4-turbo | $0.01 | $0.03 | 10k30k tokens |
| gpt-4.1 | $0.015 | $0.045 | 10k50k tokens |
| gpt-4o | $0.005 | $0.015 | 10k30k tokens |
| gpt-4o-mini | $0.0005 | $0.0015 | 5k20k tokens |
**Eksempel (NOK, kurs 10.5):**
En query med 20k input tokens (retrieved context) + 500 output tokens på GPT-4o:
- Input: (20 × $0.005) × 10.5 = 1.05 NOK
- Output: (0.5 × $0.015) × 10.5 = 0.08 NOK
- **Total per query: ~1.13 NOK**
Hvis du har 10,000 queries per måned: **11,300 NOK/måned** (kun LLM-kostnad, ikke vektor-database eller search).
### Optimaliseringstips
1. **Bruk GPT-4o-mini for enkel retrieval** (f.eks. FAQ-lookup): 10x billigere
2. **Implementer caching** av frequently asked queries (reduserer token cost med 5080%)
3. **Batch processing** for ikke-interaktive workloads (Azure OpenAI Batch API: 50% rabatt)
4. **Monitorering**: Bruk Azure Monitor for å spore token usage per deployment
**Verified (Azure OpenAI Batch Quota):**
- gpt-4.1: 500M tokens per month (Enterprise tier), 30M (Default tier)
- gpt-4o: 500M (Enterprise), 30M (Default)
---
## For arkitekten (Cosmo)
### 58 Spørsmål å Stille Kunden
1. **Hvor store er dokumentene dere skal søke i?**
→ Hvis <10 dokumenter à <50k tokens: vurder long-context. Hvis 100+ dokumenter: bruk RAG.
2. **Hva er typiske brukerforespørsler?**
→ Faktaspørsmål (RAG) eller analyse/sammenligning (long-context)?
3. **Hva er akseptabel latency?**
→ <2 sekunder → RAG med små chunks. <5 sekunder → kan bruke long-context.
4. **Hva er token-budsjettet per query?**
→ Hvis stramt: Bruk GPT-4o-mini + classical RAG. Hvis romslig: GPT-4.1 + long-context.
5. **Hvor ofte oppdateres dokumentene?**
→ Dynamisk → RAG (indexer kan inkrementelt oppdateres). Statisk → long-context kan være OK.
6. **Er conversation history viktig?**
→ Ja → reserver 25k tokens for history. Implementer auto-truncation (tiktoken).
7. **Har dere eksisterende vektor-database?**
→ Ja → bruk RAG. Nei → vurder om long-context er enklere (men dyrere).
8. **Er dette en proof-of-concept eller produksjon?**
→ POC: Long-context er raskere å sette opp. Produksjon: RAG er mer kostnadseffektivt.
### Fallgruver
| Fallgruve | Hvorfor det skjer | Hvordan unngå |
|-----------|-------------------|---------------|
| **Oversender context** | Arkitekt antar "mer context = bedre svar" | Bruk semantic ranking, test med ulike top-k verdier |
| **Glemmer token counting** | Utvikler sender raw text uten å sjekke lengde | Implementer tiktoken pre-request validation |
| **Ignorerer lost-in-the-middle** | Stoler blindt på long-context models | Kjør ablation test: plasser svar i start vs. midt vs. slutt av prompt |
| **Manglende response buffer** | Regner kun input tokens, ikke output | Alltid reserver 1520% av context window for completion |
### Anbefalinger per Modenhetsnivå
**Nivå 1 (Starter med RAG):**
- Bruk GPT-4o-mini + classical RAG (top-10 chunks, hybrid search)
- Implementer token counting med tiktoken før hver request
- Sett `max_prompt_tokens=10000`, `max_completion_tokens=2000`
**Nivå 2 (Optimaliserer for produksjon):**
- Oppgrader til GPT-4o eller GPT-4.1 for bedre quality
- Implementer adaptive top-k (flere chunks for komplekse queries)
- Bruk Azure AI Search semantic ranking (re-rank top-50 til top-10)
- Monitorering: Track average tokens per query, cost per user
**Nivå 3 (Advanced RAG arkitektur):**
- Hybrid: Klassisk RAG for presise queries, long-context for exploratory
- Implementer query classification (LLM bestemmer om RAG eller long-context)
- Bruk Assistants API med custom truncation strategy
- A/B-testing av ulike context window sizes for å optimalisere cost/quality trade-off
---
## Kilder og verifisering
### Microsoft Learn (Verified via MCP)
1. **Azure OpenAI Assistants API — Context Window Management**
https://learn.microsoft.com/en-us/azure/ai-foundry/openai/concepts/assistants#context-window-management
*Dekning: max_prompt_tokens, max_completion_tokens, truncation strategy, File Search recommendations*
**Confidence: Verified**
2. **Retrieval-augmented Generation (RAG) in Azure AI Search**
https://learn.microsoft.com/en-us/azure/search/retrieval-augmented-generation-overview
*Dekning: Token constraint challenges, agentic vs. classic RAG, lost-in-the-middle effects*
**Confidence: Verified**
3. **Azure OpenAI in Microsoft Foundry Models — Quotas and Limits**
https://learn.microsoft.com/en-us/azure/ai-foundry/openai/quotas-limits
*Dekning: TPM limits per model, context window sizes, rate limits*
**Confidence: Verified**
4. **Azure OpenAI On Your Data — Token Usage Estimation**
https://learn.microsoft.com/en-us/azure/ai-foundry/openai/concepts/use-your-data#token-usage-estimation-for-azure-openai-on-your-data
*Dekning: Intent prompt vs. generation prompt token breakdown, RAG pipeline token costs*
**Confidence: Verified**
5. **Improve RAG Chain Quality (Azure Databricks)**
https://learn.microsoft.com/en-us/azure/databricks/generative-ai/tutorials/ai-cookbook/quality-rag-chain#llm
*Dekning: LLM parameter optimization, model selection for RAG, token constraints*
**Confidence: Verified**
6. **Chat Markup Language ChatML — Managing Conversations**
https://learn.microsoft.com/en-us/azure/ai-foundry/openai/how-to/chat-markup-language#preventing-unsafe-user-inputs
*Dekning: Token counting med tiktoken, conversation history truncation*
**Confidence: Verified**
7. **Code Sample: Token Counting with tiktoken (Python)**
https://learn.microsoft.com/en-us/azure/ai-foundry/openai/how-to/chatgpt
*Dekning: Praktisk implementasjon av token management i conversation loops*
**Confidence: Verified**
### Konfidensnivå per Seksjon
| Seksjon | Konfidens | Kilde |
|---------|-----------|-------|
| Azure OpenAI Context Limits | **Verified** | Microsoft Learn (quotas-limits) |
| Assistants API Token Management | **Verified** | Microsoft Learn (assistants API docs) |
| Token Usage Estimation | **Verified** | Microsoft Learn (use-your-data) |
| Lost-in-the-Middle Effect | **Baseline** | Generell forskning (ikke Microsoft-spesifikk) |
| Sliding Window Pattern | **Baseline** | Arkitekturmønster (ikke GA i Azure) |
| Token Pricing | **Verified** | Azure OpenAI Pricing (per februar 2026) |
| Semantic Kernel Token Management | **Baseline** | API-dokumentasjon, ikke testet i MCP |
---
**Oppsummering:**
Context window management er kritisk for RAG-suksess. Velg riktig strategi basert på dokumentstørrelse, query type, kostnad og latency-krav. Bruk token counting (tiktoken) for å unngå context limit errors, og vurder hybrid approach (RAG for presise queries, long-context for analyse) for avanserte use cases. Husk: Større context window betyr ikke alltid bedre svar — lost-in-the-middle effekten er reell.