Supermemory 自托管版因 embedding 维度与已存数据不一致拒绝启动，怎么排查

Supermemory 自托管版因 embedding 维度与已存数据不一致拒绝启动怎么排查【免费下载链接】supermemoryMemory and context engine app that is extremely fast, scalable, and can be run fully locally. The Memory API for the AI era.项目地址: https://gitcode.com/GitHub_Trending/su/supermemory自托管的 Supermemory 单二进制服务器在一种情况下会直接拒绝启动当前配置的 embedding 维度与数据目录里已存的向量不一致。官方文档明确说明 If configured dimensions disagree with stored data, the serverrefuses to boot配置维度与已存数据不符时服务器拒绝启动。这篇文章给出排查这条问题的完整路径确认配置来源、比对两个维度值、选择文档给出的三条修复路径之一最后验证服务器能再次启动。适用环境自托管二进制macOS Apple Silicon Intel、Linux x64 arm64无论是交互式首启还是 Docker/CI 等无 TTY 的部署方式。依据的文档是 Embeddings (self-hosted)、Self-Hosting Configuration 和 Self-Hosting Quickstart。“拒绝启动”的触发机制自托管版和托管平台共用同一套 embedding provider 栈本地 ONNX 模型、OpenAI、Gemini或任意 OpenAI 兼容端点如 Ollama。控制它的配置项是变量用途默认值SUPERMEMORY_EMBEDDING_PROVIDERembedding 后端local、openai、gemini或 OpenAI 兼容远端localSUPERMEMORY_EMBEDDING_MODEL所选 provider 的模型 idXenova/bge-base-en-v1.5localSUPERMEMORY_EMBEDDING_DIMENSIONS向量维度必须与模型和已存数据匹配768SUPERMEMORY_EMBEDDING_BASE_URLOpenAI 兼容 embedding API 的 base URLOllama、vLLM 等未设置默认本地模型Xenova/bge-base-en-v1.5是 768 维。文档的要求是使用你所选模型官方公布的维度Use the dimension published for your chosen model。只要已存向量与当前配置不一致启动即失败——这就是本文要排查的现象它不是崩溃或报错后继续运行而是进程在启动阶段被拦截。排查定位对不上的两个数第一步确认当前实际生效的 embedding 配置配置可能来自三个地方逐一核对shell 或进程管理器中设置的环境变量——Docker、CI 等无 TTY 环境下只有这一种方式没有交互提示~/.supermemory/env——安装器写入的 API key 文件每次启动都会加载首启交互向导保存的选择——在带 TTY 的首次启动中可选 embedding provider/model选择会加密保存在数据目录$SUPERMEMORY_DATA_DIR默认./.supermemory下。注意文档没有提供一条独立命令直接读出已存向量的维度值所以排查思路是核对“写入时生效的配置”与“当前生效的配置”而不是读取存储本身。第二步确认已存数据是用哪个模型、什么维度写入的回想或翻查数据目录里第一次写入内容时生效的 embedding 配置向导选择或当时的环境变量再对照文档给出的各模型维度Provider / 模型文档中的维度示例localXenova/bge-base-en-v1.5默认768localXenova/bge-m3多语言1024OpenAItext-embedding-3-small1536Geminitext-embedding-004768Ollamanomic-embed-text经SUPERMEMORY_EMBEDDING_BASE_URL768第三步比对并判断如果当前配置含你后来新增或修改的SUPERMEMORY_EMBEDDING_*变量与写入时的模型/维度不同启动拒绝就是这一项引起的。典型触发场景先在默认 768 维下写了数据之后切换到 OpenAI/Gemini/Ollama 或其他本地模型而没有重置数据或多语言改造时中途把SUPERMEMORY_EMBEDDING_DIMENSIONS改成了1024。文档专门提醒provider、model、dimensions 三者要一起设置Changing them later requires a fresh data directory or full re-ingestion。如果两个来源的模型与维度完全一致却仍无法启动则不属于本文这一故障模式文档没有覆盖其他启动拒绝原因需要另行排查。修复文档给出的三条路径文档对“事后改模型/维度”的立场是明确的不支持原地修改Not supported in place不同模型或不同维度的 embedding 不可比。对应地有两条正路加一条兜底路径一把配置改回与已存数据一致改动最小如果你希望保留已有数据把 provider、model、dimensions 三项改回写入数据时使用的组合。以恢复默认本地模型为例文档原示例SUPERMEMORY_EMBEDDING_PROVIDERlocal SUPERMEMORY_EMBEDDING_MODELXenova/bge-base-en-v1.5 SUPERMEMORY_EMBEDDING_DIMENSIONS768如果写入时用的是其他 provider按 embeddings 文档 中对应小节的示例恢复例如 OpenAIOPENAI_API_KEYsk-... # 替换为你自己的 key文档示例写法 SUPERMEMORY_EMBEDDING_PROVIDERopenai SUPERMEMORY_EMBEDDING_MODELtext-embedding-3-small SUPERMEMORY_EMBEDDING_DIMENSIONS1536改完检查~/.supermemory/env和启动环境里没有残留的旧值把新配置覆盖掉然后重启服务器。路径二换一个全新数据目录文档方案之一是 Start from a fresh data directory。做法是把SUPERMEMORY_DATA_DIR指向一个尚未存放过 Supermemory 数据的新路径让图引擎在新目录里从零创建。副作用API key、auth secret 都存在数据目录里新目录的首次启动会生成并打印一套新的API key原有机密和旧数据不再被这个实例使用——旧目录及其内容保持原样不会被动。路径三整体重新写入文档的另一方案是 re-ingest all content so vectors stay in one space——在目标 embedding 配置下把所有内容重新写入使全部向量落在同一向量空间。写入走的是常规加文档接口POST /v3/documents见 Quickstart 中的 curl 示例。这条路径适合你确定要换模型、且原始内容在别处有完整副本的情况。验证确认服务器恢复正常重启supermemory-server判断标准就两条进程不再在启动阶段被拦截而是正常进入监听状态默认PORT为6767终端输出首启信息框包含url、database、api key、org id四项。文档示例输出如下数值为示例不是固定预期┌──────────────────────────────────────────────────┐ │ url http://localhost:6767 │ │ database ./.supermemory │ │ api key sm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx │ │ org id xxxxxxxxxxxxxxxxxxxxxx │ └──────────────────────────────────────────────────┘database一行会显示实际使用的数据目录可用来顺带确认你选的是哪条修复路径生效。边界说明不支持原地切换 embedding不同模型或不同维度的向量不可比这是文档声明的限制没有配置项可以绕过维度一致性在 v0.0.7 起通过数据库存储中的 locked plan 在文档写入与查询两条 embedding 路径上统一强制。区分另一个相关但不同的问题v0.0.5 存在 embedding 模型混用 bug写入路径和查询路径使用不同模型症状是/v4/search、/v4/profile的精确文本搜索静默返回{results:[],total:0}而不是拒绝启动。文档给出的解决方式是升级到v0.0.7或更高版本升级可用 Quickstart 文档中的supermemory-server upgrade或安装时显式指定版本例如curl -fsSL https://supermemory.ai/install | bash -s -- 0.0.3数字替换为目标版本。如果你在 v0.0.5 上遇到的是搜索无结果而不是启动失败走这条而不是本文路径。回滚二进制版本前文档要求先备份数据目录因为旧版服务器可能无法理解新版写入的数据或 schema 变更。【免费下载链接】supermemoryMemory and context engine app that is extremely fast, scalable, and can be run fully locally. The Memory API for the AI era.项目地址: https://gitcode.com/GitHub_Trending/su/supermemory创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考