---
title: "启用语义搜索"
description: "可选的向量搜索：一套沉重的原生栈、VECTOR_SEARCH 开关、模型档位，以及回退到全文搜索而不损失任何功能。"
---

# 启用语义搜索

Notarium 的全文搜索（FTS）**始终可用，无需任何配置**。语义（向量）搜索则是一项可选能力：它带来按语义的混合排序，但会引入一套沉重的原生栈（`onnxruntime` + `sqlite-vec`，磁盘占用约 660 MB），以及首次启用时下载的本地嵌入模型（磁盘占用约 600 MB，还要吃掉数百 MB 内存）。正因如此，它默认关闭，需刻意开启。想了解搜索底层如何运作，参见[概念：搜索](/docs/concepts/search/)。

## 两个相互独立的开关

把两个层面分清楚很有帮助——安装与运行时：

1. **安装**——原生向量栈是否存在于 `node_modules` 中。**Docker 镜像始终自带它**，因此在容器内开启无需重新构建。从源码运行时，默认的 `make deps` **不会**安装它（本地 `node_modules` 因此轻约 660 MB）——若要在本地做向量相关工作，你需要 `make deps-vector`。
2. **运行时**——`VECTOR_SEARCH` 变量。在发布的镜像中，它默认为 `off`。

在 Docker 中启用语义搜索，只需拨动运行时开关即可——原生栈早已就位。

## 开启

```bash
docker run -d --name notarium \
  -p 3000:3000 \
  -v notarium-data:/data \
  -e VECTOR_SEARCH=on \
  docouno/notarium:latest
```

（单个 `/data` 数据卷承载全部状态——元数据库、索引、你的笔记、导出产物；与普通运行时相同，参见[安装](/docs/self-hosting/install/)。这里只是多加了一个 `VECTOR_SEARCH=on`。）

首次启用时，默认模型（bge-m3）会下载（磁盘占用约 600 MB）并占用数百 MB 内存。索引在后台构建：全文搜索立即可用，向量随后追上。

## 模型档位

模型由 `EMBED_MODEL` + `EMBED_DIMENSIONS` 这一对参数决定（维度**必须**与模型匹配）——它是同一镜像上的运行时设置，而非另行构建：

| 档位 | 变量 | 内存 | 何时使用 |
|---|---|---|---|
| **off** | `VECTOR_SEARCH=off` | 0 | 低配机器，或关键词搜索已够用。镜像的默认值。 |
| **compact** | `VECTOR_SEARCH=on`、`EMBED_MODEL=Xenova/multilingual-e5-small`、`EMBED_DIMENSIONS=384` | 约 120 MB | Homelab、小型 VPS。 |
| **full** | `VECTOR_SEARCH=on`（默认：bge-m3，1024） | 约 600 MB | 高性能机器；100+ 种语言、长上下文。 |

> [!warning] 非对称的 e5 模型
> compact 档位（e5）需要前缀 `EMBED_QUERY_PREFIX="query: "` 和 `EMBED_PASSAGE_PREFIX="passage: "`——遗漏它们会悄无声息地拉低搜索质量。而对于对称的 bge-m3 则恰恰相反：你**不应**设置这些前缀。

## 资源紧张的机器上

在没有 swap、约 6 GB 内存的主机上，bge-m3 的首次索引可能触顶内存。有两个手段：改用 compact 档位（e5-small），或设置 `EMBED_CPU_MEM_ARENA=off`——这会把消耗控制在约 1.9 GB，代价是略微变慢。嵌入参数的完整清单，见[参考](/docs/reference/environment-variables/)。

## 回退到全文搜索

若 `VECTOR_SEARCH=off`，或原生栈因任何原因加载失败，搜索**仍会基于全文继续工作**——不报错，结果看上去也一样。语义搜索是叠加在始终可用的 FTS 之上的一路额外排序通道，而非硬性依赖。没有向量的实例，同样是一个完全可用的实例。