18 API Reference_zh.md

16. API 参考速查表

QuiverDbContext

方法 / 属性	返回类型	说明
Set<TEntity>()	QuiverSet<TEntity>	按类型获取向量集合（未注册抛异常）
SaveAsync(path?)	Task	异步全量原子快照（临时文件 + File.Move）
AppendAsync(path?)	Task	将当前内存实体作为新段追加到现有 v4 文件，仅重写 footer。O(Δ)
FlushTombstonesAsync(path?)	Task	仅将待删除主键作为 Tombstone 段追加，不重写存活实体
LoadAsync(path?)	Task	异步按顺序回放段 + 应用墓碑 + （可选）重绑 mmap region；文件不存在静默返回
ExportAsync(path, format)	Task	导出为 JSON / XML 旁路
ImportAsync(path, format)	Task	从 JSON / XML 导入到当前内存
Dispose()	void	同步释放（不保存）
DisposeAsync()	ValueTask	异步释放资源；仅当 SaveOnDispose = true 时才会先调用 SaveAsync()

文件格式迁徙（Vorcyc.Quiver.Migration）

类型 / 方法	说明
QuiverMigrator.MigrateAsync(sourceFile, destinationFile, typeMap, migrationRules?, options?)	将 v1/v2/v3 旧 .vdb 文件离线升级为当前 v4 QDB\x04 格式。可同时应用 Schema 迁移规则。
MigrateOptions.Overwrite	目标文件已存在时是否允许覆盖。
MigrateOptions.DeleteSourceOnSuccess	迁徙成功后是否删除源文件。
MigrateOptions.AllowNoop	源文件已经是 v4 且源/目标相同时是否允许直接返回。

迁徙时必须提供 typeMap（文件中的类型全名 → 当前 CLR 类型）。如果旧文件存在属性重命名，应通过 migrationRules 传入 SchemaMigrationRule，否则旧字段可能在解码阶段被跳过。

QuiverSet<TEntity>

属性

属性	类型	说明
Count	int	实体数量（读锁保护，线程安全）
VectorFields	IReadOnlyDictionary<string, int>	向量字段名 → 维度的只读映射（惰性缓存）

枚举

方法	返回类型	锁	说明
GetEnumerator()	IEnumerator<TEntity>	读锁（快照）	支持 foreach 和 LINQ。读锁内拍快照，释放后枚举

CRUD 方法

方法	返回类型	锁	说明
Add(entity)	void	写锁	添加单个实体（主键重复抛异常）
AddRange(entities)	void	写锁	批量添加（原子，两阶段提交）
AddRangeAsync(entities, ct)	Task	写锁	异步批量添加（Task.Run）
Upsert(entity)	void	写锁	插入或更新（单次写锁内完成）
Remove(entity)	bool	写锁	按实体主键删除
RemoveByKey(key)	bool	写锁	按主键值删除
Find(key)	TEntity?	读锁	按主键查找，O(1)
Exists(key)	bool	读锁	按主键判断存在性，O(1)（仅查 _keyToId）
Exists(predicate)	bool	读锁	按条件判断存在性，O(n) 短路（命中即返回，无快照分配）
Clear()	void	写锁	清空全部数据 + 索引

搜索方法（同步）

方法	返回类型	说明
Search(selector, query, topK)	List<QuiverSearchResult<T>>	Top-K 搜索
Search(selector, query, topK, Expression filter)	List<QuiverSearchResult<T>>	带表达式过滤
Search(selector, query, topK, Func filter, overFetchMultiplier)	List<QuiverSearchResult<T>>	带委托过滤 + 过采样
SearchByThreshold(selector, query, threshold)	List<QuiverSearchResult<T>>	阈值搜索
SearchTop1(selector, query)	QuiverSearchResult<T>?	最相似单个实体
Search(query, topK)	List<QuiverSearchResult<T>>	默认字段 Top-K
SearchTop1(query)	QuiverSearchResult<T>?	默认字段 Top-1

搜索参数规则：query 不能为 null；查询向量长度必须等于字段的 Dimensions 或 EffectiveDimensions；topK 和 overFetchMultiplier 必须大于 0；阈值搜索拒绝 float.NaN。

搜索方法（异步）

所有同步搜索方法均有对应的 Async 后缀版本，附加 CancellationToken 参数，通过 Task.Run 卸载到线程池。这些方法是 CPU-bound 便利封装，不是真正的 I/O 异步。

特性标记

特性	目标	必需	说明
[QuiverKey]	属性	✅	标记主键（有且仅有一个）
[QuiverVector(dim, metric)]	属性	✅	标记向量字段（至少一个，类型须为 float[] 或 Half[]）。可用具名参数见下表
[QuiverIndex(type, ...)]	属性	❌	配置索引类型及参数（默认 Flat）
[QuiverLargeField]	属性	❌	标记大 byte[] 字段，写入独立 Blob 段。可用具名参数见下表
[QuiverEntity(name)]	类 / 结构体	❌	为实体类型声明持久化稳定名，解耦 CLR 命名空间与磁盘标识符

[QuiverVector] 具名参数

参数	类型	默认值	说明
Nullable	bool	false	为 true 时允许向量为 null；null 向量的实体仍可写入但不进入该字段索引
MemoryMode	VectorMemoryMode	InMemory	字段级向量内存策略，仅在全局模式为 PerField 时生效
Quantization	VectorQuantization	None	磁盘量化模式；Sq8 使磁盘和 mmap 占用降至 float32 的 ~25%，召回率损失通常 < 1%
EffectiveDimensions	int	0（禁用）	Matryoshka 截断维度；正值且小于 Dimensions 时仅存储 / 索引前 N 维
CustomSimilarity	Type?	null	自定义相似度计算类型（须为实现 ISimilarity<float> 的 struct），设置后 Metric 被忽略

[QuiverLargeField] 具名参数

参数	类型	默认值	说明
Nullable	bool	true	为 false 时不允许 null，写入 null 时抛出异常
MemoryMode	LargeFieldMemoryMode	InMemory	字段级大字段内存策略，仅在全局模式为 PerField 时生效

[QuiverEntity] 参数

参数	类型	说明
name（构造参数）	string	持久化稳定名，必须非空且在同一 QuiverDbContext 内全局唯一

对于非 InMemory 的向量字段（VectorMemoryMode.LazyLoad / MemoryMapped），属性及其所在的整条嵌套类型链都必须是 partial，属性类型必须是 float[] 或 float[]?。大字段的 LazyLoad / PagedCache 模式同理要求 partial byte[]?。源生成器会针对无效声明报告 QVR001–QVR004 诊断。

枚举

DistanceMetric

值	说明
Cosine	余弦相似度（预归一化优化）
Euclidean	欧几里得距离（转换为相似度）
DotProduct	内积
Manhattan	曼哈顿距离 / L1 范数（转换为相似度）
Chebyshev	切比雪夫距离 / L∞ 范数（转换为相似度）
Pearson	皮尔逊相关系数（去均值余弦）
Hamming	汉明相似度（匹配比例）
Jaccard	广义 Jaccard 相似度（Σmin/Σmax）
Canberra	堪培拉距离（转换为相似度）

VectorIndexType

值	说明
Flat	暴力搜索，100% 精确
HNSW	分层可导航小世界图
IVF	倒排文件索引
KDTree	KD 树

VectorQuantization

值	说明
None	无量化，原始 float32 存储（默认，无损）
Sq8	8 位有符号标量量化，每行一个缩放因子，磁盘/mmap 占用约为 float32 的 25%。推荐用于余弦/点积归一化向量

VectorMemoryMode（字段级）

值	说明
InMemory	向量在数据库加载时全量读入托管堆
LazyLoad	向量在首次访问属性时按需物化到托管堆（需要 partial 属性）
MemoryMapped	向量通过内存映射文件暴露，不占用托管堆（需要 partial 属性和有效 DatabasePath）

GlobalVectorMemoryMode（全局，配置于 QuiverDbOptions.Vectors.MemoryMode）

值	说明
InMemory	所有向量字段使用 InMemory
LazyLoad	所有向量字段使用 LazyLoad
MemoryMapped	所有向量字段使用 MemoryMapped
Auto	按 MemoryMapThresholdBytes 阈值自动选择 InMemory 或 MemoryMapped
PerField	由各字段 [QuiverVector(MemoryMode = ...)] 决定

LargeFieldMemoryMode（字段级）

值	说明
InMemory	大字段在数据库加载时全量读入托管堆
LazyLoad	大字段在首次访问时从文件按需读取（需要 partial 属性和有效 DatabasePath）
PagedCache	大字段按需读取，并以有界 LRU 缓存保存最近访问的 payload（需要 partial 属性）

GlobalLargeFieldMemoryMode（全局，配置于 QuiverDbOptions.LargeFields.MemoryMode）

值	说明
InMemory	所有大字段使用 InMemory
LazyLoad	所有大字段使用 LazyLoad
PagedCache	所有大字段使用 PagedCache
PerField	由各字段 [QuiverLargeField(MemoryMode = ...)] 决定

ExportFormat

值	说明
Json	JSON 格式（导出/导入）
Xml	XML 格式（导出/导入）

搜索结果

public record QuiverSearchResult<TEntity>(TEntity Entity, float Similarity);

属性	类型	说明
Entity	TEntity	匹配的实体实例
Similarity	float	相似度分数（值越大越相似）