选择 / 配置嵌入模型

嵌入为记忆与用户画像提供相似性搜索能力。在同一文件中配置（~/.config/opencode/opencode-mem.jsonc）。没有 MLX 后端 — 本地嵌入使用带 ONNX 的 @huggingface/transformers，而非 Apple MLX。

本地（默认）： 仅设置 embeddingModel。首次使用时模型从 Hugging Face 下载并缓存在 {storagePath}/.cache（默认 ~/.opencode-mem/data/.cache）下。

远程（OpenAI 兼容）： 同时设置 embeddingApiUrl 与 embeddingApiKey。插件随后使用 Bearer 令牌调用 {embeddingApiUrl}/embeddings。embeddingApiKey 接受与 memoryApiKey 相同的密钥格式（literal、env://…、file://…）。

键	作用
embeddingModel	Hugging Face id（本地）或 API 模型名（远程）。默认：Xenova/nomic-embed-text-v1
embeddingDimensions	可选覆盖；通常可省略 — 维度从内置映射查找
embeddingPooling	本地池化："mean"（默认）、"cls" 或 "last_token"。未设置 → 小型已知模型预设或 "mean"
embeddingQueryPrefix	查询任务嵌入的前缀。未设置 → 模型预设，或在 embeddingUseTaskPrefixes 为 true 时使用 Nomic。显式 "" 禁用
embeddingDocumentPrefix	文档任务嵌入的前缀（与 embeddingQueryPrefix 相同的解析规则）
embeddingUseTaskPrefixes	当自定义/预设前缀未设置时，可选启用 Nomic 的 search_query: / search_document: 前缀。默认 false
embeddingDtype	可选的本地 ONNX dtype 覆盖（例如 "q8"、"fp32"）。设置后会传给 transformers.js 的 pipeline({ dtype })
embeddingApiUrl	OpenAI 兼容嵌入 API 的基础 URL（末尾路径不超过 /v1）
embeddingApiKey	该端点的 API 密钥（需与 embeddingApiUrl 一起设置）

推荐的本地模型：

模型	维度	说明
Xenova/nomic-embed-text-v1	768	默认；多语言，8192 上下文；mean 池化
Xenova/jina-embeddings-v2-base-en	768	仅英语，8192 上下文
Xenova/jina-embeddings-v2-small-en	512	更快，8192 上下文
Xenova/all-MiniLM-L6-v2	384	非常快，512 上下文
Xenova/all-mpnet-base-v2	768	质量较好，512 上下文
Xenova/bge-m3	1024	多语言；自动 CLS 池化
intfloat/multilingual-e5-large	1024	自动 query: / passage: 前缀

示例 — 远程 OpenAI 嵌入：

{
  "embeddingApiUrl": "https://api.openai.com/v1",
  "embeddingApiKey": "env://OPENAI_API_KEY",
  "embeddingModel": "text-embedding-3-small",
}

示例 — 本地 bge-m3（池化通过预设默认为 CLS；如需可覆盖）：

{
  "embeddingModel": "Xenova/bge-m3",
  // "embeddingPooling": "cls",
  // "embeddingDtype": "q8",
}

更改 embeddingModel、维度、池化或任务前缀可能需要对已存储的记忆重新嵌入，以使存储与查询向量保持对齐。建议为给定数据目录选定一次模型（以及池化/前缀设置）并坚持使用。

不支持 — Intel Mac（darwin/x64）： 本地持久化需要 @tursodatabase/database，其不发布 Intel Mac 原生绑定。固定版本的 onnxruntime-node 发行版（1.24.1+，包括固定的 1.31.1）也缺少 darwin/x64。请使用 Apple Silicon Mac、Linux 或 Windows，或通过 embeddingApiUrl + embeddingApiKey 使用远程端点（见上方示例）。在受支持平台上，opencode-mem 固定 onnxruntime-node@1.31.1（来自 1.24.1 / #225 的 Ort::Env 拆卸修复），并通过 CJS 解析 shim 加载 transformers，以便 OpenCode 嵌套安装保留该绑定。在安装该 shim 之前，transformers 会解析为绝对路径，以免 OpenCode 的 Bun --compile 主机因 Cannot find module '@huggingface/transformers' from '' 而失败。升级后，请清除 OpenCode 的嵌套插件缓存（~/.cache/opencode/packages/opencode-mem@*）并重新安装。