Home
Softono
nebula-kb

nebula-kb

Open source Python
Website GitHub
23
Stars
2
Forks
25
Issues
1
Watchers
1 week
Last Commit
AI Agents Knowledge Bases & RAG

About nebula-kb

Local-first knowledge asset lifecycle platform — ingestion, governance, retrieval, feedback loops & ops dashboard. Built with Django, PostgreSQL (pgvector), Redis.

Platforms

Web Self-hosted

Languages

Python

Links

Website Source Code
h
Published by
however-yir
Visit View Profile

README.md

View on GitHub

NebulaKB - 知识资产生命周期平台 | Knowledge Operations Hub

Build Tests Docs License Status

Matrix role: nebula-kb owns the knowledge asset lifecycle: ingestion, governance, retrieval quality, feedback loops, and operations dashboards. For the Spring AI backend platform layer, see knowledgeops-agent.

Status: active

Matrix: knowledgeops-agent · tianji-ai-agent · nebula-kb · forgepilot-studio · however-microservices-lab

NebulaKB is a local-first knowledge asset lifecycle platform for teams that need measurable knowledge quality — combining document ingestion, semantic indexing (pgvector), retrieval-augmented Q&A, human feedback loops, and an operations dashboard. Built with Django, PostgreSQL, and Redis. For the enterprise Spring AI RAG backend, see knowledgeops-agent.

NebulaKB 面向知识运营团队，不是泛泛的知识库或 RAG 示例，而是把知识资产的入库、治理、检索、反馈、回看和运营后台串成一条可演示、可测试、可度量的工作流。

定位一句话：NebulaKB 负责让知识资产持续变好，knowledgeops-agent 负责提供 Spring AI 企业后端工程基线。

NebulaKB demo

项目快照

  • 定位：知识资产生命周期平台，而不是通用聊天工作台。
  • 亮点：Django + PostgreSQL + Redis、多模型接入、知识资产生命周期、检索链路可观测、质量评测闭环。
  • 最短运行路径：python apps/manage.py migrate && python main.py dev web
  • 作品矩阵角色：NebulaKB 负责知识资产运营层，和企业 RAG 后端、业务 Agent、AI 工程执行平台、云原生微服务实验室形成互补。
  • 证据索引：docs/evidence/README.md

与 knowledgeops-agent 的边界

维度 NebulaKB knowledgeops-agent
主定位 知识资产生命周期平台 企业级 Spring AI RAG 后端平台
关键用户 知识运营、客服质检、内容治理、业务管理员 后端工程师、AI 平台工程师、架构负责人
关键链路 文档入库、解析、切片、索引、检索问答、反馈闭环、低质答案回看 Spring AI 接入、租户隔离、异步任务、鉴权审计、可观测、部署基线
产品表面 运营后台、知识库列表、文档入库、问答反馈、质量指标 API、Spring Boot 服务、鉴权、队列、向量库、监控栈
成功标准 知识命中率提升、低质答案率下降、未命中问题可治理 后端能力完整、接口稳定、部署和观测可验证

产品截图

Knowledge Health Dashboard

运营后台 知识库列表
运营后台截图 知识库列表截图
文档入库 问答反馈
文档入库截图 问答反馈截图

生命周期验证资产

阶段 平台能力 验证资产
入库 文件上传、来源登记、知识库归属、租户边界 demo-data/knowledge-sample/、apps/knowledge/tests.py
治理 解析状态、失败原因、切片结果、待更新标记 apps/knowledge/services/asset_lifecycle_demo.py
检索 命中排序、引用返回、空结果兜底 scripts/demo_lifecycle.py
反馈 人工评分、低质答案沉淀、闭环状态 docs/demo-script.md
运营 知识命中率、低质答案率、未命中问题、热门知识、待更新知识 docs/observability.md

矩阵角色

NebulaKB 是 however-yir AI 工程作品矩阵中的“知识运营中枢”，负责展示知识资产从文档接入、解析、切片、索引、检索，到问答反馈、低质答案回看和知识质量优化的生命周期闭环。完整项目矩阵见 docs/project-matrix.md。

同系列相关项目

Repo 角色 与 NebulaKB 的关系
local-ai-hub 本地 AI 工作台与统一入口 更偏模型接入、本地工具台和团队日常使用入口
yourrag 企业 RAG / Agent 交付参考 更偏私有化交付方案和 RAG + Agent 组合实践，核心引擎内嵌于 engines/yourrag/

目录

1. 项目概述

本仓库围绕知识资产生命周期组织代码和文档：知识进入系统后，要能被解析、切片、索引、检索、反馈、回看和持续治理。它的价值不只是“能问答”，而是把知识命中率、低质答案、待更新知识和运营后台放到同一条可演示链路里。

2. 目标与场景

适用场景：

  • 作为业务功能开发与验证的基础仓库。
  • 作为团队内部协作与知识沉淀的载体。
  • 作为后续扩展和二次开发的起点。

相对主作品矩阵与同系列项目的职责边界：

  • NebulaKB 更像知识入库、知识治理、检索问答与质量反馈闭环平台。
  • knowledgeops-agent 更偏企业级 Spring AI RAG 后端、安全治理与可观测基线。
  • tianji-ai-agent 更偏业务 Agent 流程、Tool Calling、多智能体路由和课程业务闭环。
  • forgepilot-studio 更偏 AI 工程执行、任务编排、审计回放和团队工作台。
  • however-microservices-lab 更偏云原生微服务、多语言服务治理、Kubernetes 和 AI 服务集成。
  • local-ai-hub 与 yourrag 作为同系列相关项目，分别偏本地 AI 工作台和企业 RAG/Agent 交付参考。

3. 核心能力

  • 支持知识入库、索引、检索与问答闭环。
  • 支持本地化部署与可控的数据边界。
  • 支持持续扩展知识源与应用场景。
  • 安全加固：SECRET_KEY 生产环境强制校验、DRF 速率限制、SSO (OIDC/SAML) 接入、审计日志脱敏、安全响应头。
  • 可观测性：Prometheus 指标暴露、OpenTelemetry 链路追踪、Grafana 预置仪表盘、Celery Flower 监控。
  • 数据库运维：自动化备份（Celery 任务 + cron 脚本）、PgBouncer 连接池、HNSW 索引可调参数。
  • CI/CD：60% 覆盖率门禁、Vitest 前端测试、Helm Chart、Docker 非 root 运行。
  • 性能优化：检索结果缓存、Gunicorn 可配 workers/threads、Celery 并发可配、LLM Fallback 降级。
  • API 版本化：/api/v1/ 前缀路由、知识版本管理、批量导入导出。

3.1 典型用例

场景 主要模块 目标结果
文档入库与解析 apps/knowledge 把资料转为可检索知识资产
检索问答与运营 apps/chat, ui/ 形成知识问答与后台运营闭环
模型接入与切换 apps/models_provider, apps/local_model 对接本地或远端模型
安装与部署 installer/ 本地快速起服与依赖初始化
应用扩展 apps/application, appstore/nebula.json 面向后续插件化或应用化拓展

3.2 模块职责矩阵

路径 角色
apps/knowledge 知识库核心、入库与检索相关能力
apps/chat 问答交互与知识调用入口
apps/models_provider 模型提供方接入层
apps/common / apps/system_manage 平台公共与系统管理能力
installer/ 本地部署、数据库与 Redis 启动辅助
ui/ 管理后台与问答前端（Vue 3 + Vite + TypeScript + Ant Design）

4. 技术栈

  • 后端：Python 3.11 · Django 5.2 · DRF · Celery · django-prometheus
  • 数据：PostgreSQL + pgvector · Redis · django-redis 缓存
  • AI/LLM：LangChain · LangGraph · OpenAI / Anthropic / DeepSeek / Ollama / DashScope 等多模型接入
  • 前端：Vue 3 · Vite · Vitest
  • 部署：Docker · Helm (Kubernetes) · PgBouncer · Gunicorn
  • CI/CD：GitHub Actions · coverage 60% 门禁 · pip-audit 依赖审计 · Helm lint

5. 仓库结构

建议优先阅读：

  • README.md：项目入口与整体说明。
  • README_CN.md：更细化的中文交付说明。
  • apps/、ui/：后端与界面主目录。
  • installer/：安装、初始化与部署辅助脚本。

6. Quick Start

  1. 克隆仓库并进入目录：
git clone https://github.com/however-yir/nebula-kb.git
cd nebula-kb
  1. 安装依赖并初始化：
python -m venv .venv
source .venv/bin/activate
pip install -U pip
[ -f requirements.txt ] && pip install -r requirements.txt
[ -f pyproject.toml ] && pip install -e .
python apps/manage.py migrate
  1. 启动开发环境：
python main.py dev web

首次启动检查清单

首次运行或换机器演示前，按顺序确认：

  1. .env 已由 .env.example 复制，且所有 CHANGE_ME_* 值已经替换；scripts/bootstrap-local.sh 会阻止占位密码启动。
  2. Python 使用 3.11，虚拟环境已激活，pip install -e . 已完成；前端使用 Node 20 并执行过 npm ci。
  3. Docker Desktop 正在运行；如使用本地依赖栈，执行 docker compose --env-file .env -f docker-compose.dev.yml ps 能看到 postgres 和 redis。
  4. 5432、6379、8080、5173、5174 未被占用；如被占用，先在 .env 调整 NEBULA_DB_PORT、NEBULA_REDIS_PORT 或前端 dev server 端口。
  5. PostgreSQL 使用 pgvector/pgvector:pg16，并能执行 CREATE EXTENSION IF NOT EXISTS vector;。
  6. 本地数据目录已明确：开发默认使用 NEBULA_DATA_DIR=/tmp/nebula；Docker 演示或长期数据请挂载到持久目录，例如 ~/.nebula-kb。
  7. 运行 python apps/manage.py check 和 python apps/manage.py migrate 后再启动 python main.py dev web。

常见启动失败排查见 docs/ops/operability.md#本地启动排查矩阵。

启动前端

cd ui
npm ci
npm run dev      # 管理后台 (http://localhost:5173)
npm run chat     # 问答界面 (http://localhost:5174)

启动成功检查

本地开发默认端口：

服务 地址 成功标准
后端 API / 管理端静态入口 http://localhost:8080/admin 页面可访问，API 请求不返回启动错误
聊天端静态入口 http://localhost:8080/chat 页面可访问，聊天端资源可加载
管理前端 Vite http://localhost:5173 Vite dev server 启动成功
聊天前端 Vite http://localhost:5174 chat mode dev server 启动成功

健康检查：

curl -fsS http://localhost:8080/healthz
curl -fsS http://localhost:8080/readyz

/healthz 只验证进程存活；/readyz 会验证 PostgreSQL、Redis、模型服务和对象存储等依赖是否可用。发布或演示前应以 /readyz 返回成功作为切流量或继续操作的条件。

最小演示闭环：

  1. 登录管理端并创建知识库。
  2. 上传 demo-data/knowledge-sample/ 中的示例资料。
  3. 等待解析、切片、向量化完成。
  4. 在检索或问答页面提出一个命中示例资料的问题。
  5. 提交一次点赞或点踩反馈。
  6. 打开知识运营大盘，确认命中、低质答案或待更新知识指标可见。

6.1 本地依赖一键准备（PostgreSQL / Redis / 可选 Ollama）

首次启动建议先执行：

cp .env.example .env
# 修改 .env 中所有 CHANGE_ME_* 密码

./scripts/bootstrap-local.sh --start
# 如需一起拉起 Ollama:
# ./scripts/bootstrap-local.sh --start --with-ollama

该脚本会：

  1. 校验 .env 是否存在并阻止占位密码直接启动；
  2. 按 docker-compose.dev.yml 拉起 PostgreSQL / Redis；
  3. 自动确保 pgvector 扩展已启用；
  4. 可选拉起本地 Ollama，降低首次联调门槛。

6.2 极速安装脚本（macOS / Windows）

macOS:

./scripts/quick-install-mac.sh
# 如需一起拉起 Ollama:
# ./scripts/quick-install-mac.sh --with-ollama

Windows (PowerShell):

powershell -ExecutionPolicy Bypass -File .\scripts\quick-install-win.ps1
# 如需一起拉起 Ollama:
# powershell -ExecutionPolicy Bypass -File .\scripts\quick-install-win.ps1 -WithOllama

快速脚本会自动完成：

  1. 初始化 .env 并替换 CHANGE_ME_* 占位密钥；
  2. 创建 .venv 并安装 Python 依赖；
  3. 拉起 PostgreSQL / Redis（可选 Ollama）并确保 pgvector；
  4. 执行数据库迁移。

7. 配置建议

建议按 dev / staging / prod 分层配置，并将密钥类信息放入环境变量或密钥管理系统。

7.1 部署形态矩阵

形态 入口 适合场景
开发模式 python main.py dev web 本地功能开发
一键本地启动 installer/start-all.sh 演示与快速验证
分组件启动 installer/start-postgres.sh / installer/start-redis.sh / installer/start-maxkb.sh 更接近生产的联调环境
可运维分离部署 docker compose -f deploy/docker-compose.operational.yml up -d web / worker / scheduler / PostgreSQL / Redis / object storage 独立部署

运维部署、环境变量契约、健康检查、备份恢复和回滚流程见 docs/ops/operability.md 与 docs/ops/postgres-backup-restore.md。

8. 开发与测试

推荐流程：

  1. 基于默认分支创建功能分支。
  2. 小步提交并保持提交目标单一。
  3. 本地完成构建与测试后再推送。
  4. 通过 Pull Request 完成评审与合并。

本地验证入口：

python apps/manage.py check
python apps/manage.py test apps.knowledge
cd ui && npm ci && npm test && npm run type-check && npm run build
bash scripts/quality-gate.sh all          # 覆盖率 + lint + 结构检查
helm lint deploy/helm/nebula-kb           # Helm Chart 校验
python scripts/demo_lifecycle.py

8.1 评测与验收路径

建议把以下链路作为最小验收闭环：

  1. 导入一组真实文档并验证索引完成。
  2. 对同一问题做检索命中检查与答案可解释性检查。
  3. 验证不同模型提供方下的响应一致性与延迟。
  4. 校验后台管理入口、知识集管理与权限边界是否稳定。

9. 协作与发布

建议使用语义化版本，发布说明应包含新增、修复与兼容性说明。

10. 路线图

已完成 (v2.0.0)

  • [x] SECRET_KEY 生产环境强制校验
  • [x] DRF 速率限制 (Anon/User/KnowledgeSearch)
  • [x] SSO 框架 (OIDC/SAML Provider 模型)
  • [x] 审计日志中间件（敏感字段脱敏）
  • [x] 安全响应头中间件
  • [x] django-prometheus 指标暴露
  • [x] OpenTelemetry 链路追踪中间件
  • [x] Grafana 预置仪表盘 + 数据源配置
  • [x] Celery Flower 服务
  • [x] 自动化备份任务 + cron 脚本
  • [x] PgBouncer 连接池服务
  • [x] HNSW 索引参数可配置
  • [x] CI 覆盖率门禁 60%
  • [x] Vitest 前端测试框架
  • [x] Helm Chart (Kubernetes 部署)
  • [x] Docker 非 root 用户运行
  • [x] 检索结果缓存
  • [x] Gunicorn workers/threads 可配置
  • [x] Celery 并发可配置
  • [x] LLM Fallback 降级管理器
  • [x] API v1 路由前缀
  • [x] 知识版本管理序列化器
  • [x] 批量导入导出序列化器

后续规划

  1. 稳定主流程与关键接口。
  2. 优化模块边界与可观测性。
  3. 完善自动化测试与文档体系。

11. 贡献指南

提交建议包含：变更背景、实现说明、验证结果、风险评估。

12. License

请以仓库内现有 License 文件为准。