小节五:怎么给未来 MySQL / PostgreSQL 留接口——不要让 SQLite 变成业务代码的一部分

这一节的最后一个重点,是为未来迁移做准备。

很多项目第一版:

SQLite

后面业务增长:

PostgreSQL

真正痛苦的不是迁移数据。

而是代码里到处都是:

sqlite3.connect(...)

所以我们提前设计一个抽象接口。

定义 Protocol

Python 可以用:

typing.Protocol

定义 Store 行为。

from __future__ import annotations
from typing import (
    Any,
    Optional,
    Protocol,
)


class AgentStore(
    Protocol
):

    def create_session(
        self,
        session_id: str,
        status: str = "active",
    ) -> None:
        ...

    def append_message(
        self,
        session_id: str,
        role: str,
        content: str,
    ) -> None:
        ...

    def create_run(
        self,
        run_id: str,
        session_id: str,
        status: str = "ready",
    ) -> None:
        ...

    def update_run(
        self,
        run_id: str,
        *,
        status: str,
        start_time: Optional[str] = None,
        end_time: Optional[str] = None,
        answer: Optional[str] = None,
        error: Optional[dict[str, Any]] = None,
    ) -> None:
        ...

    def append_step(
        self,
        run_id: str,
        step_no: int,
        kind: str,
        detail: str,
    ) -> None:
        ...

    def get_run(
        self,
        run_id: str,
    ) -> Optional[dict[str, Any]]:
        ...

然后:

SQLiteStore

实现这套方法。

未来:

PostgresStore
MySQLStore

也实现同样方法。

AgentService 不需要改变

原来:

store = SQLiteStore(...)

未来:

store = PostgresStore(...)

然后:

run_manager = RunManager(
    store
)

核心业务仍然一样。

未来真正需要改的通常是什么?

数据库差异主要在:

Connection
SQL Placeholder
Auto Increment
JSON Type
Transaction
Connection Pool
DDL

但如果这些都封装在 Store 内,AgentEngine 不受影响。

为什么 PostgreSQL 后面可能更适合?

Agent 系统未来可能有:

大量 Run
复杂 Trace
JSON 数据
多实例服务
并发写入
统计查询

PostgreSQL 对这类场景很强。

尤其:

JSONB
索引
事务
并发

都很适合。

但这不是现在必须解决的问题。

现在先把:

Store Interface

留好。

重启实验会告诉我们,哪些状态还没有落盘

我们先保存一次 Run,再结束进程、重新创建 Store 并查询。能查到结果,只证明历史记录持久化。接下来让任务停在中间再重启,检查是否还能找到消息、待执行动作和工作区版本。这一步才开始验证执行恢复,不能与普通查询混为一谈。

配套 SQLiteStore 已经包含 sessions、messages、runs、trace_steps、tool_calls 和 run_events。当前 Web Run 主链路会实际写入 Run、Trace、Tool Call 与 Event;Session 和 Message API 已经具备,但还要等会话入口传入 session_id 后才会进入这条主链路。我们把“表已经存在”和“产品流程已经使用”分开描述,避免看到 Schema 就误以为所有数据都自动落盘。

配套实现还把 Run 状态变化与对应事件放在同一事务提交,Trace Step 与其 Tool Call 记录也作为一个工作单元写入。这样状态、事件和执行证据不容易在进程崩溃时只落下一半。

动手验证:用第二个 Store 读回来

写入 Run 与事件后关闭连接,使用相同路径创建新 Store 并读取。再准备旧版本数据库运行升级。参考验收是历史数据保留、升级可重复执行、状态和事件一致。进程崩溃后的动作恢复需要独立测试,不能被这项持久化测试代替。

持久化以后,还要考虑保留期、敏感数据与大结果

“写进数据库”不是终点。Agent 数据常常包含 Prompt、用户输入、Tool 参数、SQL、路径和错误信息,其中可能夹带密钥或个人信息。落盘之前要做字段分级与脱敏,数据库文件也要设置合适的文件权限;生产环境还要结合磁盘加密、访问审计和备份策略。不要因为 SQLite 是本地文件,就默认它天然安全。

数据也不能无限增长。我们可以按类型制定不同保留期:

Run 摘要       保留较久
Trace / Event  按排障窗口保留
Token 增量     短期或不逐条保存
Artifact       按归属、大小和合规策略清理

删除历史行以后,SQLite 文件通常不会立刻缩小;需要在合适的维护窗口评估 VACUUM,不能在请求高峰随手执行。大段 Tool 输出也不适合无限塞进 JSON/TEXT:更稳妥的做法是保存有大小上限的摘要,把完整内容放进 Artifact Store,数据库记录 artifact_id、哈希、大小与归属。

JSON 字段同样要有合同。写入时使用统一序列化策略,读取时处理旧版本字段;无法序列化的对象要么转换为明确结构,要么拒绝写入,不能在不同 Store 方法里各自 default=str 后就当作语义完全可靠。课程项目用 default=str 保证 Trace 教学流程不中断,生产系统还应对关键字段做更严格的 Schema 校验。

© 版权声明
THE END
喜欢就支持一下吧
点赞9 分享
评论 抢沙发
头像-大赛人网
欢迎您留下宝贵的见解!
提交
头像-大赛人网

昵称

取消
昵称

    请登录后查看评论内容