Laravel 13 AsVector 跨库迁移怎么对齐向量值：MariaDB 二进制与 PostgreSQL 文本边界

Laravel 13 新增 AsVector 后，Eloquent 模型可以把向量列当成 PHP 浮点数组使用，但“统一的 PHP 访问方式”不等于“数据库里存的是同一种字节”。这个 cast 会根据当前连接的 grammar 区分 MariaDB 和 PostgreSQL：前者写入时把 JSON 文本交给 vec_fromtext()，读取时解码小端 float32；后者则直接使用 JSON 文本。迁移时真正要盯住的是写入值、读取值和查询绑定这三条边界。

先看 AsVector 的 PHP 输入输出契约

在模型里声明 embedding cast：

 AsVector::class,
        ];
    }
}

赋值时可以传 [0.12, -0.30, 0.88]，也可以传实现 Arrayable 的集合或值对象；cast 会把元素转成浮点数并按连续索引编码。读取时拿到的是 PHP 浮点数组，空值仍然是 null。因此业务层不要依赖数据库原始字节，也不要把读出的数组重新当作已经适配某个驱动的 SQL 片段。

模型声明相同，MariaDB 与 PostgreSQL 的落库形态不同

AsVector::set() 会先把数组编码成 JSON。连接使用 MariaDB grammar 时，写入值被包装为 vec_fromtext('...') 表达式，让服务端完成从 JSON 文本到向量列的转换；非 MariaDB grammar 则返回 JSON 字符串。

读取路径正好相反：MariaDB grammar 下，返回的向量值按照小端 float32 解包；其他路径按 JSON 文本解码，再逐项转成浮点数。这解释了一个常见现象：同一条记录在 SQL 客户端里看起来可能是二进制或带括号的文本，但在 Eloquent 中都应成为可迭代的浮点数组。

向量距离查询交给 grammar 生成绑定

Laravel 13 同时补充了面向向量距离的查询方法，例如 whereVectorSimilarTo、whereVectorDistanceLessThan、orderByVectorDistance 和 selectVectorDistance。代码可以保持数据库无关：

$query = Document::query()
    ->whereVectorSimilarTo('embedding', $queryEmbedding)
    ->orderByVectorDistance('embedding', $queryEmbedding)
    ->get();

在 MariaDB grammar 中，距离表达式使用 vec_distance_cosine(column, vec_fromtext(?))，查询参数仍通过绑定传入。实践上不要把数组拼进 SQL，也不要在模型里手写 MariaDB 函数来“修正”参数；这样会破坏跨驱动切换，并绕开框架对列名包装和绑定位置的处理。至于相似度阈值、维度不一致和索引策略，仍应按实际数据库版本与项目迁移方案单独确认，AsVector 本身不是维度校验器。

迁移时用四项回归清单锁住兼容边界

第一，确认模型字段名、数据库列名和当前连接一致；同一模型切换连接时，cast 会跟着连接 grammar 走。第二，准备固定维度的浮点样本，同时覆盖正数、负数、零和小数，检查写入后重新读取的类型与顺序。第三，单独测 null、普通数组和 Arrayable，避免集合被业务层提前序列化成字符串。第四，分别在 MariaDB 与 PostgreSQL 连接上编译并执行距离查询，确认查询方法、绑定参数和列表达式属于同一驱动语义。

如果项目只是从 PostgreSQL 迁到 MariaDB，不要只复制表结构或把历史文本直接当作二进制列导入。先确定目标列的真实类型和数据库提供的向量文本转换方式，再通过应用层或一次性迁移脚本重写数据；Laravel 的 cast 负责运行时表示转换，不替代数据迁移本身。

相关问题

AsVector 读取出来一定是字符串吗？

不是。官方文档说明读取结果是浮点数组；MariaDB 的二进制返回值也由 cast 解包后再交给模型。

MariaDB 和 PostgreSQL 可以共用同一段模型 cast 吗？

可以共用 AsVector::class 声明，但列类型、驱动 grammar、历史数据格式和距离函数支持必须分别准备。

为什么不直接把向量 JSON 拼进 SQL？

因为 Laravel 的向量查询方法会按 grammar 生成表达式并绑定参数。手工拼接既容易产生转义问题，也会把 MariaDB 专用函数泄漏到跨库代码中。

发布前摘要

• 模型层统一使用 AsVector，业务层只处理浮点数组。
• MariaDB 重点核对 vec_fromtext、小端 float32 与距离函数；PostgreSQL 重点核对 JSON 文本与兼容列。
• 迁移前固定维度、样本和驱动矩阵，距离查询保持参数绑定。