---
title: "Plugin d'intégration"
description: "Transformez le texte en vecteurs. Similarité cosinus. Stockage compact. L'infrastructure sous-jacente du plugin RAG, également utile à part elle-même."
---

Le plugin Embed est un simple wrapper autour de `/api/embeddings` d'Ollama, plus trois utilitaires utiles : la similarité cosinus, le paquetage compact en base64 et le dépaquetage inverse. Le [plugin RAG](/en/ai/module/rag/) l'utilise internement, mais il est également utile à part lui — pour le regroupement, la suppression des doublons, la recherche sémantique, la détection d'anomalies.

## API
```php
$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[]
```
## Modèle : dédoublonner des chaînes similaires
```php
$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";
        }
    }
}
```
## Modèle : balisage sémantique
```php
$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)
```
## Stockage

Les embeddings sont des tableaux de flottants — généralement 768 flottants pour `nomic-embed-text`, 1024 pour `mxbai-embed-large`. Cela représente 3 Ko ou 4 Ko par vecteur brut.

Utilisez `Embed::pack()` pour les encoder en base64 comme des flottants sur 4 octets :
```php
$compact = Embed::pack($vec);    // ~4 KB → ~5.3 KB base64 string
$vec     = Embed::unpack($compact);
```
Le plugin RAG utilise ce format internalement pour ses fichiers JSON.

## Choix des modèles d'incrustation

Tirez sur neuronetz.ai une fois :
```bash
curl https://api.neuronetz.ai/api/pull -d '{"name":"nomic-embed-text"}'   # 768 dim, default
curl https://api.neuronetz.ai/api/pull -d '{"name":"mxbai-embed-large"}'  # 1024 dim, higher quality
```
Dans `ai.ini`:
```ini
[AI]
embed.model = "nomic-embed-text"
embed.dim   = 768
```
:::caution[N'entremez pas les modèles]
Les vecteurs de `nomic-embed-text` et `mxbai-embed-large` existent dans des espaces géométriques différents — le cosinus entre eux n'a aucun sens. Si vous changez `embed.model`, **réinitialisez** toute collection RAG ou tout embedding sauvegardé avant de les mélanger.
:::

## Trépieds courants

- **Appel à `one()` dans une boucle serrée.** Chaque appel est un aller-retour HTTP. Pour plus de 100 éléments, privilégiez `batch()` (toujours en série sous-jacentement, mais avec une gestion d'erreurs cohérente).
- **Stockage de tableaux bruts de flottants dans JSON.** Utilisez `pack()` pour des fichiers ~5 fois plus petits et un analyse plus rapide.
- **Comparaison du cosinus à un seuil fixe.** Les modèles d'incrustation différents ont différentes bases de "similitude". Ne codez pas en dur 0.85 — calibrez par modèle.
