本地部署 AI 数据问答平台：3 条命令从克隆到提问，附报错速查

【免费下载链接】auto-ontology Auto Ontology is a Python framework for building semantic, graph-based reasoning layers over data. It enables deterministic query generation, better context retrieval, and more explainable AI for LLM and agent workflows. 项目地址: https://gitcode.com/GitHub_Trending/au/auto-ontology

想直接拿自然语言问数据库「上周发出了多少订单」并拿到数字和 SQL？Auto Ontology 从元数据自动构建语义本体，把自然语言问题翻译成可执行的 Text-to-SQL。本文是它的 Docker Compose 本地部署全流程：配置环境变量、拉起整套服务、问出第一个问题。

项目速览：给数据库装一层语义本体

Auto Ontology 是一个开源 Python 框架，在数据上构建图结构的语义推理层：自动从源库元数据中抽取业务术语、表间关系与 SQL 属性，沉淀成本体（ontology），让大模型基于这层上下文把自然语言问题确定性地翻译成可校验的 SQL。

能力清单：

• 本体自动构建：术语（Terms）、SQL 属性（SQL attributes）、关系（Relationships）三类定义从元数据与查询历史中提取
• 自然语言问答：问题翻译为 SQL 并直接执行，答案附带 SQL 与推理步骤
• 认证与 RBAC：Better Auth、SSO、API tokens
• Web UI：聊天问答、数据目录、分析、设置
• 部署：本地 Docker Compose，生产 Helm Chart

组件	职责	默认端口
Frontend（Next.js 16 + Better Auth + Prisma）	Web UI、认证、API 网关	3000
Backend（FastAPI + LangChain）	聊天 / 自然语言转 SQL、目录与数据源 API	3001
Ingestion worker（FastAPI）	摄取元数据、语义编译、写入向量	3002
Postgres + pgvector	目录、本体、向量存储	5432
pgAdmin	数据库管理界面	5050

数据流向一句话概括：问题从前端（或 Agent）进入 Backend，由 NVIDIA NIM 完成推理与向量化，生成的 SQL 直接在源库执行；Ingestion Service 则持续从源库抽取元数据写入 PostgreSQL，形成不断更新的语义层。

部署前检查清单

启动前确认以下四项，缺一项部署都会在对应环节卡住：

检查项	具体要求	如何确认已就绪
Docker（含 Compose v2）	Docker Desktop 或 Linux 上的 Docker Engine	docker compose version 输出 v2.x
NVIDIA API Key	nvapi- 开头，供 NIM 的 LLM、向量化、重排序推理使用	已从 NVIDIA API catalog 取得并可填入 .env
可连接的数据源	你要问答的数据库，且从部署机可达	连接串就绪，形如 postgresql://user:pass@host:5432/dbname
宿主端口占用	5432、3000、3001、3002、5050 未被占用	查看监听端口，或启动后看是否有 bind 报错

开始部署

克隆仓库并进入目录

git clone https://gitcode.com/GitHub_Trending/au/auto-ontology auto_ontology
cd auto_ontology

仓库自带 docker-compose.yml 编排与前后端 Dockerfile，无需额外构建脚本。

✅ 成功信号：目录内能看到 docker-compose.yml、.env.example 与 frontend/。

复制模板并配置环境变量

cp .env.example .env

用编辑器打开 .env 填写必填项。模板为每个模型角色都预填了 nvapi-your-api-key-here 占位，留空的字段会回落到 DEFAULT_MODELS_*，所以通常只需把 DEFAULT_MODELS_API_KEY 填成你的 Key，其余占位行删掉即可。

变量	用途	填写建议
AUTH_SECRET	Better Auth 签名密钥	⚠️ 必填，缺了每个页面都会报错；用 openssl rand -base64 32 生成长随机串
APP_URL	前端访问源	⚠️ 必填，本地保持 http://localhost:3000
POSTGRES_PASSWORD / PGADMIN_PASSWORD	Postgres 与 pgAdmin 密码	⚠️ 至少 8 位
DEFAULT_MODELS_API_KEY	NVIDIA NIM 的 API Key	nvapi- 开头
CONNECTION_STRINGS	数据源连接串	如 postgresql://user:pass@host:5432/dbname；DuckDB、SQLite 仅支持连接串方式接入
AUTO_ONTOLOGY_ADMIN_EMAIL / AUTO_ONTOLOGY_ADMIN_PASSWORD	初始管理员账号	首次登录用

⚠️ 两点直说：未配置 HashiCorp Vault 时，连接凭证明文存放在 Postgres 的目录行中，别拿生产库试水；POSTGRES_PORT 只改宿主机映射，容器内部固定走 5432。

✅ 成功信号：grep -c nvapi-your-api-key-here .env 输出 0，即占位 Key 已全部替换或删除。

构建并启动全部服务

docker compose up -d --build

首次构建需要几分钟。Compose 会先起 Postgres 与 pgAdmin，再跑两个一次性迁移任务：auto-ontology-migrate（Alembic 迁移 public schema）与 frontend-migrate（Prisma 同步 frontend schema），两者成功后才拉起 backend、ingestion-service 与 frontend——这层编排就是为了让 backend 不在迁移完成前抢跑导致 500。

✅ 成功信号：docker compose ps 中两个一次性任务显示 exited (0)，其余服务为 running；日志可跟 docker compose logs -f auto-ontology。

启动后验证：登录并问出第一个问题

地址	用途	说明
http://localhost:3000	Web UI：登录、问答、管理数据源	用 .env 里的管理员邮箱和密码登录
http://localhost:5050	pgAdmin 数据库管理界面	用 PGADMIN_EMAIL / PGADMIN_PASSWORD 登录
http://localhost:3001	Backend API	⚠️ 仅限内部网络，它信任 x-auto-ontology-user-id 请求头中的身份，勿暴露公网

登录后先到 Settings → Semantic Compilation 打开语义编译：ingestion 在服务启动时自动执行一次，编译完成后页面提示 "Semantic compilation is ready"。然后到 Chat 直接提问，例如「How many orders shipped last week?」——agent 会把问题中的实体解析成本体中的术语、检索候选表、生成并执行 SQL，答案附带 SQL 与执行步骤；数据答不上来时它会明确说明，而不是编一个数。

报错速查

现象	原因	处理
每个页面报 Better Auth "default secret" 错误	AUTH_SECRET 或 APP_URL 未配置	在 .env 补全后 docker compose up -d 重启
启动时出现端口 bind 报错	5432 等端口被其他服务占用	.env 中改 POSTGRES_PORT（如 15432），只影响宿主机映射
重启后 UI 缺少左侧导航栏	浏览器残留了旧的 session cookie（AUTH_SECRET 变更或数据库重置后出现）	清除 localhost:3000 站点数据，或删除 better-auth.session_token cookie 后重新登录

更多场景参考仓库内的排障文档：troubleshooting.md。

后续可做的事

• 接入更多数据源、连接的作用域与 Vault 存储：docs/connections.md
• 把 Cursor、Claude Desktop 等 MCP 客户端接进来查数：docs/mcp.md
• 创建 API token 做程序化问答：docs/conversation-api.md
• 生产环境 Kubernetes 部署：见仓库根目录的 DEPLOYMENT.md（Helm Chart 流程）

到这里本地问答链路已经跑通，换上自己的数据源就可以开始问了。

【免费下载链接】auto-ontology Auto Ontology is a Python framework for building semantic, graph-based reasoning layers over data. It enables deterministic query generation, better context retrieval, and more explainable AI for LLM and agent workflows. 项目地址: https://gitcode.com/GitHub_Trending/au/auto-ontology