在实际检索类应用里数据很少只以一种形态存在。一条商品数据既是属性图中的一个节点要和品牌、类目、同款商品建立关系它的标题和详情又包含大量文本需要被全文索引命中它的图片或描述经过 embedding 模型变成高维向量还要支持语义相似检索。过去要同时满足这三种能力通常要把 Neo4j、Elasticsearch、pgvector 或 Qdrant 拼在一起随之而来的就是数据同步延迟、一致性维护困难和多套系统运维成本。LatticeDB 的定位正好切在这个点上它是一款嵌入式属性图数据库同时原生支持向量索引与全文索引把图结构、文本关键词和向量语义放进同一个引擎里写入、更新和查询。下面会围绕 LatticeDB 的定位和用法展开先讲清楚它解决什么问题再给环境准备、数据建模、查询示例、参数调优和排错思路适合正在做 RAG 知识库、推荐系统、智能客服或关联分析场景的开发者参考。1. 先理解 LatticeDB 的定位图、向量、全文为什么需要协同1.1 属性图数据库解决什么问题属性图Property Graph由顶点Vertex和边Edge组成。顶点代表实体边代表实体之间的关系顶点和边都可以挂上键值属性。比如“张三 关注了 李四”这条数据里“张三”“李四”是顶点“关注了”是边边上可以放“关注时间”这类属性。这种模型最大的优势是关联查询天然高效不需要像关系型数据库那样反复 JOIN 多张表去还原关系。LatticeDB 作为嵌入式数据库把图数据放进应用进程内部落地为本地文件由应用直接调用库接口读写。嵌入式这个特征决定了它的适用边界单机部署、数据量在千万级以内、需要低延迟访问、不想额外部署服务端进程的场景。它和 SQLite 在关系型数据库里的定位类似只是数据模型换成了图。使用方不需要维护独立服务应用启动时打开数据目录应用关闭时数据文件落盘。1.2 “原生支持向量和全文索引”到底意味着什么很多数据库都能存一个 float[] 类型的字段但“原生支持向量索引”意味着向量是一等公民有专门的向量类型、相似度度量方式余弦、欧氏距离、点积等还有为高维近似最近邻设计的索引结构最常见的是 HNSW。如果没有索引查询时只能把全表向量全部加载出来逐条算距离数据量到了百万级延迟就会不可接受。全文索引也一样。普通字符串字段只能做精确匹配或模糊匹配全文索引则会把文本切分成词条建立倒排索引再用 BM25 这类相关性排序算法计算得分。LatticeDB 把这两种能力放进同一个存储引擎核心收益是事务一致性一次写入操作会同时修改图结构、向量索引和倒排索引要么全部成功要么全部回滚。如果拆成三个系统就需要自己处理分布式事务或最终一致性一旦出现半成功状态检索结果就会变得不可信。1.3 与“Neo4j Elasticsearch pgvector”组合方案的对比组合方案本身没有错它们在各自领域都非常成熟。Neo4j 擅长图分析Elasticsearch 擅长文本相关性和分布式检索pgvector 或 Qdrant 擅长向量近似检索。问题是组合带来的连接成本对比维度LatticeDB 单引擎Neo4j Elasticsearch pgvector/Qdrant部署形态嵌入式进程内运行至少三个独立服务端进程数据一致性同一事务维护图、向量、全文依赖同步任务存在延迟窗口查询成本一次调用可融合三类信号多次跨服务调用再在应用层融合扩展性单机为主适合中小规模可水平扩展适合大规模运维成本低随应用打包高索引、分片、备份都要单独管理如果你的业务刚起步、数据规模可控、重点是把检索链路快速跑通单引擎方案能节省大量基建时间。如果你的数据规模已经到亿级或者团队已经具备完善的 ES 和向量数据库运维能力组合方案仍然是合理选择。技术选型不是选“最强的”而是选“现在最合适的”。2. 环境准备与嵌入式启动先把最小闭环跑起来2.1 最小依赖与版本确认拿到 LatticeDB 项目后第一件事是读 README 里的三块内容支持的语言和运行版本、数据目录格式、当前版本是否处于快速迭代阶段。因为是社区项目API 可能随版本调整下面的接口名和参数名用于说明调用流程实际以你拉取到的版本为准。如果项目提供 JVM 版本依赖结构通常类似下面这样。实际坐标、groupId、artifactId 要与项目发布页保持一致dependency groupIdorg.latticedb/groupId artifactIdlatticedb-core/artifactId version0.x/version /dependency如果你使用 Python、Go 或 Rust 绑定思路也一样先安装对应语言包再确认数据目录可以同时被你的运行时访问。# 例如 Python 绑定包名和版本以仓库说明为准 pip install latticedb学习阶段建议在一个临时目录里做实验不要直接打开生产数据目录。嵌入式数据库的优势是文件即数据库实验结束时删除目录即可不会留下服务进程。2.2 数据目录与配置LatticeDB 启动时需要指定数据目录。目录不存在时会自动创建存在时会按元数据识别版本。配置建议用外部文件管理而不是写死在代码里方便后面切换测试目录和生产目录。{ storage: { path: ./data/lattice, mmap: true }, vector: { defaultMetric: COSINE, indexType: HNSW, M: 32, efConstruction: 200, efSearch: 64 }, fulltext: { analyzer: icu, enablePosition: true } }这里的mmap控制是否使用内存映射文件vector段决定向量索引的构建参数fulltext段决定分词和位置信息。对学习环境默认值通常够用对生产环境后面会专门讲怎么调。2.3 写入一条数据并读回来先写一个最小示例创建一个物品顶点挂上名称、向量属性再建立一条“属于某个分类”的边。LatticeDB db LatticeDB.open(Paths.get(./data/lattice-demo)); // 开启索引给 item 顶点建唯一键索引、向量索引和全文索引 db.enableVertexIndex(item, id); db.enableVectorIndex(item, embedding, 768, VectorMetric.COSINE); db.enableFullTextIndex(item, name); try (Transaction tx db.beginWrite()) { Vertex item db.vertex(item, sku-001); item.property(name, 嵌入式图数据库实战); item.property(price, 59.0); item.property(embedding, loadEmbedding(嵌入式图数据库实战)); db.edge(item, sku-001, belongsTo, category, 数据库); tx.commit(); }这段代码里最关键的是事务的commit()。嵌入式数据库的事务语义和关系型数据库一致写操作不提交其他读事务不可见不关闭事务直接退出可能造成未完成写入。写完后再从只读事务里读回来try (Transaction tx db.beginRead()) { Vertex v db.vertex(item, sku-001); System.out.println(v.property(name)); System.out.println(v.property(embedding).asFloatArray().length); }正常输出里名称是“嵌入式图数据库实战”向量长度是 768。到这里图、向量、文本三部分已经写入同一个数据文件可以开始设计更完整的模型了。3. 数据建模顶点、边、属性和索引如何配合3.1 先想清楚“顶点类型”和“边类型”建模时最忌讳一上来就写代码。先用一张白纸把业务对象画出来哪些实体是顶点哪些关系是边。以商品搜索为例顶点类型至少包括item商品、category分类、brand品牌边类型包括belongsTo属于、producedBy生产等。边可以带方向也可以带属性。比如用户对商品的click边上可以记录点击时间、点击位置、停留时长。这些属性将来既可以用作过滤条件也可以作为图特征参与排序。try (Transaction tx db.beginWrite()) { Vertex item db.vertex(item, sku-002); item.property(name, Qt 嵌入式开发入门); item.property(price, 89.0); Edge e db.edge(item, sku-002, click, user, u-1001); e.property(timestamp, System.currentTimeMillis()); e.property(durationMs, 3200); tx.commit(); }属性图的好处是扩展灵活。给顶点加属性不需要改表结构新增边类型也不需要迁移旧数据。坏处是如果类型写错查询阶段才会暴露问题所以建议在应用层维护一套类型常量或枚举。3.2 向量属性维度、度量方式和索引类型向量索引开启时必须指定维度。这个维度不是随便定的而是由你的 embedding 模型决定。常见模型输出 384、512、768、1024 维选型后全链路要统一。如果写入的向量维度和索引声明不一致通常会在事务提交时报错或者在建索引时抛异常。更隐蔽的问题是“维度一致但语义不一致”训练向量时用的是模型 A查询时换成模型 B两个模型输出的向量不在同一个向量空间余弦相似度再高也没有意义。度量方式的选择也要先想清楚度量方式适合场景说明COSINE文本语义相似、文档检索对向量长度不敏感推荐文本场景使用EUCLIDEAN (L2)地理坐标、物理特征对绝对距离敏感DOT_PRODUCT部分训练好的模型通常要求向量已归一化内积与余弦等价代码里可以通过枚举显式声明避免每次写查询都传一遍db.enableVectorIndex(item, embedding, 768, VectorMetric.COSINE);注意如果使用 COSINE建议在写入前对向量做归一化。归一化后余弦相似度、内积和欧氏距离的排序关系会变得更容易解释也能让部分索引结构发挥更好效果。3.3 全文索引分词器决定检索质量全文索引的质量很大程度上由分词器决定。英文按空格和标点切分基本够用中文分词则复杂很多。“嵌入式图数据库”如果被简单切成一个长词用户搜索“图数据库”就匹配不到。LatticeDB 如果内置 ICU 或类似支持中文的分词组件建议优先启用如果默认是简单 whitespace 分词则要考虑配置更合适的分词器。db.enableFullTextIndex(item, name);这里还有两个容易忽略的参数。第一个是minTokenLength可以过滤掉过短的词条避免“的”“了”这类无意义字符占据索引空间第二个是是否记录词位置信息如果业务需要短语查询位置信息必须开启否则无法判断“嵌入式 数据库”是不是连续出现。索引配置与查询配置必须保持一致。写入时用分词器 A查询时用分词器 B会出现明显的召回不一致。遇到“这个词明明存在但搜不到”的问题时第一反应应该是检查索引和查询是不是走了同一套分词逻辑。4. 查询能力拆解图遍历、向量召回、全文匹配怎么组合4.1 图遍历查询图遍历是按关系找邻居的过程。比如要找出某个分类下最近上架的商品可以从分类顶点出发沿belongsTo边的反向找到item顶点ListVertex items db.traverse() .from(category, 数据库) .follow(belongsTo, Direction.IN) .to(item) .orderBy(createTime, SortOrder.DESC) .limit(100) .all();实际项目中图遍历经常和过滤条件一起用。比如只看价格在 50 到 200 之间的商品可以在遍历过程中追加where条件对深度较大的关系还要注意遍历层数限制避免一次查询拖垮线程。图遍历的优势在于它能拿到“直接关系”和“多跳关系”这是向量和全文索引单独做不到的。4.2 向量相似检索向量检索的输入是一个查询向量输出是一批相似度最高的顶点。LatticeDB 的调用大致如下ListScoredVertex semanticHits db.vectorSearch(item) .on(embedding) .query(queryVector) .topK(50) .where(v - v.property(status).asInt() 1) .run();这里要特别关注topK和where的执行顺序。如果先取 topK 再过滤过滤后结果可能远少于预期甚至为空。比如候选集 100 万向量相似度前 50 名里有 40 个是下架商品过滤后就只剩 10 个。推荐做法是让过滤条件进入索引查询阶段或者把候选 K 调大一些例如取 500 再过滤到 50。HNSW 是近似索引不是精确暴力搜索。efSearch参数越大召回越接近精确结果但查询延迟也会上升。对召回率要求极高的场景可以先跑小批量验证找到“延迟可接受、召回率达标”的参数区间。4.3 全文匹配全文检索擅长处理精确词条和短语。用户在搜索框输入“嵌入式 数据库”时如果只靠向量检索可能召回过宽加上全文索引后标题里真正出现这两个词的文档会被优先取出再和向量结果融合。ListScoredVertex keywordHits db.fullTextSearch(item) .match(name, 嵌入式 数据库) .topK(50) .run();全文索引背后的核心算法是 BM25。它考虑了词频、文档长度、文档频率比简单的“包含多少关键词”更合理。对电商、知识库这类场景全文索引能精准命中型号词、SKU 码、人名等向量模型容易模糊化的关键信息。4.4 混合检索多路召回、加权融合与重排序真正稳定可用的检索链路往往是多路召回加融合排序。所谓“向量混合检索加 BM25 多路召回”就是把向量语义结果和全文关键词结果都取出来再统一打分。LatticeDB 的混合查询如果提供原生接口使用方式可能类似HybridResult fused db.hybridSearch(item) .vector(embedding, queryVector, 0.5f) .fullText(name, 嵌入式 数据库, 0.3f) .graphBias(belongsTo, 数据库, 0.2f) .topK(20) .run();这里的三个权重分别表示向量分、全文分、图关系的贡献比例。融合逻辑可以理解为finalScore alpha * normalize(vectorScore) beta * normalize(bm25Score) gamma * normalize(graphScore)其中alpha beta gamma一般为 1。归一化很重要因为向量相似度通常是 0 到 1BM25 得分可能是几十图关系距离可能是跳数不归一化直接相加数值大的信号会完全压过其他信号。如果对精排要求更高可以在混合召回之后接一个 rerank 模型也就是把候选集交给 cross-encoder 或 reranker 重新打分。常见落地方案是粗召回阶段用 LatticeDB 同时输出向量、全文、图三类候选精排阶段用交叉编码器排序。这样既保留了多路召回的召回率又能用模型提升排名的准确性。5. 关键参数与调优哪些配置会明显影响效果5.1 HNSW 向量索引参数HNSW 有三个参数最影响效果M、efConstruction、efSearch。参数含义常见范围影响与建议M每个节点的最大连接数16 到 64M 越大召回越高、索引内存越大数据量小时默认 32 足够efConstruction构建索引时的候选队列长度100 到 300越大索引质量越高、构建越慢首次全量建索引时可适当调大efSearch查询时的候选队列长度32 到 256越大召回越高、延迟越高生产环境按延迟预算动态调整调参原则是先固定M和efConstruction单独调efSearch观察召回率和 p99 延迟。如果召回率总差一点优先提高efSearch如果还不够再提高efConstruction并重建索引。要注意HNSW 索引更新是增量式的参数调整后可能需要对存量数据重建索引才能完全生效。5.2 全文索引参数全文索引的配置直接影响召回率和索引体积。常用参数如下参数作用推荐做法analyzer分词器选择中文场景使用 ICU 或 jieba 类分词器minTokenLength最短词条长度设为 2过滤无意义单字符stopWords停用词表按业务维护不要直接用大而全的停用词表enablePosition是否记录词位置需要短语查询时开启否则关闭节省空间调优时先验证“目标文本是否能被查询命中”再验证“噪声词是否被过滤”。比如搜索“了”应该没有结果搜索“嵌入式”应该能命中标题包含该词的文档。5.3 写入、事务与缓存参数嵌入式数据库的性能瓶颈经常在写入和落盘。批量写入时建议把一批变更放进一个事务而不是一条一提交。提交太频繁会产生大量小文件写入导致索引重建和磁盘碎片。mmap开启后读取性能会提升但要注意操作系统内存占用。如果机器内存紧张可以关闭mmap改用普通文件 IO。生产环境建议定期做一次数据目录的备份检查确认落盘文件没有损坏。5.4 调优检查清单确认向量维度与 embedding 模型输出一致。确认所有写入向量使用同一个模型且归一化策略一致。确认全文索引和查询使用同一分词器。先用 1 万条数据做基准测试再放大到全量。记录每次调参后的召回率和 p99 延迟不要凭感觉改参。每次修改索引参数后验证是否需要重建索引。6. 常见问题排查从现象到根因再到修复6.1 向量检索返回结果为空现象执行向量查询后结果为空或返回数量远小于topK。常见原因和排查路径写入的向量维度与索引声明不一致事务提交时失败或索引写入被忽略。检查写入日志和向量维度日志。查询和写入使用的向量模型不一致向量空间错位。检查 embedding 服务的配置是否同一个地址。where条件过滤掉了大部分候选且过滤发生在 topK 之后。检查查询计划的过滤顺序。索引尚未构建完成。嵌入式数据库首次写入后异步或延迟索引可能出现“刚写入查不到”的现象确认提交并等待索引完成。处理建议先去掉where条件跑一次确认是否有原始结果有结果再逐步加过滤没有结果则确认索引和维度。6.2 中文全文检索匹配不到现象文档里明明有“嵌入式数据库”搜索“数据库”却返回空。原因默认分词器可能按空格或标点切分把“嵌入式数据库”当作一个整体词条查询词“数据库”无法命中完整词条。检查方式查看索引里的词条列表确认目标文本被切成了哪些词。处理建议换成支持中文分词的 analyzer重建全文索引。同时检查查询端是否也使用相同分词器。这个坑在做中文知识库时非常常见不要在“为什么搜不到”上浪费太多时间先看词条列表。6.3 数据重复写入导致顶点和索引膨胀现象运行一段时间后数据量超出预期或查询出现重复顶点。原因代码在每次导入时新建顶点而不是按唯一键查找已有顶点再更新。比如定时任务每跑一次就 insert 一个新商品同一 sku 产生多个顶点。处理建议写入前显式按唯一键 upsert。可以参考下面这种模板Vertex v db.vertex(item, sku-001); // 已存在则读取不存在则创建如果你的上游是消息队列或批量文件提前对相同业务键去重。这个问题和 Spring AI 把文档存入 ES 时每次新增一条、覆盖不生效的问题本质一样更新操作必须使用稳定 ID而不是每次创建新文档。6.4 查询延迟随数据量增长明显上升现象1 万条数据时查询很快100 万条后延迟翻了几十倍。原因排查顺序向量索引是否真的生效。如果查询被降级为全表扫描延迟必然线性增长。efSearch是否设置过小导致检索需要多次回溯。全文索引的倒排列表是否过大停用词没有过滤。mmap是否关闭导致每次读取都走磁盘 IO。处理建议先看查询日志里有没有全表扫描提示再看慢查询参数对常用过滤条件建立二级索引避免向量索引查询时还要扫描大量顶点。6.5 问题汇总表问题现象常见原因检查方式处理建议向量检索结果为空维度不一致、索引未生效、过滤过严去掉过滤条件重试检查维度日志统一维度重建索引把过滤提前到索引查询阶段中文全文搜不到分词器不切分中文查看索引词条列表配置中文分词器并重建索引数据重复写入使用新建而非 upsert检查业务唯一键使用稳定 ID upsert导入前去重延迟上升全表扫描、参数过小、停用词未过滤查看慢查询日志和索引状态开启向量索引调整 efSearch更新停用词更新不生效覆盖逻辑用了新增检查文档 ID 或顶点键统一主键语义先查后改排错时遵循“输入 - 路径 - 配置 - 索引 - 日志”的顺序不要一开始就怀疑数据库本身有 bug。绝大多数问题是维度、分词器、过滤顺序和事务提交这些常规环节造成的。7. 从学习到生产部署检查清单和扩展方向7.1 学习环境和生产环境的差异学习阶段先用临时目录、默认参数、少量数据跑通完整链路。生产环境还需要额外考虑几个方面。第一是配置外置化。数据目录、索引参数、mmap、日志级别都不能写死在代码里建议通过配置文件或环境变量注入。第二是 embedding 服务地址。代码里不要硬编码 API 地址生产环境要独立部署 embedding 服务并确认服务不可用时应用能快速失败或降级而不是每次查询都抛超时。第三是监控。嵌入式数据库没有独立服务可访问应用要周期性记录数据文件大小、索引状态、查询延迟出现异常才能定位。7.2 发布前检查清单确认 LatticeDB 版本已经固定并且有升级回滚方案。确认数据目录放在持久化磁盘而不是临时目录或容器根文件系统。确认向量维度、度量方式与 embedding 模型一致。确认全文索引分词器支持目标语言索引和查询端配置一致。确认所有写入操作使用事务并有异常回滚处理。确认首次全量建索引时预留足够内存和时间。确认备份策略定期拷贝数据文件升级前先备份。确认查询接口有超时控制和日志记录。7.3 典型落地场景RAG 知识库是最典型的场景。文档先切分再生成向量维度统一后写入 LatticeDB文档的分类、标签、引用关系用图模型存储搜索时先用向量召回语义相近的片段再用全文索引命中关键术语最后按图关系合并同一主题的上下文最后交给大模型生成答案。推荐系统也可以用它。用户行为构成图物品描述构成全文和语义向量。召回阶段同时考虑“我关注的人看过的物品”图“和当前物品文本相似的物品”向量“标题包含关键型号的物品”全文三类结果再统一排序。反欺诈和关联分析场景更依赖图遍历能力。一个可疑账号能通过边关联到多少个高风险实体这种问题用向量和全文都解决不了只有属性图能直接回答。LatticeDB 的优势是这三个信号可以写进同一条事务分析时不需要跨系统拉数据。7.4 后续扩展方向如果项目后续支持服务端模式可以在多实例、分片和集群方向上扩展如果只是单机场景重点研究数据导入工具和备份恢复机制即可。和 Spring AI、LangChain 等框架集成时关键是封装好“写入向量”和“混合检索”这两个入口让上层应用只传文本底层统一处理 embedding、索引、召回和重排。对新手来说最有价值的练习是做一个一万条商品数据的本地搜索 demo。步骤可以是先准备商品标题和描述用一个开源 embedding 模型生成向量再在 LatticeDB 里建item顶点和category分类边然后写三个查询接口分别是图遍历、向量检索、全文检索最后做混合查询验证 BM25 多路召回和加权融合的效果。把这一套跑通比单独看文档更能在实际项目中稳住。 LatticeDB：融合属性图、向量检索与全文索引的嵌入式数据库实践
在实际检索类应用里数据很少只以一种形态存在。一条商品数据既是属性图中的一个节点要和品牌、类目、同款商品建立关系它的标题和详情又包含大量文本需要被全文索引命中它的图片或描述经过 embedding 模型变成高维向量还要支持语义相似检索。过去要同时满足这三种能力通常要把 Neo4j、Elasticsearch、pgvector 或 Qdrant 拼在一起随之而来的就是数据同步延迟、一致性维护困难和多套系统运维成本。LatticeDB 的定位正好切在这个点上它是一款嵌入式属性图数据库同时原生支持向量索引与全文索引把图结构、文本关键词和向量语义放进同一个引擎里写入、更新和查询。下面会围绕 LatticeDB 的定位和用法展开先讲清楚它解决什么问题再给环境准备、数据建模、查询示例、参数调优和排错思路适合正在做 RAG 知识库、推荐系统、智能客服或关联分析场景的开发者参考。1. 先理解 LatticeDB 的定位图、向量、全文为什么需要协同1.1 属性图数据库解决什么问题属性图Property Graph由顶点Vertex和边Edge组成。顶点代表实体边代表实体之间的关系顶点和边都可以挂上键值属性。比如“张三 关注了 李四”这条数据里“张三”“李四”是顶点“关注了”是边边上可以放“关注时间”这类属性。这种模型最大的优势是关联查询天然高效不需要像关系型数据库那样反复 JOIN 多张表去还原关系。LatticeDB 作为嵌入式数据库把图数据放进应用进程内部落地为本地文件由应用直接调用库接口读写。嵌入式这个特征决定了它的适用边界单机部署、数据量在千万级以内、需要低延迟访问、不想额外部署服务端进程的场景。它和 SQLite 在关系型数据库里的定位类似只是数据模型换成了图。使用方不需要维护独立服务应用启动时打开数据目录应用关闭时数据文件落盘。1.2 “原生支持向量和全文索引”到底意味着什么很多数据库都能存一个 float[] 类型的字段但“原生支持向量索引”意味着向量是一等公民有专门的向量类型、相似度度量方式余弦、欧氏距离、点积等还有为高维近似最近邻设计的索引结构最常见的是 HNSW。如果没有索引查询时只能把全表向量全部加载出来逐条算距离数据量到了百万级延迟就会不可接受。全文索引也一样。普通字符串字段只能做精确匹配或模糊匹配全文索引则会把文本切分成词条建立倒排索引再用 BM25 这类相关性排序算法计算得分。LatticeDB 把这两种能力放进同一个存储引擎核心收益是事务一致性一次写入操作会同时修改图结构、向量索引和倒排索引要么全部成功要么全部回滚。如果拆成三个系统就需要自己处理分布式事务或最终一致性一旦出现半成功状态检索结果就会变得不可信。1.3 与“Neo4j Elasticsearch pgvector”组合方案的对比组合方案本身没有错它们在各自领域都非常成熟。Neo4j 擅长图分析Elasticsearch 擅长文本相关性和分布式检索pgvector 或 Qdrant 擅长向量近似检索。问题是组合带来的连接成本对比维度LatticeDB 单引擎Neo4j Elasticsearch pgvector/Qdrant部署形态嵌入式进程内运行至少三个独立服务端进程数据一致性同一事务维护图、向量、全文依赖同步任务存在延迟窗口查询成本一次调用可融合三类信号多次跨服务调用再在应用层融合扩展性单机为主适合中小规模可水平扩展适合大规模运维成本低随应用打包高索引、分片、备份都要单独管理如果你的业务刚起步、数据规模可控、重点是把检索链路快速跑通单引擎方案能节省大量基建时间。如果你的数据规模已经到亿级或者团队已经具备完善的 ES 和向量数据库运维能力组合方案仍然是合理选择。技术选型不是选“最强的”而是选“现在最合适的”。2. 环境准备与嵌入式启动先把最小闭环跑起来2.1 最小依赖与版本确认拿到 LatticeDB 项目后第一件事是读 README 里的三块内容支持的语言和运行版本、数据目录格式、当前版本是否处于快速迭代阶段。因为是社区项目API 可能随版本调整下面的接口名和参数名用于说明调用流程实际以你拉取到的版本为准。如果项目提供 JVM 版本依赖结构通常类似下面这样。实际坐标、groupId、artifactId 要与项目发布页保持一致dependency groupIdorg.latticedb/groupId artifactIdlatticedb-core/artifactId version0.x/version /dependency如果你使用 Python、Go 或 Rust 绑定思路也一样先安装对应语言包再确认数据目录可以同时被你的运行时访问。# 例如 Python 绑定包名和版本以仓库说明为准 pip install latticedb学习阶段建议在一个临时目录里做实验不要直接打开生产数据目录。嵌入式数据库的优势是文件即数据库实验结束时删除目录即可不会留下服务进程。2.2 数据目录与配置LatticeDB 启动时需要指定数据目录。目录不存在时会自动创建存在时会按元数据识别版本。配置建议用外部文件管理而不是写死在代码里方便后面切换测试目录和生产目录。{ storage: { path: ./data/lattice, mmap: true }, vector: { defaultMetric: COSINE, indexType: HNSW, M: 32, efConstruction: 200, efSearch: 64 }, fulltext: { analyzer: icu, enablePosition: true } }这里的mmap控制是否使用内存映射文件vector段决定向量索引的构建参数fulltext段决定分词和位置信息。对学习环境默认值通常够用对生产环境后面会专门讲怎么调。2.3 写入一条数据并读回来先写一个最小示例创建一个物品顶点挂上名称、向量属性再建立一条“属于某个分类”的边。LatticeDB db LatticeDB.open(Paths.get(./data/lattice-demo)); // 开启索引给 item 顶点建唯一键索引、向量索引和全文索引 db.enableVertexIndex(item, id); db.enableVectorIndex(item, embedding, 768, VectorMetric.COSINE); db.enableFullTextIndex(item, name); try (Transaction tx db.beginWrite()) { Vertex item db.vertex(item, sku-001); item.property(name, 嵌入式图数据库实战); item.property(price, 59.0); item.property(embedding, loadEmbedding(嵌入式图数据库实战)); db.edge(item, sku-001, belongsTo, category, 数据库); tx.commit(); }这段代码里最关键的是事务的commit()。嵌入式数据库的事务语义和关系型数据库一致写操作不提交其他读事务不可见不关闭事务直接退出可能造成未完成写入。写完后再从只读事务里读回来try (Transaction tx db.beginRead()) { Vertex v db.vertex(item, sku-001); System.out.println(v.property(name)); System.out.println(v.property(embedding).asFloatArray().length); }正常输出里名称是“嵌入式图数据库实战”向量长度是 768。到这里图、向量、文本三部分已经写入同一个数据文件可以开始设计更完整的模型了。3. 数据建模顶点、边、属性和索引如何配合3.1 先想清楚“顶点类型”和“边类型”建模时最忌讳一上来就写代码。先用一张白纸把业务对象画出来哪些实体是顶点哪些关系是边。以商品搜索为例顶点类型至少包括item商品、category分类、brand品牌边类型包括belongsTo属于、producedBy生产等。边可以带方向也可以带属性。比如用户对商品的click边上可以记录点击时间、点击位置、停留时长。这些属性将来既可以用作过滤条件也可以作为图特征参与排序。try (Transaction tx db.beginWrite()) { Vertex item db.vertex(item, sku-002); item.property(name, Qt 嵌入式开发入门); item.property(price, 89.0); Edge e db.edge(item, sku-002, click, user, u-1001); e.property(timestamp, System.currentTimeMillis()); e.property(durationMs, 3200); tx.commit(); }属性图的好处是扩展灵活。给顶点加属性不需要改表结构新增边类型也不需要迁移旧数据。坏处是如果类型写错查询阶段才会暴露问题所以建议在应用层维护一套类型常量或枚举。3.2 向量属性维度、度量方式和索引类型向量索引开启时必须指定维度。这个维度不是随便定的而是由你的 embedding 模型决定。常见模型输出 384、512、768、1024 维选型后全链路要统一。如果写入的向量维度和索引声明不一致通常会在事务提交时报错或者在建索引时抛异常。更隐蔽的问题是“维度一致但语义不一致”训练向量时用的是模型 A查询时换成模型 B两个模型输出的向量不在同一个向量空间余弦相似度再高也没有意义。度量方式的选择也要先想清楚度量方式适合场景说明COSINE文本语义相似、文档检索对向量长度不敏感推荐文本场景使用EUCLIDEAN (L2)地理坐标、物理特征对绝对距离敏感DOT_PRODUCT部分训练好的模型通常要求向量已归一化内积与余弦等价代码里可以通过枚举显式声明避免每次写查询都传一遍db.enableVectorIndex(item, embedding, 768, VectorMetric.COSINE);注意如果使用 COSINE建议在写入前对向量做归一化。归一化后余弦相似度、内积和欧氏距离的排序关系会变得更容易解释也能让部分索引结构发挥更好效果。3.3 全文索引分词器决定检索质量全文索引的质量很大程度上由分词器决定。英文按空格和标点切分基本够用中文分词则复杂很多。“嵌入式图数据库”如果被简单切成一个长词用户搜索“图数据库”就匹配不到。LatticeDB 如果内置 ICU 或类似支持中文的分词组件建议优先启用如果默认是简单 whitespace 分词则要考虑配置更合适的分词器。db.enableFullTextIndex(item, name);这里还有两个容易忽略的参数。第一个是minTokenLength可以过滤掉过短的词条避免“的”“了”这类无意义字符占据索引空间第二个是是否记录词位置信息如果业务需要短语查询位置信息必须开启否则无法判断“嵌入式 数据库”是不是连续出现。索引配置与查询配置必须保持一致。写入时用分词器 A查询时用分词器 B会出现明显的召回不一致。遇到“这个词明明存在但搜不到”的问题时第一反应应该是检查索引和查询是不是走了同一套分词逻辑。4. 查询能力拆解图遍历、向量召回、全文匹配怎么组合4.1 图遍历查询图遍历是按关系找邻居的过程。比如要找出某个分类下最近上架的商品可以从分类顶点出发沿belongsTo边的反向找到item顶点ListVertex items db.traverse() .from(category, 数据库) .follow(belongsTo, Direction.IN) .to(item) .orderBy(createTime, SortOrder.DESC) .limit(100) .all();实际项目中图遍历经常和过滤条件一起用。比如只看价格在 50 到 200 之间的商品可以在遍历过程中追加where条件对深度较大的关系还要注意遍历层数限制避免一次查询拖垮线程。图遍历的优势在于它能拿到“直接关系”和“多跳关系”这是向量和全文索引单独做不到的。4.2 向量相似检索向量检索的输入是一个查询向量输出是一批相似度最高的顶点。LatticeDB 的调用大致如下ListScoredVertex semanticHits db.vectorSearch(item) .on(embedding) .query(queryVector) .topK(50) .where(v - v.property(status).asInt() 1) .run();这里要特别关注topK和where的执行顺序。如果先取 topK 再过滤过滤后结果可能远少于预期甚至为空。比如候选集 100 万向量相似度前 50 名里有 40 个是下架商品过滤后就只剩 10 个。推荐做法是让过滤条件进入索引查询阶段或者把候选 K 调大一些例如取 500 再过滤到 50。HNSW 是近似索引不是精确暴力搜索。efSearch参数越大召回越接近精确结果但查询延迟也会上升。对召回率要求极高的场景可以先跑小批量验证找到“延迟可接受、召回率达标”的参数区间。4.3 全文匹配全文检索擅长处理精确词条和短语。用户在搜索框输入“嵌入式 数据库”时如果只靠向量检索可能召回过宽加上全文索引后标题里真正出现这两个词的文档会被优先取出再和向量结果融合。ListScoredVertex keywordHits db.fullTextSearch(item) .match(name, 嵌入式 数据库) .topK(50) .run();全文索引背后的核心算法是 BM25。它考虑了词频、文档长度、文档频率比简单的“包含多少关键词”更合理。对电商、知识库这类场景全文索引能精准命中型号词、SKU 码、人名等向量模型容易模糊化的关键信息。4.4 混合检索多路召回、加权融合与重排序真正稳定可用的检索链路往往是多路召回加融合排序。所谓“向量混合检索加 BM25 多路召回”就是把向量语义结果和全文关键词结果都取出来再统一打分。LatticeDB 的混合查询如果提供原生接口使用方式可能类似HybridResult fused db.hybridSearch(item) .vector(embedding, queryVector, 0.5f) .fullText(name, 嵌入式 数据库, 0.3f) .graphBias(belongsTo, 数据库, 0.2f) .topK(20) .run();这里的三个权重分别表示向量分、全文分、图关系的贡献比例。融合逻辑可以理解为finalScore alpha * normalize(vectorScore) beta * normalize(bm25Score) gamma * normalize(graphScore)其中alpha beta gamma一般为 1。归一化很重要因为向量相似度通常是 0 到 1BM25 得分可能是几十图关系距离可能是跳数不归一化直接相加数值大的信号会完全压过其他信号。如果对精排要求更高可以在混合召回之后接一个 rerank 模型也就是把候选集交给 cross-encoder 或 reranker 重新打分。常见落地方案是粗召回阶段用 LatticeDB 同时输出向量、全文、图三类候选精排阶段用交叉编码器排序。这样既保留了多路召回的召回率又能用模型提升排名的准确性。5. 关键参数与调优哪些配置会明显影响效果5.1 HNSW 向量索引参数HNSW 有三个参数最影响效果M、efConstruction、efSearch。参数含义常见范围影响与建议M每个节点的最大连接数16 到 64M 越大召回越高、索引内存越大数据量小时默认 32 足够efConstruction构建索引时的候选队列长度100 到 300越大索引质量越高、构建越慢首次全量建索引时可适当调大efSearch查询时的候选队列长度32 到 256越大召回越高、延迟越高生产环境按延迟预算动态调整调参原则是先固定M和efConstruction单独调efSearch观察召回率和 p99 延迟。如果召回率总差一点优先提高efSearch如果还不够再提高efConstruction并重建索引。要注意HNSW 索引更新是增量式的参数调整后可能需要对存量数据重建索引才能完全生效。5.2 全文索引参数全文索引的配置直接影响召回率和索引体积。常用参数如下参数作用推荐做法analyzer分词器选择中文场景使用 ICU 或 jieba 类分词器minTokenLength最短词条长度设为 2过滤无意义单字符stopWords停用词表按业务维护不要直接用大而全的停用词表enablePosition是否记录词位置需要短语查询时开启否则关闭节省空间调优时先验证“目标文本是否能被查询命中”再验证“噪声词是否被过滤”。比如搜索“了”应该没有结果搜索“嵌入式”应该能命中标题包含该词的文档。5.3 写入、事务与缓存参数嵌入式数据库的性能瓶颈经常在写入和落盘。批量写入时建议把一批变更放进一个事务而不是一条一提交。提交太频繁会产生大量小文件写入导致索引重建和磁盘碎片。mmap开启后读取性能会提升但要注意操作系统内存占用。如果机器内存紧张可以关闭mmap改用普通文件 IO。生产环境建议定期做一次数据目录的备份检查确认落盘文件没有损坏。5.4 调优检查清单确认向量维度与 embedding 模型输出一致。确认所有写入向量使用同一个模型且归一化策略一致。确认全文索引和查询使用同一分词器。先用 1 万条数据做基准测试再放大到全量。记录每次调参后的召回率和 p99 延迟不要凭感觉改参。每次修改索引参数后验证是否需要重建索引。6. 常见问题排查从现象到根因再到修复6.1 向量检索返回结果为空现象执行向量查询后结果为空或返回数量远小于topK。常见原因和排查路径写入的向量维度与索引声明不一致事务提交时失败或索引写入被忽略。检查写入日志和向量维度日志。查询和写入使用的向量模型不一致向量空间错位。检查 embedding 服务的配置是否同一个地址。where条件过滤掉了大部分候选且过滤发生在 topK 之后。检查查询计划的过滤顺序。索引尚未构建完成。嵌入式数据库首次写入后异步或延迟索引可能出现“刚写入查不到”的现象确认提交并等待索引完成。处理建议先去掉where条件跑一次确认是否有原始结果有结果再逐步加过滤没有结果则确认索引和维度。6.2 中文全文检索匹配不到现象文档里明明有“嵌入式数据库”搜索“数据库”却返回空。原因默认分词器可能按空格或标点切分把“嵌入式数据库”当作一个整体词条查询词“数据库”无法命中完整词条。检查方式查看索引里的词条列表确认目标文本被切成了哪些词。处理建议换成支持中文分词的 analyzer重建全文索引。同时检查查询端是否也使用相同分词器。这个坑在做中文知识库时非常常见不要在“为什么搜不到”上浪费太多时间先看词条列表。6.3 数据重复写入导致顶点和索引膨胀现象运行一段时间后数据量超出预期或查询出现重复顶点。原因代码在每次导入时新建顶点而不是按唯一键查找已有顶点再更新。比如定时任务每跑一次就 insert 一个新商品同一 sku 产生多个顶点。处理建议写入前显式按唯一键 upsert。可以参考下面这种模板Vertex v db.vertex(item, sku-001); // 已存在则读取不存在则创建如果你的上游是消息队列或批量文件提前对相同业务键去重。这个问题和 Spring AI 把文档存入 ES 时每次新增一条、覆盖不生效的问题本质一样更新操作必须使用稳定 ID而不是每次创建新文档。6.4 查询延迟随数据量增长明显上升现象1 万条数据时查询很快100 万条后延迟翻了几十倍。原因排查顺序向量索引是否真的生效。如果查询被降级为全表扫描延迟必然线性增长。efSearch是否设置过小导致检索需要多次回溯。全文索引的倒排列表是否过大停用词没有过滤。mmap是否关闭导致每次读取都走磁盘 IO。处理建议先看查询日志里有没有全表扫描提示再看慢查询参数对常用过滤条件建立二级索引避免向量索引查询时还要扫描大量顶点。6.5 问题汇总表问题现象常见原因检查方式处理建议向量检索结果为空维度不一致、索引未生效、过滤过严去掉过滤条件重试检查维度日志统一维度重建索引把过滤提前到索引查询阶段中文全文搜不到分词器不切分中文查看索引词条列表配置中文分词器并重建索引数据重复写入使用新建而非 upsert检查业务唯一键使用稳定 ID upsert导入前去重延迟上升全表扫描、参数过小、停用词未过滤查看慢查询日志和索引状态开启向量索引调整 efSearch更新停用词更新不生效覆盖逻辑用了新增检查文档 ID 或顶点键统一主键语义先查后改排错时遵循“输入 - 路径 - 配置 - 索引 - 日志”的顺序不要一开始就怀疑数据库本身有 bug。绝大多数问题是维度、分词器、过滤顺序和事务提交这些常规环节造成的。7. 从学习到生产部署检查清单和扩展方向7.1 学习环境和生产环境的差异学习阶段先用临时目录、默认参数、少量数据跑通完整链路。生产环境还需要额外考虑几个方面。第一是配置外置化。数据目录、索引参数、mmap、日志级别都不能写死在代码里建议通过配置文件或环境变量注入。第二是 embedding 服务地址。代码里不要硬编码 API 地址生产环境要独立部署 embedding 服务并确认服务不可用时应用能快速失败或降级而不是每次查询都抛超时。第三是监控。嵌入式数据库没有独立服务可访问应用要周期性记录数据文件大小、索引状态、查询延迟出现异常才能定位。7.2 发布前检查清单确认 LatticeDB 版本已经固定并且有升级回滚方案。确认数据目录放在持久化磁盘而不是临时目录或容器根文件系统。确认向量维度、度量方式与 embedding 模型一致。确认全文索引分词器支持目标语言索引和查询端配置一致。确认所有写入操作使用事务并有异常回滚处理。确认首次全量建索引时预留足够内存和时间。确认备份策略定期拷贝数据文件升级前先备份。确认查询接口有超时控制和日志记录。7.3 典型落地场景RAG 知识库是最典型的场景。文档先切分再生成向量维度统一后写入 LatticeDB文档的分类、标签、引用关系用图模型存储搜索时先用向量召回语义相近的片段再用全文索引命中关键术语最后按图关系合并同一主题的上下文最后交给大模型生成答案。推荐系统也可以用它。用户行为构成图物品描述构成全文和语义向量。召回阶段同时考虑“我关注的人看过的物品”图“和当前物品文本相似的物品”向量“标题包含关键型号的物品”全文三类结果再统一排序。反欺诈和关联分析场景更依赖图遍历能力。一个可疑账号能通过边关联到多少个高风险实体这种问题用向量和全文都解决不了只有属性图能直接回答。LatticeDB 的优势是这三个信号可以写进同一条事务分析时不需要跨系统拉数据。7.4 后续扩展方向如果项目后续支持服务端模式可以在多实例、分片和集群方向上扩展如果只是单机场景重点研究数据导入工具和备份恢复机制即可。和 Spring AI、LangChain 等框架集成时关键是封装好“写入向量”和“混合检索”这两个入口让上层应用只传文本底层统一处理 embedding、索引、召回和重排。对新手来说最有价值的练习是做一个一万条商品数据的本地搜索 demo。步骤可以是先准备商品标题和描述用一个开源 embedding 模型生成向量再在 LatticeDB 里建item顶点和category分类边然后写三个查询接口分别是图遍历、向量检索、全文检索最后做混合查询验证 BM25 多路召回和加权融合的效果。把这一套跑通比单独看文档更能在实际项目中稳住。