{"title":"セマンティック検索（埋め込み）","slug":"semantic-search","category":"concepts","summary":"ベクトル埋め込みを使用した概念メモリ検索 — キーワードだけでなく意味で検索。","audience":["human","llm"],"tags":["concept","semantic","embeddings","vector-search"],"difficulty":"advanced","updated":"2026-06-27","word_count":211,"read_minutes":1,"lang":"ja","translated":true,"requested_lang":"ja","content_markdown":"\n# セマンティック検索（埋め込み）\n\nSynapse はベクトル埋め込みを使用したセマンティック検索をサポートしています。FTS5（キーワードマッチング）とは異なり、セマンティック検索はキーワードが一致しなくても**意味**でメモリを検索します。\n\n## 仕組み\n\n```\n1. Memory stored → embedding generated → vector stored\n2. Search query → embedding generated → vector compared\n3. Cosine similarity → top N results returned\n```\n\n### 埋め込みとは？\n\n埋め込みはテキストの数値ベクトル表現です。類似する意味のテキストは類似するベクトルを持ちます。Synapse は各メモリのコンテンツに対しベクトル（例：1536 次元）を生成します。\n\n### コサイン類似度\n\n意味的に類似するメモリを見つけるため、Synapse はクエリベクトルと各メモリベクトルのコサイン類似度を計算します。類似度が高い = より関連性が高い。\n\n## セマンティック検索を使うべき場面\n\n### セマンティック検索が適している場合：\n\n- X が保存されている表現と異なる形で記述されている「X に関するメモリ」を探したい\n- FTS5 が結果を返さない（キーワードが一致しない）\n- 概念的グループ化が欲しい（例：一部が「release」と言っている場合でも、すべての「deployment」メモリ）\n- クエリが質問の場合：「認証はどう処理していますか？」\n\n### FTS5 が適している場合：\n\n- 正確なキーワードが分かっている\n- ブールロジック（AND、OR、NOT）が必要\n- サブミリ秒の応答が必要\n- フレーズマッチングが欲しい\n\n## エンドポイント\n\n### GET /memory/semantic-search\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/semantic-search?q=container+orchestration\"\n```\n\nレスポンス：\n\n```json\n{\n \"results\": [\n {\n \"id\": \"mem_001\",\n \"category\": \"project\",\n \"key\": \"project_synapse_deployment\",\n \"content\": \"Synapse deployed using Docker Swarm on vps1...\",\n \"tags\": [\"docker\", \"swarm\", \"deployment\"],\n \"similarity\": 0.89\n },\n {\n \"id\": \"mem_042\",\n \"category\": \"fact\",\n \"key\": \"kubernetes_cluster\",\n \"content\": \"We use Kubernetes for production orchestration...\",\n \"tags\": [\"kubernetes\", \"orchestration\"],\n \"similarity\": 0.84\n }\n ]\n}\n```\n\n## 例\n\n### デプロイメントメモリの検索\n\n```bash\n# FTS5 might miss some — semantic catches all\ncurl .../memory/semantic-search?q=deployment+process\n```\n\n「deployment」「release」「publishing」「rolling out」などに関するメモリを返します。\n\n### 認証パターンの検索\n\n```bash\ncurl .../memory/semantic-search?q=how+do+users+log+in\n```\n\nlogin、auth、JWT、セッション管理、OAuth などに関するメモリを返します。\n\n### 類似メモリの検索\n\n```bash\n# Find memories similar to a specific one\ncurl .../memory/related/mem_001\n```\n\nセマンティック類似度（共通タグと埋め込みベクトルの両方）を使用します。\n\n## 埋め込みの生成\n\n### 埋め込みはいつ生成されるか？\n\n- **メモリ保存時** — 埋め込みサービスが構成されていれば、同期的に生成\n- **バッチ生成** — `POST /memory/embed-batch` が埋め込みを持たないメモリに対して生成\n- **非同期更新** — コンテンツ更新時に埋め込みを再生成\n\n### 埋め込みプロバイダー\n\nSynapse は構成可能な埋め込みプロバイダーをサポートします。\n\n- **OpenAI**（`text-embedding-3-small`、`text-embedding-3-large`）\n- **ローカルモデル**（Ollama 経由など）\n- **カスタム**（embeddings インターフェースを実装）\n\n環境変数で構成：\n\n```bash\nEMBEDDINGS_PROVIDER=openai\nEMBEDDINGS_API_KEY=sk-...\nEMBEDDINGS_MODEL=text-embedding-3-small\n```\n\n### バッチ生成\n\n埋め込みが欠落しているメモリが多数ある mind の場合：\n\n```bash\n# Generate embeddings for up to 100 memories\ncurl -X POST https://synapse.schaefer.zone/memory/embed-batch \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"limit\": 100}'\n\n# Check progress\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/embed-batch-status\n```\n\n## パフォーマンス\n\n| 操作 | レイテンシ |\n|-----------|---------|\n| 埋め込み生成（OpenAI） | 100〜200ms |\n| セマンティック検索（1k メモリ） | 50〜100ms |\n| セマンティック検索（10k メモリ） | 200〜500ms |\n| バッチ生成（100 メモリ） | 10〜20s |\n\n> [!NOTE]\n> セマンティック検索はベクトル計算のため FTS5 より遅くなります。既知のキーワードには FTS5 を、概念的クエリにはセマンティックを使用してください。\n\n## 制限事項\n\n### 埋め込みのコスト\n\nOpenAI を使用する場合、埋め込み生成にはコストがかかります（text-embedding-3-small で 100 万トークンあたり約 $0.02）。平均 100 トークンのメモリ 10,000 件で約 $0.02 — 無視できる程度です。\n\n### コールドスタート\n\n埋め込みが構成される前に保存されたメモリには埋め込みがありません。`POST /memory/embed-batch` を実行してバックフィルしてください。\n\n### プロバイダー依存\n\n埋め込みプロバイダーがダウンした場合、セマンティック検索は graceful に失敗します（空の結果またはエラーを返す）。FTS5 は引き続き動作します。\n\n## 埋め込みが利用できない場合\n\n埋め込みサービスが構成されていない場合：\n\n- `GET /memory/semantic-search` は 503 Service Unavailable を返す\n- `POST /memory` は引き続き動作（埋め込みは生成されないだけ）\n- FTS5 検索は引き続き動作\n\n## ベストプラクティス\n\n> [!TIP]\n> - **概念的クエリにはセマンティックを使用** — 「X をどう処理するか？」\n> - **特定の用語には FTS5 を使用** — 「docker swarm」\n> - **定期的に埋め込みをバックフィル** — `POST /memory/embed-batch`\n> - **プロバイダーの健全性を監視** — セマンティック検索はそれに依存\n> - **タグと組み合わせ** — セマンティック + タグフィルタで結果を絞り込み\n\n## 次のステップ\n\n- [FTS5 Search](/docs/concepts/fts5-search)\n- [Memory API](/docs/api/memory)\n- [Architecture](/docs/concepts/architecture)\n","content_html":"

セマンティック検索（埋め込み）

\n

Synapse はベクトル埋め込みを使用したセマンティック検索をサポートしています。FTS5（キーワードマッチング）とは異なり、セマンティック検索はキーワードが一致しなくても意味でメモリを検索します。

\n

仕組み

\n
1. Memory stored → embedding generated → vector stored\n2. Search query → embedding generated → vector compared\n3. Cosine similarity → top N results returned

埋め込みとは？

\n

埋め込みはテキストの数値ベクトル表現です。類似する意味のテキストは類似するベクトルを持ちます。Synapse は各メモリのコンテンツに対しベクトル（例：1536 次元）を生成します。

\n

コサイン類似度

\n

意味的に類似するメモリを見つけるため、Synapse はクエリベクトルと各メモリベクトルのコサイン類似度を計算します。類似度が高い = より関連性が高い。

\n

セマンティック検索を使うべき場面

\n

セマンティック検索が適している場合：

\n\n

FTS5 が適している場合：

\n\n

エンドポイント

\n

GET /memory/semantic-search

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory/semantic-search?q=container+orchestration"

レスポンス：

\n
{\n  "results": [\n    {\n      "id": "mem_001",\n      "category": "project",\n      "key": "project_synapse_deployment",\n      "content": "Synapse deployed using Docker Swarm on vps1...",\n      "tags": ["docker", "swarm", "deployment"],\n      "similarity": 0.89\n    },\n    {\n      "id": "mem_042",\n      "category": "fact",\n      "key": "kubernetes_cluster",\n      "content": "We use Kubernetes for production orchestration...",\n      "tags": ["kubernetes", "orchestration"],\n      "similarity": 0.84\n    }\n  ]\n}

例

\n

デプロイメントメモリの検索

\n
# FTS5 might miss some — semantic catches all\ncurl .../memory/semantic-search?q=deployment+process

「deployment」「release」「publishing」「rolling out」などに関するメモリを返します。

\n

認証パターンの検索

\n
curl .../memory/semantic-search?q=how+do+users+log+in

login、auth、JWT、セッション管理、OAuth などに関するメモリを返します。

\n

類似メモリの検索

\n
# Find memories similar to a specific one\ncurl .../memory/related/mem_001

セマンティック類似度（共通タグと埋め込みベクトルの両方）を使用します。

\n

埋め込みの生成

\n

埋め込みはいつ生成されるか？

\n\n

埋め込みプロバイダー

\n

Synapse は構成可能な埋め込みプロバイダーをサポートします。

\n\n

環境変数で構成：

\n
EMBEDDINGS_PROVIDER=openai\nEMBEDDINGS_API_KEY=sk-...\nEMBEDDINGS_MODEL=text-embedding-3-small

バッチ生成

\n

埋め込みが欠落しているメモリが多数ある mind の場合：

\n
# Generate embeddings for up to 100 memories\ncurl -X POST https://synapse.schaefer.zone/memory/embed-batch \\\n  -H "Authorization: Bearer YOUR_MIND_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d '{"limit": 100}'\n\n# Check progress\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     https://synapse.schaefer.zone/memory/embed-batch-status

パフォーマンス

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
操作レイテンシ
埋め込み生成（OpenAI）100〜200ms
セマンティック検索（1k メモリ）50〜100ms
セマンティック検索（10k メモリ）200〜500ms
バッチ生成（100 メモリ）10〜20s
\n
セマンティック検索はベクトル計算のため FTS5 より遅くなります。既知のキーワードには FTS5 を、概念的クエリにはセマンティックを使用してください。

制限事項

\n

埋め込みのコスト

\n

OpenAI を使用する場合、埋め込み生成にはコストがかかります（text-embedding-3-small で 100 万トークンあたり約 $0.02）。平均 100 トークンのメモリ 10,000 件で約 $0.02 — 無視できる程度です。

\n

コールドスタート

\n

埋め込みが構成される前に保存されたメモリには埋め込みがありません。POST /memory/embed-batch を実行してバックフィルしてください。

\n

プロバイダー依存

\n

埋め込みプロバイダーがダウンした場合、セマンティック検索は graceful に失敗します（空の結果またはエラーを返す）。FTS5 は引き続き動作します。

\n

埋め込みが利用できない場合

\n

埋め込みサービスが構成されていない場合：

\n\n

ベストプラクティス

\n

次のステップ

\n\n","urls":{"html":"/docs/concepts/semantic-search","text":"/docs/concepts/semantic-search?format=text","json":"/docs/concepts/semantic-search?format=json","llm":"/docs/concepts/semantic-search?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}