RAG Ingestion¶

Stand: 2026-05-25

Ziel¶

Die Wiki-/Gitea-Dokumentation soll nicht nur als Markdown lesbar sein, sondern auch als Knowledge-Index fuer Agenten nutzbar werden.

Aktive Zielkomponenten:

Qdrant im Agent-Runtime-LXC 259
Collection fuer Doku: lanstyle_docs
Collection fuer secretfreie Infrastruktur-Summaries: lanstyle_inventory
Embedding-Modell: nomic-embed-text:latest
Embedding-Provider: Ollama auf dem GB10

Script¶

Repository:

agent-runtime/scripts/ingest-docs-to-qdrant.py

Das Script:

liest Markdown unter docs/
entfernt Codebloecke und Markdown-Links fuer saubere Embedding-Texte
chunked Dokumente in kleine Abschnitte
erzeugt Embeddings ueber Ollama
legt die Qdrant-Collection an
schreibt Punkte mit Payload source, source_system, last_refreshed_at, source_hash, collection, chunk, text, type, embedding_model
setzt customer_context, damit Agenten später nach Kundenkontext filtern können
setzt bei Inventardaten zusätzlich Scope-Felder, damit Prefixe/VLANs verschiedener Standorte nicht vermischt werden

Freshness-Felder¶

Neue und aktualisierte Punkte in lanstyle_docs und lanstyle_inventory erhalten ab 2026-05-25 diese Governance-Felder:

Feld	Bedeutung
`source_system`	Ursprungssystem, zum Beispiel `mkdocs`, `netbox`, `npm` oder `proxmox`
`last_refreshed_at`	UTC-Zeitpunkt des Ingest-Laufs
`source_hash`	SHA-256 über Quelle und normalisierten Inhalt
`collection`	Ziel-Collection, zum Beispiel `lanstyle_docs` oder `lanstyle_inventory`
`source_site`	NetBox-Site oder abgeleiteter Standortkontext, wenn vorhanden
`source_tenant`	NetBox-Tenant oder abgeleiteter Kundenkontext, wenn vorhanden
`source_scope`	NetBox-Scope, Site, Cluster oder Gruppe fuer standortgenaue Abfragen
`source_type`	technischer Quellentyp, zum Beispiel `netbox`, `npm` oder `proxmox`

Bestehende Punkte werden nicht separat migriert. Die Felder werden beim nächsten Re-Ingest geschrieben. Dadurch bleibt die Migration risikoarm und nachvollziehbar.

Scope-aware Inventory¶

NetBox-Prefixe und VLANs duerfen nicht nur ueber VID oder Prefix korreliert werden. VLAN-IDs sind je Standort wiederverwendbar. Ab 2026-05-25 exportiert agent-runtime/scripts/netbox-export-summary.sh deshalb fuer Prefixe und VLANs den vollstaendigen Kontext:

Feldgruppe	Inhalt
Prefix	`id`, `prefix`, `scope_type`, `scope_id`, `scope`, `site`, `tenant`, `role`, `status`, `description`
VLAN	`vlan.id`, `vlan.vid`, `vlan.name`, `vlan.display`, `vlan.description`, `vlan.group`
Direktfelder	`vlan_id`, `vlan_vid`, `vlan_name`, `vlan_group` fuer einfache Filter
Governance	`tags`, `custom_fields`, `comments`

RAG-Agenten sollen bei NetBox-Antworten mindestens nach source_site, source_tenant oder source_scope filtern. Eine reine Suche nach VLAN 70 ist nicht ausreichend.

Beispiel fuer korrekte Trennung:

Kontext	VLAN	Prefix	Bedeutung
`source_site=Jena`, `source_tenant=Sportgymnasium Jena`	`70 Haustechnik`	`10.7.0.0/24`	SGJ/Jena Haustechnik, produktiver Bestand
`source_site=Lindenstraße`, `source_tenant=Lanstyle IT Solutions GmbH`	`70 LS_AI_Services`	`10.222.70.0/24`	geplantes AI-Services-VLAN, noch nicht produktiv migriert

Aktueller Index¶

Aktueller Lauf am 2026-05-25:

Wert	Ergebnis
Collection	`lanstyle_docs`
Dateien	`56`
Chunks/Punkte	`289`
Qdrant Status	`green`

Ausfuehrung¶

export QDRANT_API_KEY='aus Vaultwarden laden'
agent-runtime/scripts/ingest-docs-to-qdrant.py

Optionen:

agent-runtime/scripts/ingest-docs-to-qdrant.py \
  --docs-dir docs \
  --collection lanstyle_docs \
  --qdrant-url http://10.222.70.20:6333 \
  --ollama-base-url http://gb10-01.ad.lanstyle.de:11434

Für vollständige Neuaufbauten ohne Alt-Chunks:

agent-runtime/scripts/ingest-docs-to-qdrant.py --recreate

Sicherheit¶

Es werden nur Markdown-Dokumente aus dem Repository indexiert.
Secrets dürfen nicht in docs/ liegen.
Der bestehende Secret-Scan bleibt vor Commits Pflicht.
Qdrant ist nur mit API-Key nutzbar und der Key liegt in Vaultwarden.

Suche¶

Repository:

agent-runtime/scripts/query-qdrant-docs.py

Beispiel:

export QDRANT_API_KEY='aus Vaultwarden laden'
agent-runtime/scripts/query-qdrant-docs.py "LiteLLM OpenCode externer Zugriff" --top-k 5

Ausgabe:

Score
source
chunk
Textauszug

Snapshots¶

Repository:

agent-runtime/scripts/snapshot-qdrant.sh

Produktiver Zielpfad auf LXC 259:

/opt/agent-runtime/backups/qdrant/

Letzter Snapshot:

/opt/agent-runtime/backups/qdrant/lanstyle_docs-8529590124808714-2026-05-25-17-00-24.snapshot

Fuer andere Collections:

QDRANT_COLLECTION=lanstyle_inventory agent-runtime/scripts/snapshot-qdrant.sh

Infrastruktur-Inventar¶

Repository:

agent-runtime/scripts/ingest-inventory-to-qdrant.py

Quelle sind secretfreie JSON-Summaries unter:

agent-runtime/exports/

Bei Verzeichnissen werden bevorzugt *-latest*.json-Summaries ingestiert. Historische Exportdateien bleiben fuer Audits erhalten, werden aber nicht in den aktuellen Inventory-Kontext gemischt. Das verhindert, dass alte, kontextarme NetBox-Exports neue Scope-Felder ueberlagern.

Aktueller Lauf am 2026-05-25:

Wert	Ergebnis
Collection	`lanstyle_inventory`
Dateien	`3`
Objekte/Punkte	`730`
Qdrant Status	`green`
Letzter Snapshot	`/opt/agent-runtime/backups/qdrant/lanstyle_inventory-8529590124808714-2026-05-25-18-28-17.snapshot`

Beispiel:

export QDRANT_API_KEY='aus Vaultwarden laden'
agent-runtime/scripts/ingest-inventory-to-qdrant.py --recreate
agent-runtime/scripts/query-qdrant-docs.py \
  "NetBox Lanstyle Lindenstrasse" \
  --collection lanstyle_inventory \
  --top-k 5

Nächster Ausbau¶

Kundenkontext-Map weiter verfeinern, sobald weitere NetBox-Sites und Kunden-Repositories verbindlich gepflegt sind.