Einbetten des Plugins

Das Embed-Plugin ist ein dünner Wrapper um Ollama’s /api/embeddings plus drei nützliche Hilfsmittel: Kosinusähnlichkeit, kompakte Base64-Packung und inverse Entpackung. Das RAG-Plugin verwendet es intern, ist aber auch selbstständig hilfreich – für Clustering, Deduplikation, semantische Suche und Anomalieerkennung.

API

$embed = (new \Nibiru\Module\Ai\Ai())->embed();

$vec     = $embed->one('controller');                  / float[]
$vectors = $embed->batch(['a', 'b', 'c']);             / float[][]

$score   = \Nibiru\Module\Ai\Plugin\Embed::cosine($a, $b);     / 0..1
$packed  = \Nibiru\Module\Ai\Plugin\Embed::pack($vec);          / base64 string
$vec     = \Nibiru\Module\Ai\Plugin\Embed::unpack($packed);     / back to float[]

Muster: Entfernen ähnlicher Zeichenfolgen

$embed = $ai->embed();
$candidates = ['How do I create a module?',
               'How can I make a new module?',
               'What is MMVC?'];

$vecs = $embed->batch($candidates);
foreach ($vecs as $i => $a) {
    foreach ($vecs as $j => $b) {
        if ($i >= $j) continue;
        $sim = \Nibiru\Module\Ai\Plugin\Embed::cosine($a, $b);
        if ($sim > 0.9) {
            echo "Near-dup: {$candidates[$i]} ≈ {$candidates[$j]} ($sim)\n";
        }
    }
}

Muster: semantische Markierung

$tags = ['authentication', 'forms', 'database', 'modules'];
$tagVecs = array_combine($tags, $embed->batch($tags));

function bestTag(string $text, array $tagVecs, $embed): string {
    $tv = $embed->one($text);
    $best = ['_unknown', -INF];
    foreach ($tagVecs as $tag => $vec) {
        $s = \Nibiru\Module\Ai\Plugin\Embed::cosine($tv, $vec);
        if ($s > $best[1]) $best = [$tag, $s];
    }
    return $best[0];
}

echo bestTag('User::isAuthorized', $tagVecs, $embed);  / → 'authentication'
echo bestTag('Pageination::setTable', $tagVecs, $embed); / → 'database' (probably)

Speicherung

Einbettungen sind Gleitkommazahlenarrays – typischerweise 768 Gleitkommazahlen für nomic-embed-text und 1024 für mxbai-embed-large. Das entspricht 3 KB oder 4 KB pro Vektor im Rohformat.

Verwenden Sie Embed::pack(), um sie als 4-Byte-Gleitkommazahlen in Base64 zu kodieren:

$compact = Embed::pack($vec);    / ~4 KB → ~5.3 KB base64 string
$vec     = Embed::unpack($compact);

Das RAG-Plugin verwendet dieses Format intern für seine JSON-Dateien.

Auswahl der eingebetteten Modelle

Ziehen Sie auf Ihrer Ollama.ai einmal:

curl https://your-ollama-host.example/api/pull -d '{"name":"nomic-embed-text"}'   # 768 dim, default
curl https://your-ollama-host.example/api/pull -d '{"name":"mxbai-embed-large"}'  # 1024 dim, higher quality

In ai.ini:

[AI]
embed.model = "nomic-embed-text"
embed.dim   = 768

Kombination von Modellen vermeiden

Vektoren aus nomic-embed-text und mxbai-embed-large befinden sich in unterschiedlichen geometrischen Räumen — der Kosinus zwischen ihnen ist ohne Bedeutung. Wenn Sie embed.model ändern, setzen Sie vor der Kombination jede RAG-Sammlung oder gespeicherten Embeddings zurück.

Häufige Fallen

• Aufrufen von one() in einer engen Schleife. Jeder Aufruf ist eine HTTP-Roundtrip. Für >100 Elemente bevorzugen Sie batch() (immer noch seriell unter der Haube, aber mit konsistenter Fehlerbehandlung).
• Speichern roher Gleitkommazahlenarrays in JSON. Verwenden Sie pack() für etwa 5-fach kleinere Dateien und schnellere Analyse.
• Vergleichen von Kosinus zu einem festen Schwellenwert. Verschiedene Einbettungsmodelle haben unterschiedliche “ähnliche” Baseline-Werte. Vermeiden Sie die Festlegung auf 0,85 – kalibrieren Sie es je nach Modell.