ai-memory 向量检索详解page_embeddings 表设计与嵌入供应商选型指南【免费下载链接】ai-memorySolution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors项目地址: https://gitcode.com/GitHub_Trending/ai/ai-memoryai-memory 是一个面向 AI 编码助手的长期记忆系统它的向量检索Vector Search能力通过 SQLite 中的page_embeddings表存储文本嵌入向量让 Agent 在查询时能用语义相似度召回换了说法的相关记忆页。本文带你完整看懂这张表的设计、四种嵌入供应商Embedding Provider的选型方式以及为什么它刻意不引入向量数据库。向量检索在混合检索中的位置 ai-memory 的memory_query并不是纯向量搜索而是一条多路召回 融合的混合检索流水线检索通道作用特点FTS5 全文检索精确关键词匹配零配置始终可用实体匹配项目内声明实体的命中结构化信号图邻居扩展沿页面链接扩散发现相关页向量余弦相似度语义级相似改写查询也能命中需配置嵌入供应商每一路通道都贡献到同一个有界候选窗口最后经 RRF 融合、再叠加页面权威度调整。也就是说向量相似度只是其中一路信号它无法单独让某个页面压倒一条人工维护的决策记录——这是 ai-memory 记忆系统语义不凌驾于权威之上的设计底线。 若嵌入供应商配置缺失或调用失败memory_query会优雅降级到 FTS5 实体 图检索记忆功能不会因此中断。page_embeddings 表一行一版的设计解剖 表结构定义在 V04__embeddings.sql 中字段非常克制字段类型含义page_idBLOB主键外键指向pages(id)ON DELETE CASCADE级联删除vectorBLOB打包的Vecf32字节每维 4 字节即单位化后的嵌入向量providerTEXT供应商标识openai/voyage/google/openai-compatmodelTEXT模型名如text-embedding-3-smalldimINTEGER向量维度带dim 0约束created_atINTEGER写入时间戳为什么每行都冗余存{provider, model, dim}三元组这是整张表最值得借鉴的设计拒绝错配启动检查服务启动时对比当前配置的三元组与表内存量数据若你在没重新嵌入的情况下切换了供应商status会直接报告供应商/模型/维度不一致而不是悄悄算出错误的相似度精准定位过期行idx_page_embeddings_provider索引让ai-memory embed快速找出仍停留在旧三元组上的页面只补嵌这些页面异构可观测单条 SQL 查询即可暴露库内向量混血情况。向量写入路径很轻量嵌入结果先经 normalise 单位化这样点积就等于余弦相似度再由 f32_vec_to_bytes 打包成字节通过 store_embeddings 批量落库批大小 100 行/次。嵌入供应商选型4 种后端一览 ️供应商抽象集中在 factory.rs 的build_embedder通过环境变量选择供应商默认模型维度鉴权方式适用场景openaitext-embedding-3-small1536OPENAI_API_KEY通用首选-3-small比-3-large便宜 5 倍、召回损失极小voyagevoyage-31024VOYAGE_API_KEYVoyage 当前通用推荐google/geminigemini-embedding-001768GEMINI_API_KEYGoogle 托管走embedContentopenai-compat无默认需显式指定需显式指定可无密钥Keyless自托管Ollama / LM Studio / vLLM例如nomic-embed-text768 维几个关键细节维度自动推断try_default_embedding_dim 对已知模型内置安全默认值OpenAI→1536、Voyage→1024、Google→768openai-compat因自托管模型千差万别必须显式配置AI_MEMORY_EMBEDDING_DIM密钥独立EMBEDDING_API_KEY只为嵌入角色鉴权可让聊天模型走 OpenAI、向量走更便宜的兼容端点这种组合共存限流与冷启动所有请求带 120 秒超时容忍 Ollama 首次加载约 30 秒的冷启动429 限流按指数退避重试最多 5 次切换供应商把已有的openai自定义 BaseURL 配置切成openai-compat会改变存储的三元组需运行ai-memory embed --force全量重嵌。一键开启混合检索配置步骤 ✅设置环境变量以 OpenAI 为例AI_MEMORY_EMBEDDING_PROVIDERopenaiOPENAI_API_KEY模型与维度自动取默认值回填补嵌执行ai-memory embed它是 POST /admin/embed 的 HTTP 客户端由 run_embedding_backfill 扫描缺向量或三元组过期的最新页面逐页嵌入、批量写库先试跑加--dry-run只统计将嵌入多少页、多少页已最新不实际调用供应商加--force不带--project则扇出到整个 workspace 的全部项目常态化维护服务端的定时维护 tick 会自动补嵌新页面通常无需手动干预。成本参考按官方 install.md 的分级表 混合检索档的回填补嵌成本约$0.0001/页属于可忽略级别。为什么不用向量数据库⚡这是项目最反直觉也最克制的一点。docs/vector-backend-policy.md 明确sqlite-vec是故意推迟而非拒绝。理由在于规模判断——典型项目是数百到低千页量级暴力余弦扫描足够快且向量只是多路信号之一。引入向量扩展要付出额外运维面每个连接加载扩展的一致性、Docker/静态链接打包可靠性、启动诊断要区分扩展加载失败与嵌入三元组漂移……在价值未被证实前不值得。官方给出了明确的触发再评估门槛单项目嵌入页面常态超过 5k–10kmemory_queryp95 因向量打分超过 150–250msFTS/图路径已优化后检索评测显示向量结果相对纯 FTS5实体图有 5–10% 的 recall5 提升存在可从page_embeddings无损回填、可随时重建的安全迁移路径。而即使落地sqlite-vec也只是page_embeddings之后的派生索引绝不成为事实来源。小结 page_embeddings表用冗余三元组换取了供应商漂移的可观测性与安全拒绝机制四种嵌入供应商覆盖云端到自托管openai-compat Ollama 可实现零 API 费用的语义检索向量检索是混合检索的一路信号失败时静默降级永远不影响基础记忆功能。核心资料索引表结构V04__embeddings.sql嵌入供应商实现embedding.rs、factory.rs回填逻辑embed.rsCLI 命令embed.rs向量后端策略vector-backend-policy.md环境变量与分级说明ARCHITECTURE.md、install.md【免费下载链接】ai-memorySolution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors项目地址: https://gitcode.com/GitHub_Trending/ai/ai-memory创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考