Skip to content

README.md

Latest commit

 

History

History
144 lines (109 loc) · 10.8 KB

README.md

File metadata and controls

144 lines (109 loc) · 10.8 KB
Raw

部署与环境搭建（学科知识中心）

状态：定义已就绪、按需构建——所有编排与初始化定义已入库并可执行，实际起栈由 落地方案 §4.5 的阶段时点触发（见下文「构建时点」）。本栈与 RADAI 运行时零共享： 独立容器、独立卷、独立端口域；只共用物理机与外部模型服务。

1. 自建 vs 外部复用（硬边界）

类别 组件 方式
自建（Docker） MySQL 8.4 LTS / OpenSearch 3.8.0 / NebulaGraph v3.8.0 / Redis 8.8 / MinIO docker-compose.infra.yml 一键起
外部复用（不自建） Embedding、LLM（抽取·裁决·摘要·裁判）、MinerU 解析 沿用现有模型服务，经 .env.services 注入端点；本地栈不复制模型权重、不起新模型进程

外部模型端点属于 RADAI 侧既有服务资产；换端点/换模型只改环境变量（模型重选须过 Phase 0 基准门禁，落地方案 §2.2-⑥）。

2. 版本矩阵（2026-09 核定的最新稳定版基线）

组件 版本 / 镜像 说明
MySQL mysql:8.4 8.4 是当前成熟 LTS（8.0 已 EOL）；9.7 LTS 为备选，切换只改 MYSQL_IMAGE，新库无历史包袱时可直接上
OpenSearch opensearchproject/opensearch:3.8.0 3.x 线最新稳定（2026-08-04 发布），kNN efficient filtering 是 Phase 0 压测对象；2.19.x 为维护线备选
NebulaGraph v3.6.0 官方原生安装（tarball，oss-cdn ubuntu2004 构建） Docker 镜像在本机不可用：镜像自带 CentOS7 glibc 2.17，内核 6.8 上启动即 GPF 段错误（dmesg 实证，v3.6.0/v3.8.0 均然；对照机 为 CentOS7 内核 3.10 同镜像正常）。官方生产推荐即原生 deb/tar 安装——二进制用宿主 glibc 2.35 运行验证通过。安装于 ~/myenv/runtime/knc-nebula/nebula，启停用 deploy/nebula/native/{start,stop}.sh（须以安装目录为 cwd，share/resources 相对路径依赖）；端口 metad 19559 / storaged 19779 / graphd 19669（ws 21/22/23xxx）。infra compose 中 nebula 服务已移入 legacy-docker profile 仅作兼容机参考
Redis redis:8.8 8.x 线最新稳定（三许可含 AGPL，内部使用无碍）；角色=队列/协调/缓存，非持久权威
MinIO minio/minio:RELEASE.2025-04-22T22-12-26Z 社区完整版最后一个全功能 tag（其后社区版 UI 精简；S3 API 不受影响，SDK 用法无差）；升级前查 release notes
应用运行时 python:3.12-slim + FastAPI 0.135 + Uvicorn 0.44 与 RADAI 基线一致（requirements-radai-baseline.txt 已知组合）

升级纪律：版本只经本表变更（改 .env.infra.example 同步改此处）；大版本升级须先过数据兼容评估（MySQL 跨 LTS、OpenSearch 索引兼容、Nebula 空间升级路径）。

3. 端口规划（127.0.0.1 + 1 前缀偏移，与宿主机既有生产端口零冲突）

服务 宿主机端口 容器端口 备注
MySQL 127.0.0.1:13306 3306 宿主 3306 被 RADAI 生产 MySQL 占用
OpenSearch 127.0.0.1:19200 / 19600 9200 / 9600 HTTPS+内置安全（初始管理员密码）
NebulaGraph graphd 127.0.0.1:19669 9669 metad/storaged 不对外发布
Redis 127.0.0.1:16379 6379 宿主 6379 被生产 Redis 占用
MinIO 127.0.0.1:19000 / 19001 9000 / 9001 API / 控制台
admin-api 127.0.0.1:18100 8080
ingest-worker 127.0.0.1:18110 8080
retrieval-api 127.0.0.1:18120 8080
observer-api 127.0.0.1:18130 8080

全部绑定 127.0.0.1：本栈目前无对外暴露需求；将来经 nginx 边缘层按站开放（沿用 RADAI 边缘规范）。

4. 首启步骤（到需要时执行）

命令形态：开发机安装的是独立 docker-compose v2（无 docker compose 插件形态），二者命令等价，下文按插件形态书写。

# 0) 宿主机前置（OpenSearch 必需；重启失效需写入 /etc/sysctl.conf）
sudo sysctl -w vm.max_map_count=262144

# 1) 基础设施栈（MySQL 首启自动执行 deploy/sql/001_init.sql；
#    nebula-init / minio-init 一次性建空间与桶，幂等可重跑）
cd deploy
cp .env.infra.example .env        # 修改所有 CHANGEME
docker compose -f docker-compose.infra.yml up -d
docker compose -f docker-compose.infra.yml ps   # 全部 healthy 即就绪

# 2) OpenSearch 索引（模板 + 首代索引 + alias）
OS_PWD='<OPENSEARCH_ADMIN_PASSWORD>' ./opensearch/bootstrap.sh

# 3) 应用服务（四骨架；先补 .env.services 的外部模型端点）
cp .env.services.example .env.services   # 填 EMBEDDING/LLM/MINERU 端点
docker compose --env-file .env --env-file .env.services \
  -f docker-compose.services.yml up -d --build

# 4) 验证
curl -s 127.0.0.1:18100/healthz         # {"status":"ok","service":"admin-api"}
curl -s 127.0.0.1:18100/readyz          # ready=true（外部模型+基础设施环境齐备）
curl -s 127.0.0.1:18100/api/config-summary  # 主机/模型名联调核对（无密钥）

卷与数据：全部落 named volumes（knc-mysql-data 等）；备份基线见技术方案 §9.5（MySQL 快照+PITR、OpenSearch snapshot、MinIO 版本化）。

5. 初始化资产清单（已随 compose/脚本自动落地）

资产 定义文件 内容
MySQL 首批 Schema（17 表） sql/001_init.sql 代际三件套（asset_generation_manifest / document_active_generation 落列 / partition_active_asset_generation）+ K0 文档块 + 题录 + K1/K2/K3 + citation_registry + 能力位 + graph_mutation_log + merge_log
OpenSearch 索引 opensearch/*.json + bootstrap.sh knc-chunk-v1（R0 词法+R1 向量+serving，ACL 字段先过滤后召回）、knc-doc-v1（L-doc 题录+题名/摘要向量）、knc-query-v1（R3 合成查询）；均经 alias 暴露，代际切换=alias 原子切
Nebula 图空间 nebula/schema.nebula 空间 knc_graph（vid FIXED_STRING(64)）：entity/chunk_vertex/doc_vertex 点 + entity_link/relation/cites 边（最小路由属性 + graph_generation）
备份基线 backup/backup.sh + backup/README.md MySQL 快照（docker exec mysqldump）+ MinIO knc-raw 对象全量，保留 3 份轮转；OS/Nebula 为可重建投影不备份；恢复演练口径见 README

向量维度默认 768、analyzer 默认 standard——都是占位：Phase 0 的 S2（分词三选一）与 S3（Qwen3-Embedding vs BGE-M3 基准）出结论后回填模板并升 v2 代际。

6. 构建时点（何时真正起栈）

时点 动作 依赖
Phase 0 - S1（最先） 只起 OpenSearch 单节点 无（压测 100 万/500 万 chunk × 过滤选择性矩阵；不过线则启用 Vespa 对照分支——libs/engine 是该回退点）
Phase 0 - S4 只起 MySQL Splink 归并原型落表实测
Phase 1 全套基础设施 + 四服务骨架镜像 外部模型端点接入（.env.services）；之后实装 admin-api 建库 → ingest 基础线 → retrieval 混合检索
Phase 2 无新增组件（富化线用既有栈）
Phase 3 NebulaGraph 进入真实写入（graph_mutation_log 状态机）
Phase 5 OpenSearch 扩节点/调参（capacity_profile 实测标定后） 单节点→多副本与分片横扩

骨架服务的业务实装按 services/*/app/main.py 内的阶段注释推进；外部模型三类端点缺失时 /readyz 恒为 not-ready（fail-fast，防止静默接错通道）。

7. 解析路由：外部 MinerU（2026-09-11 实测接入）

MinerU 解析服务（外部复用、不自建）现运行于 <internal-host>:8000——mineru.cli.fast_api， VLM 后端（2 卡 TP，显存占用 0.68），/health、/docs 已验证可达；由该机 start.sh 启动 （环境变量驱动，含 .env），同机还运行 Milvus 套件等既有服务，本栈对其零改动、零重启。

路由与产物纪律（为向更大平台迁移做好准备）：

  • MINERU_API_BASE 指向该端点（真实值在 deploy/.env.services，不入库）；接口契约以 其 OpenAPI（/docs）为准，ingest-worker 走异步提交 + 轮询取结果。
  • 解析产物必须回写本栈 MinIO：远端 output/<task-uuid>/ 视为临时暂存（当前已积 3.5G，不清理、不依赖）；实现落位 libs/pipeline/knc_pipeline/parse/mineru_client.py （MineruParseClient.parse_to_raw：提交 → 轮询 → 跟随结果 URL 拉包——对远端落点 不敏感，URL 指向远端 MinIO(9010) 或远端 output/ 均可 → sha256 内容寻址写入 knc-raw 桶）。远端目录不作为任何持久事实来源。
  • 对远端存放只读是硬约束：MinerU 与其 MinIO 同时服务其他系统——本栈对远端仅 GET 下载结果包，绝不写入/重定向/删除远端对象；其他消费方的取数路径与桶内容 完全不变。变更只发生在本栈侧（多存一份到 knc-raw）。
  • 未采用「改 MinerU 的 S3 环境变量直传本栈」方案：需重启 MinerU、改变其现有消费方 取数路径、且要对外暴露本栈 MinIO——三者都违反「不影响现有服务」约束，明确否决。
  • 迁移语义：知识库整体迁往更大平台 = 迁 MinIO 桶 + MySQL 导出 + OpenSearch 快照重放， 解析算力可随时换端点（改一个环境变量），存量数据不绑定 MinerU 服务器。

7.1 媒体产物收割（M1，2026-09-12）

MinerU 把解析产物（md + 图片）上传其自有 MinIO（实测为 RADAI 同机 9004，桶 mineru-parse-latest），键 tasks/{task_id}/{stem}/hybrid_auto/images/{sha}.jpg （stem = results 键 = 文件名去扩展）；任务保留 86400s——图片收割必须发生在解析 窗口内，存量文档走 figure-backfill 重解析。环境变量（deploy/.env.services）：

  • MINERU_S3_ENDPOINT / MINERU_S3_ACCESS_KEY / MINERU_S3_SECRET_KEY / MINERU_S3_BUCKET ——产物桶只读 GET（硬约束同上），收割入本栈 knc-raw 桶 media/{sha256}/ 内容寻址。

7.2 VL 嵌入端点（M1 媒体向量）

VL_EMBED_BASE_URL / VL_EMBED_MODEL / VL_EMBED_API_KEY——Qwen3-VL-Embedding （vLLM 0.16 pooling runner）。接口契约：纯文本走 input；图文融合走 chat 形态 messages:[{content:[image_url, text]}]（该版 /v1/embeddings 不收 content 数组）。 媒体向量与 dense 的文本嵌入端点分立（向量空间不得混用）。

8. 与 RADAI 的边界（重申）

  • 运行时零共享：独立容器/卷/端口域/网络（knc-infra）；不读写 RADAI 任何业务库与命名空间。
  • RADAI 侧若后续接入，走 retrieval-api 的 API 工具封装，不动其内核（落地方案 §4.6）。
  • 禁止把本栈端口绑定 0.0.0.0 或并入生产 nginx vhost，除非另行评审。