独立 Python 向量包 mo-vector 实验

这是公开 PyPI mo-vector==0.1.13 的示例,导入 MoVectorClient。通用 matrixone-python-sdk 的 Client/Session 是另一套接口,见SDK 指南。开发源码与公开发行包的 API 不一定相同;本页从公开 PyPI 安装,不要求源码仓库访问权限。

安装与准备

python -m pip install mo-vector==0.1.13 SQLAlchemy==2.0.43 PyMySQL==1.1.1

使用 Python 3.12 和专用数据库,设置 MO_VECTOR_URI 为该库的 SQLAlchemy MySQL/PyMySQL URI;实际凭证通过环境配置提供。sdk_public_vector_lab 必须不存在,代码会先检查,不以 drop_existing_table=True 覆盖表。

可运行向量实验

本发行包的 DistanceStrategy 枚举公开 L2;本例显式使用 L2,越小越近,不把它描述成 cosine 分数。三维固定向量无需下载模型,预期 a 距离 0,b 距离 sqrt(2)。独立 SQL 验证文本、向量与元数据,再检查删除结果。

import json
import math
import os
from sqlalchemy import create_engine, text
from mo_vector.client import MoVectorClient
from mo_vector.client.vector_client import DistanceStrategy

uri = os.environ["MO_VECTOR_URI"]
engine = create_engine(uri)
client = None
created = False
try:
    with engine.connect() as connection:
        assert connection.exec_driver_sql("SHOW TABLES LIKE 'sdk_public_vector_lab'").first() is None
    client = MoVectorClient(connection_string=uri, table_name="sdk_public_vector_lab",
                            vector_dimension=3, distance_strategy=DistanceStrategy.L2,
                            drop_existing_table=False)
    created = True
    inserted = client.insert(ids=["a", "b"], texts=["dog", "fish"],
                             embeddings=[[1, 0, 0], [0, 1, 0]],
                             metadatas=[{"kind": "animal"}, {"kind": "animal"}])
    assert inserted == ["a", "b"]
    matches = client.query([1, 0, 0], k=2)
    assert [row.id for row in matches] == ["a", "b"]
    assert abs(matches[0].distance) < 1e-6
    assert abs(matches[1].distance - math.sqrt(2)) < 1e-6
    with engine.connect() as connection:
        rows = connection.execute(text("SELECT id,document,embedding,meta "
                                       "FROM sdk_public_vector_lab ORDER BY id")).all()
    assert [(row[0], row[1], json.loads(row[2]), json.loads(row[3])) for row in rows] == [
        ("a", "dog", [1, 0, 0], {"kind": "animal"}),
        ("b", "fish", [0, 1, 0], {"kind": "animal"}),
    ]
    client.delete(ids=["a", "b"])
    assert client.query([1, 0, 0], k=2) == []
    print("public mo-vector 0.1.13 insert/L2/readback/delete verified")
finally:
    try:
        if created:
            client.drop_table()
    finally:
        # 0.1.13 has no public close method; this pinned example releases its Engine.
        if client is not None:
            client._bind.dispose()
        engine.dispose()

成功输出 public mo-vector 0.1.13 insert/L2/readback/delete verified。2026-10-14 本代码在 Python 3.12.14、MO v4.2.5、公开发行包 0.1.13 实际执行,结束时仅删除本次创建的实验表。

0.1.13 没有公开 close 方法;这个固定版本示例通过内部 _bind 释放 Engine,不将该内部属性当作跨版本 API。其 create_full_text_index/full_text_query/mix_query 方法与开发快照不一定相同,本页没有认证全文排序、混合重排或过滤语义。

0.1.13 默认建表会自动创建 IVF 索引(lists=1000、vector_l2_ops),不能把此步骤描述成没有创建索引。SHOW INDEX 实测可见 vec_idx_embedding;本次验收向量结果与索引存在,不认证索引训练、执行计划使用、ANN 加速、性能或全部 filter/metric 组合。需要索引时另外检查 SHOW INDEX 与 EXPLAIN;函数或方法存在不能替代检索结果与执行计划验收。