Knowledge Hub - AI-Native RAG 智能体编排平台

把组织知识、模型、工具与工作流装配成可运行的 AI 应用。

Knowledge Hub 是一个面向组织知识资产的 AI 应用编排平台。Spring Boot 控制面负责知识库、模型、Agent、工具与工作流管理，Hermes 认知面通过 gRPC 提供规划、ReAct、记忆与工具调用能力，Vue 3 前端统一承载配置、调试和运行界面。

本项目基于 qKnow 衍生，当前聚焦可验证的 RAG 检索、流式对话和 Agent 编排路径。AI Judge 与反思机制为可选能力，默认并非全部启用。

核心能力 · 系统架构 · 快速开始 · 开发与验证 · API 文档

🔒 架构模型基线纠正 (Architecture Model Baseline Corrected): 本系统的所有生成侧（Chat/Generation/RAG 检索对话）唯一使用的是 DeepSeek API。 本系统的所有向量化侧（Embedding）唯一使用的是 阿里千问 (Qwen) Embedding。 绝无任何本地部署的大语言模型，且已彻底弃用 OpenAI/GPT API。

flowchart TB
    Web["Vue 3 / Vite<br/>知识库 · Agent · DAG 画布"]
    Control["Spring Boot 控制面<br/>RBAC · 会话 · RAG · 工具 · 工作流"]
    Hermes["Hermes 认知面<br/>规划 / ReAct · 记忆 · Tool Calling"]
    PostgreSQL[("PostgreSQL<br/>PgVector · pg_trgm")]
    Redis[("Redis")]
    Neo4j[("Neo4j")]
    Models["模型 Provider<br/>仅允许 DeepSeek (对话) / Qwen (Embedding)"]

    Web -->|"HTTP / SSE"| Control
    Control -->|"gRPC"| Hermes
    Control --> PostgreSQL
    Control --> Redis
    Control --> Neo4j
    Control --> Models
    Hermes --> Redis
    Hermes --> Models

真实执行路径为：前端发起 HTTP/SSE 请求，控制面完成身份校验、会话持久化、模型与工具解析及 RAG 预检索，再通过 gRPC 调用 Hermes，最终把流式结果返回前端。

• qKnow 知识平台架构全景图
• qknow-hermes 认知与推理算法
• 并发混合检索策略
• 有向无环图 (DAG) 工作流图计算与路由算法
• 语义分块与图谱双路抽取策略流程图

• 本地使用 SDKMAN 管理的 Java 21（路径：/Users/achilles/.sdkman/candidates/java/21.0.5-tem），Maven 3.9+
• Node.js 18+、npm
• Mac 原生（Bare Metal）部署的 PostgreSQL 15+，需启用 PgVector 与 pg_trgm（绝对不是 Docker 容器）
• Mac 原生（Bare Metal）部署的 Redis 7+（绝对不是 Docker 容器）
• Docker 与 Docker Compose v2，仅用于本地 Neo4j

☕ Java 21 独立虚拟环境与主机系统隔离铁律（重要）：

• 项目唯一版本：本项目全模块统一锁定为 Java 21（父 POM java.version=21，qknow-common、qknow-ai 及 tests 均显式配置 Java 21）。
• SDKMAN 虚拟环境管理：本项目的 Java 21 通过 SDKMAN 单独管理在 /Users/achilles/.sdkman/candidates/java/21.0.5-tem，相当于本项目的虚拟化环境。
• 主机环境零污染原则：开发者的 Mac 主机全局环境保持为 Java 17。严禁任何 Agent 或开发者修改 Mac 本机全局系统 JDK，禁止篡改全局环境变量或软链接。
• 执行规范：所有 Maven 构建、测试或后端启动，必须且只能使用局部环境变量传参，例如：

  JAVA_HOME=/Users/achilles/.sdkman/candidates/java/21.0.5-tem mvn clean compile
  JAVA_HOME=/Users/achilles/.sdkman/candidates/java/21.0.5-tem mvn test -pl tests

警告：本地开发环境使用的是 Mac 原生部署的 PostgreSQL 与 Redis，严禁使用 Docker 启动这些核心数据库；根目录 docker-compose.yml 只允许启动 Neo4j。

git clone https://github.com/wssAchilles/Spring_Agent.git
cd Spring_Agent
cp .env.example .env

编辑 .env，至少补全 PostgreSQL、模型 API Key、RSA Key 与 TOKEN_SECRET，并补上当前模板缺少的 Neo4j 开发密码：

NEO4J_PASSWORD=neo4jpass123

当前启动脚本也使用这个本地默认值进行 Neo4j 健康检查。.env 只保存本地真实配置，不要提交密钥。

仅在首次创建全新的空数据库时执行以下初始化；不要对已有 ai_agent 数据库重复运行：

set -a
source .env
set +a

createdb -h 127.0.0.1 -U "$POSTGRESQL_USERNAME" ai_agent
psql -v ON_ERROR_STOP=1 -h 127.0.0.1 -U "$POSTGRESQL_USERNAME" -d ai_agent -f deploy/sql/postgresql/00-init-extensions.sql
psql -v ON_ERROR_STOP=1 -h 127.0.0.1 -U "$POSTGRESQL_USERNAME" -d ai_agent -f deploy/sql/postgresql/01-schema.sql
psql -v ON_ERROR_STOP=1 -h 127.0.0.1 -U "$POSTGRESQL_USERNAME" -d ai_agent -f deploy/sql/postgresql/02-init-data.sql

执行扩展初始化的 PostgreSQL 用户需要具备创建 vector 与 pg_trgm 扩展的权限。

bash scripts/start.sh

该脚本会编译后端并启动 Neo4j、Spring Boot 控制面、Hermes 与 Vite。它会清理同名开发容器，并释放 80、8099、9090 端口；运行前请确认这些端口没有承载其他服务。

另开终端查看状态或停止服务：

bash scripts/status.sh
bash scripts/stop.sh

需要分别调试服务时，先启动 Neo4j 并在每个终端加载 .env：

docker compose up -d neo4j
set -a
source .env
set +a

启动 Spring Boot 控制面：

cd backend
mvn -pl qknow-server -am spring-boot:run

启动 Hermes：

cd backend
mvn -pl qknow-hermes/qknow-hermes-starter -am spring-boot:run

启动前端：

cd frontend
npm install
npm run dev

后端测试：

cd backend
mvn -pl tests -am test

前端静态检查与生产构建：

cd frontend
npm run eslint:lint
npm run build:prod

脚本与服务状态检查：

bash -n scripts/start.sh scripts/status.sh scripts/stop.sh
bash scripts/status.sh

本地开发配置：

• PostgreSQL 使用 jdbc:postgresql://127.0.0.1:5432/ai_agent，凭据来自 POSTGRESQL_USERNAME 与 POSTGRESQL_PASSWORD。
• Redis 使用宿主机 127.0.0.1:6379。
• Neo4j 由根目录 Compose 启动，连接参数来自 Neo4j 相关配置。
• PostgreSQL 初始化与后续数据修正脚本位于 deploy/sql/postgresql/；00、01、02 仅用于全新空库，其余脚本应按文件头说明单独评估后执行。

deploy/docker/ 目录下的编排文件仅供生产环境或历史遗留参考，本地开发严禁依赖它们启动数据库。它仍包含上游遗留组件，但绝不应在本地开发流程中使用。

后端启动后访问 http://localhost:8099/swagger-ui.html。主要 API 分组：

本项目基于 qKnow 开源项目衍生。当前仓库没有统一的根级许可证文件：frontend/LICENSE 为 MIT，部分后端源码头声明 Apache License 2.0 并保留上游品牌与版权约束。使用、修改或再分发前，请按具体模块核对许可；不要将本 README 视为统一授权。