feat(ms-ai-architect): add plugin to open marketplace (v1.5.0 baseline)
Initial addition of ms-ai-architect plugin to the open-source marketplace. Private content excluded: orchestrator/ (Linear tooling), docs/utredning/ (client investigation), generated test reports and PDF export script. skill-gen tooling moved from orchestrator/ to scripts/skill-gen/. Security scan: WARNING (risk 20/100) — no secrets, no injection found. False positive fixed: added gitleaks:allow to Python variable reference in output-validation-grounding-verification.md line 109. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Kjell Tore Guttormsen
parent
a8d79e4484
commit
6a7632146e
490 changed files with 213249 additions and 2 deletions
|
|
@ -0,0 +1,294 @@
|
|||
# Citation Tracking and Source Attribution
|
||||
|
||||
**Last updated:** 2026-02
|
||||
**Status:** GA (classic RAG), Preview (agentic retrieval)
|
||||
**Category:** RAG Architecture & Semantic Search
|
||||
|
||||
---
|
||||
|
||||
## Introduksjon
|
||||
|
||||
Citation tracking er en kritisk komponent i enterprise RAG-systemer. Det handler om å spore og eksponere kildene som ligger til grunn for AI-genererte svar, slik at brukere kan verifisere informasjonen. I Azure-økosystemet støttes citation tracking gjennom to hovedmønstre: **Classic RAG** (GA) med Azure AI Search og Azure OpenAI, og **Agentic Retrieval** (Preview) med strukturerte grounding data.
|
||||
|
||||
God citation tracking reduserer hallusinering ved å tvinge LLM-en til å basere seg på hentet kontekst, gir brukerne tillit til svarene, og oppfyller compliance-krav i offentlig sektor der sporbarhet er lovpålagt. Azure AI Search returnerer automatisk kildemetadata med søkeresultater, og Azure OpenAI "On Your Data"-mønsteret inkluderer citation annotations i responser.
|
||||
|
||||
Agentic Retrieval (preview 2025/2026) representerer neste evolusjon med LLM-assistert query planning, parallelle subqueries, og strukturerte citation-responser med full provenance tracking.
|
||||
|
||||
## Kjernekomponenter
|
||||
|
||||
### Citation-formater
|
||||
|
||||
#### URL Citation Annotations (Azure OpenAI)
|
||||
|
||||
```python
|
||||
for event in stream_response:
|
||||
if event.type == "response.output_item.done":
|
||||
if event.item.type == "message":
|
||||
text_content = event.item.content[-1]
|
||||
for annotation in text_content.annotations:
|
||||
if annotation.type == "url_citation":
|
||||
print(f"URL: {annotation.url}")
|
||||
print(f"Start: {annotation.start_index}")
|
||||
print(f"End: {annotation.end_index}")
|
||||
```
|
||||
|
||||
#### File Citation Annotations (Assistants API)
|
||||
|
||||
```python
|
||||
message_content = message.content[0].text
|
||||
annotations = message_content.annotations
|
||||
citations = []
|
||||
|
||||
for index, annotation in enumerate(annotations):
|
||||
message_content.value = message_content.value.replace(
|
||||
annotation.text, f' [{index}]'
|
||||
)
|
||||
if file_citation := getattr(annotation, 'file_citation', None):
|
||||
cited_file = client.files.retrieve(file_citation.file_id)
|
||||
citations.append(
|
||||
f'[{index}] {file_citation.quote} from {cited_file.filename}'
|
||||
)
|
||||
|
||||
message_content.value += '\n' + '\n'.join(citations)
|
||||
```
|
||||
|
||||
### Citation Metadata-elementer
|
||||
|
||||
| Element | Beskrivelse | Eksempel |
|
||||
|---------|-------------|---------|
|
||||
| `title` | Dokument- eller kildetittel | "Veileder for offentlige anskaffelser" |
|
||||
| `url` | URL til kildedokument | `https://docs.example.com/guide` |
|
||||
| `file_id` | Referanse til opplastet fil | `file-abc123` |
|
||||
| `snippet` | Relevant utdrag fra kilden | "I henhold til §4..." |
|
||||
| `doc_uri` | Dokumentlokasjon | `docs/mlflow/guide.md` |
|
||||
| `chunk_id` | Spesifikk chunk-identifikator | `chunk_001` |
|
||||
| `relevance_score` | Konfidensverdi | 0.95 |
|
||||
| `start_index` / `end_index` | Tekstregion som er grounded | 142 / 287 |
|
||||
|
||||
### Grounding Data (Agentic Retrieval)
|
||||
|
||||
```json
|
||||
{
|
||||
"grounding_data": "Ekstraherte relevante passasjer...",
|
||||
"references": [
|
||||
{
|
||||
"title": "Dokumenttittel",
|
||||
"url": "https://...",
|
||||
"chunk_id": "chunk_001",
|
||||
"relevance_score": 0.95
|
||||
}
|
||||
],
|
||||
"activity": [
|
||||
{
|
||||
"operation": "subquery_1",
|
||||
"tokens_used": 150,
|
||||
"latency_ms": 245
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Arkitekturmønstre
|
||||
|
||||
### Mønster 1: Classic RAG med automatisk citation
|
||||
|
||||
**Flyt:** Query → Azure AI Search → Top-k dokumenter med metadata → LLM med citation-instruks → Svar med fotnoter
|
||||
|
||||
**Implementering:**
|
||||
```python
|
||||
template = """
|
||||
Answer the following question using only the context below.
|
||||
Include citations [1], [2] etc. for each fact.
|
||||
Only include information specifically discussed in the context.
|
||||
|
||||
Question: {question}
|
||||
Context: {context}
|
||||
"""
|
||||
```
|
||||
|
||||
**Fordeler:**
|
||||
- Enkel implementering via Azure OpenAI "On Your Data"
|
||||
- Automatisk citation-generering
|
||||
- GA-funksjonalitet, produksjonsklart
|
||||
|
||||
**Ulemper:**
|
||||
- LLM kan fremdeles hallusinere citations
|
||||
- Krever post-validering av citation-nøyaktighet
|
||||
- Begrenset til kontekstvindu-størrelse
|
||||
|
||||
### Mønster 2: Agentic Retrieval med provenance
|
||||
|
||||
**Flyt:** Query → LLM query planning → Subqueries → Parallel retrieval → Grounding data + references → LLM → Svar med strukturerte citations
|
||||
|
||||
**Fordeler:**
|
||||
- Full provenance tracking (hvilke subqueries hentet hvilke dokumenter)
|
||||
- Strukturert output med references array
|
||||
- Activity log for audit og debugging
|
||||
- LLM planlegger optimale søk for bedre dekning
|
||||
|
||||
**Ulemper:**
|
||||
- Preview-funksjon, ikke GA ennå
|
||||
- Høyere kompleksitet og token-kostnad
|
||||
- Ranking tokens gratis kun under initial preview-fase
|
||||
|
||||
### Mønster 3: Fakta-verifisering med LLM-judge
|
||||
|
||||
**Flyt:** RAG-svar med citations → Fakta-verifikasjon-agent → Krysssjekk mot kildedokumenter → Verifisert svar
|
||||
|
||||
```python
|
||||
from azure.ai.evaluation import GroundednessProEvaluator
|
||||
|
||||
groundedness_eval = GroundednessProEvaluator(
|
||||
azure_ai_project=project,
|
||||
credential=credential,
|
||||
threshold=2
|
||||
)
|
||||
|
||||
result = groundedness_eval(
|
||||
query="Hva er reglene for offentlige anskaffelser?",
|
||||
response="I henhold til anskaffelsesloven §4...",
|
||||
context="Anskaffelsesloven §4 sier at..."
|
||||
)
|
||||
```
|
||||
|
||||
**Fordeler:**
|
||||
- Automatisk validering av citation-nøyaktighet
|
||||
- Kan flagge hallusinerte fakta
|
||||
- Skalerbar QA-pipeline
|
||||
|
||||
**Ulemper:**
|
||||
- Ekstra LLM-kall = ekstra kostnad
|
||||
- LLM-judges er ikke ufeilbarlige
|
||||
- Økt latency
|
||||
|
||||
## Beslutningsveiledning
|
||||
|
||||
### Når bruke hvilket mønster
|
||||
|
||||
| Scenario | Anbefaling | Begrunnelse |
|
||||
|----------|------------|-------------|
|
||||
| Intern kunnskapsbase | Classic RAG med citations | GA, tilstrekkelig for de fleste behov |
|
||||
| Publikumstjenester (høy tillit) | Agentic + fakta-verifisering | Sporbarhet og kvalitetssikring er kritisk |
|
||||
| Juridisk/medisinsk rådgivning | Alle tre mønstre | Maksimal grounding og verifisering |
|
||||
| Intern chatbot | Classic RAG | Enklest og billigst |
|
||||
| Compliance-rapportering | Agentic med full audit log | Activity-loggen dokumenterer hele søkeprosessen |
|
||||
|
||||
### Vanlige feil
|
||||
|
||||
1. **Ikke validere citations post-generering** — LLM-er kan generere plausible men feilaktige kildereferanser
|
||||
2. **Mangle chunk-til-dokument-mapping** — Brukere trenger å navigere til kilden, ikke bare se en chunk-ID
|
||||
3. **Ignorere konfidensscoring** — Vis ikke citations med lav relevance_score som primærkilde
|
||||
4. **Glemme tilgangskontroll** — Citations til dokumenter brukeren ikke har tilgang til er en sikkerhetsfeil
|
||||
|
||||
### Røde flagg
|
||||
|
||||
- Citations som peker til ikke-eksisterende dokumenter → Hallusinering i citation-genereringen
|
||||
- Høy andel scores under 0.5 → Dårlig retrieval-kvalitet, ikke kun citation-problem
|
||||
- Brukere som rapporterer at citations ikke stemmer → Trenger fakta-verifiseringslagret
|
||||
|
||||
## Konfidensscoring
|
||||
|
||||
### Tilgjengelige scoring-mekanismer
|
||||
|
||||
| Mekanisme | Skala | Kilde |
|
||||
|-----------|-------|-------|
|
||||
| Semantic Ranking | 0.0–4.0 | Azure AI Search |
|
||||
| Vector Similarity (Cosine) | 0.333–1.0 | Azure AI Search |
|
||||
| Groundedness Pro | Threshold-basert | Azure AI Content Safety |
|
||||
| Semantic Answer Confidence | 70% terskel | Azure AI Search |
|
||||
| Custom relevance_score | 0.0–1.0 | Applikasjonskode |
|
||||
|
||||
### Anbefalte terskelverdier for RAG
|
||||
|
||||
| Terskelverdi | Handling |
|
||||
|-------------|---------|
|
||||
| rerankerScore ≥ 3.0 | Vis citation med høy konfidensindikator |
|
||||
| rerankerScore 2.0–3.0 | Vis citation med moderat konfidensindikator |
|
||||
| rerankerScore < 2.0 | Utelat fra primærcitations, men behold i "Se også" |
|
||||
| relevance_score < 0.5 | Ikke vis som citation |
|
||||
|
||||
## Integrasjon med Microsoft-stakken
|
||||
|
||||
| Tjeneste | Rolle i citation tracking |
|
||||
|----------|--------------------------|
|
||||
| **Azure AI Search** | Primær retrieval med metadata og scores |
|
||||
| **Azure OpenAI** | LLM-generering med citation annotations |
|
||||
| **Azure AI Foundry** | Evaluering av groundedness og citation-kvalitet |
|
||||
| **MLflow** | Tracing og observerbarhet for citation pipeline |
|
||||
| **Azure AI Content Safety** | Groundedness-deteksjon med korreksjonsfunksjon |
|
||||
| **Copilot Studio** | Automatisk citation i Copilot-svar |
|
||||
|
||||
## Offentlig sektor (Norge)
|
||||
|
||||
### Lovmessige krav
|
||||
- **Forvaltningsloven:** Vedtak skal begrunnes med referanse til relevant regelverk
|
||||
- **Offentleglova:** Innsynsrett krever sporbar saksbehandling
|
||||
- **AI Act:** Transparenskrav for AI-systemer i offentlig forvaltning
|
||||
- **Arkivloven:** Dokumentasjon av beslutningsgrunnlag
|
||||
|
||||
### Praktiske implikasjoner
|
||||
- Citations er ikke bare "nice to have" — de er juridisk nødvendige i mange offentlige kontekster
|
||||
- Audit trail (agentic retrieval activity log) kan brukes som dokumentasjon for tilsyn
|
||||
- Brukere i offentlig sektor forventer å kunne klikke seg gjennom til kildedokumentet
|
||||
|
||||
### Sikkerhet
|
||||
- Dokumentnivå-sikkerhet (RBAC) må filtrere citations basert på brukeridentitet
|
||||
- Sensitive dokumenter skal ikke siteres til brukere uten tilgang
|
||||
- Implement security trimming i Azure AI Search før citations eksponeres
|
||||
|
||||
## Kostnad og lisensiering
|
||||
|
||||
### Komponenter som påvirker kostnad
|
||||
|
||||
| Komponent | Kostnadsdriver |
|
||||
|-----------|---------------|
|
||||
| Azure AI Search | Standard spørringskostnad (ingen ekstra for metadata) |
|
||||
| Semantic Ranker | Per 1000 requests (1000 gratis/mnd) |
|
||||
| Azure OpenAI | Token-kostnad for citation-generering i LLM-respons |
|
||||
| Agentic Retrieval | Ranking tokens (gratis under preview), Azure OpenAI for query planning |
|
||||
| Groundedness Pro | Per evaluerings-kall (Azure AI Content Safety) |
|
||||
|
||||
### Kostnadsoptimering
|
||||
- Returner kun citation-relevante felt via `select` for å redusere token-bruk
|
||||
- Bruk caching for gjentatte queries med samme citations
|
||||
- Evaluer groundedness kun for brukervendte svar, ikke interne prosesser
|
||||
- Begrens antall citations per svar (3–5 er typisk tilstrekkelig)
|
||||
|
||||
## For arkitekten (Cosmo)
|
||||
|
||||
### Spørsmål å stille kunden
|
||||
1. Har dere lovmessige krav til sporbarhet og kildehenvisning?
|
||||
2. Skal brukerne kunne navigere direkte til kildedokumentene?
|
||||
3. Hvilken grad av konfidensindikasjon trenger brukerne?
|
||||
4. Er det behov for audit trail av hele retrieval-prosessen?
|
||||
5. Har dokumentene ulik sikkerhetsgraddering som påvirker citation-eksponering?
|
||||
6. Hva er akseptabel feilrate for citations (hallusinerte kilder)?
|
||||
7. Trengs fakta-verifisering, eller er standard citation tilstrekkelig?
|
||||
8. Hvordan chunkes dokumentene — trengs chunk-til-dokument navigering?
|
||||
|
||||
### Fallgruver
|
||||
- Å anta at LLM-genererte citations alltid er korrekte — de er ikke det
|
||||
- Å eksponere chunk-IDer i brukergrensesnittet uten å mappe dem til lesbare dokumentreferanser
|
||||
- Å bruke agentic retrieval i produksjon uten å forstå at det er preview
|
||||
- Å ignorere tilgangskontroll i citation-laget — dette er et vanlig sikkerhetshull
|
||||
|
||||
### Anbefalinger per modenhetsnivå
|
||||
| Nivå | Anbefaling |
|
||||
|------|------------|
|
||||
| **Starter** | Classic RAG med Azure OpenAI "On Your Data" citation |
|
||||
| **Intermediær** | Custom citation-formatering, konfidensscoring, chunk-til-dokument mapping |
|
||||
| **Avansert** | Agentic retrieval med provenance, fakta-verifisering, audit logging |
|
||||
|
||||
## Kilder og verifisering
|
||||
|
||||
### Verified (MCP-research)
|
||||
- [RAG overview in Azure AI Search](https://learn.microsoft.com/en-us/azure/search/retrieval-augmented-generation-overview)
|
||||
- [Agentic retrieval overview](https://learn.microsoft.com/en-us/azure/search/agentic-retrieval-overview)
|
||||
- [Transparency note for Azure AI Search](https://learn.microsoft.com/en-us/azure/ai-foundry/responsible-ai/search/transparency-note)
|
||||
- [Grounding data design](https://learn.microsoft.com/en-us/azure/well-architected/ai/grounding-data-design)
|
||||
- [Azure AI Foundry agents - AI Search tools](https://learn.microsoft.com/en-us/azure/ai-foundry/agents/how-to/tools/ai-search)
|
||||
|
||||
### Baseline (modellkunnskap)
|
||||
- Norsk lovgivning (Forvaltningsloven, Offentleglova, Arkivloven)
|
||||
- Kostnadsoptimerings-anbefalinger
|
||||
- Modenhetsnivå-tabellen
|
||||
Loading…
Add table
Add a link
Reference in a new issue