opengauss-rag-ollama

体检与搭建 openGauss 7.0 向量数据库 + Ollama embedding 的 RAG 技术栈。

何时使用

• 用户要求"检查/体检本机 openGauss 7.0 与对应向量工具完整性"、排查 RAG 链路缺口
• 搭建 openGauss(>=7.0) 向量检索/RAG：部署服务端、选型 embedding、写库
• 从 sentence-transformers 迁移到 Ollama embedding，或向量写入报维度不匹配

分层架构（先记住边界，避免方向性错误）

uv(.venv) 只管轻量 Python 依赖          openGauss 7.0 服务端是数据库服务，不是 Python 包
├─ langchain-opengauss（向量存储集成）   → 部署形态：Docker 容器 / 系统包 / uv 项目内极简包(opengauss-uv)，监听 5432
├─ langchain-community（含 OllamaEmbeddings）   embedding 与对话模型统一由 Ollama(11434) 托管
└─ psycopg2-binary（连接驱动）           → 通过 psycopg2 与 Python 层连接

• 不要因为存在 rag 项目目录或装了 Python 包，就臆断 openGauss 服务端已安装；逐层用证据核对。
• 不要在 Ollama 托管 embedding 时仍装 sentence-transformers + torch（torch 2GB+，是重型可选路径）。
• 不要把 openGauss 的「uv 虚拟环境方案」当成系统级安装：极简包落在项目内（默认 .opengauss/）以普通用户进程运行，不建系统用户、不写 /opt、不装 systemd 服务——因此不会影响主机上的其他软件。
• 版本对应关系：langchain-opengauss 0.1.5 明确要求 openGauss >= 7.0.0；openGauss 7.x 内置向量引擎（vector 类型、HNSW/IVFFLAT 索引），无需数据库侧额外插件，但必须先有可连接实例。

工作流 A：完整性体检（逐层核对，只报告证据支持的结论）

1. 服务端定位：which gsql；标准目录 /opt/opengauss、/usr/local/opengauss、/home/omm、/var/lib/opengauss；全盘 find 二进制 gsql/gaussdb/gs_ctl/gs_initdb/gs_guc（排除 .venv/.git）；ps aux | grep -iE "gauss|opengauss|postgres"；环境变量 GAUSSHOME。
2. 包管理器记录：dpkg -l / rpm -qa / apt list --installed 中 grep gauss|postgres（注意：libpq5 只是 PostgreSQL 客户端库，不等于 openGauss 已装）。
3. 容器形态：docker ps -a 与 docker images | grep -iE "gauss|opengauss"；记录容器与端口映射。
4. 端口与连接：ss -tlnp/netstat -tlnp 查 5432/5433/15432；只有能实际连接（gsql/psycopg2）才可确认服务端版本为 7.0。
5. 向量集成包版本：在项目 .venv 核对 langchain_opengauss（.dist-info/METADATA 或 pip show），确认是否满足 >= 7.0.0 的官方版本前提。
6. Python 依赖逐个导入：在 uv .venv 用 importlib 逐一 import psycopg2 / langchain / langchain_core / langchain_community / langchain_opengauss 并打印版本，FAIL 项即缺口；若项目走 sentence-transformers 路径需单独确认。
7. Embedding 提供方（Ollama）：curl http://127.0.0.1:11434/api/version（服务存活）、curl http://127.0.0.1:11434/api/tags（models 为空=服务正常但无模型）、which ollama && ollama --version（CLI）。
8. 汇总报告：逐组件给 [存在/缺失/未运行/无模型]，每项缺口配修复动作（安装/启动服务端、docker pull、ollama pull、uv add）。
9. 有缺口 → 转工作流 C：存在任何缺失/未运行/无模型项时，报告后立即进入「工作流 C：缺口确认安装」，把缺失项整理成安装确认表单交给人类勾选；未经人类确认不得执行任何安装。

可直接运行 scripts/health_check.sh 一次性采集第 1/2/3/4/7 步证据； 缺失部件的安装动作统一由 scripts/install_missing.sh 承载（先 plan 出清单，人类确认后 apply 指定部件）。

工作流 B：搭建 / 接入（Ollama 托管 embedding）

1. 就绪校验：先确认 Ollama 服务可访问（/api/version）且目标 embedding 模型已 pull（/api/tags 非空）。若 Ollama 服务或模型缺失/未运行，不直接拉取——转「工作流 C」把 ollama / ollama-model 作为待安装项交给人类确认。中文场景建议 bge-m3 或 qwen3-embedding；轻量可选 nomic-embed-text。
2. uv 依赖最小集（pyproject.toml）：langchain-opengauss、langchain-community、psycopg2-binary；移除 sentence-transformers/torch（Ollama 托管时不需要）。
3. 接入代码骨架：

from langchain_community.embeddings import OllamaEmbeddings
from langchain_opengauss import OpenGauss, OpenGaussSettings

embeddings = OllamaEmbeddings(model="bge-m3", base_url="http://127.0.0.1:11434")

config = OpenGaussSettings(
    host="localhost", port=5432,
    user="gaussdb", password="...", database="postgres",
    table_name="langchain_docs",
    embedding_dimension=1024,   # 必须与所选模型实际维度一致（见故障排查）
)
vector_store = OpenGauss(embedding=embeddings, config=config)

工作流 C：缺口确认安装（人类在环）

定位：工作流 A 检出缺失后，绝不静默安装任何东西；把缺失项变成「确认表单」交给人类逐项勾选，确认后才执行安装（含 Ollama 本体）。这是技能的安全边界：体检是只读的，安装必须有人类确认。

1. 生成缺失清单：运行 bash scripts/install_missing.sh plan，得到主机配置摘要、各部件 [已具备/缺失] 结果与 openGauss 推荐方案；把缺失部件整理成安装表单。
2. 呈现表单给人类确认：
   • Web/A2UI 环境：输出多选清单（MultipleChoice/CheckBox），每个缺失部件一项，附用途与建议动作说明，让用户勾选要安装的项（含 ollama 本体、ollama-model、docker、opengauss 方案、uv-deps）。
   • 非 A2UI 环境：用 ask_user 结构化多选，逐项列出「部件 id / 缺失原因 / 将执行的安装动作」，请用户逐项回复装或不装。
   • 每项必须写明将执行的命令与影响（例如：ollama → 官方安装脚本需 root；uv-deps → 在 PROJECT_DIR 执行 uv add）。
   • openGauss 服务端必须同时给出两种方案供人类选择（见下方选型规则），并附 plan 输出的推荐：
     • opengauss-docker：docker 拉镜像 + 起容器映射 OG_PORT:5432（默认镜像 enmotech/opengauss:latest，需按 >=7.0 核对 tag）；
     • opengauss-uv（uv 虚拟环境方案）：极简包解压到项目内默认 $PROJECT_DIR/.opengauss（可用 OG_INSTALL_DIR 覆盖），以普通用户进程运行 gs_initdb/gs_ctl；不建系统用户、不写 /opt、不装系统服务，因此不影响主机其他软件。需先提供 OG_TARBALL 极简包路径。
   • 人类可全选、部分选或全不选；默认绝不替人类全选。
3. 按确认结果执行：bash scripts/install_missing.sh apply <部件id...>，只装人类勾选的部件（脚本幂等：已具备自动跳过；需 root 且免密 sudo 不可用时会打印待手动执行的命令并停下，不静默降级）。逐个部件安装并在完成后回执状态。
4. 安装后复检：重跑 scripts/health_check.sh，把结果与新缺口再报给人类（回到本工作流或工作流 B 继续搭建）。
5. 约束：
   • Ollama 缺失时必须先经人类确认才运行 scripts/install_missing.sh apply ollama；不确认不装。
   • 模型缺失而 ollama 在：拉取模型（apply ollama-model）前同样给人类确认模型名与体积（默认 bge-m3）。
   • openGauss 双方案由人类选其一（可都不装）；给出推荐但尊重人类最终选择。
   • uv-deps 需 PROJECT_DIR 指向项目目录；执行 uv add 前展示将新增的依赖。

openGauss 服务端安装方案选型规则

plan 会打印主机配置摘要（内存/磁盘/发行版/架构/Docker 是否已装）并给出推荐，供人类决策；Agent 依据以下规则向人类解释推荐理由（最终由人类选择）：

• 推荐 opengauss-docker（容器方案）：主机已装 Docker 且内存 >= 4GB——零额外基础设施、易隔离、易清理，也便于统一管理多个 openGauss 实例。
• 推荐 opengauss-uv（uv 虚拟环境方案）：未装 Docker、或内存/磁盘紧张、或使用者希望环境自包含、不影响系统其他软件（uv 方案把极简包放项目内，普通用户进程运行，不向系统目录写入、不污染主机环境）。这也是本技能作者本机采用的方式。
• 展示给人类时两个方案都要列出，用 "推荐 ✓" 标注建议项，但勾选权完全交给人类；若人类两者都未勾选，则 openGauss 不安装，如实记入复检缺口。

故障排查：embedding 维度对齐门禁

• 现象：OpenGauss 向量列在创建时即固定维度，写库报维度冲突/不匹配；或迁移 embedding 模型后旧表与新维度不符。
• 规则：OpenGaussSettings.embedding_dimension 必须等于所选 embedding 模型的实际输出维度；openGauss vector 类型维度上限 2000。不同模型维度不同（bge-m3=1024、nomic-embed-text=768、qwen3-embedding 随规格而定），不要假定与旧模型相同。
• 步骤：
  1. 实测真实维度：ollama show <model>，或对短文本调用 embed API 取 len(embedding)。
  2. 将 embedding_dimension 设为实际维度后再建表/入库。
  3. 更换 embedding 模型后维度变化：必须重建向量列/表并重新向量化入库，不能复用旧维度表。
  4. 体检"向量栈完整性"时把"向量列维度 vs embedding 模型维度"列为必查项。

报告格式

结论先行的清单式报告：总体结论（完整/不完整）→ 逐组件表格（组件/状态/证据/修复动作）→ 可选下一步。每项状态必须是证据支持的 [存在/缺失/未运行/无模型]，禁止无证据推断。

存在缺口时的收尾：表格之后附「安装确认表单」——列出每个缺失部件的部件 id、用途、将执行的安装命令，交人类逐项勾选（A2UI 多选或 ask_user），确认后再由 scripts/install_missing.sh apply <id> 执行；见工作流 C。