# https://github.com/orneryd/NornicDB 项目说明书
生成时间：2026-06-22 16:52:02 UTC
## 目录
- [项目概览](#page-overview)
- [Models 模块](#page-pkg-graphql-models)
- [Models 模块](#page-models)
- [Utils 模块](#page-ui-src-utils)
## 项目概览
### 相关页面
相关主题：[Models 模块](#page-pkg-graphql-models)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/orneryd/NornicDB/blob/main/README.md)
- [apoc/README.md](https://github.com/orneryd/NornicDB/blob/main/apoc/README.md)
- [docker/README.md](https://github.com/orneryd/NornicDB/blob/main/docker/README.md)
- [macos/README.md](https://github.com/orneryd/NornicDB/blob/main/macos/README.md)
- [neural/README.md](https://github.com/orneryd/NornicDB/blob/main/neural/README.md)
- [pkg/linkpredict/README.md](https://github.com/orneryd/NornicDB/blob/main/pkg/linkpredict/README.md)
- [pkg/qdrantgrpc/README.md](https://github.com/orneryd/NornicDB/blob/main/pkg/qdrantgrpc/README.md)
- [pkg/security/README.md](https://github.com/orneryd/NornicDB/blob/main/pkg/security/README.md)
- [ui/README.md](https://github.com/orneryd/NornicDB/blob/main/ui/README.md)
- [ui/src/components/browser/README.md](https://github.com/orneryd/NornicDB/blob/main/ui/src/components/browser/README.md)
# 项目概览
NornicDB 是一个面向 AI 时代设计的图数据库系统，定位于"AI-native database"，将图结构、向量检索与全文搜索融合在单一引擎内，专门服务于 LLM 智能体记忆、知识图谱、RAG（检索增强生成）系统等场景。资料来源：[README.md:1-100]()
## 核心定位与设计目标
NornicDB 的核心思路是把"语义检索"和"图遍历"合并到同一个查询路径中，从而省去传统 RAG 栈中多个独立系统之间的数据搬运与同步成本。资料来源：[README.md:1-50]()
其主要设计目标包括：
- **融合检索引擎**：在同一引擎内同时支持向量 + BM25 + 图遍历的混合检索。
- **Neo4j 兼容性**：提供 Bolt 协议和 Cypher 查询语言支持，使官方 Neo4j 驱动几乎无需修改即可接入。
- **Qdrant 兼容**：保留 Qdrant 风格的 gRPC 工作流（`Points.Search`、`Points.Query`），同时叠加图原生能力。
- **时序真值建模**：支持版本化事实、时效窗口（temporal validity）、三时态事实（tritemporal）和"按时间点读取"（as-of reads），适用于审计与合规场景。
- **协议灵活性**：通过 REST、GraphQL、Bolt/Cypher、Qdrant gRPC 以及附加的 Nornic gRPC 在同一平台上同时对外提供服务。
资料来源：[README.md:50-120]()
## 主要子系统与能力
NornicDB 的能力由多个内置子系统协同提供，每个子系统对应一个独立的 Go 包或前端模块：
| 子系统 | 说明 | 来源文件 |
|--------|------|----------|
| APOC 函数库 | 950+ 内置函数，覆盖文本、数学、集合、机器学习、时空等 | [apoc/README.md:1-40]() |
| Heimdall AI Assistant | 内置 AI，可进行自然语言查询、插件执行、生命周期钩子 | [README.md:120-180]() |
| GPU 加速 | 支持 Metal（Apple Silicon）和 CUDA；HNSW 构建仍为 CPU 密集（见 [issue #32](https://github.com/orneryd/NornicDB/issues/32)） | [README.md:180-210]() |
| 链接预测（Link Prediction） | 拓扑 + 语义混合打分：Common Neighbors / Jaccard / Adamic-Adar 等 | [pkg/linkpredict/README.md:1-60]() |
| Qdrant gRPC 兼容 | 保留 Qdrant 客户端接入路径，集合映射到数据库命名空间 | [pkg/qdrantgrpc/README.md:1-40]() |
| 安全子系统 | 提供 CSRF / SSRF 等防护规范参考 | [pkg/security/README.md:1-20]() |
| 浏览器 UI | 组件化拆分的 Cypher 查询、语义搜索、节点详情面板 | [ui/src/components/browser/README.md:1-30]() |
| 神经网络训练 | 提供 Cypher 生成、TLP 分类等微调数据集生成脚本 | [neural/README.md:1-60]() |
| 桌面与 Docker 部署 | macOS LaunchAgent + 菜单栏应用；多架构 Docker 镜像 | [macos/README.md:1-60]()、[docker/README.md:1-80]() |
这些子系统共同构成了"数据库 + 检索 + AI 编排"的整体形态，使 NornicDB 不同于传统图数据库或纯向量数据库。
## 典型使用场景
项目 README 明确列出了一组面向生产的使用场景，可以作为选型参考：
- **AI 智能体记忆（AI Agent Memory）**：持久化、可查询的智能体长期记忆。
- **知识图谱与 RAG**：自组织的知识库，把图遍历与混合检索合并到同一管道。
- **会话上下文**：带衰减机制的对话历史。
- **金融与合规**：用于贷款/风险状态重构、KYC/AML 状态变更、政策版本化以及审计回执。
- **AI 治理与血缘追踪**：追踪模型断言、人工覆盖与事实来源随时间的演化。
资料来源：[README.md:80-130]()
## 社区关注与已知问题
从近期 issue 反馈来看，用户最关心的几类问题集中在以下几个方向，概览页面有必要预先提示：
- **Cypher 正确性回归**：v1.1.4 之后出现若干 `SET` / `MATCH+CREATE` 解析路径的回归（[issue #192](https://github.com/orneryd/NornicDB/issues/192)、[#213](https://github.com/orneryd/NornicDB/issues/213)）。
- **向量索引副作用**：`db.index.vector.queryRelationships` 在 v1.1.7 返回 0 行（[issue #219](https://github.com/orneryd/NornicDB/issues/219)）；在 `EMBEDDING_ENABLED=false` 外部向量路径下，运行时写入不会刷新搜索底座，需要重启（[issue #220](https://github.com/orneryd/NornicDB/issues/220)）。
- **批量写入压力**：`0593642` 版本在 Graphiti 批量抽取中触发 `BuildIndexes` / k-means 预热风暴，导致 CPU 挂起（[issue #222](https://github.com/orneryd/NornicDB/issues/222)）；社区已提出"批量导入 API + 延迟重建索引"的需求（[issue #171](https://github.com/orneryd/NornicDB/issues/171)）。
- **Neo4j 兼容性边界**：默认 `neo4j` 数据库名与 3 参数全文过程形式尚未完全对齐（[issue #214](https://github.com/orneryd/NornicDB/issues/214)）。
- **文档/配置不一致**：README 与 configuration.md 中展示的 `async_writes` YAML 与 `pkg/config/config.go` 不一致（仅支持环境变量）（[issue #215](https://github.com/orneryd/NornicDB/issues/215)）。
- **参数与类型处理**：嵌套在 `UNWIND $rows … row.created_at` 列表/映射中的 datetime 被存为 Go 格式字符串而非时态类型（[issue #221](https://github.com/orneryd/NornicDB/issues/221)）。
这些问题说明 NornicDB 正在快速演进，使用方在生产部署前应关注版本变更与回归测试。
## 文档与入口
项目以"文档中心 + 议题索引"双入口组织：
- 公共文档站：
- 文档中心：[docs/README.md](https://github.com/orneryd/NornicDB/blob/main/docs/README.md)
- 议题索引（症状优先）：[docs/issues-index.md](https://github.com/orneryd/NornicDB/blob/main/docs/issues-index.md)
资料来源：[README.md:200-260]()
## See Also
- [Heimdall AI Assistant 指南](README.md)
- [APOC Plugin 指南](apoc/README.md)
- [Link Prediction 子系统](pkg/linkpredict/README.md)
- [Qdrant gRPC 兼容性](pkg/qdrantgrpc/README.md)
- [Docker 部署](docker/README.md)
- [macOS 桌面集成](macos/README.md)
---
## Models 模块
### 相关页面
相关主题：[项目概览](#page-overview), [Models 模块](#page-models)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/orneryd/NornicDB/blob/main/README.md)
- [docker/README.md](https://github.com/orneryd/NornicDB/blob/main/docker/README.md)
- [neural/README.md](https://github.com/orneryd/NornicDB/blob/main/neural/README.md)
- [plugins/README.md](https://github.com/orneryd/NornicDB/blob/main/plugins/README.md)
- [ui/src/utils/api.ts](https://github.com/orneryd/NornicDB/blob/main/ui/src/utils/api.ts)
# Models 模块
## 概述与职责
Models 模块是 NornicDB 中负责管理、加载与调用机器学习模型的子层，覆盖 **嵌入模型（Embedding Model）**、**小型语言模型（SLM / Heimdall）**、**训练模型（Neural Trainer）** 以及 **插件模型** 四个方向。它既支撑向量索引的语义检索能力（通过 BGE 系列模型），又为 Heimdall AI 助手的自然语言理解提供本地推理后端；同时通过独立的训练管线允许用户微调并导出自定义 Cypher 生成器。
根据 [README.md](https://github.com/orneryd/NornicDB/blob/main/README.md) 的描述，NornicDB 将"Vector & full-text search"、"GPU acceleration (Metal, CUDA)"与"Heimdall AI Assistant"统一在同一发行版中对外提供，而 Models 模块正是这些能力共享的底层资源层。社区在 [Issue #220](https://github.com/orneryd/NornicDB/issues/220) 中提到的"外部向量 + EMBEDDING_ENABLED=false"场景，正是 Models 模块中嵌入管线被旁路时的典型分支。
## 模型类型与目录约定
Models 模块按用途划分多个目录：
| 模型类别 | 默认位置 / 文件 | 主要用途 | 来源 |
|----------|----------------|----------|------|
| 嵌入模型（BGE） | `models/bge-m3.gguf` | 向量检索嵌入 | [docker/README.md](https://github.com/orneryd/NornicDB/blob/main/docker/README.md) |
| SLM（Heimdall） | `models/qwen3-0.6b.gguf` 等 | AI 助手对话、动作选择 | [docker/README.md](https://github.com/orneryd/NornicDB/blob/main/docker/README.md) |
| 训练产物 | `models/cypher-expert/` | 微调后的 Cypher 生成模型 | [neural/README.md](https://github.com/orneryd/NornicDB/blob/main/neural/README.md) |
| 量化导出 | `*.q4_K_M.gguf` / `q5_K_M` / `q8_0` | 不同精度/体积的推理产物 | [neural/README.md](https://github.com/orneryd/NornicDB/blob/main/neural/README.md) |
| 插件模型 | `NORNICDB_MODELS_DIR` 指向目录 | Heimdall 插件可执行的动作后端 | [plugins/README.md](https://github.com/orneryd/NornicDB/blob/main/plugins/README.md) |
`docker/README.md` 显示基础镜像、BGE 镜像、Heimdall 镜像分别通过 `make build-arm64-metal`、`make build-arm64-metal-bge`、`make build-arm64-metal-bge-heimdall` 目标构建；只有后两个目标会在构建阶段把 GGUF 模型打包进镜像。社区中 [Issue #32](https://github.com/orneryd/NornicDB/issues/32) 提出的"GPU 加速 HNSW 构造"规划也与该模块共享 GPU 计算资源。
## 加载、下载与生命周期管理
`docker/README.md` 提供了一组专用的 make 任务用于 Models 的生命周期管理：
```bash
make download-models # 下载 BGE-M3 + qwen3-0.6b（约 750MB）
make check-models # 校验模型文件是否就位
```
构建变体决定了哪些模型在镜像启动时即可用：
- **基础镜像（base）**：不包含任何 GGUF 文件，体积最小，模型需运行时挂载。
- **BGE 镜像**：内嵌 BGE-M3，可立即提供向量嵌入能力，适合纯 RAG 场景。
- **Heimdall 镜像**：在 BGE 基础上叠加 `qwen3-0.6b`，启用完整对话与异常检测；构建时会自动调用 `make download-models`，参见 [docker/README.md](https://github.com/orneryd/NornicDB/blob/main/docker/README.md) 的说明。
在运行期，`plugins/README.md` 指出可通过环境变量覆盖模型目录与具体模型文件名：
```bash
export NORNICDB_MODELS_DIR=/data/models
export NORNICDB_HEIMDALL_MODEL=phi-3.5-mini-instruct
# 实际加载 /data/models/phi-3.5-mini-instruct.gguf
```
这种"目录 + 文件名（不含 .gguf）"的约定让运维可以在不重建镜像的前提下替换 SLM，例如替换为 Phi-3.5-mini-instruct 等第三方模型。
## 训练与量化输出
Models 模块同时承担训练管线的产物管理职能。[neural/README.md](https://github.com/orneryd/NornicDB/blob/main/neural/README.md) 描述的标准流程为：生成数据集 → 校验 → 训练 → 量化 → 部署：
```bash
# 1. 生成数据集
python scripts/generate_cypher_dataset.py --output data/cypher.jsonl --num-examples 2000
# 2. 校验
python scripts/validate_dataset.py data/cypher.jsonl
# 3. 训练
python train.py --preset qwen_1_5b --dataset data/cypher.jsonl \
--output_dir models/cypher-expert --epochs 5
# 4. 导出 GGUF
python export_to_gguf.py --model_dir models/cypher-expert \
--output cypher-expert-q4.gguf
# 5. 部署
cp cypher-expert-q4.gguf /data/models/
```
可用的量化档位同样在 [neural/README.md](https://github.com/orneryd/NornicDB/blob/main/neural/README.md) 中以表格形式给出，涵盖 `Q4_K_M`（体积最小、质量良好）、`Q5_K_M`、`Q8_0` 与 `F16`。训练既支持基础模型的全量微调，也支持 LoRA 适配（`lora_r=16`、`lora_alpha=32`、`target_modules` 自定义），输出与 Heimdall 同源的 GGUF 格式，因此可直接复用插件加载路径。
## 与上层 API 的衔接
模型一旦就位，便通过 [ui/src/utils/api.ts](https://github.com/orneryd/NornicDB/blob/main/ui/src/utils/api.ts) 中定义的接口被上层消费。该文件暴露了 MVCC 生命周期、保留策略分类等结构化类型，但更重要的是它定义了模型相关运行时监控所需的契约，例如嵌入状态、向量索引刷新等字段，供前端 Data Explorer 展示。需要注意的是，[Issue #220](https://github.com/orneryd/NornicDB/issues/220) 报告的"运行时外部向量不会立即刷新底层 HNSW 索引"问题，发生在嵌入模型生成向量后写入存储的路径上，属于 Models 模块与向量索引之间的衔接点而非嵌入模型本身，因此排查时需要同时观察模型端输出与索引端刷新。
## 故障与注意事项
- **模型未下载导致启动失败**：Heimdall 镜像若未先执行 `make download-models` 且关闭了自动下载，会出现 `model file not found`。`make check-models` 可在 CI 中预先发现该问题。
- **环境变量与文档不一致**：[Issue #215](https://github.com/orneryd/NornicDB/issues/215) 报告 `async_writes_enabled` 在文档中存在 YAML 示例但 `pkg/config/config.go` 仅识别环境变量；Models 模块相关变量（`NORNICDB_MODELS_DIR`、`NORNICDB_HEIMDALL_MODEL`）目前同样仅通过环境变量设置，部署时务必使用 env 而非 YAML。
- **嵌入开关与向量陈旧**：当 `EMBEDDING_ENABLED=false` 且依赖外部向量时，运行时写入不会立即重建 HNSW 层 0 的 BM25 种子，需要重启或在批量导入完成后触发重建，参见 [Issue #171](https://github.com/orneryd/NornicDB/issues/171) 关于 Bulk Import API 的讨论。
## See Also
- [README.md](https://github.com/orneryd/NornicDB/blob/main/README.md) — 总览与功能开关
- [docker/README.md](https://github.com/orneryd/NornicDB/blob/main/docker/README.md) — 模型下载、镜像变体、pprof 调试
- [neural/README.md](https://github.com/orneryd/NornicDB/blob/main/neural/README.md) — 数据集生成、训练与 GGUF 导出
- [plugins/README.md](https://github.com/orneryd/NornicDB/blob/main/plugins/README.md) — Heimdall 插件加载与 SLM 切换
- [Issue #32](https://github.com/orneryd/NornicDB/issues/32) — GPU 加速 HNSW 构造规划
- [Issue #171](https://github.com/orneryd/NornicDB/issues/171) — Bulk Import API（影响模型重新构建路径）
- [Issue #215](https://github.com/orneryd/NornicDB/issues/215) — 文档与配置不一致问题
- [Issue #220](https://github.com/orneryd/NornicDB/issues/220) — 运行时向量陈旧问题
---
## Models 模块
### 相关页面
相关主题：[Models 模块](#page-pkg-graphql-models), [Utils 模块](#page-ui-src-utils)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/orneryd/NornicDB/blob/main/README.md)
- [models/.gitkeep](https://github.com/orneryd/NornicDB/blob/main/models/.gitkeep)
- [docker/README.md](https://github.com/orneryd/NornicDB/blob/main/docker/README.md)
- [plugins/README.md](https://github.com/orneryd/NornicDB/blob/main/plugins/README.md)
- [neural/README.md](https://github.com/orneryd/NornicDB/blob/main/neural/README.md)
- [pkg/security/README.md](https://github.com/orneryd/NornicDB/blob/main/pkg/security/README.md)
# Models 模块
## 模块概述与用途
Models 模块是 NornicDB 体系中负责 **AI 模型资产存储、加载与生命周期管理** 的核心目录。它位于仓库根目录的 `models/` 路径下（`models/.gitkeep` 为占位符，实际模型文件通过发布流程注入或本地下载），承担着三类模型资产的托管：
1. **嵌入模型（Embedding Model）**：用于将文本、节点属性或查询转换为向量，供 HNSW 向量索引、混合检索和 Graphiti 实体解析链路使用。
2. **小语言模型（SLM, Small Language Model）**：驱动 Heimdall AI 助手，提供自然语言查询、异常检测、内存整理等功能。
3. **自定义微调模型（Fine-Tuned Models）**：用户通过 `neural/` 子项目训练并以 GGUF 格式导出的领域专用模型，例如 Cypher 专家模型。
资料来源：[README.md](https://github.com/orneryd/NornicDB/blob/main/README.md) 描述 Heimdall 启用方式 `NORNICDB_HEIMDALL_ENABLED=true ./nornicdb serve`，并在「Use Cases」中将 RAG / Graph-RAG / 智能体内存列为核心使用场景。
## 模型组件与目录结构
### 预置模型
在官方 Docker 镜像（尤其是 Heimdall 与 BGE 变体）中，Models 模块会预置以下两类模型，体积约 **750MB**：
| 模型 | 用途 | 大小估算 | 引用 |
| --- | --- | --- | --- |
| `bge-m3.gguf` | 多语言嵌入模型，向量检索核心 | 主要占用 | [docker/README.md](https://github.com/orneryd/NornicDB/blob/main/docker/README.md) |
| `qwen3-0.6b`（GGUF） | Heimdall SLM，负责 NL2Cypher、状态查询 | 次要占用 | [docker/README.md](https://github.com/orneryd/NornicDB/blob/main/docker/README.md) |
模型文件命名遵循 `.gguf` 规则，运行时通过文件名（不含扩展名）解析模型引用。
资料来源：[docker/README.md](https://github.com/orneryd/NornicDB/blob/main/docker/README.md) 中 `make download-models # Downloads BGE-M3 + qwen3-0.6b (~750MB total)` 与 `ls -la models/bge-m3.gguf` 验证路径。
### 配置与环境变量
Models 模块通过环境变量进行路径与模型选择控制，相关变量如下：
- `NORNICDB_MODELS_DIR`：指定模型文件所在的本地目录，默认通常为 `/data/models`。
- `NORNICDB_HEIMDALL_MODEL`：指定 Heimdall 加载的 SLM 文件名（不含 `.gguf` 扩展名）。例如设置为 `phi-3.5-mini-instruct` 时，运行时将加载 `/data/models/phi-3.5-mini-instruct.gguf`。
- `NORNICDB_HEIMDALL_ENABLED`：布尔开关，控制是否启用 Heimdall AI 助手；关闭时不会创建模型加载器与 GPU/CPU 推理上下文。
资料来源：[plugins/README.md](https://github.com/orneryd/NornicDB/blob/main/plugins/README.md) 中给出的示例 `export NORNICDB_MODELS_DIR=/data/models` 与 `export NORNICDB_HEIMDALL_MODEL=phi-3.5-mini-instruct`。
### 数据流与组件关系
下图描述了模型从仓库到查询执行的端到端关系：
```mermaid
flowchart LR
A[models/ 目录
bge-m3.gguf] --> B[嵌入服务]
C[models/ 目录
qwen3-0.6b.gguf] --> D[Heimdall SLM]
E[neural/ 训练
导出 GGUF] --> A
E --> C
B --> F[HNSW 向量索引]
B --> G[混合检索 / Graphiti]
D --> H[NL 查询 / 插件动作]
F --> I[Cypher / Bolt / REST]
G --> I
H --> I
```
## 模型下载、构建与部署
### 拉取与验证
Models 模块支持「自动下载」与「手工预置」两种模式。`docker/README.md` 中定义的 Make 目标包括：
- `make download-models`：下载 BGE-M3 与 qwen3-0.6b，总体积约 750MB。
- `make check-models`：校验模型文件是否已就位。
- `make build-arm64-metal-bge`：构建带嵌入模型的 ARM64 Metal 镜像。
- `make build-arm64-metal-bge-heimdall`：构建带完整认知特性的 Heimdall 镜像，构建过程会自动下载缺失的模型。
### 部署变体
针对不同部署目标，Models 模块被嵌入到不同的 Docker 镜像中：
| 变体目标 | 是否含 BGE | 是否含 Heimdall SLM | 引用 |
| --- | --- | --- | --- |
| `build-arm64-metal` | 否 | 否 | [docker/README.md](https://github.com/orneryd/NornicDB/blob/main/docker/README.md) |
| `build-arm64-metal-bge` | 是 | 否 | [docker/README.md](https://github.com/orneryd/NornicDB/blob/main/docker/README.md) |
| `build-arm64-metal-bge-heimdall` | 是 | 是 | [docker/README.md](https://github.com/orneryd/NornicDB/blob/main/docker/README.md) |
| `*-headless` | 可选 | 可选 | [docker/README.md](https://github.com/orneryd/NornicDB/blob/main/docker/README.md) |
### pprof 与运行时诊断
当需要诊断模型加载或向量检索导致的 CPU 占用异常（例如社区反馈的 BuildIndexes/k-means 风暴导致的 hang）时，可启用 pprof 监听器：
```bash
docker run --rm -p 7474:7474 -p 7687:7687 -p 9091:9091 \
-e NORNICDB_PPROF_ENABLED=true \
-e NORNICDB_PPROF_LISTEN=0.0.0.0:9091 \
nornicdb-amd64-cpu-headless
```
资料来源：[docker/README.md](https://github.com/orneryd/NornicDB/blob/main/docker/README.md) 末尾的 pprof 示例。
## 模型训练与微调
`neural/` 子项目提供从数据集构造到 GGUF 导出的完整工具链，最终产物直接落入 Models 模块的加载目录。典型流程为：
1. **生成数据**：`python scripts/generate_cypher_dataset.py --count 1000 --output data/cypher_training.jsonl`（来源 [neural/README.md](https://github.com/orneryd/NornicDB/blob/main/neural/README.md)）。
2. **质量验证**：`python scripts/validate_dataset.py data/cypher_training.jsonl --check-cypher`。
3. **LoRA 微调**：
```bash
python train.py --preset qwen_1_5b --dataset data/cypher.jsonl --output_dir models/cypher-expert --epochs 5
```
4. **导出 GGUF**：
```bash
python export_to_gguf.py --model_dir models/cypher-expert --output cypher-expert-q4.gguf
```
5. **注入 Models 模块**：`cp cypher-expert-q4.gguf /data/models/`，并通过 `NORNICDB_HEIMDALL_MODEL=cypher-expert` 激活。
`neural/README.md` 同时指出训练数据质量比数量更重要：「100 perfect examples > 1000 mediocre ones」，并推荐 Cypher 任务至少 2000 条样本、覆盖 30% 基础匹配、20% WHERE 过滤、15% 关系查询等分布。
## 常见失败模式与社区反馈
- **运行时向量底物不刷新**：当 `EMBEDDING_ENABLED=false` 并由外部写入向量时，HNSW 索引需要重启或显式重建，否则会影响检索质量。资料来源：社区反馈 issue #220。
- **BuildIndexes 风暴**：批量导入触发 k-means 暖启动，可能造成 CPU 长时间挂起，issue #222 中有详细复现条件。
- **Cypher 专家模型对齐**：将 `cypher-expert-q4.gguf` 注入 Heimdall 时，需确认 `NORNICDB_HEIMDALL_MODEL` 与 `NORNICDB_MODELS_DIR` 指向一致，否则会回退到默认 qwen3 模型。
## See Also
- [README.md](https://github.com/orneryd/NornicDB/blob/main/README.md) — Heimdall 启用、模型下载入口
- [neural/README.md](https://github.com/orneryd/NornicDB/blob/main/neural/README.md) — 自定义模型训练与 GGUF 导出
- [docker/README.md](https://github.com/orneryd/NornicDB/blob/main/docker/README.md) — 模型打包、镜像变体、pprof
- [plugins/README.md](https://github.com/orneryd/NornicDB/blob/main/plugins/README.md) — 插件如何引用 Models 模块
- [pkg/security/README.md](https://github.com/orneryd/NornicDB/blob/main/pkg/security/README.md) — 模型加载与外接接口的安全约束
- [docs/operations/configuration.md](https://github.com/orneryd/NornicDB/blob/main/docs/operations/configuration.md) — `NORNICDB_*` 环境变量全集
- [docs/plans/gpu-hnsw-construction-plan.md](https://github.com/orneryd/NornicDB/blob/main/docs/plans/gpu-hnsw-construction-plan.md) — GPU 加速 HNSW 计划，涉及 Models 模块的下一步扩展
---
## Utils 模块
### 相关页面
相关主题：[Models 模块](#page-models)
相关源码文件
以下源码文件用于生成本页说明：
- [ui/src/utils/api.ts](https://github.com/orneryd/NornicDB/blob/main/ui/src/utils/api.ts)
- [ui/src/utils/basePath.ts](https://github.com/orneryd/NornicDB/blob/main/ui/src/utils/basePath.ts)
- [ui/src/utils/cyberSeed.ts](https://github.com/orneryd/NornicDB/blob/main/ui/src/utils/cyberSeed.ts)
- [ui/src/utils/cyberSim.ts](https://github.com/orneryd/NornicDB/blob/main/ui/src/utils/cyberSim.ts)
- [ui/src/utils/cypherStatements.ts](https://github.com/orneryd/NornicDB/blob/main/ui/src/utils/cypherStatements.ts)
- [ui/src/utils/demoSeed.ts](https://github.com/orneryd/NornicDB/blob/main/ui/src/utils/demoSeed.ts)
# Utils 模块
## 模块概述
`ui/src/utils/` 是 NornicDB 前端 UI 子项目的工具层目录，集中存放与数据库后端交互、路径解析、可视化样例数据生成以及 Cypher 语句辅助相关的纯函数与类型定义。该层不包含 React 组件本身，但为 `components/browser/` 下的浏览器面板、查询面板、节点详情面板以及演示页 `/demo` 提供可复用的基础能力。资料来源：[ui/src/utils/demoSeed.ts:1-6]() 注释中明确说明该文件"为 `/demo` 页程序化生成 3D 星系网格"。
模块按职责可划分为四组：**API 类型契约层**（api.ts）、**路由与基础路径解析**（basePath.ts）、**可视化样例数据生成**（demoSeed.ts / cyberSeed.ts / cyberSim.ts）、**Cypher 语句构造辅助**（cypherStatements.ts）。
## 核心文件与职责
### API 类型契约层（api.ts）
`ui/src/utils/api.ts` 集中声明了 NornicDB 后端 REST/gRPC 响应在 TypeScript 端使用的强类型结构，避免散落在多个组件中重复定义。该文件暴露以下几族接口：
| 接口族 | 用途 |
| --- | --- |
| `MVCCLifecycleDebtKey` / `MVCCLifecycleDebtResponse` | 描述压缩债（compaction debt）键的逻辑键、命名空间、字节数与墓链深度 |
| `MVCCLifecycleNamespaceMetrics` | 命名空间维度的可清理/已清理字节数 |
| `MVCCLifecycleRollup` | `prune_runs`、`keys_processed`、`fence_mismatches` 等累计指标 |
| `MVCCLifecycleLastRun` | 上一次修剪运行的瞬时指标 |
| `MVCCSnapshotReaderInfo` | 当前活跃的 MVCC 快照读取者信息（`ReaderID`、`StartTime`、`SnapshotVersion`） |
| `MVCCLifecycleStatus` | 整合上述字段，并包含 `pressure_band`、`emergency_mode`、`mvcc_tombstone_chain_max_depth` 等运维信号 |
| `RetentionCategory` / `RetentionPeriod` | 保留策略分类枚举与周期定义，覆盖 `SYSTEM`、`AUDIT`、`PHI`、`PII`、`FINANCIAL` 等类别 |
资料来源：[ui/src/utils/api.ts:1-60]() 中可见 `MVCCLifecycleDebtKey`、`MVCCLifecycleNamespaceMetrics`、`MVCCLifecycleRollup` 的字段定义；[ui/src/utils/api.ts:95-120]() 中可见 `MVCCSnapshotReaderInfo` 与 `MVCCLifecycleStatus` 的完整字段；[ui/src/utils/api.ts:130-150]() 给出 `RetentionCategory` 枚举与 `RetentionPeriod` 接口。
### 路由与基础路径解析（basePath.ts）
`basePath.ts` 负责把 NornicDB 服务可能部署在子路径下的情况抽象成统一访问函数（例如反代到 `/nornicdb/...`）。该层使得 UI 在根路径、嵌入式部署、容器化反代等场景下都能正确拼出 REST 端点（如 `/nornicdb/search`、`/db/nornicdb/tx/commit`）。该文件的具体实现细节未在当前抓取片段中直接呈现，但其语义与 `ui/README.md` 文档中列出的端点（`/health`、`/status`、`/nornicdb/search`、`/nornicdb/similar`、`/db/nornicdb/tx/commit`）相互印证。资料来源：[ui/README.md:API Endpoints 表]()
### 可视化样例数据生成（demoSeed.ts、cyberSeed.ts、cyberSim.ts）
`ui/src/utils/demoSeed.ts` 是该组中最具代表性的文件，其注释清楚地说明算法目标：
> "程序化生成 `/demo` 页使用的 3D 星系网格。布局：12 个扇区按斐波那契球面排列，每个扇区约 36 颗星，带扇区内超空间航道；扇区之间由少量网关星串接成链。从扇区 0 到扇区 11 的遍历必须跨越每个扇区边界——产生天然的 11 跳以上最短路径。"
资料来源：[ui/src/utils/demoSeed.ts:1-6]()
文件导出的类型契约与字面量如下：
- `DemoStar`：`id`、`name`、`sector`、`hue`、`mass`、`x/y/z`
- `DemoEdge`：`source`、`target`、`distance`
- `DemoGalaxy`：`stars`、`edges`、`startId`、`endId`、`sectorCount`
- `STAR_PREFIX`：北欧神话词根数组，元素含 `Yggdra`、`Nidh`、`Mim`、`Gjall`、`Heidr`、`Surt`、`Vidar`、`Hodr`、`Skuld`、`Urda`、`Verda`、`Bragi`、`Iduna`、`Freyja`、`Tyr`、`Vanir`、`Asgar`、`Mjoll`、`Gunn`、`Sleip`、`Hugin`、`Munin`、`Ratat`、`Fenris`
资料来源：[ui/src/utils/demoSeed.ts:32-50]()
与 `demoSeed.ts` 配套的 `cyberSeed.ts` 与 `cyberSim.ts` 命名暗示它们承担"赛博"主题演示的种子生成与物理/拓扑模拟（具体细节未在当前片段中直接展现）。
### Cypher 语句辅助（cypherStatements.ts）
`cypherStatements.ts` 集中提供构造 Cypher 查询的辅助函数，常用于 `QueryPanel.tsx`、浏览器面板与示例查询中。结合 `apoc/README.md` 中列出的 `CALL db.index.vector.queryNodes(...)` 用法与 README 中展示的"vector + fulltext 混合搜索"示例，可推断该文件至少包含混合检索 Cypher 模板与常用调用包装。资料来源：[apoc/README.md:plugins 目录列表]() 展示了与 `db.index.vector.queryNodes` 相关的 APOC 包结构；[README.md:Cypher (Neo4j-compatible) 段]()
## 关键数据模型与组件依赖
下面这张表汇总各工具文件的核心导出与其直接消费者，便于在修改类型时反向追踪。
| 文件 | 核心导出 | 典型消费者 |
| --- | --- | --- |
| `api.ts` | MVCC/Retention 接口族 | `Browser`、`NodeDetailsPanel`、运维仪表盘 |
| `basePath.ts` | 路径解析函数 | 所有发起 fetch 的组件 |
| `demoSeed.ts` | `DemoGalaxy` 工厂 | `/demo` 演示页、3D 渲染组件 |
| `cyberSeed.ts` / `cyberSim.ts` | 赛博主题种子与模拟器 | 赛博主题演示页 |
| `cypherStatements.ts` | Cypher 字符串构造器 | `QueryPanel.tsx`、示例库 |
## 使用模式与扩展建议
1. **新增后端接口类型**：在 `api.ts` 中补充 TypeScript interface 后，由 fetch 层使用，组件层不应重复定义响应结构。
2. **部署在反代子路径下**：通过 `basePath.ts` 统一拼装 URL，避免硬编码 `/nornicdb/...` 前缀。
3. **扩展演示数据**：修改 `demoSeed.ts` 中 `STAR_PREFIX`、扇区数量或网关星规则即可调整 `/demo` 的拓扑难度。
4. **构造 Cypher 模板**：将高频 Cypher 集中放入 `cypherStatements.ts`，便于在 `QueryPanel` 中复用并支持参数注入。
## See Also
- [Browser 组件层](浏览器组件)
- [Cypher 与 APOC 程序](Cypher参考)
- [MVCC 生命周期运维](运维指南)
- [配置文档（configuration.md）](配置参考)
---
---
## Doramagic 踩坑日志
项目：orneryd/NornicDB
摘要：发现 37 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：安装坑 - 来源证据：Datetime nested in a list/map parameter (UNWIND $rows … row.created_at) stored as Go-format string, not a temporal。
## 1. 安装坑 · 来源证据：Datetime nested in a list/map parameter (UNWIND $rows … row.created_at) stored as Go-format string, not a temporal
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Datetime nested in a list/map parameter (UNWIND $rows … row.created_at) stored as Go-format string, not a temporal
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/orneryd/NornicDB/issues/221 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 2. 安装坑 · 来源证据：Regression in 0593642: bulk Graphiti extraction triggers BuildIndexes/k-means warmup storm → CPU-bound hang (entity-res…
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Regression in 0593642: bulk Graphiti extraction triggers BuildIndexes/k-means warmup storm → CPU-bound hang (entity-resolution cosine search path)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/orneryd/NornicDB/issues/222 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 3. 安全/权限坑 · 来源证据：Vector search substrate not updated on runtime writes (external vectors, EMBEDDING_ENABLED=false) — stale until restart…
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Vector search substrate not updated on runtime writes (external vectors, EMBEDDING_ENABLED=false) — stale until restart; degrades resolution during ingest
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/orneryd/NornicDB/issues/220 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 4. 安全/权限坑 · 来源证据：[BUG] db.index.vector.queryRelationships returns 0 rows on v1.1.7 (node path works)
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG] db.index.vector.queryRelationships returns 0 rows on v1.1.7 (node path works)
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/orneryd/NornicDB/issues/219 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 5. 安装坑 · 依赖 Docker 环境
- 严重度：medium
- 证据强度：runtime_trace
- 发现：安装/运行入口包含 Docker 命令：docker run -d --name nornicdb -p 7474:7474 -p 7687:7687 -v nornicdb-data:/data timothyswt/nornicdb-arm64-metal-bge:latest # amd64 / CPU only docker run
- 对用户的影响：非工程用户可能没有 Docker，启动成本明显增加。
- 复现命令：`docker run -d --name nornicdb -p 7474:7474 -p 7687:7687 -v nornicdb-data:/data timothyswt/nornicdb-arm64-metal-bge:latest # amd64 / CPU only docker run`
- 证据：identity.distribution | https://github.com/orneryd/NornicDB | docker run -d --name nornicdb -p 7474:7474 -p 7687:7687 -v nornicdb-data:/data timothyswt/nornicdb-arm64-metal-bge:latest # amd64 / CPU only docker run
## 6. 安装坑 · 失败模式：installation: [FEATURE] - Bulk Import API
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: [FEATURE] - Bulk Import API
- 对用户的影响：Developers may fail before the first successful local run: [FEATURE] - Bulk Import API
- 证据：failure_mode_cluster:github_issue | https://github.com/orneryd/NornicDB/issues/171 | [FEATURE] - Bulk Import API
## 7. 安装坑 · 失败模式：installation: [PROPOSAL] OKF Format import/export - RFC
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: [PROPOSAL] OKF Format import/export - RFC
- 对用户的影响：Developers may fail before the first successful local run: [PROPOSAL] OKF Format import/export - RFC
- 证据：failure_mode_cluster:github_issue | https://github.com/orneryd/NornicDB/issues/217 | [PROPOSAL] OKF Format import/export - RFC
## 8. 安装坑 · 失败模式：installation: v1.1.7 - Black Math
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v1.1.7 - Black Math
- 对用户的影响：Upgrade or migration may change expected behavior: v1.1.7 - Black Math
- 证据：failure_mode_cluster:github_release | https://github.com/orneryd/NornicDB/releases/tag/v1.1.7 | v1.1.7 - Black Math
## 9. 安装坑 · 来源证据：Docs: async_writes yaml examples in README + configuration.md don't match config.go (env-only)
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Docs: async_writes yaml examples in README + configuration.md don't match config.go (env-only)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/orneryd/NornicDB/issues/215 | 来源类型 github_issue 暴露的待验证使用条件。
## 10. 安装坑 · 来源证据：SET silently fails on nodes that existed before v0→v2 storage migration
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：SET silently fails on nodes that existed before v0→v2 storage migration
- 对用户的影响：可能影响升级、迁移或版本选择。
- 证据：community_evidence:github | https://github.com/orneryd/NornicDB/issues/190 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 11. 安装坑 · 来源证据：[FEATURE] - Bulk Import API
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[FEATURE] - Bulk Import API
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/orneryd/NornicDB/issues/171 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 12. 安装坑 · 来源证据：[Feature] Neo4j drop-in compatibility: accept the default "neo4j" database name and the 3-arg fulltext procedure form
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature] Neo4j drop-in compatibility: accept the default "neo4j" database name and the 3-arg fulltext procedure form
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/orneryd/NornicDB/issues/214 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 13. 安装坑 · 来源证据：[PROPOSAL] OKF Format import/export - RFC
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[PROPOSAL] OKF Format import/export - RFC
- 对用户的影响：可能影响升级、迁移或版本选择。
- 证据：community_evidence:github | https://github.com/orneryd/NornicDB/issues/217 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 14. 配置坑 · 可能修改宿主 AI 配置
- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/orneryd/NornicDB | host_targets=claude
## 15. 配置坑 · 失败模式：configuration: Cypher regressions in main since v1.1.4: MATCH+CREATE relationship-only and SET clause parsing
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: Cypher regressions in main since v1.1.4: MATCH+CREATE relationship-only and SET clause parsing
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Cypher regressions in main since v1.1.4: MATCH+CREATE relationship-only and SET clause parsing
- 证据：failure_mode_cluster:github_issue | https://github.com/orneryd/NornicDB/issues/192 | Cypher regressions in main since v1.1.4: MATCH+CREATE relationship-only and SET clause parsing
## 16. 配置坑 · 失败模式：configuration: Docs: async_writes yaml examples in README + configuration.md don't match config.go (env-only)
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: Docs: async_writes yaml examples in README + configuration.md don't match config.go (env-only)
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Docs: async_writes yaml examples in README + configuration.md don't match config.go (env-only)
- 证据：failure_mode_cluster:github_issue | https://github.com/orneryd/NornicDB/issues/215 | Docs: async_writes yaml examples in README + configuration.md don't match config.go (env-only)
## 17. 配置坑 · 失败模式：configuration: Multiple Cypher correctness bugs: OPTIONAL MATCH, CONTAINS quoting, elementId parameters, wri...
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: Multiple Cypher correctness bugs: OPTIONAL MATCH, CONTAINS quoting, elementId parameters, write counters, RETURN after writes
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Multiple Cypher correctness bugs: OPTIONAL MATCH, CONTAINS quoting, elementId parameters, write counters, RETURN after writes
- 证据：failure_mode_cluster:github_issue | https://github.com/orneryd/NornicDB/issues/191 | Multiple Cypher correctness bugs: OPTIONAL MATCH, CONTAINS quoting, elementId parameters, write counters, RETURN after writes
## 18. 配置坑 · 失败模式：configuration: UNWIND $list AS name returns variable name as string literal instead of iterating list (Bolt,...
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: UNWIND $list AS name returns variable name as string literal instead of iterating list (Bolt, v1.1.4)
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: UNWIND $list AS name returns variable name as string literal instead of iterating list (Bolt, v1.1.4)
- 证据：failure_mode_cluster:github_issue | https://github.com/orneryd/NornicDB/issues/189 | UNWIND $list AS name returns variable name as string literal instead of iterating list (Bolt, v1.1.4)
## 19. 配置坑 · 失败模式：configuration: Vector search substrate not updated on runtime writes (external vectors, EMBEDDING_ENABLED=fa...
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: Vector search substrate not updated on runtime writes (external vectors, EMBEDDING_ENABLED=false) — stale until restart; degrades resolution during ingest
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Vector search substrate not updated on runtime writes (external vectors, EMBEDDING_ENABLED=false) — stale until restart; degrades resolution during ingest
- 证据：failure_mode_cluster:github_issue | https://github.com/orneryd/NornicDB/issues/220 | Vector search substrate not updated on runtime writes (external vectors, EMBEDDING_ENABLED=false) — stale until restart; degrades resolution during ingest
## 20. 配置坑 · 失败模式：configuration: [BUG] Cypher correctness (v1.1.5): `SET x =