用途:该技能用于启动当前版本的 Auto Ontology 实现、排查运行问题,或将智能体连接到已运行的 Auto Ontology 实例。官方安装方式为仓库根目录 DEPLOYMENT.md 中的 Helm chart;Docker Compose 可在单机上运行相同技术栈;dev_tools/setup_env.sh 是开发者工具而非安装器。
主要能力与安装方式:
- Helm(官方推荐):从 NGC 公共 nvidia 组织获取 chart,需先由用户自行在编辑器中创建 values 文件(含 defaultModelsApiKey、postgresPassword、adminEmail、adminPassword,可选 connectionStrings),再执行 helm fetch 与 helm install,并通过端口转发访问前端。appUrl 必须与用户实际浏览的源一致;authSecret 首次安装生成并在升级时保留。chart 拉取返回 404 时应询问用户,不得回退到内部 staging 仓库。
- Docker Compose:复制 .env.example 为 .env,填写 AUTH_SECRET、APP_URL、AUTO_ONTOLOGY_ADMIN_EMAIL、AUTO_ONTOLOGY_ADMIN_PASSWORD 等必填项后执行 docker compose up -d --build。该命令会构建后端与前端镜像、启动 Postgres、pgAdmin、摄入服务,运行两个一次性迁移任务,再启动应用。缺少 AUTH_SECRET 与 APP_URL 会导致所有页面报 Better Auth 默认密钥错误。
- 开发者工作流(--dev、--ds):仅用于修改 Auto Ontology 本身。--dev 只以 Docker 运行基础设施,前端与 FastAPI 在本地运行;--ds 在 Docker 中运行前端,FastAPI 运行在宿主机。需注意前端镜像固定使用 host.docker.internal:3001,FastAPI 端口 3001 应做好防火墙隔离。
MCP 连接:若 Auto Ontology 已运行,不应重装。将 AUTO_ONTOLOGY_API_URL 指向 Web 应用(Compose 下为 3000 端口而非 FastAPI 的 3001),用 uvx 从 GitHub 子目录启动 MCP 服务。在包发布到 PyPI 前,需要能读取 NVIDIA/auto-ontology 的 GitHub 凭据。客户端配置使用带 /mcp 后缀的 MCP 服务器 URL,用户通过 Auto Ontology 登录,不要在 MCP 服务器上放置令牌。需用 curl 检查 OAuth 授权服务器发现端点返回 200,否则应从前端 checkout 运行并调整地址。
数据源连接:UI 管理的连接与 .env 中的 CONNECTION_STRINGS 二选一,存在 UI 连接时忽略环境变量。可先调用 POST /api/connections/test 校验凭据并获取 schema 白名单,再调用 POST /api/connections 保存;201 仅表示保存成功,摄入为尽力触发。随后通过 GET /api/datasources/dbs、GET /api/semantic-compilation/status 和 MCP check_readiness 验证。连接可设置 schema 白名单及 table_allow_regex / table_deny_regex(deny 优先、区分大小写、未限定),但表级范围保证端到端仍不可强制,相关表不可编目、采样或嵌入的诉求目前无法完全保证。
验证与停止:UI 应能加载并显示左侧导航;语义编译状态返回 JSON,calculated 为 false 表示术语表为空,应先摄入/编译。helm uninstall 与 docker compose down -v 都会销毁数据,执行前需询问用户。故障排查参考 troubleshooting.md,分享输出前应脱敏。
限制:不覆盖 Astra GitOps,不修改语义定义,不将部分 Vault 配置视为密钥存储;不提供第二个安装器;破坏性删除卷前必须询问。