zvec的Doc与vectors字段怎么配新手必看的5大避坑指南【免费下载链接】zvecA lightweight, lightning-fast, in-process vector database项目地址: https://gitcode.com/GitHub_Trending/zve/zveczvec 是一个轻量、极速的进程内向量数据库in-process vector database而Doc与vectors字段是它最基础的两块拼图前者是写入/检索的文档单元后者定义相似度搜索依赖的向量字段。这篇指南用 5 个真实高频坑点帮你在 10 分钟内配好 Doc 与 vectors少走弯路。一、Doc 的 4 个属性一次看懂结构Doc位于 doc.py是插入和检索的核心载体只包含 4 个属性属性类型必填说明idstr✅文档唯一主键PKscorefloat❌检索返回的相关性得分vectorsdict[str, 向量]❌命名向量字典如{embedding: [...]}fieldsdict[str, 值]❌标量字段如标题、时间戳最小可用示例来自 README.md 的 One-Minute Exampledoc zvec.Doc( iddoc_1, vectors{embedding: [0.1, 0.2, 0.3, 0.4]}, fields{title: 第一份文档}, )几个实用小方法doc.vector(embedding)按名取向量、doc.has_field(title)判断字段是否存在、doc.vector_names()列出全部向量名。另外vectors里传入 numpy 数组会被自动转成 list见 _normalize_vectors无需手动处理。二、vectors 字段配置 3 步法从 Schema 到入库vectors 配置的核心在CollectionSchema的vectors参数上规则定义在 collection_schema.py 和 field_schema.py第 1 步给每个向量命名。vectors参数可以传单个VectorSchema也可以传列表实现多向量schema zvec.CollectionSchema( namearticles, fields[zvec.FieldSchema(title, zvec.DataType.STRING)], vectors[ zvec.VectorSchema(title_emb, zvec.DataType.VECTOR_FP32, dimension128), zvec.VectorSchema(body_emb, zvec.DataType.VECTOR_FP32, dimension128), ], )第 2 步选对向量类型。zvec 支持 6 种向量类型field_schema.py 中的SUPPORT_VECTOR_DATA_TYPE稠密向量VECTOR_FP32最常用、VECTOR_FP16省内存、VECTOR_FP64高精度、VECTOR_INT8量化压缩稀疏向量SPARSE_VECTOR_FP32/SPARSE_VECTOR_FP16数据格式是字典{索引: 值}如{3: 0.8, 12: 0.2}第 3 步Doc 的 vectors 字典与 Schema 名一一对应。写入时Doc(vectors{title_emb: [...], body_emb: [...]})的每个键都必须在 Schema 的vectors中声明过——底层转换逻辑 convert.py 会对每个键做严格匹配校验。三、新手 5 大避坑清单 ⚠️坑 1字段名撞车 —— 全局唯一不只是各自唯一CollectionSchema的校验逻辑_check_vectors要求标量字段名与向量名之间也不能重名。# ❌ 报错duplicate vector name embedding zvec.CollectionSchema( namedemo, fields[zvec.FieldSchema(embedding, zvec.DataType.STRING)], # 标量占了名字 vectorszvec.VectorSchema(embedding, zvec.DataType.VECTOR_FP32, 128), )避坑方法向量字段建议带后缀命名如emb、embedding、sparse_emb避免和id、title等标量混淆。坑 2维度写错 —— 稠密向量必须 0稀疏向量留空稠密向量的dimension必须大于 0且要和 Embedding 模型实际输出维度一致例如 BGE 模型是 1024 维就写 1024稀疏向量不要传 dimension可留空/None因为词表索引不固定# ❌ 稀疏向量误传 dimension或稠密向量 dimension0 zvec.VectorSchema(sparse, zvec.DataType.SPARSE_VECTOR_FP32, 0)维度不一致是入库报错的第一大来源Schema 里写 128模型输出 768插入时立刻校验失败。坑 3Doc 里塞了 Schema 没声明的向量convert_to_cpp_docconvert.py对doc.vectors的每个键都会反查 Schema找不到就抛错schema validate failed: xxx not found in collection schema避坑方法写入前用schema.vector(name)检查或干脆遍历schema.vectors组装 Doc测试用例 doc_helper.py 就是这个做法。坑 4稀疏向量当稠密向量传稀疏向量在 Doc 里是字典而不是列表# ✅ 稀疏向量{向量索引: 权重} zvec.Doc(idd1, vectors{sparse_emb: {3: 0.8, 12: 0.2}})如果 Schema 声明的是SPARSE_VECTOR_FP32却传了[0.1, 0.2, ...]这种 list类型不匹配会直接报错。反过来稠密字段传字典同样会失败。坑 5忘了配索引参数默认落回 Flat 暴力检索VectorSchema的index_param不传时默认是FlatIndexParam()精确暴力检索。小数据没问题数据量大了查询会明显变慢# ✅ 生产环境推荐显式指定 HNSW 索引 zvec.VectorSchema( nameembedding, data_typezvec.DataType.VECTOR_FP32, dimension128, index_paramzvec.HnswIndexParam(ef_construction200, m16), )zvec 提供 5 种向量索引可选FlatIndexParam、HnswIndexParam、HnswRabitqIndexParam、IvfRabitqIndexParam、IVFIndexParam完整示例见 C 语言版 doc_example.c。四、速查表标量与向量支持的类型标量字段FieldSchema支持 15 种类型field_schema.py分类类型整数INT32INT64UINT32UINT64浮点FLOATDOUBLE其他STRINGBOOL数组以上基础类型对应的ARRAY_*版本向量字段支持 6 种类型VECTOR_FP32VECTOR_FP16VECTOR_FP64VECTOR_INT8SPARSE_VECTOR_FP32SPARSE_VECTOR_FP16。五、小结一张表记住配置口诀要点口诀命名标量 向量名字全局不重名维度稠密向量 dimension 0 且与模型一致稀疏不传对应Doc 的 vectors 键名 Schema 的向量名一一对应格式稠密传 list稀疏传 dict索引生产环境显式指定 HNSW / IVF-RaBitQ别靠默认 Flat掌握以上 5 点Doc 与 vectors 字段就能一次配到位。更多完整代码可参考 Python 测试辅助工具 doc_helper.py 和 C API 示例目录 examples/c/动手实践一遍即可上手 zvec 向量数据库。【免费下载链接】zvecA lightweight, lightning-fast, in-process vector database项目地址: https://gitcode.com/GitHub_Trending/zve/zvec创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 zvec的Doc与vectors字段怎么配？新手必看的5大避坑指南
zvec的Doc与vectors字段怎么配新手必看的5大避坑指南【免费下载链接】zvecA lightweight, lightning-fast, in-process vector database项目地址: https://gitcode.com/GitHub_Trending/zve/zveczvec 是一个轻量、极速的进程内向量数据库in-process vector database而Doc与vectors字段是它最基础的两块拼图前者是写入/检索的文档单元后者定义相似度搜索依赖的向量字段。这篇指南用 5 个真实高频坑点帮你在 10 分钟内配好 Doc 与 vectors少走弯路。一、Doc 的 4 个属性一次看懂结构Doc位于 doc.py是插入和检索的核心载体只包含 4 个属性属性类型必填说明idstr✅文档唯一主键PKscorefloat❌检索返回的相关性得分vectorsdict[str, 向量]❌命名向量字典如{embedding: [...]}fieldsdict[str, 值]❌标量字段如标题、时间戳最小可用示例来自 README.md 的 One-Minute Exampledoc zvec.Doc( iddoc_1, vectors{embedding: [0.1, 0.2, 0.3, 0.4]}, fields{title: 第一份文档}, )几个实用小方法doc.vector(embedding)按名取向量、doc.has_field(title)判断字段是否存在、doc.vector_names()列出全部向量名。另外vectors里传入 numpy 数组会被自动转成 list见 _normalize_vectors无需手动处理。二、vectors 字段配置 3 步法从 Schema 到入库vectors 配置的核心在CollectionSchema的vectors参数上规则定义在 collection_schema.py 和 field_schema.py第 1 步给每个向量命名。vectors参数可以传单个VectorSchema也可以传列表实现多向量schema zvec.CollectionSchema( namearticles, fields[zvec.FieldSchema(title, zvec.DataType.STRING)], vectors[ zvec.VectorSchema(title_emb, zvec.DataType.VECTOR_FP32, dimension128), zvec.VectorSchema(body_emb, zvec.DataType.VECTOR_FP32, dimension128), ], )第 2 步选对向量类型。zvec 支持 6 种向量类型field_schema.py 中的SUPPORT_VECTOR_DATA_TYPE稠密向量VECTOR_FP32最常用、VECTOR_FP16省内存、VECTOR_FP64高精度、VECTOR_INT8量化压缩稀疏向量SPARSE_VECTOR_FP32/SPARSE_VECTOR_FP16数据格式是字典{索引: 值}如{3: 0.8, 12: 0.2}第 3 步Doc 的 vectors 字典与 Schema 名一一对应。写入时Doc(vectors{title_emb: [...], body_emb: [...]})的每个键都必须在 Schema 的vectors中声明过——底层转换逻辑 convert.py 会对每个键做严格匹配校验。三、新手 5 大避坑清单 ⚠️坑 1字段名撞车 —— 全局唯一不只是各自唯一CollectionSchema的校验逻辑_check_vectors要求标量字段名与向量名之间也不能重名。# ❌ 报错duplicate vector name embedding zvec.CollectionSchema( namedemo, fields[zvec.FieldSchema(embedding, zvec.DataType.STRING)], # 标量占了名字 vectorszvec.VectorSchema(embedding, zvec.DataType.VECTOR_FP32, 128), )避坑方法向量字段建议带后缀命名如emb、embedding、sparse_emb避免和id、title等标量混淆。坑 2维度写错 —— 稠密向量必须 0稀疏向量留空稠密向量的dimension必须大于 0且要和 Embedding 模型实际输出维度一致例如 BGE 模型是 1024 维就写 1024稀疏向量不要传 dimension可留空/None因为词表索引不固定# ❌ 稀疏向量误传 dimension或稠密向量 dimension0 zvec.VectorSchema(sparse, zvec.DataType.SPARSE_VECTOR_FP32, 0)维度不一致是入库报错的第一大来源Schema 里写 128模型输出 768插入时立刻校验失败。坑 3Doc 里塞了 Schema 没声明的向量convert_to_cpp_docconvert.py对doc.vectors的每个键都会反查 Schema找不到就抛错schema validate failed: xxx not found in collection schema避坑方法写入前用schema.vector(name)检查或干脆遍历schema.vectors组装 Doc测试用例 doc_helper.py 就是这个做法。坑 4稀疏向量当稠密向量传稀疏向量在 Doc 里是字典而不是列表# ✅ 稀疏向量{向量索引: 权重} zvec.Doc(idd1, vectors{sparse_emb: {3: 0.8, 12: 0.2}})如果 Schema 声明的是SPARSE_VECTOR_FP32却传了[0.1, 0.2, ...]这种 list类型不匹配会直接报错。反过来稠密字段传字典同样会失败。坑 5忘了配索引参数默认落回 Flat 暴力检索VectorSchema的index_param不传时默认是FlatIndexParam()精确暴力检索。小数据没问题数据量大了查询会明显变慢# ✅ 生产环境推荐显式指定 HNSW 索引 zvec.VectorSchema( nameembedding, data_typezvec.DataType.VECTOR_FP32, dimension128, index_paramzvec.HnswIndexParam(ef_construction200, m16), )zvec 提供 5 种向量索引可选FlatIndexParam、HnswIndexParam、HnswRabitqIndexParam、IvfRabitqIndexParam、IVFIndexParam完整示例见 C 语言版 doc_example.c。四、速查表标量与向量支持的类型标量字段FieldSchema支持 15 种类型field_schema.py分类类型整数INT32INT64UINT32UINT64浮点FLOATDOUBLE其他STRINGBOOL数组以上基础类型对应的ARRAY_*版本向量字段支持 6 种类型VECTOR_FP32VECTOR_FP16VECTOR_FP64VECTOR_INT8SPARSE_VECTOR_FP32SPARSE_VECTOR_FP16。五、小结一张表记住配置口诀要点口诀命名标量 向量名字全局不重名维度稠密向量 dimension 0 且与模型一致稀疏不传对应Doc 的 vectors 键名 Schema 的向量名一一对应格式稠密传 list稀疏传 dict索引生产环境显式指定 HNSW / IVF-RaBitQ别靠默认 Flat掌握以上 5 点Doc 与 vectors 字段就能一次配到位。更多完整代码可参考 Python 测试辅助工具 doc_helper.py 和 C API 示例目录 examples/c/动手实践一遍即可上手 zvec 向量数据库。【免费下载链接】zvecA lightweight, lightning-fast, in-process vector database项目地址: https://gitcode.com/GitHub_Trending/zve/zvec创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考