# vector-flow-demo

**Repository Path**: likaicodingcore/vector-flow-demo

## Basic Information

- **Project Name**: vector-flow-demo
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-19
- **Last Updated**: 2026-08-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# vector-flow-demo

文本模拟向量化与向量检索微服务。

模拟 Embedding 向量化（不调用 LLM / Embedding API），通过异步队列完成耗时向量化任务，
支持文档入库、Top-N 向量检索、文档元信息溯源统计与失效文档标记。

## 功能特性

- **模拟向量化**：固定 256 维 float 向量；同一文本多次向量化结果完全一致；空文本输出零向量
- **异步处理**：向量化耗时任务入自研队列，后台线程池消费，提交接口快速返回任务 ID
- **向量检索**：余弦相似度降序 Top-K，同步接口
- **文档管理**：入库、标记失效（失效文档不参与检索）、列表/详情查询
- **溯源统计**：每篇文档记录渠道、提交时间、完成时间、命中次数，检索命中自动计数
- **并发安全**：自研阻塞队列 + JPA 原子更新命中计数，多线程场景数据一致

## 技术栈

| 项 | 选型 |
|---|---|
| 语言 | Java 17+ |
| 框架 | Spring Boot 3.2 |
| 构建 | Maven |
| 基础库 | Guava、Apache Commons Lang3 |
| 数据库 | H2 嵌入式（**文件持久化**，重启保留数据） |
| 数据访问 | Spring Data JPA |
| 建表 | 随项目提供 `schema.sql`，启动自动建表 |
| 队列 | 项目自研 `SimpleBlockingQueue`（环形数组 + 锁） |

## 快速开始

### 环境要求

- JDK 17+
- Maven 3.8+

### 启动

```bash
mvn spring-boot:run
```

或打包后运行：

```bash
mvn clean package
java -jar target/vector-flow-demo-0.1.0.jar
```

启动后：

- 服务地址：http://localhost:8080
- H2 控制台：http://localhost:8080/h2-console（JDBC URL: `jdbc:h2:file:./data/vector-flow`，用户 `sa`，密码为空）
- 数据库文件：`./data/vector-flow.mv.db`（重启保留）

### 运行测试

```bash
mvn test
```

## 接口说明

### 1. 提交文档（异步向量化）

```
POST /api/documents
```

请求体：

```json
{
  "docId": "doc-001",
  "text": "机器学习与自然语言处理",
  "channel": "app"
}
```

- `channel` 可选，默认 `default`
- 响应 `202 Accepted`，返回任务 ID：

```json
{
  "taskId": "a1b2c3d4e5f6",
  "docId": "doc-001",
  "status": "QUEUED"
}
```

> 向量化完成前，该文档不会参与向量检索。

### 2. 查询任务状态

```
GET /api/documents/{docId}/task
```

响应：

```json
{
  "taskId": "a1b2c3d4e5f6",
  "docId": "doc-001",
  "status": "COMPLETED",
  "createdAt": "2026-08-19T13:00:00",
  "startedAt": "2026-08-19T13:00:00",
  "finishedAt": "2026-08-19T13:00:01",
  "document": {
    "id": "doc-001",
    "channel": "app",
    "vectorReady": true,
    "invalid": false,
    "submittedAt": "2026-08-19T13:00:00",
    "vectorizedAt": "2026-08-19T13:00:01",
    "hitCount": 0
  }
}
```

状态取值：`QUEUED`（排队中）/ `PROCESSING`（处理中）/ `COMPLETED`（完成）/ `FAILED`（失败）。

### 3. 向量检索（同步）

```
POST /api/search
```

请求体：

```json
{
  "query": "机器学习",
  "topK": 10,
  "channel": "app"
}
```

- `topK` 取值范围 1~100，默认 10
- `channel` 可选，按渠道过滤

响应（相似度降序）：

```json
{
  "query": "机器学习",
  "total": 2,
  "hits": [
    { "docId": "doc-001", "channel": "app", "score": 0.87 },
    { "docId": "doc-002", "channel": "app", "score": 0.72 }
  ]
}
```

### 4. 标记文档失效

```
POST /api/documents/{docId}/invalidate
```

失效后文档不再参与检索，历史元信息与统计保留。

### 5. 文档列表 / 详情

```
GET /api/documents?channel=app   # 列表（可按渠道过滤）
GET /api/documents/{docId}        # 详情
```

## 设计思路

### 模拟向量化算法

真实 Embedding 的特性是"相同文本输出稳定、语义相近向量接近"。本服务不调用外部 API，
采用**字符 n-gram 特征哈希**算法模拟：

1. 文本归一化（trim + 小写），保证同文本输出稳定
2. 提取字符 3-gram 作为特征
3. 每个 n-gram 经 Murmur3 哈希映射到 256 维向量的某个位置，按哈希符号位正负加权累加
4. L2 归一化，消除文本长度影响

特性：

- **确定性**：Murmur3 无随机源，同一文本输出完全一致
- **空文本 → 零向量**：归一化后为空则直接返回全 0 数组
- **相似文本接近**：相同/重叠 n-gram 越多，余弦相似度越高（字符级近似，非真实语义）

### 自研队列

项目约定不引入外部消息中间件，因此自研 `SimpleBlockingQueue`：

- 环形数组存储，容量可配置（默认 1024）
- `ReentrantLock` + 两个 `Condition`（notFull / notEmpty）实现满时阻塞入队、空时阻塞出队
- 支持 `put`（阻塞）/ `offer(timeout)`（限时）/ `take`（阻塞）/ `poll(timeout)`（限时）
- 服务启动时创建固定数量（默认 4）消费者线程，常驻后台消费任务

### 并发安全设计

| 场景 | 方案 |
|---|---|
| 队列读写 | 自研阻塞队列内部锁保证原子性 |
| 任务状态流转 | 单线程消费者处理，无并发写冲突 |
| 命中计数递增 | JPA `@Modifying UPDATE ... hitCount = hitCount + 1` 原子递增 |
| 重复文档 ID | 入库前 `existsById` 校验，拒绝重复提交 |

### 数据持久化

- H2 文件模式 `jdbc:h2:file:./data/vector-flow`，服务重启后数据保留
- 表结构由 `schema.sql` 定义，启动时自动执行（`spring.sql.init.mode=always`）
- JPA `ddl-auto: none`，避免与 DDL 脚本冲突

## 目录结构

```
src/main/java/com/vectorflow/demo
├── VectorFlowApplication.java    # 启动入口
├── config/                       # 配置（队列 Bean）
├── controller/                   # REST 接口 + 全局异常处理
├── dto/                          # 请求/响应对象
├── entity/                       # JPA 实体（document / vectorization_task）
├── queue/                        # 自研阻塞队列
├── repository/                   # Spring Data JPA 仓库
├── service/                      # 业务服务（入库/检索/消费者）
└── vectorize/                    # 向量化算法 + 相似度 + 序列化
src/main/resources
├── application.yml               # 配置（H2 文件模式、队列参数）
└── schema.sql                    # 建表 DDL
```

## Git 提交规范

本仓库遵循 Conventional Commits（约定式提交），提交信息主体使用中文：

```
feat(queue): 添加内存阻塞队列实现
fix(search): 从 top-k 结果中排除失效文档
```

详见 `CLAUDE.md` 项目约定。