IvorySQL Agent 探索与实践
本文基于 HOW 2026 Oreo Yang 的演讲内容整理。 视频回放：https://www.bilibili.com/video/BV1CFLB6DEHV/
一、项目背景
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 完成缓存命中
关键设计决策：关键词互斥防止跨域冲突、中英双语正则、渐进降级（关键词 → LLM → general 三层兜底）、模式感知根据 compat_mode 动态裁剪工具表、LLM 容错（指数退避重试 ×2，超时降级 general）、域隔离防污染。
3.2 本地向量检索（零外部依赖）
采用 BAAI/bge-small-zh-v1.5 嵌入模型，512 维，完全离线运行。pgvector 扩展 + IVFFlat 索引加速。知识库来源包括 IvorySQL 官方文档、PostgreSQL 官方文档和历史分析结果。RAG 检索采用"加权向量搜索 + BM25 重排 + MMR 多样化"组合方案。切片管理按文档章节划分，包含版本和模式标记防止跨版本知识污染。
3.3 上下文管理与智能压缩
- Schema 缓存：1 小时 TTL，DDL 后自动失效
- 包定义缓存：IvorySQL Oracle 模式包信息
- 实时指标：动态加载当前会话、锁、慢查询
- 历史异常：RAG 检索相关案例，top-K=5
智能压缩机制应对 15+ 轮长对话：DDL 判断 → 选择性保留（DDL + 最近 6 轮）→ Token 检查 → LLM 摘要生成 → 注入优化上下文。
3.4 工具系统与安全控制
21 个内置工具，分领域管理。SQL 验证四层防护：Prompt 预过滤（拦截 80% 无效 SQL）→ 语法缓存校验 → 预确认验证 → 错误反馈重试（最多 3 次）。安全认证采用 API Token + SHA256 + 配置热重载。审计系统记录操作日志与错误追踪。IvorySQL Oracle/PG 模式工具差异化。
3.5 Chat 流程：规划 · 生成 · 验证 · 流式输出
Plan 规划由 LLM 生成 JSON 格式步骤计划。SSE 流式输出实时推送 token、tool_start、tool_end 事件。状态往返保证多步计划跨轮次连贯性，无需重建上下文。
3.6 部署架构
Docker 容器化设计：服务拆分（存储 PostgreSQL + Agent 服务 + Grafana 可视化 + knowledge 批量导入）、settings.json 运行时配置热更新、多目标支持监控多个实例、环境隔离 、docker-compose 一键启动。
四、技术特色
- 纯离线本地运行，无需外部 API
- 多 RAG 领域扩展（当前 7 个 Agent，可继续扩展）
- 智能上下文缓存与压缩机制
- 多层次安全校验与审计日志
- 模块化可扩展设计，支持自定义工具与知识库
五、应用场景
| 场景 | 用户问题 | 处理 Agent |
|---|---|---|
| 连接数异常诊断 | "为什么连接数这么高？" | Ops Agent 分析活跃会话、长事务 |
| 慢查询优化 | "帮我找出最慢的查询" | NL2SQL Agent 检索慢查询日志 |
| 备份配置查询 | "备份配置正常吗？" | Backup Agent 检查 WAL 归档 |
| 知识库问答 | "如何使用 %rowtype？" | Knowledge Agent 检索 RAG 知识库 |
六、未来规划
6.1 短期规划
- 完善智能 Agent 框架，支持多 Model 后端与流式输出
- 实现 IvorySQL 与 PostgreSQL 双模式兼容
- 多模态输入支持：文件分析、截图识别、语音输入
- 知识库管理：在线新增、编辑、删除知识条目与切片
6.2 长期规划
功能扩展：多模式多版本支持、自动化修复、多实例管理、安全与访问控制、告警通知集成、自学习能力、更多领域 Agent。
愿景：原生集成 pgvector 成为 Agent 首选向量存储、多语言 SDK 开箱即用、Agent 开发套件、一键 Docker Compose 部署完整环境。核心能力：3 行代码实现 RAG 应用，无需配置外部向量服务。
七、总结
IvorySQL Agent 是 IvorySQL 社区在 AI 赋能数据库管理领域的一次系统性探索。项目基于 ReAct 框架与 LangGraph 工作流编排，构建了覆盖路由、检索、上下文管理、工具调用和安全审计的完整技术体系，实现了从自然语言到数据库运维动作的端到端自动化。未来，项目将持续向多模态交互、自动化修复、SDK 生态等方向演进，降低数据库的使用门槛，提升运维效率，让 IvorySQL 不仅是优秀的数据库，更成为智能数据管理的基础设施。