SqlSugar 接入 PostgreSQL pgvector 完整方案（增删改查 + 强类型相似度查询）
背景
最近在做向量检索相关的功能，技术栈是 .NET + SqlSugar + PostgreSQL + pgvector。SqlSugar 官方对 pgvector 的支持比较有限，网上能搜到的资料大多只解决了一半问题——要么只讲了插入、要么只讲了查询，而且坑点散在好几个不同的地方，单独看每一篇都跑不通。
折腾了一天之后终于把整套方案打通了，这里完整记录一下，希望能帮后来人少走弯路。
环境准备
PostgreSQL 启用 pgvector 扩展：
CREATE EXTENSION IF NOT EXISTS vector;
NuGet 安装两个包：
dotnet add package Pgvector
dotnet add package Pgvector.Npgsql
程序启动时注册 vector 类型映射（必须，否则 Npgsql 不认识 vector 类型）：
NpgsqlConnection.GlobalTypeMapper.UseVector();
核心难点
SqlSugar + pgvector 有两条独立的数据通路，必须分别处理，这是最容易踩坑的地方：
插入/更新路径：走 Insertable / Updateable，SqlSugar 会根据 .NET 类型自动推断参数 DbType。Pgvector.Vector 这个它不认识的类型会被推断成 String，导致 PostgreSQL 报 22P02: invalid input syntax for type vector 错误。
查询表达式路径：走 LINQ 的 OrderBy / Select / Where，里面调用相似度函数（如 <->、<=>、<#>）需要通过 SqlFuncExternal 翻译成 SQL，且参数（查询向量）必须以 pgvector 能识别的格式发送。
把这两条路径分开理解，整套方案就清晰了。
第一步：自定义 Converter（解决插入/更新）
using System.Data;
using SqlSugar;namespace xtop.core;public class PgVectorConverter : ISugarDataConverter
{// Insert / Update 时触发public SugarParameter ParameterConverter<T>(object columnValue, int columnIndex){var name = "@MyPgVector_" + columnIndex;if (columnValue == null) return new SugarParameter(name, null);if (columnValue is float[] floatArray){var vectorValue = new Pgvector.Vector(floatArray);return new SugarParameter(name, vectorValue){// 【核心】必须显式指定为 Object// 否则 SqlSugar 会把 Pgvector.Vector 推断成 String，// Npgsql 按字符串发送，pgvector 列解析失败// 设为 Object 后，Npgsql 会走 GlobalTypeMapper.UseVector() 注册的原生映射DbType = DbType.Object};}throw new Exception($"不支持的向量参数类型: {columnValue.GetType().Name}");}// Select 时触发public T QueryConverter<T>(IDataRecord dataRecord, int dataRecordIndex){var columnValue = dataRecord.GetValue(dataRecordIndex);if (columnValue == null || columnValue == DBNull.Value) return default;// 注册了 UseVector() 之后，读出来直接就是 Pgvector.Vector 对象if (columnValue is Pgvector.Vector vectorObj){if (typeof(T) == typeof(float[])){return (T)(object)vectorObj.ToArray();}}else if (columnValue is string str) // 兼容兜底{if (string.IsNullOrWhiteSpace(str)) return default;var strArray = str.Trim('[', ']').Split(',');return (T)(object)strArray.Select(float.Parse).ToArray();}throw new Exception($"无法将向量转换至目标类型: {typeof(T).Name}");}
}
这里最关键的一行就是 DbType = DbType.Object。少了这一行，所有插入操作都会失败。我在这上面卡了非常久。
第二步：实体定义
[SugarTable("documents")]
public class Document
{[SugarColumn(IsPrimaryKey = true, IsIdentity = true)]public int Id { get; set; }public string Content { get; set; }[SugarColumn(ColumnDataType = "vector(1024)", // 维度按你的 embedding 模型来ColumnName = "contentvector",SqlParameterDbType = typeof(PgVectorConverter))]public float[] ContentVector { get; set; }
}
注意 ColumnDataType = "vector(1024)" 这一行是必须的。SqlSugar 的 CodeFirst 不认识 vector 类型，需要原样指定。维度根据你用的 embedding 模型来选——OpenAI ada-002 是 1536，BGE-large 是 1024，等等。
第三步：定义占位扩展方法（用于 LINQ 表达式）
namespace xtop.core;public static class PgVectorFunc
{public static double L2Distance(float[] vectorColumn, float[] targetVector)=> throw new NotImplementedException();public static double CosineDistance(float[] vectorColumn, float[] targetVector)=> throw new NotImplementedException();public static double InnerProduct(float[] vectorColumn, float[] targetVector)=> throw new NotImplementedException();
}
这些方法只在表达式树里使用，运行时不会真的执行，所以方法体直接抛异常就行。它们的作用是给 LINQ 提供强类型签名，让 IDE 有提示、有类型检查。
第四步：注册 SqlFuncExternal（解决查询）
这是整套方案里最巧妙的一步，把上面三个占位方法翻译成 pgvector 的 SQL 操作符：
var SqlFuncList = new List<SqlFuncExternal>
{new SqlFuncExternal{UniqueMethodName = "CosineDistance",MethodValue = (expInfo, dbType, expContext) =>{// 1. 翻译列名var colName = expInfo.Args[0].MemberName?.ToString();var col = expContext.GetTranslationColumnName(colName);// 2. 取参数占位符名（例如 @MethodConst0）var valName = expInfo.Args[1].MemberName?.ToString();// 3. 【核心黑科技】拦截参数并改写值// 从表达式上下文里找到这个参数，如果它的值是 float[]，// 就当场把它改成 pgvector 字面量字符串var param = expContext.Parameters.FirstOrDefault(p => p.ParameterName == valName);if (param != null && param.Value is float[] floatArr){param.Value = "[" + string.Join(",", floatArr) + "]";}// 4. 用 ::vector 把字符串强转成 vector 类型return $"({col} <=> {valName}::vector)";}},new SqlFuncExternal{UniqueMethodName = "L2Distance",MethodValue = (expInfo, dbType, expContext) =>{var colName = expInfo.Args[0].MemberName?.ToString();var col = expContext.GetTranslationColumnName(colName);var valName = expInfo.Args[1].MemberName?.ToString();var param = expContext.Parameters.FirstOrDefault(p => p.ParameterName == valName);if (param != null && param.Value is float[] floatArr){param.Value = "[" + string.Join(",", floatArr) + "]";}return $"({col} <-> {valName}::vector)";}},new SqlFuncExternal{UniqueMethodName = "InnerProduct",MethodValue = (expInfo, dbType, expContext) =>{var colName = expInfo.Args[0].MemberName?.ToString();var col = expContext.GetTranslationColumnName(colName);var valName = expInfo.Args[1].MemberName?.ToString();var param = expContext.Parameters.FirstOrDefault(p => p.ParameterName == valName);if (param != null && param.Value is float[] floatArr){param.Value = "[" + string.Join(",", floatArr) + "]";}return $"({col} <#> {valName}::vector)";}}
};
为什么要"伸手进参数集合改 Value"：
SqlSugar 在解析 CosineDistance(it.ContentVector, vector) 时，会把 vector（一个 float[]）作为参数生成出来。但 SqlSugar 并不知道这个数组该按什么格式发给数据库，默认推断会出问题。
直接在调用方把数组转成字符串再传进去也能跑通，但那样业务代码就脏了——每次查询都得手动转换一次。这个方案的精髓是在 SqlFunc 翻译的时候，从 expContext.Parameters 里把已经生成好的参数找出来，当场把 Value 改成字符串。配合 SQL 里的 ::vector cast，让 PostgreSQL 自己把字符串转回 vector 类型。
这样一来，业务代码可以保持完全的类型安全和直觉化，所有的脏活都封装在了 SqlFuncExternal 内部。
把这个 list 注册到 SqlSugarClient：
ConfigureExternalServices = new ConfigureExternalServices
{SqlFuncServices = SqlFuncList
}
第五步：使用
插入：
var doc = new Document
{Content = "hello vector",ContentVector = embeddingFromModel // float[1024]
};
await _rawRep.InsertAsync(doc);
更新：
item.ContentVector = vector;
item.VectorStatus = 2;
item.VectorDate = DateTime.Now;
await _rawRep.AsUpdateable(item).ExecuteCommandAsync();
相似度查询（强类型 LINQ）：
var list = _rawRep.AsQueryable()// 可以混合其他业务条件//.Where(it => it.Id > 0)// 强类型排序，按余弦距离从近到远（距离越小越相似）.OrderBy(it => PgVectorFunc.CosineDistance(it.ContentVector, vector)).Select(it => new{it.Id,it.Content,// 在 Select 里直接把距离查出来，方便前端展示匹配度Distance = PgVectorFunc.CosineDistance(it.ContentVector, vector)}).Take(5).ToList();
可以看到业务代码非常干净，和普通 LINQ 查询几乎没有区别。
性能优化：建索引
数据量大了之后必须建索引，否则全表扫描会非常慢：
-- HNSW 索引（推荐，查询快，构建慢）
CREATE INDEX ON documents USING hnsw (contentvector vector_cosine_ops);-- 或者 IVFFlat 索引（构建快，查询稍慢）
CREATE INDEX ON documents USING ivfflat (contentvector vector_cosine_ops) WITH (lists = 100);
注意：索引的操作符类必须和你查询用的距离函数匹配，否则索引不会生效：
距离函数 SQL 操作符 索引操作符类
CosineDistance <=> vector_cosine_ops
L2Distance <-> vector_l2_ops
InnerProduct <#> vector_ip_ops
踩坑总结
按照我自己的踩坑顺序整理，希望你不用再踩一遍：
DbType = DbType.Object 是 Converter 的灵魂。少这一行，插入直接报 22P02: invalid input syntax for type vector。
NpgsqlConnection.GlobalTypeMapper.UseVector() 必须在程序启动时调用。少了这步，读取时会报 Reading as 'System.Object' is not supported for fields having DataTypeName 'public.vector'。
插入路径和查询路径是两条独立的管道，要分别处理。Converter 解决插入/更新，SqlFuncExternal 解决 LINQ 查询，互不替代。
SqlFuncExternal 里改写 param.Value 是关键技巧。这样业务代码可以保持强类型 + 干净，不用每次手动转字符串。
::vector cast 是必须的。因为参数被改成了字符串，需要让 PostgreSQL 强转回 vector 类型。
CosineDistance 越小越相似，所以是 OrderBy 升序，不是 OrderByDescending。
维度必须严格匹配。建表时声明的 vector(N) 和插入的 float[] 长度必须一致，差一个都会报错。同一张表里所有向量维度也必须一致。
embedding 模型一旦选定就和数据绑定了。换模型就必须重新生成所有向量，没有捷径。所以选模型之前先想清楚。
结语
SqlSugar 没有官方的 pgvector 支持，但通过 ISugarDataConverter 和 SqlFuncExternal 这两个扩展点，完全可以做到强类型、干净的接入。希望这篇文章能帮到同样在折腾这个组合的朋友。
如果有疑问或者更好的方案，欢迎评论交流。