IvorySQL Agent 探索与实践
本文基于 HOW 2026 Oreo Yang 的演讲内容整理。
一、项目背景
1.1 什么是 IvorySQL
IvorySQL 是一个基于 PostgreSQL 并兼容 Oracle 的开源关系型数据库项目，致力于提供灵活、高性能的数据管理解决方案。其核心特性包括：
- Oracle 兼容：支持 Oracle 数据类型、PL/SQL 语法、内置函数及 Package 包，显著降低从 Oracle 迁移或混合部署的技术门槛与成本。
- 社区生态：拥有活跃的开源社区，通过社区协作持续推动产品迭代与技术创新。
- 部署灵活性：支持传统部署、容器化、云服务、在线体验、沙盒环境等多种部署方式。
1.2 项目背景与目标
数据库运维面临多重挑战：指标分散、诊断困难、人力成本高、文档查找繁琐。IvorySQL Agent 的核心理念是利用大模型技术实现智能对话与自动化分析，构建一站式监控、诊断、运维辅助平台。
项目要解决的六大核心问题包括：智能文档检索、数据库运维、性能调优、SQL 编写效率提升、企业知识管理，最终通过 AI 技术实现从“被动检索”到“主动服务”的转型。
1.3 什么是 Agent
Agent = 大模型 + 工具 + 推理。智能体将语言模型与工具能力结合，能够对任务进行推理、决定使用哪些工具，并通过迭代寻求解决方案。
IvorySQL Agent 的技术选型：
- 模型层：支持 OpenAI GPT 系列、Anthropic Claude 系列、智谱 AI 等多模型后端
- 工具层：21 个数据库工具，覆盖 7 大领域专家
- 框架层：基于 LangGraph 工作流编排，实现 ReAct 循环迭代
- 知识层：矩阵式知识库，覆盖多版本、多模式
二、系统架构
2.1 整体架构
系统采用四层架构设计：
| 层级 | 技术栈 | 职责 |
|---|---|---|
| Web 接入层 | FastAPI + 静态资源 + CORS | 用户界面交互 |
| 智能路由层 | LangGraph 工作流 + 状态管理 | 意图识别与请求分发 |
| 专家 Agent 层 | NL2SQL / Analysis / Ops / Backup / Install / Knowledge / General | 领域任务处理 |
| 工具与存储层 | 数据库工具集 + LLM 接口 + 向量存储 + 时序数据库 | 数据访问与工具执行 |
2.2 核心数据流
系统运行两条核心工作流：
监控采集流：通过 Collector 设计，覆盖 50+ 监控指标（连接、缓存、锁、事务、查询、表膨胀等）。针对 IvorySQL 的 Oracle 兼容模式，动态注册自定义类型编解码器。采集数据以 JSONB 格式存储于 PostgreSQL，后台采用 APScheduler 每 30 秒执行一次采集任务，并通过 Delta 增量计算减少开销。
智能对话流：用户输入经路由分发至对应 Agent，构建上下文后调用工具链执行推理，最终生成回答并返回用户。
2.3 异常检测：规则引擎 + LLM 协同
异常检测采用规则引擎与 LLM 协同工作的双轨机制：
- 规则引擎：预定义阈值规则，命中后自动触发 LLM 分析
- LLM 分析：支持 Claude/OpenAI/智谱 AI 等多模型，对异常进行智能解读
- 向量化存储：512 维本地向量（支持 256~2048 维自定义），配合 pgvector 索引加速检索
- 历史学习：通过相似案例检索复用诊断经验
三、关键技术实现
3.1 两阶段智能路由
路由系统采用渐进式匹配策略：
- Phase 1（确定性路由）：基于关键词与正则表达式匹配，响应时间约 0ms，覆盖约 70% 的场景
- Phase 2（LLM 分类）：规则匹配失败时调用大模型进行意图识别，响应时间约 300ms
- Post-Confirm：短路复用机制，0ms 完成缓存命中
7 个意图域的差异化配置：
| 域 | 触发方式 | 工具数 | RAG top_k | 上下文范围 |
|---|---|---|---|---|
| nl2sql | 关键词 + LLM | 5 | 4 | schema + packages |
| analysis | 关键词 + LLM | 5 | 5 | 全量 |
| ops | 关键词 + LLM | 8 | 3 | 会话指标子集 |
| backup | 关键词 + LLM | 5 | 3 | 知识库 |
| install | 关键词 + LLM | 4 | 5 | 知识库 |
| knowledge | 关键词 + LLM | 1 ★ | 10 ★ | 知识库（最高召回） |
| general | LLM only ★ | 21 ★ | 5 | 全量 |
关键设计决策：
- 关键词互斥：精心设计正则防止跨域冲突（如 analysis 的“索引建议”≠ ops 的“索引管理”）
- 中英双语：每域同时维护中英文关键词正则
- 渐进降级：关键词 → LLM 分类 → general 三层兜底
- 模式感知：根据 compat_mode 动态裁剪工具表（Oracle 模式含 getpackages，PG 模式自动排除）
- LLM 容错：指数退避重试 ×2，JSON 解析失败时提取首词，超时降级 general
- 域隔离防污染：knowledge 域仅配 1 个工具，SQL 约束按域过滤，防止误写入操作
3.2 本地向量检索（零外部依赖）
嵌入模型：采用 BAAI/bge-small-zh-v1.5，512 维，支持中英双语，完全离线运行。使用 fastembed 进行本地推理，无外部 API 调用。处理性能约为每千份文档 1~2 分钟。
向量存储：pgvector 扩展，IVFFlat 索引加速，余弦距离相似度搜索。
知识库来源：IvorySQL 官方文档 + PostgreSQL 官方文档 + 历史分析结果向量化。
RAG 检索策略：采用“加权向量搜索 + BM25 重排 + MMR 多样化”组合方案。文档 Title 与 Content 分别赋予 0.3 和 0.7 的权重；检索结果经 BM25 关键词重排后，通过 MMR（threshold=0.46）引入多样化内容，避免结果过度集中。
知识库切片管理：按文档章节划分，每个切片附带 YAML frontmatter 元数据，包含 title、category、tags、source、version、mode、content_hash 等字段。其中 version 和 mode 标记适用数据库版本与模式，防止跨版本知识污染；content_hash 防止重复导入。
3.3 上下文管理与智能压缩
缓存机制：
- Schema 缓存：1 小时 TTL，DDL 后自动失效
- 包定义缓存：IvorySQL Oracle 模式包信息
- 实时指标：动态加载当前会话、锁、慢查询
- 历史异常：RAG 检索相关案例，top-K=5
智能压缩机制（应对 15+ 轮长对话）：
- 智能分类（DDL vs 普通对话）
- 选择性保留（DDL + 最近 6 轮）
- Token 检查（必要时裁剪）
- LLM 摘要生成（压缩旧对话）
- 注入：[摘要] + 保留历史 → LLM 获得优化上下文
3.4 工具系统与安全控制
工具系统注册了 21 个内置工具，分领域管理：
- SQL 验证四层防护：① Prompt 预过滤（拦截 80% 无效 SQL 生成）→ ② 语法缓存校验 → ③ 预确认验证（捕获兼容性问题）→ ④ 错误反馈重试（最多 3 次自动修正）
- 安全认证：API Token + SHA256 + 配置热重载
- 审计系统：操作日志与错误追踪
- IvorySQL 适配：Oracle/PG 模式工具差异化
- Reflect 机制：类型安全转换 + JSON 友好输出 + 大模型审核
3.5 Chat 流程：规划 · 生成 · 验证 · 流式输出
Plan 规划：多步写任务由 LLM 生成 JSON 格式步骤计划，已执行步骤标记完成后注入进度到上下文，防止重复执行或乱序。
SSE 流式输出：token、tool_start、tool_end 实时推送，status、confirm、complete、error 节点事件。出错时前端保留已流内容，错误追加于下方。
状态往返：plan、plan_idx、domain 经 API 在确认轮次间往返，保证多步计划跨轮次连贯性，无需重建上下文。
3.6 部署架构
采用 Docker 容器化设计：
- 服务拆分：存储 PostgreSQL + Agent 服务 + Grafana 可视化 + knowledge 一次性导入
- 配置管理：settings.json 运行时配置，支持热更新
- 多目标支持：监控多个 IvorySQL 实例，支持活跃切换
- 环境隔离：虚拟环境 + 依赖版本锁定
- 一键启动：docker-compose 编排全部服务
四、技术特色
- 纯离线本地运行，无需外部 API
- 多 RAG 领域扩展（当前 7 个 Agent，可继续扩展）
- 智能上下文缓存与压缩机制
- 多层次安全校验与审计日志
- 模块化可扩展设计，支持自定义工具与知识库
五、应用场景
| 场景 | 用户问题 | 处理 Agent |
|---|---|---|
| 连接数异常诊断 | “为什么连接数这么高？” | Ops Agent 分析活跃会话、长事务，提供详情与终止建议 |
| 慢查询优化 | “帮我找出最慢的查询” | NL2SQL Agent 检索慢查询日志，展示 SQL 文本、执行次数、平均耗时 |
| 备份配置查询 | “备份配置正常吗？” | Backup Agent 检查 WAL 归档、最近备份时间、归档状态 |
| 知识库问答 | “如何使用 %rowtype？” | Knowledge Agent 检索 RAG 知识库，构建 LLM context，生成 SQL 用例 |
六、未来规划
6.1 短期规划
- 完善智能 Agent 框架，支持多 Model 后端与流式输出
- 实现 IvorySQL 与 PostgreSQL 双模式兼容，优化路由提示词与工具适配
- 多模态输入支持：文件分析、截图识别、语音输入
- 知识库管理：在线新增、编辑、删除知识条目与切片
6.2 长期规划
功能扩展：
- 多模式多版本支持：覆盖 Postgres 与 IvorySQL 的主流版本
- 自动化修复：对低风险操作（终止会话、创建索引）支持一键执行
- 多实例管理：统一管理多个 IvorySQL 实例，跨实例对比分析
- 安全与访问控制：多层级认证、细粒度权限、只读保护
- 告警通知：集成邮件、钉钉、Slack 等渠道
- 自学习能力：从历史操作中学习用户偏好和最佳实践
- 更多领域 Agent：安全加固、高可用架构、性能调优专家
愿景：IvorySQL 作为 AI 数据基础设施平台：
- 原生集成 pgvector，成为 Agent 首选向量存储
- 多语言 SDK：开箱即用，3 行代码实现 RAG 应用
- Agent 开发套件：内置 LangGraph/LlamaIndex 模板
- 一键部署：Docker Compose 启动完整 Agent 开发环境
IvorySQL Agent SDK 核心能力：
# 3 行代码实现 RAG 应用pip install ivorysql-vector-sdkfromivorysqlimportVectorDB db=VectorDB('postgresql://...')db.add_documents(docs)answer=db.query('用户问题')核心优势：无需配置外部向量服务，IvorySQL 开箱即用。
七、总结
IvorySQL Agent 是 IvorySQL 社区在 AI 赋能数据库管理领域的一次系统性探索。项目基于 ReAct 框架与 LangGraph 工作流编排，构建了覆盖路由、检索、上下文管理、工具调用和安全审计的完整技术体系，实现了从自然语言到数据库运维动作的端到端自动化。未来，项目将持续向多模态交互、自动化修复、SDK 生态等方向演进，降低数据库的使用门槛，提升运维效率，让 IvorySQL 不仅是优秀的数据库，更成为智能数据管理的基础设施。