Laravel 13 AsVector 怎么映射向量字段：MariaDB 二进制与 PostgreSQL 文本值

同一个 Document 模型要同时跑在 MariaDB 和 PostgreSQL 上时，embedding 最容易泄漏数据库差异：业务代码想拿到普通数组，MariaDB 保存的是二进制向量，PostgreSQL 兼容驱动常见的是文本向量。Laravel 13 新增的 AsVector，就是把这层转换收回 Eloquent cast，而不是让控制器和仓储层到处判断连接类型。

AsVector 把领域数组和数据库向量隔开

这个模式可以叫“端口式类型转换”：Document 只声明 embedding 经过 AsVector::class，上层始终面对 PHP 浮点数组；底层才分别处理 MariaDB 二进制向量和 PostgreSQL 文本向量。数据库格式是适配细节，不再成为领域对象的一部分。

use Illuminate\Database\Eloquent\Casts\AsVector;

class Document extends Model
{
    protected function casts(): array
    {
        return [
            'embedding' => AsVector::class,
        ];
    }
}

官方文档给出的契约很明确：设置属性时可传 PHP 数组或实现 Arrayable 的对象，读取时得到由浮点数组成的数组。这样服务层可以统一做维度校验、归一化或批量组装，而不用碰数据库表示。

为什么跨库迁移时这个边界更重要

没有 cast 时，常见做法是在 setter、仓储方法甚至控制器里手写序列化。短期看只是两行转换，长期却会形成三类耦合：模型属性有时是字符串、有时是数组；测试必须了解驱动格式；切换连接时还要逐个查找手写分支。

这里别急着把“可移植”理解成数据库能力完全相同。cast 统一的是值边界，列类型、索引方式、距离算子和版本要求仍由目标数据库决定。迁移时要把 schema 与查询计划单独验收。

查询绑定为什么不能只做字符串拼接

向量相似度查询里，queryEmbedding 不只用于模型赋值，还会进入 whereVectorSimilarTo 和 orderByVectorDistance。Laravel 13 的更新说明强调，AsVector 会为 MariaDB 距离函数正确转换绑定值；同一套 Eloquent 查询接口也延续 PostgreSQL 兼容查询的使用方式。

$queryEmbedding = [0.12, 0.34, 0.56];

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

如果绕过查询构造器手工拼值，MariaDB 距离函数可能收到不符合原生格式的参数；即使语句能发送，也把转义、类型和维度问题重新带回业务层。更稳妥的边界是让 AsVector 处理绑定，让查询方法表达“筛选相似项”和“按距离排序”。

哪些写法会破坏这个模式

• 把字符串当领域值：读取 embedding 后继续解析数据库文本，说明 cast 没有成为唯一入口。
• 在模型外判断驱动：业务服务出现 MariaDB/PostgreSQL 分支，会让迁移成本继续扩散。
• 忽略维度约束：AsVector 负责表示转换，不替业务校验每条向量的维度和来源。
• 只测保存不测检索：应同时验证赋值、读取、相似度过滤和距离排序，避免查询绑定成为盲区。

采用前可以做一个小型双库契约测试：同一组浮点数分别写入两种数据库，再读取为数组，并用相同 queryEmbedding 完成排序。应用层断言应只关心数组内容和结果顺序，不比较底层序列化文本。

常见问题

AsVector 会自动创建向量列和索引吗？

不会。它是 Eloquent 值转换边界；迁移文件中的列类型、维度、索引和数据库扩展仍需按目标数据库配置。

已有自定义 cast 要立刻替换吗？

先比较契约。若现有 cast 还承担归一化、加密或业务校验，应把这些职责拆清并补双库回归测试，再决定是否换成 AsVector。