Semantische Suche

Die Stichwortsuche findet Dokumente, die Tokens mit der Anfrage teilen. Sobald jemand „was kostet das“ statt „Preise“ tippt, ist sie blind. Semantische Suche schließt diese Lücke: Inhalte werden in Vektoren eingebettet, die Anfrage ebenfalls, und die Nähe im Vektorraum entscheidet mit.

AACSearch bietet zwei Wege dorthin — Auto-Embedding, bei dem die Engine die Vektoren beim Indizieren selbst erzeugt, und explizite Vektoren, die Ihr Ingest-Job mitliefert.

Auto-EmbeddingCopy Anchor Link

Ein Feld vom Typ float[] mit embed-Block im Indexschema aktiviert Auto-Embedding für den ganzen Index:

{
	"name": "embedding",
	"type": "float[]",
	"embed": {
		"from": ["title", "content"],
		"model": "openai/text-embedding-3-small"
	},
	"facet": false,
	"optional": true,
	"index": true
}

Suchdienst ruft den Embedder beim Schreiben auf und speichert den Vektor im Feld. Dokumente, die Sie später mit POST /documents hinzufügen, werden genauso eingebettet, ohne dass Ihr Code den Vektor kennt.

Anbieterschlüssel und Zugangsdaten in URLs werden verschlüsselt gespeichert und in Schemaantworten maskiert. Alte Klartextwerte bleiben kompatibel lesbar; der Rotationsbefehl verschlüsselt sie. Änderungen an Modell, Quellfeldern, Endpunkt oder Schlüssel erfordern einen Neuaufbau des Index.

Voraussetzungen:

• Engine-Version 30.0 oder neuer — prüfen Sie GET /capabilities auf features.autoEmbedding.
• Der Tarif muss hybridSearch enthalten. Free nicht; Pro und Enterprise schon.
• Der Embedding-Anbieter muss vom Knoten aus erreichbar sein. OpenAI-Modelle ohne eigene URL können die verwaltete Plattform-Authentifizierung nutzen. Eigene URLs erhalten nur ausdrücklich angegebene Kundenzugangsdaten. Integrierte Modelle und andere Anbieter erhalten den OpenAI-Plattformschlüssel nicht.

Ein Index ohne Auto-Embedding-Feld kann semantic=true nicht nutzen — die Anfrage scheitert mit 400 INVALID_QUERY:

{
	"error": {
		"code": "INVALID_QUERY",
		"message": "Index \"documentation\" has no auto-embedding field",
		"request_id": "req_8c0e2b4d6f8a0c2e4b6d8f0a"
	}
}

Hybride SucheCopy Anchor Link

curl -sS -G "$AAC_API/indexes/documentation/search" \
  -H "Authorization: Bearer $AAC_KEY" \
  --data-urlencode "q=was kostet der pro tarif" \
  --data-urlencode "semantic=true" \
  --data-urlencode "alpha=0.6" \
  --data-urlencode "per_page=5"

Was dabei intern passiert: Das Embedding-Feld wird an query_by angehängt, prefix wird auf false gezwungen (remote Embedder können nicht präfix-matchen) und eine vector_query mit k gleich per_page ergänzt. Suchdienst verschmilzt beide Ranglisten.

alpha steuert die Mischung:

Ein brauchbarer Startwert für Dokumentation und Support-Inhalte ist 0.6; für Kataloge mit exakten Produktnamen eher 0.3. Für kurze Anfragen mit einem Wort liefert 0 oft das bessere Ergebnis — ein Vektor hat bei „SSO“ wenig Kontext.

Explizite VektorenCopy Anchor Link

Wenn Sie Vektoren außerhalb der Engine erzeugen (eigenes Modell, eigene Pipeline, Reproduzierbarkeit), deklarieren Sie das Feld ohne embed:

{
	"name": "embedding",
	"type": "float[]",
	"num_dim": 1536,
	"facet": false,
	"index": true
}

und schicken den Vektor im Dokument mit:

curl -sS -X POST "$AAC_API/indexes/documentation/documents" \
  -H "Authorization: Bearer $AAC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      { "external_id": "pricing", "title": "Preise", "content": "Pro kostet 29 USD im Monat.", "embedding": [0.0123, -0.0456, 0.0789] }
    ]
  }'

Abfragen laufen dann mit vector_query statt semantic:

curl -sS -G "$AAC_API/indexes/documentation/search" \
  -H "Authorization: Bearer $AAC_KEY" \
  --data-urlencode "q=preise" \
  --data-urlencode "vector_query=embedding:([0.0123,-0.0456,0.0789], k:10, alpha:0.5)"

k ist die Zahl der Kandidaten aus dem kNN, alpha dieselbe Mischung wie oben. Zu großes k kostet Latenz, zu kleines lässt relevante Treffer gar nicht erst ins Ranking. vectorSearch muss im Tarif enthalten sein — Free hat es nicht.

Die Dimensionen müssen exakt zu num_dim passen, sonst lehnt die Engine das Dokument ab und es landet in failed.

Wenn der Vektor nicht hilftCopy Anchor Link

• Filtern statt suchen. Wer nach category:=pricing filtert, braucht keine Semantik. filter_by läuft vor dem Ranking und ist billiger.
• Tippfehler sind kein Semantikproblem. Dafür ist num_typos da; Vektoren fangen Tippfehler nur zufällig.
• Latenz. Semantische Suche ist teurer: Der Embedder muss die Anfrage vektorisieren, bevor die Engine suchen kann. took_ms steigt typischerweise um 20–80 ms. Wenn das nicht in Ihr Budget passt, cachen Sie Embeddings häufiger Anfragen oder nutzen Sie search_cutoff_ms.
• Gemischte Sprache. Ein multilinguales Embedding-Modell deckt mehrere Sprachen in einem Index ab — ein reines text-embedding-3-small auf einem deutschen Index liefert für deutsche Umformulierungen schlechtere Nachbarn als für englische.

Prüfen, ob es wirktCopy Anchor Link

Vergleichen Sie nicht nach Gefühl, sondern über die Analytics: zeroResultRate sollte sinken, ctr steigen. Ein A/B-Test zwischen zwei Profilen mit unterschiedlichem alpha ist der sauberere Weg — siehe A/B-Experimente. Für den schnellen Blick:

curl -sS "$AAC_API/analytics/overview?days=7" \
  -H "Authorization: Bearer $AAC_KEY"

Steigt avgLatencyMs deutlich und ctr nicht, ist alpha zu hoch oder das Embedding-Modell passt nicht zum Inhalt.

Schemaansichten und Migrationspläne zeigen Anbieterschlüssel und URL-Zugangsdaten als ***. Die Maske behält die gespeicherten Zugangsdaten für denselben Anbieter und Endpunkt bei. Bei einem Wechsel sind die Zugangsdaten erneut anzugeben. Für die Bearbeitung eines anderen Feldes muss der Schlüssel nicht kopiert werden.