# mag

**Repository Path**: gcpaas/mag

## Basic Information

- **Project Name**: mag
- **Description**: 是一款以业务指标知识为核心、兼顾企业通用知识管理的开源项目，面向业务人员、数据分析师、产品及数据治理等人员，支持多种文档导入及知识自动解析，提供知识库管理、向量检索、关联检索、原文引用和知识问答等能力，可统一沉淀指标口径、技术文档、制度资料及项目知识，帮助企业提升知识检索与复用效率。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-22
- **Last Updated**: 2026-09-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MAG 指标知识库

[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Java 17](https://img.shields.io/badge/Java-17-blue.svg)](backend/pom.xml)
[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.3-brightgreen.svg)](backend/pom.xml)
[![Vue 2](https://img.shields.io/badge/Vue-2.7-42b883.svg)](frontend/package.json)

[English](README.en.md) | 简体中文

MAG（Metric-Augmented Generation）是一个专门面向业务指标、统计口径和数据知识管理的轻量开源项目。它参考上游 SAG 的 event-entity 索引与多路检索思想，将指标文档转换为可检索、可关联、可追溯的结构化知识。

当前版本适合本地体验、团队内网部署和二次开发。项目不依赖原业务平台，也不包含登录、权限、多租户或指标审批流程；部署到共享环境时，需要在网关层补充认证和访问控制。

项目包含：

- Java 17 + Spring Boot 后端
- PostgreSQL + pgvector 正式向量检索，SQLite 小数据演示模式
- Vue 2 + JavaScript + Vite 前端
- 文档导入、指标事件/实体抽取、向量检索、知识问答、模型配置、原文与图片引用

项目面向本地单机和轻量自托管场景，不包含登录、租户和权限体系。它支持 OpenAI 兼容的 Embedding 与 Chat Completions 接口，以及 Cohere/Jina 风格的 Rerank 接口。模型既可通过页面保存，也可通过环境变量提供默认值；API Key 只写入本地数据库且不会由接口回显。

## 用户群体与使用场景

| 用户群体 | 典型场景 |
| --- | --- |
| 业务人员 | 查询指标定义、计算口径、公式、统计粒度和业务解释 |
| 数据分析师 | 从指标手册、需求文档和报表说明中快速定位可信依据 |
| 数据治理人员 | 统一沉淀指标名称、维度、单位、来源和关联业务术语 |
| 产品与研发人员 | 检索产品手册、技术方案、制度资料和项目知识 |
| AI/Agent 开发者 | 通过 REST API 获取带原文和图片引用的知识证据 |

MAG 适合建设指标口径库、企业制度库、产品手册库、项目文档库和面向 Agent 的本地知识服务。当前版本强调“导入、索引、检索、问答、证据追溯”的完整闭环，而不是通用内容管理或权限平台。

## 功能概览

- TXT、Markdown、PDF、DOC、DOCX、CSV、JSON、XML、HTML、LOG 导入。
- 文档分块、指标事件抽取、指标/公式/单位/粒度/维度/数据源等实体提取。
- pgvector HNSW 向量检索、事件增强检索和可选 Rerank。
- 基于知识证据的多轮问答，支持 Markdown、原文引用和文档图片展示。
- Embedding、Chat、Rerank 模型页面配置与连通性测试。
- PostgreSQL 正式模式与 SQLite 小数据演示模式。

## 工作流程

```mermaid
flowchart LR
    A[导入文档] --> B[解析文本与图片]
    B --> C[分块]
    C --> D[事件与实体抽取]
    C --> E[Embedding 向量化]
    D --> F[(PostgreSQL / SQLite)]
    E --> F
    F --> G[向量与关联检索]
    G --> H[Chat 生成带引用回答]
    H --> I[原文与图片证据]
```

## 快速启动

环境要求：Java 17+、Maven 3.8+、Node.js 18+；推荐使用 Node.js 20 LTS。Node.js 10 不支持当前 Vite 构建链。

默认启用 PostgreSQL 16 + pgvector。以下命令会启动一个仅用于本地开发的数据库：

```powershell
git clone https://gitee.com/gcpaas/mag.git
cd mag
docker compose up -d
cd backend
mvn spring-boot:run
```

另开终端：

```powershell
cd frontend
npm install
npm run dev
```

打开 `http://localhost:5175`。

后端默认地址为 `http://localhost:8091`。打开“模型设置”填写 Embedding、Chat、Rerank 地址和模型名，再到“知识库”导入文档，最后在“知识问答”中选择知识库提问。
默认连接 `jdbc:postgresql://localhost:5432/mag?currentSchema=public`，用户名为 `mag`，本地开发密码为 `mag-local-dev`，与 `docker-compose.yml` 一致。该密码仅用于本机快速启动，部署到共享环境前必须修改。
开发时如后端改用其他端口，可通过 `SERVER_PORT` 修改后端端口，并在前端启动前设置相同目标，例如 `$env:MAG_API_TARGET="http://localhost:8092"`。

使用已有 PostgreSQL 或自定义 schema 时，通过环境变量覆盖配置。例如 pgvector 扩展安装在 `public`、业务表放在 `mag_app`：

```powershell
$env:MAG_DB_URL="jdbc:postgresql://localhost:5432/mag?currentSchema=mag_app,public"
$env:MAG_DB_USERNAME="mag_app"
$env:MAG_DB_PASSWORD="change-me"
```

`currentSchema` 中应把业务 schema 放在前面，把 pgvector 扩展所在 schema 放在后面。Spring Boot 不会自动读取 `.env`，`.env.example` 仅作为变量清单。

只想使用 SQLite 体验页面和流程时，将 `application.yml` 中的默认值 `pgvector` 改为 `sqlite`，或启动前设置 `$env:MAG_STORAGE_PROFILE="sqlite"`。SQLite 使用 `data/mag.db`，把向量保存为文本并由 Java 全量计算余弦相似度，仅适合少量文档演示。

## 模型配置

正式使用至少配置 Embedding 和 Chat，Rerank 可选。可直接使用前端“模型设置”页面；环境变量仍可作为初始默认值。`.env.example` 是变量模板，Spring Boot 不会自动加载该文件。

```powershell
$env:MAG_EMBEDDING_BASE_URL="https://embedding.example.com/v1"
$env:MAG_EMBEDDING_API_KEY="<your-api-key>"
$env:MAG_EMBEDDING_MODEL="your-embedding-model"

$env:MAG_LLM_BASE_URL="https://chat.example.com/v1"
$env:MAG_LLM_API_KEY="<your-api-key>"
$env:MAG_LLM_MODEL="your-chat-model"

$env:MAG_RERANK_BASE_URL="https://rerank.example.com/v1"
$env:MAG_RERANK_API_KEY="<your-api-key>"
$env:MAG_RERANK_MODEL="your-rerank-model"
```

| 模型 | 是否必需 | 用途 | 兼容接口 |
| --- | --- | --- | --- |
| Embedding | 正式使用必需 | 文档、实体和查询向量化 | `POST /embeddings` |
| Chat | 建议配置 | 抽取指标、公式、单位、粒度、维度和数据来源；理解检索问题 | `POST /chat/completions` |
| Rerank | 可选 | 对 `multi` 模式候选证据重新排序 | `POST /rerank` |

模型地址填写 API 根路径，MAG 会自动追加接口路径。例如填写 `https://api.example.com/v1`，系统将调用 `/v1/embeddings` 和 `/v1/chat/completions`。不要把完整的 `/chat/completions` 再填入 Base URL，否则通常会得到 404。

默认 `MAG_MODEL_FALLBACK_ENABLED=true`，模型超时或返回异常时自动使用本地能力。需要严格验证模型调用时设置为 `false`。更换 Embedding 模型、API Key 或向量维度后，在知识库页面选择旧文档并点击“重新索引”，也可以从知识库菜单执行“重新索引全部”。系统会重新拆分原文，并重建事件、实体和向量。完整配置说明见 [`docs/model-config.md`](docs/model-config.md)。

MAG 只在同一 Embedding provider 和相同向量维度内进行向量比较。旧文档如果显示为 `local-hash`，而当前查询使用远程 Embedding，系统仍可通过指标名称和实体关联进行精确召回，但不会把两种不兼容的向量混合计算。要获得完整语义检索能力，请使用当前 Embedding 配置重新索引旧文档。

`MAG_EMBEDDING_DIMENSION` 必须与 Embedding 服务实际返回维度一致。默认值 `1024` 适配常见的 `bge-m3`；OpenAI `text-embedding-3-small` 常用 `1536`，切换时应在启动前修改该变量。pgvector 会按此维度建立 HNSW 余弦索引。

## 构建

```powershell
cd frontend
npm run build

cd ..\backend
mvn clean package
java -jar target/mag-0.1.0.jar
```

生产构建后的前端文件默认输出到 `frontend/dist`。开发阶段由 Vite 代理 `/api` 到后端；单 JAR 托管前端文件的配置留作下一步工作，当前可以分别启动前后端。

## 数据库初始化与升级

Spring Boot 启动时会执行与当前存储模式匹配的初始化 SQL。需要人工审查、受控部署或已有数据库升级时，可使用 `scripts/db/` 中的脚本：

| 脚本 | 用途 |
| --- | --- |
| `scripts/db/postgresql/V001__init.sql` | 创建 PostgreSQL + pgvector 全量表结构 |
| `scripts/db/postgresql/V002__index_metadata.sql` | 增加索引元数据和 HNSW 索引 |
| `scripts/db/postgresql/V003__document_images.sql` | 增加文档图片及切片关联 |
| `scripts/db/sqlite/V001__init.sql` | 创建 SQLite 演示库 |
| `scripts/db/sqlite/V002__index_metadata.sql` | 增加 SQLite 索引元数据 |
| `scripts/db/sqlite/V003__document_images.sql` | 增加 SQLite 图片元数据 |

PostgreSQL 新库通常直接启动应用即可完成初始化。已有库执行升级脚本前应先备份，并确认目标 schema、向量维度和脚本版本。详细说明见 [`scripts/db/README.md`](scripts/db/README.md)。

## 技术架构

| 层级 | 技术 |
| --- | --- |
| 前端 | Vue 2.7、JavaScript、Vite、Element UI |
| 后端 | Java 17、Spring Boot 3.3、Spring JDBC |
| 文档解析 | Apache PDFBox、Apache POI |
| 向量存储 | PostgreSQL + pgvector；SQLite 演示模式 |
| 模型协议 | OpenAI-compatible Embedding/Chat，Cohere/Jina-style Rerank |

详细设计见 [`docs/architecture.md`](docs/architecture.md)，接口说明见 [`docs/api.md`](docs/api.md)，模型配置见 [`docs/model-config.md`](docs/model-config.md)。

## 工程结构

```text
mag/
├─ backend/                    Spring Boot REST 服务
│  └─ src/main/java/org/mag/  MAG 后端源码
├─ frontend/                   Vue 2 + JavaScript 工作台
│  └─ src/views/               知识库、知识问答、模型设置页面
├─ docs/                       架构、API 与模型配置文档
├─ scripts/db/                 SQLite、PostgreSQL 初始化与升级 DDL
├─ examples/documents/         指标文档示例
├─ docker-compose.yml          PostgreSQL + pgvector
├─ .env.example                模型环境变量模板
└─ README.md
```

## 核心能力

1. 创建、删除知识库。
2. 导入 TXT、Markdown、PDF、DOC、DOCX、CSV、JSON、XML、HTML、LOG。
3. 在导入窗口确认文件后，同步执行原文解析、标题和段落分块、事件实体抽取与向量化；大文档可能需要数分钟。
4. 切片和去重后的实体采用批量 Embedding，减少远程模型请求次数。
5. 配置模型后，为每个块生成语义向量，并抽取指标、公式、单位、粒度、维度、数据来源等实体。
6. `vector` 检索返回相似原文块。
7. `multi` 检索使用 LLM 查询理解、事件语义和可选 Rerank 返回原文证据。
8. 提取 DOCX、PDF 中的内嵌图片，将图片与文档切片关联并保存到 `data/images/`。
9. 以检索结果为上下文回答指标问题，并返回编号引用、原文证据和相关图片。
10. 在页面配置并测试 Embedding、Chat、Rerank 服务。
11. 浏览文档、事件、实体和检索分数。

## API

| 方法 | 地址 | 说明 |
| --- | --- | --- |
| GET | `/api/system/capabilities` | 查看模型是否配置，不返回密钥 |
| GET/PUT | `/api/settings/models` | 读取或保存模型设置，密钥不回显 |
| POST | `/api/settings/models/test` | 测试指定模型连接 |
| POST | `/api/chat/ask` | 基于知识库证据进行带引用问答 |
| GET | `/api/images/{id}` | 内联读取文档图片 |
| GET | `/api/sources` | 知识库列表 |
| POST | `/api/sources` | 创建知识库，JSON: `name`, `description` |
| PUT | `/api/sources/{id}` | 编辑知识库，JSON: `name`, `description` |
| DELETE | `/api/sources/{id}` | 删除知识库及其文档 |
| GET | `/api/sources/{id}/workspace` | 获取工作区 |
| POST | `/api/sources/{id}/documents/file` | multipart 上传文件 |
| POST | `/api/sources/{id}/documents/text` | JSON: `title`, `content` |
| POST | `/api/sources/{id}/reindex` | 使用当前模型配置重建知识库全部索引 |
| POST | `/api/documents/{id}/reindex` | 使用当前模型配置重建单个文档索引 |
| DELETE | `/api/documents/{id}` | 删除文档 |
| POST | `/api/search` | JSON: `query`, `sourceIds`, `strategy`, `topK` |
| GET | `/api/events/{id}` | 获取事件详情 |

示例：

```json
{
  "query": "活跃客户的统计口径",
  "sourceIds": ["source-id"],
  "strategy": "multi",
  "topK": 5
}
```

问答示例：

```json
{
  "question": "验收节点及时率的计算口径是什么？",
  "sourceIds": ["source-id"],
  "topK": 5,
  "history": []
}
```

## 存储模式

| 模式 | 启动方式 | 向量检索 | 适用场景 |
| --- | --- | --- | --- |
| pgvector（推荐） | `MAG_STORAGE_PROFILE=pgvector` | PostgreSQL 距离排序 + HNSW | 正式使用、较多文档、并发查询 |
| sqlite-demo | `MAG_STORAGE_PROFILE=sqlite` | Java 内存全量余弦计算 | 功能体验、单元测试、小样本 |

## 运行边界

- 未配置模型时的本地哈希向量只适合演示，不代表真实语义检索质量。
- 已导入文档不会因模型配置变化自动重建；页面会显示 `remote`、`local-hash` 和向量维度，请主动执行重新索引。
- 图片抽取从当前版本开始生效。升级前已导入的 DOCX/PDF 没有保存原始图片二进制，需要删除后重新导入；仅点击“重新索引”无法恢复旧图片。
- 图片元数据保存在 `mag_images`，文件保存在 `${MAG_DATA_DIR}/images/<sourceId>/<documentId>/`。已有数据库可执行 `scripts/db/postgresql/V003__document_images.sql`，正常启动时也会由 Spring SQL 初始化自动补表。
- Chat 抽取围绕指标名称、业务口径、公式、单位、粒度、维度和数据来源组织 event-entity 索引。
- Rerank 协议没有统一的 OpenAI 标准，当前支持常见的 Cohere/Jina 请求与响应结构。
- OCR、MCP 和指标版本审批暂未包含。
- 归档、权限、多租户、数据源连接、SQL 执行和指标版本治理不在当前范围。
- MAG 是本项目的独立名称，不是上游 SAG 项目的官方改名或官方发行版。
- 当前版本聚焦“导入、索引、检索、问答、原文证据”主链路；MCP 可后续作为同一服务层的薄适配器加入。

## 常见问题

### 模型测试返回 404

确认 Base URL 是服务根路径，而不是完整接口地址，并检查服务实际使用 `/v1/embeddings`、`/v1/chat/completions` 或 `/rerank` 中的哪一种协议。不同厂商的 Rerank 协议并不统一。

### PostgreSQL 启动提示找不到 `vector_dims`

业务 schema 与 pgvector 扩展不在同一 schema 时，将两者都加入 `currentSchema`，例如 `currentSchema=mag_app,public`。当前代码的索引过滤使用 `embedding_dimension` 字段，不再依赖 `vector_dims()`。

### 明明导入了指标，问答却没有命中

先在知识库文档列表检查 `embedding_provider` 和 `embedding_dimension`。如果旧文档是 `local-hash`，当前模型配置是远程 Embedding，请执行“重新索引”。MAG 不会混合比较不同 provider 的向量；指标名称精确匹配仍可召回，但改写、同义表达等语义检索依赖重新生成远程向量。

### 问答没有展示文档图片

图片抽取只对升级后重新导入的 DOCX/PDF 生效。旧数据只保存了文本，删除旧文档并重新导入后才会生成 `mag_images` 记录和本地图片文件。

### 导入速度较慢

导入同步执行解析、分块、事件实体抽取和向量化。远程模型延迟、文档切片数和实体数量都会影响耗时；Embedding 已按批次调用，但大文档仍可能需要数分钟。

## 安全与部署

MAG 没有内置认证和权限控制，不应直接暴露到公网。生产环境应通过网关或反向代理增加 TLS、认证、访问控制和请求大小限制，并保护数据库、`data/` 目录及备份。详见 [`SECURITY.md`](SECURITY.md)。

模型设置页面保存的 API Key 会进入 `mag_model_settings`。因此数据库文件、数据库备份和生产数据导出均属于敏感资料，不应作为示例数据提交。

## 开源发布前检查

项目提供了一键发布验证脚本：

```powershell
pwsh -File scripts/verify-release.ps1
```

该脚本会执行隐私检查、后端测试和前端生产构建。隐私检查覆盖常见密钥形态、非占位敏感配置、个人绝对路径、内网 IP，以及 Git 中误跟踪的数据库、日志、构建产物和本地配置，并且不会输出疑似密钥原值。只执行隐私检查时可运行：

```powershell
pwsh -File scripts/check-publication.ps1
```

完整清单见 [`docs/release-checklist.md`](docs/release-checklist.md)。`.gitignore` 已排除 `data/`、`logs/`、`.idea/`、`node_modules/`、`target/`、`dist/`、本地 `.env`、数据库文件和常见证书文件，但仓库所有者仍应在首次推送前人工检查暂存区。

## 参与贡献

请阅读 [`CONTRIBUTING.md`](CONTRIBUTING.md)。提交前至少运行：

```powershell
cd backend
mvn test

cd ..\frontend
npm run build
```

版本变化记录见 [`CHANGELOG.md`](CHANGELOG.md)。

## 来源

MAG 以独立 Java/Vue 工程重新实现，不依赖原业务平台的用户、租户、模型注册、MyBatis、图数据库或 AgentScope 体系。

算法与产品思路参考 MIT License 的上游 SAG：<https://github.com/Zleap-AI/SAG>。发布者仍应按自身组织要求完成项目名称、商标和依赖许可证审查。

第三方和上游说明见 [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md)。本项目使用 [MIT License](LICENSE)。MAG 是独立项目，不是 SAG 的官方发行版或官方改名。