vector stats

vector stats zeigt Modell-Signatur, Coverage und Dateigröße des vault-lokalen Vektor-Index. Reine Lese-Operation — weder Graph noch Vektor-Index werden mutiert.

Wofür ist das?

• Sanity-Check nach vector ping. ping sagt dir, ob der Embedding-Service läuft; stats sagt dir, ob der Index zu deinem Vault tatsächlich Daten enthält und wie viele Entitäten noch fehlen.
• Erkennen von Modell-Drift. Die ausgegebene Modell-Signatur (Name, Dimension, Chunking-Version) ist die Wahrheit über den persistierten Index. Wenn sie nicht mehr zur Konfiguration passt, ist ein vector rebuild --force fällig — die Spec macht Modellwechsel zum Breaking Change.
• Coverage-Indikator. „Wie weit ist der Embedding-Worker?" beantwortest du in einer Zeile. Coverage 100% heißt: jeder Entität im Graph entspricht mindestens ein Chunk im Index.

Aufruf

apparat vector stats --vault=recherche

Beispielausgabe

Index gefüllt, vollständige Coverage:

Vault "recherche" — vector index:

  Model:            jina/jina-embeddings-v2-base-de
  Dimension:        768
  Chunking version: 3
  Last rebuild:     never (incremental only)

  Chunks indexed:   1842
  Entities indexed: 1000
  Entities total:   1000 (graph)
  Coverage:         100.0% (0 missing)

 Vector file: .apparat/vectors.sqlite (12.4 MB)

Frischer Vault, noch nichts geschrieben:

Vault "recherche" — vector index:

  Index not yet initialised. Run `apparat vector rebuild` once entities have been written,
  or wait for the embedding worker to process the queue.

Index aktiv, aber Modell oder Chunking-Version weichen ab:

Vault "recherche" — vector index:

  Model:            jina/jina-embeddings-v2-base-de
  Dimension:        768
  Chunking version: 3
  Last rebuild:     never (incremental only)

  …

⚠ Vector index drift: model "jina/jina-embeddings-v2-base-de" → "alibaba-NLP/gte-large-de". Run `apparat vector rebuild --force`.

Die Warnung erscheint, sobald der persistierte Index nicht mehr zur Laufzeit-Konfiguration (APPARAT_EMBEDDING_MODEL, aktuelle Chunking-Version) passt. Das Kommando bleibt bei Exit-Code 0 — nur eine Warnzeile —, weil die Detektion selbst nicht der Fehler ist; der Fehler tritt beim nächsten Schreibvorgang ein, sofern du keinen vector rebuild --force zwischenschiebst.

Felder im Detail

• Model. Der Modell-String wie er beim ersten Schreiben im Index hinterlegt wurde. Stimmt er nicht mit APPARAT_EMBEDDING_MODEL überein, ist der Index inkonsistent — alle weiteren Embedding-Schreibvorgänge schlagen mit einer expliziten Fehlermeldung fehl, bis du vector rebuild --force aufrufst.
• Dimension. Vektor-Dimension (z. B. 768). Wird beim ersten Schreiben fixiert; ein Modell mit anderer Dimension löst einen Hard-Fault aus.
• Chunking version. Schema-Version des Chunkers, der die persistierten Chunks erzeugt hat. Erhöht sich, wenn die Chunking-Logik in der Codebase geändert wird.
• Last rebuild. ISO-8601-Zeitstempel des letzten erfolgreichen Voll-Rebuilds, oder never (incremental only), falls der Index ausschließlich inkrementell durch den Watcher gefüllt wurde — im laufenden Betrieb der Normalfall.
• Chunks indexed. Summe aller Zeilen in der chunks-Tabelle. Bei zwei-Ebenen-Chunking liegt der Faktor pro Entität typischerweise zwischen 1 (kurz) und 5+ (lang).
• Entities indexed. Anzahl unterschiedlicher entity_id-Werte mit mindestens einem Chunk.
• Entities total. Anzahl aller Entitäten im Graph-Index. Quelle ist graph.sqlite, nicht das Dateisystem — ein vorhandener graph rebuild ist Voraussetzung für aussagekräftige Coverage.
• Coverage. entities_indexed / entities_total, in Prozent. Differenz = Drift; Detail siehe vector drift.

Exit-Codes

vector stats selbst wertet Coverage nicht — Coverage 0% liefert weiterhin Exit-Code 0. Nutze vector drift für einen monitor-fähigen Indikator.