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
commit
baa2d0220b
488 changed files with 213221 additions and 0 deletions
|
|
@ -0,0 +1,324 @@
|
|||
# RAG Evaluation Metrics and Frameworks
|
||||
|
||||
**Last updated:** 2026-02
|
||||
**Status:** GA (Azure AI Evaluation SDK), Preview (agentic evaluators, Groundedness Pro)
|
||||
**Category:** RAG Architecture & Semantic Search
|
||||
|
||||
---
|
||||
|
||||
## Introduksjon
|
||||
|
||||
Evaluering av RAG-systemer er en av de mest undervurderte fasene i enterprise AI-utvikling. Uten systematisk evaluering er det umulig å vite om endringer i chunking, embedding, retrieval eller prompting faktisk forbedrer kvaliteten. Azure AI Foundry tilbyr et komplett evaluerings-rammeverk med 30+ innebygde evaluatorer, LLM-as-judge, human evaluation, og integrasjon med MLflow for produksjonsovervåking.
|
||||
|
||||
RAG-evaluering dekker to distinkte dimensjoner: **retrieval quality** (fant vi de riktige dokumentene?) og **generation quality** (genererte LLM-en et godt svar basert på dokumentene?). Azure AI Evaluation SDK operasjonaliserer dette med spesialiserte evaluatorer for groundedness, relevance, completeness, utilization og mer — tilgjengelig som Python-pakke (`azure-ai-evaluation`).
|
||||
|
||||
Et kritisk poeng for offentlig sektor: LLM-judges bruker EU-hostede modeller for EU/EØS-arbeidsområder, noe som sikrer datasuverenitet i evalueringsprosessen.
|
||||
|
||||
## Kjernekomponenter
|
||||
|
||||
### Retrieval-metrikker
|
||||
|
||||
| Metrikk | Hva den måler | Optimal bruk |
|
||||
|---------|---------------|-------------|
|
||||
| **Precision@K** | Andel relevante dokumenter blant topp K resultater | Evaluere presisjon i retrieval |
|
||||
| **Recall@K** | Andel av alle relevante dokumenter funnet i topp K | Evaluere dekning |
|
||||
| **MRR** (Mean Reciprocal Rank) | Gjennomsnittlig invers rang av første relevante resultat | Evaluere rangering |
|
||||
| **NDCG** (Normalized Discounted Cumulative Gain) | Evaluerer ranking-kvalitet sammenlignet med ideell rekkefølge | Evaluere ranking med gradert relevans |
|
||||
| **MAP** (Mean Average Precision) | Gjennomsnittlig presisjon over alle relevante dokumenter | Overordnet retrieval-kvalitet |
|
||||
|
||||
### Genererings-metrikker
|
||||
|
||||
#### RAG-spesifikke evaluatorer (Azure AI)
|
||||
|
||||
| Evaluator | Hva den måler | Metode |
|
||||
|-----------|---------------|--------|
|
||||
| `GroundednessEvaluator` | Er svaret basert på konteksten? | LLM-judge |
|
||||
| `GroundednessProEvaluator` | Forbedret groundedness med Content Safety | Azure AI Content Safety |
|
||||
| `RelevanceEvaluator` | Er svaret relevant for spørsmålet? | LLM-judge |
|
||||
| `ResponseCompletenessEvaluator` | Svarer svaret på alle deler av spørsmålet? | LLM-judge |
|
||||
| `RetrievalEvaluator` | Kvalitet på hentede dokumenter | LLM-judge |
|
||||
| `DocumentRetrievalEvaluator` | Dokumentnivå retrieval-kvalitet | LLM-judge |
|
||||
|
||||
#### Tekstuell likhet
|
||||
|
||||
| Evaluator | Hva den måler |
|
||||
|-----------|---------------|
|
||||
| `SimilarityEvaluator` | Semantisk likhet (cosine på embeddings) |
|
||||
| `F1ScoreEvaluator` | Vektet gjennomsnitt av precision og recall |
|
||||
| `BleuScoreEvaluator` | N-gram presisjon for maskinoversettelse |
|
||||
| `RougeScoreEvaluator` | N-gram overlap for summarisering |
|
||||
| `MeteorScoreEvaluator` | Eksakt match, stemming, synonymer |
|
||||
|
||||
#### Generell kvalitet
|
||||
|
||||
| Evaluator | Hva den måler |
|
||||
|-----------|---------------|
|
||||
| `CoherenceEvaluator` | Logisk flyt og struktur |
|
||||
| `FluencyEvaluator` | Språklig kvalitet |
|
||||
|
||||
#### Agentic evaluatorer (Preview)
|
||||
|
||||
| Evaluator | Hva den måler |
|
||||
|-----------|---------------|
|
||||
| `IntentResolutionEvaluator` | Forstod agenten brukerens intensjon? |
|
||||
| `ToolCallAccuracyEvaluator` | Kalte agenten riktige verktøy? |
|
||||
| `TaskAdherenceEvaluator` | Fulgte agenten oppgaveinstruksjonene? |
|
||||
|
||||
### Evaluerings-metoder
|
||||
|
||||
| Metode | Kostnad | Pålitelighet | Bruk |
|
||||
|--------|---------|-------------|------|
|
||||
| **Deterministisk** | Lav | Høy (for målbare ting) | Latency, token-bruk, presisjon |
|
||||
| **LLM-as-Judge** | Medium | God (krever tuning) | Groundedness, relevans, koherens |
|
||||
| **Human Evaluation** | Høy | Høyest | Domene-spesifikk kvalitet, edge cases |
|
||||
| **Automatisert harness** | Lav-medium | Varierer | Batch-evaluering, CI/CD |
|
||||
|
||||
## Arkitekturmønstre
|
||||
|
||||
### Mønster 1: Offline evaluering i utviklingsfasen
|
||||
|
||||
**Flyt:** Test-datasett → RAG-pipeline → Resultater → Azure AI Evaluation SDK → Metrics-rapport
|
||||
|
||||
```python
|
||||
from azure.ai.evaluation import evaluate, GroundednessEvaluator, RelevanceEvaluator
|
||||
|
||||
model_config = {
|
||||
"azure_endpoint": os.environ["AZURE_OPENAI_ENDPOINT"],
|
||||
"api_key": os.environ["AZURE_OPENAI_KEY"],
|
||||
"azure_deployment": os.environ["AZURE_OPENAI_DEPLOYMENT"],
|
||||
}
|
||||
|
||||
result = evaluate(
|
||||
data="test_data.jsonl",
|
||||
evaluators={
|
||||
"groundedness": GroundednessEvaluator(model_config),
|
||||
"relevance": RelevanceEvaluator(model_config),
|
||||
},
|
||||
evaluator_config={
|
||||
"default": {
|
||||
"column_mapping": {
|
||||
"query": "${data.query}",
|
||||
"context": "${data.context}",
|
||||
"response": "${data.response}"
|
||||
}
|
||||
}
|
||||
},
|
||||
output_path="./evaluation_results.json"
|
||||
)
|
||||
|
||||
print(result["metrics"])
|
||||
```
|
||||
|
||||
**Fordeler:**
|
||||
- Systematisk, reproduserbar evaluering
|
||||
- Kan kjøres i CI/CD
|
||||
- Støtter batch-prosessering
|
||||
|
||||
**Ulemper:**
|
||||
- Krever test-datasett
|
||||
- LLM-judge-kostnader kan akkumulere
|
||||
- Offline — fanger ikke produksjonsproblemer
|
||||
|
||||
### Mønster 2: Online evaluering med MLflow tracing
|
||||
|
||||
**Flyt:** Produksjons-RAG → MLflow trace spans → Metrikksamling → Dashboard → Alerting
|
||||
|
||||
```python
|
||||
import mlflow
|
||||
from mlflow.entities import Document, SpanType
|
||||
|
||||
@mlflow.trace(span_type=SpanType.RETRIEVER)
|
||||
def retrieve_docs(query: str):
|
||||
return [
|
||||
Document(
|
||||
page_content="Relevant innhold...",
|
||||
metadata={"source": "veileder.pdf", "relevance_score": 0.95}
|
||||
)
|
||||
]
|
||||
|
||||
@mlflow.trace(span_type=SpanType.CHAT_MODEL)
|
||||
def generate_answer(question: str, documents: list):
|
||||
# LLM-kall med kontekst
|
||||
return "Generert svar..."
|
||||
|
||||
@mlflow.trace(span_type=SpanType.CHAIN)
|
||||
def rag_pipeline(question: str):
|
||||
docs = retrieve_docs(question)
|
||||
response = generate_answer(question, docs)
|
||||
return {"answer": response, "sources": [d.metadata for d in docs]}
|
||||
```
|
||||
|
||||
**Fordeler:**
|
||||
- Real-time observerbarhet
|
||||
- Fanger produksjonsmønstre
|
||||
- Integrert med Azure ML
|
||||
|
||||
**Ulemper:**
|
||||
- Overhead fra tracing
|
||||
- Krever infrastruktur for metrikksamling
|
||||
- Mer kompleks oppsett
|
||||
|
||||
### Mønster 3: Human-in-the-loop evaluering
|
||||
|
||||
**Flyt:** RAG-output → Review App → Domeneekspert-vurdering → Feedback-logging → Modellforbedering
|
||||
|
||||
Bruk `mlflow.log_feedback()` med `AssessmentSourceType.HUMAN` for å logge menneskelig evaluering.
|
||||
|
||||
**Fordeler:**
|
||||
- Høyest kvalitet evaluering
|
||||
- Fanger domene-spesifikke nyanser
|
||||
- Bygger ground truth-datasett over tid
|
||||
|
||||
**Ulemper:**
|
||||
- Skalerer dårlig
|
||||
- Subjektivt
|
||||
- Kostbart (arbeidstid)
|
||||
|
||||
## Beslutningsveiledning
|
||||
|
||||
### Evalueringsrammeverk-valg
|
||||
|
||||
| Scenario | Anbefalt verktøy | Begrunnelse |
|
||||
|----------|-------------------|-------------|
|
||||
| Azure-natve RAG | Azure AI Evaluation SDK | Best integrasjon, 30+ evaluatorer |
|
||||
| Databricks-basert | MLflow 3 | Native integration, Mosaic AI |
|
||||
| Eksperimentering | RAG Experiment Accelerator | CLI-basert, hyperparameter-tuning |
|
||||
| Produksjon | MLflow + Azure Monitor | Tracing + alerting |
|
||||
| CI/CD | Azure AI Evaluation SDK | Batch-evaluering i pipeline |
|
||||
|
||||
### Metrikkombinations-strategi
|
||||
|
||||
| Mål | Metrikker å kombinere | Hva det avdekker |
|
||||
|-----|----------------------|------------------|
|
||||
| Svarskvalitet | Groundedness + Correctness | Om systemet tolker kontekst riktig |
|
||||
| Retrieval-effektivitet | Utilization + Completeness | Om retrieval-systemet henter nok |
|
||||
| Transformasjonskvalitet | Groundedness + Utilization + Similarity | Om systemet bevarer sannhet under transformering |
|
||||
| Overordnet RAG-helse | Alle + Coherence + Fluency | Helhetsvurdering |
|
||||
|
||||
### Vanlige feil
|
||||
|
||||
1. **Evaluere kun generering, ikke retrieval** — Dårlige svar skyldes ofte dårlig retrieval, ikke dårlig generering
|
||||
2. **Bruke kun én metrikk** — Groundedness alene forteller ingenting om completeness
|
||||
3. **Evaluere på for lite data** — 50+ test-queries er minimum for pålitelige resultater
|
||||
4. **Glemme baseline** — Uten baseline vet du ikke om forbedringene er reelle
|
||||
5. **Ignorere edge cases** — Test med tomme resultater, irrelevante dokumenter, multilinguale queries
|
||||
|
||||
### Røde flagg
|
||||
|
||||
- Groundedness < 70% → Alvorlig hallusinerings-problem
|
||||
- Retrieval Precision@5 < 50% → Indeksering eller embedding-problemer
|
||||
- Store avvik mellom LLM-judge og human evaluation → LLM-judge trenger kalibrering
|
||||
- Fallende scores over tid → Data drift eller modellendringer
|
||||
|
||||
## Verktøy og SDKer
|
||||
|
||||
### Primær-verktøy
|
||||
|
||||
| Verktøy | Installasjon | Bruk |
|
||||
|---------|-------------|------|
|
||||
| Azure AI Evaluation SDK | `pip install azure-ai-evaluation` | Offline/batch evaluering |
|
||||
| MLflow 3 | `pip install mlflow` | Tracing + online evaluering |
|
||||
| Prompt Flow | Via Azure AI Foundry | End-to-end utvikling |
|
||||
|
||||
### Spesialverktøy
|
||||
|
||||
| Verktøy | Formål | Lenke |
|
||||
|---------|--------|-------|
|
||||
| RAG Experiment Accelerator | Systematisk RAG-optimering | [GitHub](https://github.com/microsoft/rag-experiment-accelerator) |
|
||||
| Mosaic AI Agent Evaluation | Agentic-spesifikk evaluering | Azure Databricks |
|
||||
| Azure AI Studio Portal | Visuell evaluering og testing | portal.azure.com |
|
||||
|
||||
### Token-budsjetter for evaluatorer
|
||||
|
||||
| Evaluator | Token-budsjett |
|
||||
|-----------|---------------|
|
||||
| Standard evaluatorer | 800 tokens |
|
||||
| `RetrievalEvaluator` | 1600 tokens |
|
||||
| `ToolCallAccuracyEvaluator` | 3000 tokens |
|
||||
|
||||
## Integrasjon med Microsoft-stakken
|
||||
|
||||
| Tjeneste | Rolle i evaluering |
|
||||
|----------|-------------------|
|
||||
| **Azure AI Foundry** | Sentral evaluerings-plattform med portal og SDK |
|
||||
| **Azure OpenAI** | Judge-modeller for LLM-basert evaluering |
|
||||
| **MLflow** | Tracing, observerbarhet, human feedback |
|
||||
| **Azure Monitor** | Alerting og dashboards for produksjonsmetrikker |
|
||||
| **Azure DevOps / GitHub Actions** | CI/CD-integrasjon for automatisert evaluering |
|
||||
| **Azure AI Content Safety** | Groundedness Pro-evaluering |
|
||||
|
||||
## Offentlig sektor (Norge)
|
||||
|
||||
### Data residency for evaluering
|
||||
- LLM-judges bruker **EU-hostede modeller** for EU/EØS-arbeidsområder
|
||||
- US-hostede modeller for andre regioner
|
||||
- Sikrer datasuverenitet i evalueringsprosessen
|
||||
- Abuse monitoring kan opts ut av med godkjenning
|
||||
|
||||
### Compliance-relatert evaluering
|
||||
- **AI Act:** Krever dokumentert evaluering av AI-systemer
|
||||
- **Forvaltningsloven:** Krav til kvalitetssikring av vedtaksgrunnlag
|
||||
- **GDPR:** Evalueringsdata kan inneholde personopplysninger — håndtér med forsiktighet
|
||||
|
||||
### Anbefalte metrikker for offentlig sektor
|
||||
1. **Groundedness** (obligatorisk) — Svar skal være basert på verifiserbare kilder
|
||||
2. **Correctness** — Spesielt viktig for juridisk/regelverk-rådgivning
|
||||
3. **Safety** — Content Safety-evaluatorer for å sikre forsvarlig innhold
|
||||
4. **Completeness** — Unngå ufullstendige svar på komplekse spørsmål
|
||||
|
||||
## Kostnad og lisensiering
|
||||
|
||||
### Evalueringskostnader
|
||||
|
||||
| Komponent | Kostnad |
|
||||
|-----------|---------|
|
||||
| Azure AI Evaluation SDK | Gratis (open source) |
|
||||
| LLM-judge-kall | Azure OpenAI token-kostnad per evaluering |
|
||||
| Groundedness Pro | Azure AI Content Safety-prising |
|
||||
| MLflow | Gratis (open source), compute-kostnad for hosting |
|
||||
| Human evaluation | Arbeidstid |
|
||||
|
||||
### Kostnadsoptimering
|
||||
- Bruk `gpt-4o-mini` som judge-modell (billigere enn `gpt-4o`, tilstrekkelig kvalitet)
|
||||
- Evaluer kun representative utvalg, ikke alle queries
|
||||
- Kjør tunge evalueringer (Groundedness Pro) kun før releases
|
||||
- Bruk deterministiske metrikker (F1, ROUGE) der det er tilstrekkelig
|
||||
|
||||
## For arkitekten (Cosmo)
|
||||
|
||||
### Spørsmål å stille kunden
|
||||
1. Har dere et test-datasett med spørsmål og forventede svar?
|
||||
2. Hvilke kvalitetskrav har dere — groundedness, completeness, nøyaktighet?
|
||||
3. Er det behov for kontinuerlig evaluering i produksjon, eller kun ved releases?
|
||||
4. Hvem skal vurdere kvaliteten — domeneeksperter, utviklere, eller begge?
|
||||
5. Har dere CI/CD der evaluering kan integreres?
|
||||
6. Hva er budsjett for LLM-judge-kall i evaluering?
|
||||
7. Trengs det compliance-dokumentasjon av evalueringsresultater?
|
||||
|
||||
### Fallgruver
|
||||
- Å evaluere kun med LLM-judges uten human validation — LLM-judges har egne bias
|
||||
- Å optimere for én metrikk på bekostning av andre — groundedness uten completeness gir korte, ufullstendige svar
|
||||
- Å ikke ha baseline — uten sammenligning er metrics meningsløse
|
||||
- Å evaluere for sjelden — RAG-kvalitet kan degenerere over tid uten overvåking
|
||||
|
||||
### Anbefalinger per modenhetsnivå
|
||||
| Nivå | Anbefaling |
|
||||
|------|------------|
|
||||
| **Starter** | Groundedness + Relevance evaluering med Azure AI SDK, 50+ test-queries |
|
||||
| **Intermediær** | Legg til MLflow tracing, CI/CD-integrasjon, multiple metrikker |
|
||||
| **Avansert** | Produksjonsovervåking, human-in-the-loop, A/B-testing av RAG-konfigurasjoner |
|
||||
|
||||
## Kilder og verifisering
|
||||
|
||||
### Verified (MCP-research)
|
||||
- [Azure AI Evaluation SDK](https://learn.microsoft.com/en-us/azure/ai-foundry/how-to/develop/evaluate-sdk)
|
||||
- [RAG LLM Evaluation Phase](https://learn.microsoft.com/en-us/azure/architecture/ai-ml/guide/rag/rag-llm-evaluation-phase)
|
||||
- [RAG Solution Design Guide](https://learn.microsoft.com/en-us/azure/architecture/ai-ml/guide/rag/rag-solution-design-and-evaluation-guide)
|
||||
- [Built-in RAG Evaluators](https://learn.microsoft.com/en-us/azure/ai-foundry/concepts/evaluation-evaluators/rag-evaluators)
|
||||
- [Azure AI Foundry Observability](https://learn.microsoft.com/en-us/azure/ai-foundry/concepts/observability)
|
||||
- [RAG Experiment Accelerator](https://github.com/microsoft/rag-experiment-accelerator)
|
||||
|
||||
### Baseline (modellkunnskap)
|
||||
- Metrikkbeskrivelser basert på IR-teori (MRR, NDCG, MAP)
|
||||
- Kostnadsoptimerings-tips
|
||||
- Modenhetsnivå-anbefalinger
|
||||
Loading…
Add table
Add a link
Reference in a new issue