PostgreSQL 的内部统计数据从来不缺——pg_stat_bgwriter、pg_stat_checkpoint、pg_stat_activity，随便一个 DBA 都能列出一串视图。缺的是把时间序列上的变化串起来看，然后告诉你"这个 WAL 峰值和那批长事务是同一件事"。pg_statviz 一直在做前半段：轻量采集、出图、零侵入。1.0 版补上了后半段——用视觉大模型读图、读数据、读配置，给出 [HEALTHY] / [WARNING] / [CRITICAL] 判定和具体修复建议，同时用一套硬规则兜底，防止模型把真问题粉饰太平。
采集和可视化：不动数据库，不装 Agent
pg_statviz 的哲学很明确：一切轻量、最小化。扩展部分是纯 SQL 和 PL/pgSQL，不需要加载额外模块，也不往数据库里装任何外部连接。可视化工具是独立的 Python 程序，从任意机器运行即可。数据留在你的数据库里，导出自由。
这意味着你不需要像商业监控平台那样开一个持续连接的 Agent，也不需要把统计数据持续推到某个 SaaS 后端。pg_statviz 只读 PostgreSQL 内部统计和元数据，不碰应用数据。
AI 分析的架构：规则先跑，模型后看
1.0 的核心新增是 --ai 标志。但整个设计不是"把数据丢给 LLM 等它说话"这么简单，而是三层叠加：
第一层：确定性规则引擎。 在调用 LLM 之前，pg_statviz 先对原始数值跑一套硬规则检查。规则发现的问题会作为额外上下文注入 prompt，并且设定一个严重度下限（severity floor）——最终判定不能低于最严重的规则发现。换句话说，如果规则引擎已经标记了 [CRITICAL]，LLM 再乐观也降不回 [WARNING] 或 [HEALTHY]。这是对"模型爱说没事"的有效约束。
第二层：配置感知的 prompt。 每个模块的 prompt 不是泛泛地问"帮我看看这张图"，而是把该模块相关的 pg_settings 拉进来。比如 buffers 模块会带上 shared_buffers 和 bgwriter_* 系列；checkpoints 模块带上 checkpoint_* 和 max_wal_size；connections 模块带上 max_connections。模型的建议因此锚定在你实际的服务器配置上，而不是复读"shared_buffers 设 25% 内存"这种民间偏方。
第三层：校准块（calibration block）。 系统 prompt 里专门辟了一段 debunk 常见 PostgreSQL 谜语——25% RAM 给 shared_buffers 的经验值、默认 random_page_cost=4 的历史遗留、work_mem × max_connections 的简单乘法陷阱。先把这些偏见堵住，模型就不容易给出"看似专业实则误导"的建议。
三种 AI 后端，一个标志切换
# Anthropic Claude（默认）
pg_statviz analyze -d mydb --ai claude
# Google AI Studio Gemini 2.5 Flash（免费额度）
pg_statviz analyze -d mydb --ai gemini
# 本地 Ollama，推荐 gemma4:e4b
pg_statviz analyze -d mydb --ai local
不传 --ai，pg_statviz 行为和之前完全一样，零额外依赖、零外部调用。AI 功能完全 opt-in。
安装时也一样区分：
# 只装核心，不带 AI 依赖
pip install pg_statviz
# 装 AI 相关依赖（按你选的 provider 拉取）
pip install pg_statviz[ai]
扩展侧从 PostgreSQL 官方仓库或 PGXN 安装，和之前没区别。
报告产出：从单图诊断到全局摘要
每个模块生成一个 HTML 报告页，内嵌对应图表 PNG，渲染 LLM 的 markdown 分析——状态徽章（[HEALTHY] / [WARNING] / [CRITICAL]）和格式化段落。
更关键的是顶层 index.html：它聚合所有模块的判定，然后让模型做一次跨图表综合分析。比如 WAL 写入峰值和长运行会话出现在同一时段，模型会被要求识别这种关联模式，并给出"最该先做的一件事"。这比逐图看结论再自己拼拼图要省力得多。
Prompt 注入防护
所有来自用户的字段——配置值、角色名、复制槽名、查询文本——都被 <user_data>...</user_data> 标签包裹。系统 prompt 明确指示模型不要把这些内容当作指令执行。这在实际场景中不是杞人忧天：角色名或查询文本里混入指令式字符串的情况并不罕见，尤其多租户环境下。
隐私边界：第三方 API vs 本地模型
原文直说了：如果你用 Claude 或 Gemini，你就是在把 PostgreSQL 统计数据上传到别人的服务器。对方的隐私条款大概率允许用你的输入做进一步训练。如果这不可接受，--ai local 是唯一合规路径。
这不是小事——统计数据本身不含应用业务数据，但 pg_stat_activity 里的查询文本、角色名、连接来源 IP 这些信息对很多组织来说仍然敏感。选哪个后端，取决于你对这些数据外流的容忍度。
实操示例：从安装到出报告
下面是一个完整的本地运行流程，用 Ollama 做后端，数据不出本机：
# 1. 安装 Ollama 并拉取推荐模型
ollama pull gemma4:e4b
# 2. 安装 pg_statviz 扩展（在 PostgreSQL 里执行）
# 从 PGXN 或手动安装，然后在目标数据库启用
psql -d mydb -c "CREATE EXTENSION pg_statviz;"
# 3. 安装 Python 工具（含 AI 依赖）
pip install pg_statviz[ai]
# 4. 采集快照（可以 cron 定时跑）
pg_statviz snapshot -d mydb
# 5. 多次采集后，生成图表 + AI 分析报告
pg_statviz analyze -d mydb --ai local
# 6. 查看报告
# 输出目录下打开 index.html，浏览器即可浏览
# 每个模块有独立 HTML，顶层 index.html 是综合摘要
如果你想快速验证而不等长时间序列，可以手动跑几次快照：
# 连续采集 5 个快照，间隔 30 秒
for i in $(seq 1 5); do
pg_statviz snapshot -d mydb
sleep 30
done
# 然后分析
pg_statviz analyze -d mydb --ai local
1.0 的其他改进
- 分析编排器现在对单个模块缺数据的情况优雅降级——继续跑其余模块，而不是整个中断。这在刚部署、某些统计视图还没积累数据的阶段很实用。
- I/O 速率计算的测试修复，AI 功能的新增测试覆盖。
- 仓库新增
run-ci-local.sh本地 CI 脚本，提交前可以自检。
什么时候值得用，什么时候不必
值得启用 --ai 的场景：
- 你已经有 pg_statviz 的定期采集，但没时间逐图解读，需要快速拿到优先行动项。
- 多模块指标出现异常，你怀疑有关联但不确定因果方向。
- 团队里有非 DBA 背景的人需要可读的判定和建议，而不是一堆折线图。
可以不启用的场景： - 数据隐私要求严格，且本地没有可用的视觉模型硬件。 - 你自己就是资深 DBA，看图比看模型文字更快。 - 采集量太小，时间序列还没形成有意义的趋势。
选后端的判断：
- 本地有 GPU 或足够内存跑 Ollama → --ai local，隐私最安全。
- 想零成本试一下 → --ai gemini，Google AI Studio 有免费额度，但数据外流。
- 需要最高分析质量且隐私可接受 → --ai claude，当前视觉理解能力最强，但成本和数据外流都在。
pg_statviz 1.0 的 AI 功能不是把监控交给模型，而是让模型在你已经拥有的数据上做一次结构化解读，同时用硬规则守住底线。用不用、用哪个后端，都是你自己的选择——这比"必须连我们的云才能用"的商业产品，更符合 PostgreSQL 生态的作风。