首页 > 基础资料博客日记

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

2026-04-14 16:00:02基础资料围观1次

这篇文章介绍了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 这两个扩展点，完全可以做到强类型、干净的接入。希望这篇文章能帮到同样在折腾这个组合的朋友。
如果有疑问或者更好的方案，欢迎评论交流。

文章来源:https://www.cnblogs.com/harryPei/p/19866048
本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系邮箱：jacktools123@163.com进行投诉反馈，一经查实，立即删除！

标签：

上一篇：做 AI 应用必懂：Function Call 和 Skills，到底差在哪？
下一篇：Rudist v0.5.1 发布：AI 驱动的 Redis 客户端，更快、更直观

首页 > 基础资料博客日记

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

相关文章

最新发布

点击排行

本站推荐

标签云

首页 > 基础资料 博客日记

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

相关文章

最新发布

点击排行

本站推荐

标签云

首页 > 基础资料博客日记