---
title: 意味検索の仕組み
description: 埋め込み、類似度、モデル変更、再インデックスの考え方を説明します。
---

## 埋め込みとは [#what-is-embedding]

埋め込みは、テキストや画像を固定長の数値ベクトルに変換したものです。意味が近い入力は、ベクトル空間上でも近い位置に配置されます。

Omnio は `IEmbedder` で埋め込みを生成し、`Float32Array` としてインデックスに保存します。

```ts
const object = await omnio.putObject({
  key: "notes/a.txt",
  data: bytes,
  contentType: "text/plain",
  description: "海辺に沈む夕日",
});
```

このとき、`description` の埋め込みが生成され、`embeddingModel` にモデル名、`embeddingDims` に次元数、`embeddingSource` に由来が記録されます。

## 何が埋め込まれるか [#what-is-embedded]

既定では、`putObject` の `description` だけが自動で埋め込まれます。

- `tags` は埋め込み対象ではありません。
- 保存したファイルのバイト列は、中身にかかわらず埋め込みません。
- 画像クエリーでは、画像を埋め込み、保存済みの説明文の埋め込みと比較します。

ファイルの内容そのものを検索したいときは、内容を説明するテキストを `description` に保存してください。

## 類似度 [#similarity]

SQL インデックスは 2 種類の類似度に対応しています。

| 方式     | スコア         | 意味                                     |
| -------- | -------------- | ---------------------------------------- |
| `cosine` | コサイン類似度 | `-1` から `1`。大きいほど近いです。      |
| `l2`     | 負の L2 距離   | `0` が最も近く、小さくなるほど遠いです。 |

`Omnio.searchObjects` は `metric` を指定しないため、常にコサイン類似度を使います。L2 距離を使う場合は `IObjectIndex.search` を直接呼び出してください。

`minScore` はこのスコアに対するしきい値です。方式によって意味が変わるため、値を決める前に実際のスコアを確認してください。

## モデルと次元数 [#model-and-dims]

保存済みのベクトルは、生成したモデルに依存します。異なるモデルのベクトルを同じ検索で比較しても、意味のある結果は得られません。

Omnio は次の方法でモデルの混在を防ぎます。

- `putObject` は `embedder.info.name` を `embeddingModel` に記録します。
- `searchObjects` のテキスト・画像クエリーは、同じモデル名を持つ行だけを対象にします。
- `open()` は、モデル名または次元数が現在の設定と異なる行に dirty フラグを立てます。

モデルを変えると、再インデックスが完了するまで対象の行は検索から外れます。メタデータの取得や一覧には引き続き現れます。

## 再インデックス [#reindexing]

再インデックスは、現在の埋め込み器で説明文を埋め込み直す処理です。

- `open()` は dirty フラグが立った行をバックグラウンドで処理します。
- `reindexObject` は 1 件だけを明示的に処理します。
- 説明文を更新しても、自動では再インデックスされません。`reindexObject` を呼び出してください。

再インデックス中にオブジェクトが更新または削除された場合、Omnio は古いスナップショットを書き戻しません。現在の説明文とエンティティが変わっていなければ反映し、変わっていればその結果は破棄します。

## 検索の実行方法 [#execution]

現在の SQL インデックスは、近似最近傍探索用のベクトルインデックスを作りません。検索は、絞り込み条件に合う行を走査して類似度を計算する正確な検索です。

そのため、データが増えると検索にも時間がかかります。大規模なデータを扱うときは、次の点を検討してください。

- `filter` で候補を減らす。
- `topK` を小さくする。
- 独自のインデックスで近似最近傍探索を実装する。

読み取りは書き込みを待たず、検索時点で完了している埋め込みだけを使います。バックグラウンドの埋め込み計算が終わっていない行は、検索結果に含まれません。

## 全文検索との違い [#full-text-vs-semantic]

`MetadataFilter.fullText` は、説明文とキーに対する部分一致です。単語に分割したり、順位を付けたりはしません。

意味検索は、表記が一致しなくても意味が近ければヒットします。用途に応じて使い分けてください。

```ts
// 表記の一致
await omnio.listObjects({ filter: { fullText: "夕日" } });

// 意味の近さ
await omnio.searchObjects({ query: { text: "夕暮れの海" } });
```

## 次に読む [#next]

- [埋め込みを管理する](/omnio-js/how-to/manage-embeddings)
- [インデックス](/omnio-js/reference/indexes)
- [埋め込み器](/omnio-js/reference/embedders)
