# 向量搜尋

本頁說明 ToriiDB 向量操作的前置條件，以及 `SetVector` 如何在背景為 entry 附加 OpenAI embedding。

## 前置條件

`store.New` 找到 API key 時會建立 embedder（見 [設定](/zh/configuration-api-key)）。沒有 embedder 時一般儲存照常運作，向量寫入與搜尋回傳 `ErrNoEmbedder`。

| 設定 | 值 |
|---|---|
| 模型 | `text-embedding-3-small` |
| 維度 | `TORIIDB_EMBED_DIM`，預設 `256` |
| Endpoint | `https://api.openai.com/v1/embeddings` |
| 回應檢查 | 向量長度必須等於維度 |

## 附加向量

```text
SET article:1 Redis-style embedded storage VECTOR
```

```go
err := torii.SetVector(ctx, "article:1", "embedded JSON database", store.SetDefault, nil)
err = d.SetVector(ctx, 0, "article:1", "embedded JSON database", nil)
```

`SetVector` 拒絕空白文字，先執行一般 `Set`（值立即可讀，舊向量被清除），再啟動由 store wait group 追蹤的背景工作：

1. 在讀鎖下查詢 embedding 快取。
2. 未命中時在不持鎖的情況下呼叫 OpenAI（35 秒 timeout），並把結果存入快取。
3. 在寫鎖下，只有鍵仍存在且值仍等於被 embedding 的文字時才附加向量。
4. 附加一筆帶編碼向量的 `SET` 紀錄。

Embedding 失敗會被靜默丟棄；文字仍保存但沒有向量。`Store.Close()` 會等待尚未完成的工作。

## 一致性說明

- 寫入要等背景工作完成後才能被搜尋到。
- 工作完成前修改值，過時的 embedding 會被丟棄。
- 搜尋只比較長度與查詢向量相同的向量。
- 欄位層級的 `SET` 不能帶 `VECTOR`。

## 相關頁面

- [Embedding 快取](/zh/vector-search-cache)
- [VSEARCH 與 VSIM](/zh/vector-search-query)
- [API Key](/zh/configuration-api-key)