SqlSugar 接入 PostgreSQL pgvector 完整方案（增删改查 + 强类型相似度查询）

背景

最近在做向量检索相关的功能，技术栈是 .NET + SqlSugar + PostgreSQL + pgvector。SqlSugar 官方对 pgvector 的支持比较有限，网上能搜到的资料大多只解决了一半问题------要么只讲了插入、要么只讲了查询，而且坑点散在好几个不同的地方，单独看每一篇都跑不通。

折腾了一天之后终于把整套方案打通了，这里完整记录一下，希望能帮后来人少走弯路。

环境准备

PostgreSQL 启用 pgvector 扩展：

sql 复制代码

CREATE EXTENSION IF NOT EXISTS vector;

NuGet 安装两个包：

bash 复制代码

dotnet add package Pgvector
dotnet add package Pgvector.Npgsql

程序启动时注册 vector 类型映射（必须，否则 Npgsql 不认识 vector 类型）：

csharp 复制代码

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（解决插入/更新）

csharp 复制代码

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。少了这一行，所有插入操作都会失败。我在这上面卡了非常久。

第二步：实体定义

csharp 复制代码

[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 表达式）

csharp 复制代码

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 操作符：

csharp 复制代码

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：

csharp 复制代码

ConfigureExternalServices = new ConfigureExternalServices
{
    SqlFuncServices = SqlFuncList
}

第五步：使用

插入：

csharp 复制代码

var doc = new Document
{
    Content = "hello vector",
    ContentVector = embeddingFromModel  // float[1024]
};
await _rawRep.InsertAsync(doc);

更新：

csharp 复制代码

item.ContentVector = vector;
item.VectorStatus = 2;
item.VectorDate = DateTime.Now;
await _rawRep.AsUpdateable(item).ExecuteCommandAsync();

相似度查询（强类型 LINQ）：

csharp 复制代码

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 查询几乎没有区别。

性能优化：建索引

数据量大了之后必须建索引，否则全表扫描会非常慢：

sql 复制代码

-- 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 这两个扩展点，完全可以做到强类型、干净的接入。希望这篇文章能帮到同样在折腾这个组合的朋友。

如果有疑问或者更好的方案，欢迎评论交流。