---
title: "埋め込みプラグイン"
description: "テキストをベクトルに変換します。コサイン類似度。コンパクトな保存。RAGプラグインの下層構造であり、単独で役立つこともできます。"
---

Embedプラグインは、Ollamaの`/api/embeddings`に薄いラッパーであり、コサイン類似度、コンパクトなBase64エンコード、逆デコードという3つの便利なヘルパーを備えています。[RAGプラグイン](/en/ai/module/rag/)は内部でそれを使用していますが、単独でも役立ちます — クラスタリング、重複除去、意味検索、異常検出に。

## 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[]
```
## パターン: 遠近似の文字列を重複除去する
```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";
        }
    }
}
```
## パターン: セマンティックタグ付け
```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)
```
## ストレージ

埋め込みは浮動小数点配列です。通常、`nomic-embed-text` の場合は 768 個の浮動小数点数、`mxbai-embed-large` の場合は 1024 個の浮動小数点数です。これはベクトルの生データで 3 KB または 4 KB です。

`Embed::pack()` を使用して、それらを 4 バイトの浮動小数点数として base64 エンコードします。
```php
$compact = Embed::pack($vec);    // ~4 KB → ~5.3 KB base64 string
$vec     = Embed::unpack($compact);
```
RAG プラグインは、この形式を使用して内部の JSON ファイルを管理しています。

## モデル選択の埋め込み

neuronetz.ai に一度プルしてください。
```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
```
In `ai.ini`:
```ini
[AI]
embed.model = "nomic-embed-text"
embed.dim   = 768
```
:::caution[モデルを混ぜないでください]
`nomic-embed-text` と `mxbai-embed-large` のベクトルは異なる幾何空間に存在します — コサイン類似度は意味がありません。`embed.model` を変更する場合は、**リセット** してください。
:::

## 一般的な落とし穴

- **`one()` を緊密なループ内で呼び出す。** 各呼び出しは1つのHTTPラウンドトリップです。100項目を超える場合は、`batch()`（内部的にはまだシリアルですが、一貫したエラー処理があります）を使用することをお勧めします。
- **生の浮動小数点配列を JSON に保存する。** `pack()` を使用して約5倍小さいファイルと高速なパースを行います。
- **コサインを固定しきい値と比較する。** 異なる埋め込みモデルには異なる「類似」の基準があります。0.85をハードコーディングしないでください — モデルごとに調整してください。
