yimo-kit 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- yimo/__init__.py +26 -0
- yimo/kit/__init__.py +98 -0
- yimo/kit/ai/__init__.py +110 -0
- yimo/kit/ai/_internal/__init__.py +27 -0
- yimo/kit/ai/_internal/failover.py +535 -0
- yimo/kit/ai/_internal/pool.py +526 -0
- yimo/kit/ai/_internal/rerank_transport.py +137 -0
- yimo/kit/ai/_internal/retry_after.py +51 -0
- yimo/kit/ai/_internal/sdk_client.py +463 -0
- yimo/kit/ai/_internal/service_base.py +115 -0
- yimo/kit/ai/_internal/types.py +28 -0
- yimo/kit/ai/agent/__init__.py +127 -0
- yimo/kit/ai/agent/approval.py +66 -0
- yimo/kit/ai/agent/errors.py +128 -0
- yimo/kit/ai/agent/loop.py +643 -0
- yimo/kit/ai/agent/mcp.py +278 -0
- yimo/kit/ai/agent/registry.py +203 -0
- yimo/kit/ai/agent/session.py +150 -0
- yimo/kit/ai/agent/skill.py +370 -0
- yimo/kit/ai/agent/types.py +161 -0
- yimo/kit/ai/chat_service.py +724 -0
- yimo/kit/ai/decision/__init__.py +57 -0
- yimo/kit/ai/decision/decima.py +853 -0
- yimo/kit/ai/decision/laya.py +552 -0
- yimo/kit/ai/embedding_service.py +198 -0
- yimo/kit/ai/exceptions.py +109 -0
- yimo/kit/ai/image_service.py +84 -0
- yimo/kit/ai/messages.py +105 -0
- yimo/kit/ai/model_builder.py +121 -0
- yimo/kit/ai/model_client.py +62 -0
- yimo/kit/ai/profiles.py +577 -0
- yimo/kit/ai/rerank_service.py +136 -0
- yimo/kit/ai/runner.py +1127 -0
- yimo/kit/common_kit.py +221 -0
- yimo/kit/config/__init__.py +44 -0
- yimo/kit/config/kit_config.py +210 -0
- yimo/kit/config/log_config.py +171 -0
- yimo/kit/crawl/__init__.py +71 -0
- yimo/kit/crawl/article_io.py +325 -0
- yimo/kit/crawl/article_models.py +172 -0
- yimo/kit/crawl/deepseek_kit.py +673 -0
- yimo/kit/crawl/web_article_kit.py +638 -0
- yimo/kit/crawl/wx_article_kit.py +692 -0
- yimo/kit/db/__init__.py +101 -0
- yimo/kit/db/audit.py +625 -0
- yimo/kit/db/base_db_kit.py +1265 -0
- yimo/kit/db/crud.py +423 -0
- yimo/kit/db/engine.py +235 -0
- yimo/kit/db/exceptions.py +45 -0
- yimo/kit/db/models/__init__.py +33 -0
- yimo/kit/db/models/base.py +56 -0
- yimo/kit/db/mysql_kit.py +348 -0
- yimo/kit/db/pg_kit.py +442 -0
- yimo/kit/db/query.py +338 -0
- yimo/kit/db/session.py +85 -0
- yimo/kit/db/sqlite_kit.py +462 -0
- yimo/kit/db/transaction.py +109 -0
- yimo/kit/docs/__init__.py +34 -0
- yimo/kit/docs/anydoc_kit.py +490 -0
- yimo/kit/docs/docx_kit.py +895 -0
- yimo/kit/docs/md2doc_kit.py +1801 -0
- yimo/kit/docs/mineru_kit.py +1497 -0
- yimo/kit/docs/rc_docparser_kit.py +654 -0
- yimo/kit/file_kit.py +518 -0
- yimo/kit/license_kit.py +533 -0
- yimo/kit/redis_kit.py +392 -0
- yimo_kit-0.1.0.dist-info/METADATA +1673 -0
- yimo_kit-0.1.0.dist-info/RECORD +70 -0
- yimo_kit-0.1.0.dist-info/WHEEL +4 -0
- yimo_kit-0.1.0.dist-info/licenses/LICENSE +201 -0
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Copyright (c) 2021-2026 溢墨修心(Yimo). All Rights Reserved.
|
|
3
|
+
|
|
4
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
5
|
+
you may not use this file except in compliance with the License.
|
|
6
|
+
You may obtain a copy of the License at
|
|
7
|
+
|
|
8
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
9
|
+
|
|
10
|
+
Unless required by applicable law or agreed to in writing, software
|
|
11
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
12
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
13
|
+
See the License for the specific language governing permissions and
|
|
14
|
+
limitations under the License.
|
|
15
|
+
|
|
16
|
+
Project: yimo
|
|
17
|
+
Author: 溢墨修心(Yimo)
|
|
18
|
+
"""
|
|
19
|
+
|
|
20
|
+
# date: 2026-08-23
|
|
21
|
+
"""统一数据库异常体系
|
|
22
|
+
|
|
23
|
+
所有异常继承 SQLAlchemyError,确保 @transactional 装饰器能统一捕获。
|
|
24
|
+
"""
|
|
25
|
+
|
|
26
|
+
from sqlalchemy.exc import SQLAlchemyError
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
class DBError(SQLAlchemyError):
|
|
30
|
+
"""所有数据库异常的基类"""
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
class NotFoundError(DBError):
|
|
34
|
+
"""记录不存在"""
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
class VectorNotSupportedError(DBError):
|
|
38
|
+
"""当前后端不支持所请求的向量能力
|
|
39
|
+
|
|
40
|
+
用于语义上"该后端没有这条能力路径"的场景(区别于"执行失败")。典型用法:
|
|
41
|
+
``MySqlKit.search_vectors`` 在 MySQL Community / Commercial 发行版上恒定抛出本异常
|
|
42
|
+
(未提供 `DISTANCE()` 距离函数,且 `VECTOR` 列无法建立索引)。
|
|
43
|
+
|
|
44
|
+
仅继承 :class:`DBError`,遵循项目「异常 ``*Error`` 继承 ``DBError``」的统一错误面约定。
|
|
45
|
+
"""
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Copyright (c) 2021-2026 溢墨修心(Yimo). All Rights Reserved.
|
|
3
|
+
|
|
4
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
5
|
+
you may not use this file except in compliance with the License.
|
|
6
|
+
You may obtain a copy of the License at
|
|
7
|
+
|
|
8
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
9
|
+
|
|
10
|
+
Unless required by applicable law or agreed to in writing, software
|
|
11
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
12
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
13
|
+
See the License for the specific language governing permissions and
|
|
14
|
+
limitations under the License.
|
|
15
|
+
|
|
16
|
+
Project: yimo
|
|
17
|
+
Author: 溢墨修心(Yimo)
|
|
18
|
+
"""
|
|
19
|
+
|
|
20
|
+
# date: 2026-08-23
|
|
21
|
+
"""模型导出"""
|
|
22
|
+
|
|
23
|
+
from yimo.kit.db.models.base import (
|
|
24
|
+
AuditMixin,
|
|
25
|
+
SoftDeleteMixin,
|
|
26
|
+
TimestampMixin,
|
|
27
|
+
)
|
|
28
|
+
|
|
29
|
+
__all__ = [
|
|
30
|
+
"TimestampMixin",
|
|
31
|
+
"SoftDeleteMixin",
|
|
32
|
+
"AuditMixin",
|
|
33
|
+
]
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Copyright (c) 2021-2026 溢墨修心(Yimo). All Rights Reserved.
|
|
3
|
+
|
|
4
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
5
|
+
you may not use this file except in compliance with the License.
|
|
6
|
+
You may obtain a copy of the License at
|
|
7
|
+
|
|
8
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
9
|
+
|
|
10
|
+
Unless required by applicable law or agreed to in writing, software
|
|
11
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
12
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
13
|
+
See the License for the specific language governing permissions and
|
|
14
|
+
limitations under the License.
|
|
15
|
+
|
|
16
|
+
Project: yimo
|
|
17
|
+
Author: 溢墨修心(Yimo)
|
|
18
|
+
"""
|
|
19
|
+
|
|
20
|
+
# date: 2026-08-23
|
|
21
|
+
"""SQLModel 基础模型混入类
|
|
22
|
+
|
|
23
|
+
提供 TimestampMixin(时间戳)、SoftDeleteMixin(软删除)、AuditMixin(审计字段)。
|
|
24
|
+
default_factory 统一使用 datetime.now(UTC),避免废弃的 utcnow()。
|
|
25
|
+
"""
|
|
26
|
+
|
|
27
|
+
from datetime import UTC, datetime
|
|
28
|
+
from typing import Optional
|
|
29
|
+
|
|
30
|
+
from sqlmodel import Field, SQLModel
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def _utcnow() -> datetime:
|
|
34
|
+
"""获取当前 UTC 时间"""
|
|
35
|
+
return datetime.now(UTC)
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
class TimestampMixin(SQLModel):
|
|
39
|
+
"""时间戳混入:自动添加 created_at 和 updated_at 字段"""
|
|
40
|
+
|
|
41
|
+
created_at: datetime = Field(default_factory=_utcnow, nullable=False)
|
|
42
|
+
updated_at: Optional[datetime] = Field(default=None, nullable=True)
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
class SoftDeleteMixin(SQLModel):
|
|
46
|
+
"""软删除混入:添加 is_deleted 和 deleted_at 字段"""
|
|
47
|
+
|
|
48
|
+
is_deleted: bool = Field(default=False, nullable=False)
|
|
49
|
+
deleted_at: Optional[datetime] = Field(default=None, nullable=True)
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
class AuditMixin(TimestampMixin):
|
|
53
|
+
"""审计混入:在 TimestampMixin 基础上添加操作人字段"""
|
|
54
|
+
|
|
55
|
+
created_by: Optional[str] = Field(default=None, max_length=100)
|
|
56
|
+
updated_by: Optional[str] = Field(default=None, max_length=100)
|
yimo/kit/db/mysql_kit.py
ADDED
|
@@ -0,0 +1,348 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Copyright (c) 2021-2026 溢墨修心(Yimo). All Rights Reserved.
|
|
3
|
+
|
|
4
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
5
|
+
you may not use this file except in compliance with the License.
|
|
6
|
+
You may obtain a copy of the License at
|
|
7
|
+
|
|
8
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
9
|
+
|
|
10
|
+
Unless required by applicable law or agreed to in writing, software
|
|
11
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
12
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
13
|
+
See the License for the specific language governing permissions and
|
|
14
|
+
limitations under the License.
|
|
15
|
+
|
|
16
|
+
Project: yimo
|
|
17
|
+
Author: 溢墨修心(Yimo)
|
|
18
|
+
"""
|
|
19
|
+
|
|
20
|
+
from __future__ import annotations
|
|
21
|
+
|
|
22
|
+
# date: 2026-08-22
|
|
23
|
+
"""MySQL 数据库工具类
|
|
24
|
+
|
|
25
|
+
基于 yimo.kit.db 统一数据库层封装,提供开箱即用的服务方法。
|
|
26
|
+
业务代码无需管理 session/transaction,直接调用即可。
|
|
27
|
+
|
|
28
|
+
本类继承 BaseDbKit,复用全部共享实现(连接管理 / ORM / 原生 SQL / 原生表操作 /
|
|
29
|
+
事务 / 表操作),并覆写 MySQL 专属的 get_table_info,另提供基于 MySQL 9.x 原生
|
|
30
|
+
`VECTOR` 类型的向量方法(签名与 SQLiteKit / PgKit 完全一致,能力按发行版差异收敛)。
|
|
31
|
+
|
|
32
|
+
使用方式::
|
|
33
|
+
|
|
34
|
+
# 单条操作(自动管理事务)
|
|
35
|
+
user = MySqlKit.create(UserModel, {"name": "张三", "email": "zs@example.com"})
|
|
36
|
+
users = MySqlKit.list(UserModel, skip=0, limit=10)
|
|
37
|
+
MySqlKit.update(UserModel, user.id, {"name": "李四"})
|
|
38
|
+
|
|
39
|
+
# 原生 SQL 操作
|
|
40
|
+
rows = MySqlKit.query("SELECT * FROM users WHERE id = :id", {"id": 1})
|
|
41
|
+
|
|
42
|
+
# 多操作事务
|
|
43
|
+
with MySqlKit.transaction() as session:
|
|
44
|
+
crud = CRUDBase(UserModel)
|
|
45
|
+
crud.create(session, {"name": "test"})
|
|
46
|
+
# 退出 with 时统一提交
|
|
47
|
+
|
|
48
|
+
# 向量存储(需 MySQL 9.x)
|
|
49
|
+
MySqlKit.create_vector_table("images", 384)
|
|
50
|
+
MySqlKit.insert_vectors("images", [[0.1, 0.2, ...], ...])
|
|
51
|
+
|
|
52
|
+
向量能力要点(实测 MySQL 9.7.2 Community):
|
|
53
|
+
|
|
54
|
+
- ``store=True``:``create_vector_table`` / ``insert_vectors`` 用原生 ``VECTOR(N)`` +
|
|
55
|
+
``STRING_TO_VECTOR()`` 实现(均无发行版限制)。
|
|
56
|
+
- ``search=False``:``DISTANCE()`` / ``VECTOR_DISTANCE()`` 仅 HeatWave on OCI 与 MySQL AI
|
|
57
|
+
可用(Community 实测 1305 函数不存在),且 ``VECTOR`` 列无法建立索引 →
|
|
58
|
+
``search_vectors()`` **恒定抛 ``VectorNotSupportedError``**(保留同签名以便跨库代码统一)。
|
|
59
|
+
- ``VECTOR_CAPABILITIES`` 已声明上述能力,调用方可 feature-detect 而无需 try/except。
|
|
60
|
+
"""
|
|
61
|
+
|
|
62
|
+
import re
|
|
63
|
+
|
|
64
|
+
from sqlalchemy import text
|
|
65
|
+
|
|
66
|
+
from yimo.kit.config.log_config import get_default_logger
|
|
67
|
+
from yimo.kit.db.base_db_kit import (
|
|
68
|
+
DEFAULT_DISTANCE_TYPE,
|
|
69
|
+
BaseDbKit,
|
|
70
|
+
normalize_extra_cols,
|
|
71
|
+
)
|
|
72
|
+
from yimo.kit.db.engine import MYSQL
|
|
73
|
+
from yimo.kit.db.exceptions import DBError, VectorNotSupportedError
|
|
74
|
+
|
|
75
|
+
logger = get_default_logger(__name__)
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
class MySqlKit(BaseDbKit):
|
|
79
|
+
"""MySQL 数据库工具类
|
|
80
|
+
|
|
81
|
+
基于 yimo.kit.db 统一数据库层,封装为业务可直调的服务方法。
|
|
82
|
+
所有 ORM 方法内部使用 session_scope 管理事务(自动提交/回滚),
|
|
83
|
+
业务代码无需手动管理 session。
|
|
84
|
+
|
|
85
|
+
对于多操作事务场景,请使用 transaction() 上下文管理器。
|
|
86
|
+
"""
|
|
87
|
+
|
|
88
|
+
DB_TYPE = MYSQL
|
|
89
|
+
|
|
90
|
+
# 向量列占位符:本后端 VECTOR 列需经 STRING_TO_VECTOR 转换(覆写基类的 ":vec")
|
|
91
|
+
VECTOR_PLACEHOLDER = "STRING_TO_VECTOR(:vec)"
|
|
92
|
+
|
|
93
|
+
# 向量能力声明(供调用方 feature-detect,详见 docs/agents/modules/kit-db.md)
|
|
94
|
+
VECTOR_CAPABILITIES: dict[str, object] = {
|
|
95
|
+
"store": True, # 可建表 / 可写入
|
|
96
|
+
"search": False, # search_vectors 不可用
|
|
97
|
+
"exact": False,
|
|
98
|
+
"distances": (),
|
|
99
|
+
"distance_kind": None,
|
|
100
|
+
"fast_distance_kind": None,
|
|
101
|
+
"dimension_kind": "max", # VECTOR(N) 的 N 是「最大维度上限」,非必须相等
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
@classmethod
|
|
105
|
+
def get_table_info(cls, table_name: str) -> list[dict[str, object]]:
|
|
106
|
+
"""获取表的列信息
|
|
107
|
+
|
|
108
|
+
Args:
|
|
109
|
+
table_name: 表名
|
|
110
|
+
|
|
111
|
+
Returns:
|
|
112
|
+
列信息字典列表(column_name, data_type, is_nullable 等)
|
|
113
|
+
"""
|
|
114
|
+
sql = """
|
|
115
|
+
SELECT
|
|
116
|
+
COLUMN_NAME as column_name,
|
|
117
|
+
DATA_TYPE as data_type,
|
|
118
|
+
IS_NULLABLE as is_nullable,
|
|
119
|
+
COLUMN_DEFAULT as column_default,
|
|
120
|
+
COLUMN_COMMENT as column_comment
|
|
121
|
+
FROM INFORMATION_SCHEMA.COLUMNS
|
|
122
|
+
WHERE TABLE_NAME = :table_name
|
|
123
|
+
AND TABLE_SCHEMA = DATABASE()
|
|
124
|
+
ORDER BY ORDINAL_POSITION
|
|
125
|
+
"""
|
|
126
|
+
return cls.query(sql, {"table_name": table_name})
|
|
127
|
+
|
|
128
|
+
# ==================== 向量操作(MySQL 9.x 原生 VECTOR 类型) ====================
|
|
129
|
+
|
|
130
|
+
@classmethod
|
|
131
|
+
def vector_column_dimension(
|
|
132
|
+
cls, table_name: str, column: str = "embedding"
|
|
133
|
+
) -> int | None:
|
|
134
|
+
"""查询向量列的**声明维度上限**(MySQL 9.x 原生 ``VECTOR``)
|
|
135
|
+
|
|
136
|
+
Args:
|
|
137
|
+
table_name: 表名(当前连接的库内,即 ``DATABASE()``)
|
|
138
|
+
column: 向量列名(默认 ``embedding``)
|
|
139
|
+
|
|
140
|
+
Returns:
|
|
141
|
+
列声明的维度上限;列不存在或不是 ``VECTOR`` 类型时返回 ``None``
|
|
142
|
+
|
|
143
|
+
Note:
|
|
144
|
+
- MySQL 的 ``VECTOR(N)`` 是**上限语义**:写入维度 ≤ N 即可(实测 9.7.2:
|
|
145
|
+
``VECTOR(1024)`` 写入 1024 维成功,写入 1025 维报 ``1406 Data too long``)。
|
|
146
|
+
故 ``VECTOR_CAPABILITIES["dimension_kind"] == "max"``,
|
|
147
|
+
**不能**用「配置维度 != 列值」判定不一致。
|
|
148
|
+
- 建表时未指定维度的 ``VECTOR`` 由服务端落为 ``vector(2048)``(实测 9.7.2),
|
|
149
|
+
因此本后端不存在「无维度」列,``None`` 只表示「列不是向量列」。
|
|
150
|
+
- 维度元数据只在 ``information_schema.COLUMNS.COLUMN_TYPE`` 里(形如
|
|
151
|
+
``vector(1024)``),需按文本解析。
|
|
152
|
+
"""
|
|
153
|
+
rows = cls.query(
|
|
154
|
+
"SELECT COLUMN_TYPE AS column_type "
|
|
155
|
+
"FROM information_schema.COLUMNS "
|
|
156
|
+
"WHERE TABLE_SCHEMA = DATABASE() "
|
|
157
|
+
"AND TABLE_NAME = :table_name "
|
|
158
|
+
"AND COLUMN_NAME = :column",
|
|
159
|
+
{"table_name": table_name, "column": column},
|
|
160
|
+
)
|
|
161
|
+
if not rows:
|
|
162
|
+
return None
|
|
163
|
+
value = rows[0]["column_type"]
|
|
164
|
+
if not isinstance(value, str):
|
|
165
|
+
return None
|
|
166
|
+
matched = re.fullmatch(r"vector\((\d+)\)", value.strip(), re.IGNORECASE)
|
|
167
|
+
return int(matched.group(1)) if matched else None
|
|
168
|
+
|
|
169
|
+
@classmethod
|
|
170
|
+
def _ensure_vector_supported(cls) -> None:
|
|
171
|
+
"""确保服务端支持 VECTOR 类型(需 MySQL 9.x)
|
|
172
|
+
|
|
173
|
+
Raises:
|
|
174
|
+
DBError: 无法获取服务端版本(如服务不可达),或主版本号 < 9
|
|
175
|
+
"""
|
|
176
|
+
version = cls.vector_version()
|
|
177
|
+
if version == "unavailable":
|
|
178
|
+
raise DBError(
|
|
179
|
+
"无法获取 MySQL 版本,不能确认服务端是否支持 VECTOR 类型"
|
|
180
|
+
"(请检查服务连通性后重试)。"
|
|
181
|
+
)
|
|
182
|
+
|
|
183
|
+
major = version.split(".")[0]
|
|
184
|
+
if not major.isdigit() or int(major) < 9:
|
|
185
|
+
raise DBError(
|
|
186
|
+
f"当前 MySQL 版本 {version} 不支持 VECTOR 类型,"
|
|
187
|
+
"向量表需 MySQL 9.x 及以上(Community 即可存储;"
|
|
188
|
+
"距离检索另需 HeatWave on OCI / MySQL AI)。"
|
|
189
|
+
)
|
|
190
|
+
|
|
191
|
+
@classmethod
|
|
192
|
+
def create_vector_table(
|
|
193
|
+
cls,
|
|
194
|
+
table_name: str,
|
|
195
|
+
dims: int,
|
|
196
|
+
id_col: str = "id",
|
|
197
|
+
column: str = "embedding",
|
|
198
|
+
extra_cols: dict[str, str] | list[dict[str, str]] | None = None,
|
|
199
|
+
) -> None:
|
|
200
|
+
"""创建包含向量列的表(MySQL 9.x 原生 VECTOR 类型)
|
|
201
|
+
|
|
202
|
+
Args:
|
|
203
|
+
table_name: 表名
|
|
204
|
+
dims: 向量**最大条目数**(**必填**;写入维度不得超过该值,服务端上限 16383)
|
|
205
|
+
id_col: 主键列名(``BIGINT PRIMARY KEY``,**不自增**,id 由调用方提供
|
|
206
|
+
或由 `insert_vectors` 兜底生成雪花 ID)
|
|
207
|
+
column: 向量列名(默认 ``embedding``)
|
|
208
|
+
extra_cols: 额外列定义,**两种形态**(产出 DDL 逐字一致):
|
|
209
|
+
``{列名: 方言类型串}``(**推荐**,与 `create_raw_table` 同形,键序即列序)
|
|
210
|
+
或既有 ``[{"name": str, "type": str}]``;
|
|
211
|
+
type 按 MySQL 方言书写,如 ``{"label": "VARCHAR(32)"}``
|
|
212
|
+
|
|
213
|
+
表结构示例::
|
|
214
|
+
|
|
215
|
+
CREATE TABLE images (
|
|
216
|
+
id BIGINT PRIMARY KEY, -- 雪花 ID(18~19 位,int64)
|
|
217
|
+
embedding VECTOR(384),
|
|
218
|
+
label VARCHAR(32)
|
|
219
|
+
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
|
|
220
|
+
|
|
221
|
+
Raises:
|
|
222
|
+
ValueError: dims < 1
|
|
223
|
+
DBError: 服务端版本低于 9.x(无 VECTOR 类型),或无法获取版本信息
|
|
224
|
+
|
|
225
|
+
Note:
|
|
226
|
+
- MySQL 的 ``VECTOR(N)`` 是**上限**语义(非精确维度约束),由服务端逐行校验,
|
|
227
|
+
故本方法不做"已存在表维度比对"(与 PgKit 的硬约束不同,属后端真实差异)。
|
|
228
|
+
- ``VECTOR`` 列不能作为键(主键 / 外键 / 唯一键 / 分区键),也无法建立索引。
|
|
229
|
+
- 主键为纯 ``BIGINT``(非 ``AUTO_INCREMENT``):三库统一由应用侧生成 id。
|
|
230
|
+
"""
|
|
231
|
+
if dims < 1:
|
|
232
|
+
raise ValueError(f"dims 必须为正整数,当前为 {dims}")
|
|
233
|
+
|
|
234
|
+
cls._ensure_vector_supported()
|
|
235
|
+
|
|
236
|
+
extra_defs = "".join(
|
|
237
|
+
f", {name} {col_type}"
|
|
238
|
+
for name, col_type in normalize_extra_cols(extra_cols)
|
|
239
|
+
)
|
|
240
|
+
|
|
241
|
+
sql = (
|
|
242
|
+
f"CREATE TABLE IF NOT EXISTS {table_name} ("
|
|
243
|
+
f"{id_col} BIGINT PRIMARY KEY, "
|
|
244
|
+
f"{column} VECTOR({int(dims)}){extra_defs}"
|
|
245
|
+
f") ENGINE=InnoDB DEFAULT CHARSET=utf8mb4"
|
|
246
|
+
)
|
|
247
|
+
cls.execute(sql)
|
|
248
|
+
logger.info(f"✅ 创建向量表 {table_name}(维度上限={dims})")
|
|
249
|
+
|
|
250
|
+
@classmethod
|
|
251
|
+
def insert_vectors(
|
|
252
|
+
cls,
|
|
253
|
+
table_name: str,
|
|
254
|
+
vectors: list[list[float]],
|
|
255
|
+
ids: list[int] | None = None,
|
|
256
|
+
extra_data: list[dict[str, object]] | None = None,
|
|
257
|
+
id_col: str = "id",
|
|
258
|
+
column: str = "embedding",
|
|
259
|
+
) -> int:
|
|
260
|
+
"""批量插入向量数据(经 STRING_TO_VECTOR 转换)
|
|
261
|
+
|
|
262
|
+
Args:
|
|
263
|
+
table_name: 表名
|
|
264
|
+
vectors: 向量列表,每个向量为 float 列表(维度不得超过列的 VECTOR(N))
|
|
265
|
+
ids: 可选的 ID 列表(长度需与 vectors 一致);None 时由 Kit 生成雪花 ID
|
|
266
|
+
(应用侧生成,**非数据库自增**)
|
|
267
|
+
extra_data: 额外列数据列表(长度需与 vectors 一致)
|
|
268
|
+
id_col: 主键列名(默认 ``id``,供自建 DDL 的表使用)
|
|
269
|
+
column: 向量列名(默认 ``embedding``,供自建 DDL 的表使用)
|
|
270
|
+
|
|
271
|
+
Returns:
|
|
272
|
+
插入的行数
|
|
273
|
+
|
|
274
|
+
Raises:
|
|
275
|
+
ValueError: 入参自洽性校验失败——ids / extra_data 长度与 vectors 不一致、
|
|
276
|
+
批内向量长度不一致、``extra_data`` 键为保留绑定名(``id`` / ``vec``)、
|
|
277
|
+
键与 ``id_col`` / ``column`` 重复、键不是合法标识符、``id_col == column``
|
|
278
|
+
|
|
279
|
+
Note:
|
|
280
|
+
单次事务内批量写入(``cls.transaction()``,与 SQLiteKit / PgKit 同语义:整体提交);
|
|
281
|
+
语句由 `build_insert_vectors` 构造(**单一事实源**,本后端经 ``VECTOR_PLACEHOLDER``
|
|
282
|
+
输出 ``STRING_TO_VECTOR(:vec)``)。需要把向量行写入**调用方自己的事务**时,
|
|
283
|
+
请改用 `build_insert_vectors` + `transaction()`。
|
|
284
|
+
"""
|
|
285
|
+
with cls.transaction() as session:
|
|
286
|
+
for sql, params in cls.build_insert_vectors(
|
|
287
|
+
table_name,
|
|
288
|
+
vectors,
|
|
289
|
+
ids=ids,
|
|
290
|
+
extra_data=extra_data,
|
|
291
|
+
id_col=id_col,
|
|
292
|
+
column=column,
|
|
293
|
+
):
|
|
294
|
+
session.execute(text(sql), params)
|
|
295
|
+
logger.info(f"✅ 插入 {len(vectors)} 条向量到 {table_name}")
|
|
296
|
+
return len(vectors)
|
|
297
|
+
|
|
298
|
+
@classmethod
|
|
299
|
+
def search_vectors(
|
|
300
|
+
cls,
|
|
301
|
+
table_name: str,
|
|
302
|
+
query_vector: list[float],
|
|
303
|
+
top_k: int = 10,
|
|
304
|
+
distance_type: str = DEFAULT_DISTANCE_TYPE,
|
|
305
|
+
filter_sql: str | None = None,
|
|
306
|
+
exact: bool = True,
|
|
307
|
+
id_col: str = "id",
|
|
308
|
+
column: str = "embedding",
|
|
309
|
+
) -> list[dict[str, object]]:
|
|
310
|
+
"""搜索最近邻向量——**MySQL 侧不支持**
|
|
311
|
+
|
|
312
|
+
Args:
|
|
313
|
+
table_name: 表名
|
|
314
|
+
query_vector: 查询向量(float 列表)
|
|
315
|
+
top_k: 返回结果数上限
|
|
316
|
+
distance_type: 距离类型(本后端无可用取值)
|
|
317
|
+
filter_sql: 可选的过滤条件 WHERE 子句
|
|
318
|
+
exact: 是否禁止近似加速(本后端无可用路径,形参仅为保持签名一致)
|
|
319
|
+
id_col: 主键列名(同上)
|
|
320
|
+
column: 向量列名(同上)
|
|
321
|
+
|
|
322
|
+
Raises:
|
|
323
|
+
VectorNotSupportedError: 恒定抛出。MySQL Community / Commercial 未提供向量
|
|
324
|
+
距离函数(`DISTANCE()` 仅 HeatWave on OCI 与 MySQL AI 可用),
|
|
325
|
+
且 `VECTOR` 列无法建立索引,故无原生距离检索路径。
|
|
326
|
+
"""
|
|
327
|
+
raise VectorNotSupportedError(
|
|
328
|
+
"MySqlKit.search_vectors 不可用:当前 MySQL 发行版未提供向量距离函数"
|
|
329
|
+
"(DISTANCE() 仅 HeatWave on OCI 与 MySQL AI 可用),且 VECTOR 列无法建索引。"
|
|
330
|
+
"替代方案:改用 PgKit.search_vectors(pgvector);"
|
|
331
|
+
"本后端仅支持向量的存储与读取(VECTOR_CAPABILITIES['store']=True)。"
|
|
332
|
+
)
|
|
333
|
+
|
|
334
|
+
@classmethod
|
|
335
|
+
def vector_version(cls) -> str:
|
|
336
|
+
"""获取服务端版本号(MySQL 的向量能力内建,非可插拔扩展)
|
|
337
|
+
|
|
338
|
+
Returns:
|
|
339
|
+
版本号字符串(如 "9.7.2");查询失败时返回 "unavailable"
|
|
340
|
+
"""
|
|
341
|
+
try:
|
|
342
|
+
rows = cls.query("SELECT VERSION() AS vector_version")
|
|
343
|
+
if rows:
|
|
344
|
+
return str(rows[0]["vector_version"])
|
|
345
|
+
return "unavailable"
|
|
346
|
+
except Exception as e:
|
|
347
|
+
logger.warning(f"⚠️ 获取 MySQL 版本失败: {e}")
|
|
348
|
+
return "unavailable"
|