# Api Agent Core

**Repository Path**: mrwhitebare/api-agent-core

## Basic Information

- **Project Name**: Api Agent Core
- **Description**: 基于 NestJS 11 的向量检索后端服务，使用 Ollama（本地大模型）将文本转换为向量，并存储到 Qdrant 向量数据库中进行相似度检索。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-12
- **Last Updated**: 2026-09-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# api-agent-core

基于 NestJS 11 的向量检索后端服务，使用 Ollama（本地大模型）将文本转换为向量，并存储到 Qdrant 向量数据库中进行相似度检索。

## 技术栈

- **NestJS 11** — Node.js 框架
- **TypeScript** — 类型安全
- **LangChain** — AI 应用框架
- **Ollama** — 本地大模型推理
- **Qdrant** — 向量数据库
- **SQLite** — 本地数据存储（Drizzle ORM）
- **Swagger** — API 文档

## 项目结构

```
src/
├── app.module.ts                     # 根模块
├── app.controller.ts                 # 根控制器
├── app.service.ts                    # 根服务
├── main.ts                           # 入口文件
├── config/                           # 配置相关
│   ├── configuration.ts              # 配置聚合
│   ├── qdrant.config.ts              # Qdrant 配置
│   └── embedding.config.ts           # Embedding 配置
├── sqlite/                           # SQLite 数据库（Drizzle ORM）
│   ├── sqlite.module.ts              # SQLite 模块
│   ├── sqlite.service.ts             # SQLite 服务
│   ├── sqlite.constants.ts           # 常量
│   └── schema.ts                     # 表结构定义（Drizzle）
├── embedding/                        # 向量生成模块
│   ├── embedding.module.ts           # Embedding 模块
│   ├── embedding.controller.ts       # Embedding 控制器
│   ├── embedding.service.ts          # Embedding 服务
│   └── dto/                          # DTO
├── qdrant/                           # Qdrant 向量数据库模块
│   ├── qdrant.module.ts              # Qdrant 模块
│   ├── qdrant.controller.ts          # Qdrant 控制器
│   ├── qdrant.service.ts             # Qdrant 服务
│   ├── qdrant.constants.ts           # 常量
│   └── dto/                          # DTO
├── knowledgebase/                    # 知识库模块
│   ├── knowledgebase.module.ts       # 模块
│   ├── knowledgebase.controller.ts   # 控制器
│   ├── knowledgebase.service.ts      # 服务
│   └── dto/                          # DTO
└── rag/                              # RAG 检索模块
    ├── rag.module.ts                 # 模块
    ├── rag.controller.ts             # 控制器
    ├── rag.service.ts                # 服务
    └── rag.dto.ts                    # DTO
```

## 安装与运行

```bash
# 安装依赖
pnpm install

# 开发模式
pnpm run start:dev

# 调试模式
pnpm run start:debug

# 生产模式
pnpm run start:prod
```

## 数据库（Drizzle ORM）

本项目使用 **Drizzle ORM** 管理 SQLite 数据库。

### 表结构定义

```typescript
// src/sqlite/schema.ts
import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core';

export const conversation = sqliteTable('conversation', {
  id: text('id').primaryKey(),
  userId: text('user_id'),
  createdAt: text('created_at').default('CURRENT_TIMESTAMP'),
  updatedAt: text('updated_at').default('CURRENT_TIMESTAMP'),
});

export const message = sqliteTable('message', {
  id: integer('id', { autoIncrement: true }).primaryKey(),
  conversationId: text('conversation_id').notNull(),
  role: text('role').notNull(),
  content: text('content').notNull(),
  createdAt: text('created_at').default('CURRENT_TIMESTAMP'),
});
```

### Drizzle CLI 命令

```bash
# 生成迁移文件（对比 schema 和数据库差异）
pnpm db:generate

# 推送 schema 到数据库（开发用，生产推荐 migrate）
pnpm db:push

# 启动 Studio 可视化数据库（Web UI）
pnpm db:studio
```

### 添加新表

1. 在 `src/sqlite/schema.ts` 中定义新表结构
2. 导出表类型
3. 运行 `pnpm db:generate` 生成迁移文件
4. 运行 `pnpm db:push` 推送 schema 到数据库

## API 端点

### Embedding（向量生成）

| 方法 | 路径                    | 说明             |
| ---- | ----------------------- | ---------------- |
| POST | `/embedding/generate` | 将文本转换为向量 |

### Qdrant（向量数据库）

| 方法   | 路径                             | 说明                               |
| ------ | -------------------------------- | ---------------------------------- |
| POST   | `/qdrant/collection`           | 创建向量集合                       |
| GET    | `/qdrant/collections`          | 获取所有集合列表                   |
| POST   | `/qdrant/points`               | 添加/更新向量数据                  |
| POST   | `/qdrant/save-text`            | 文本自动转向量并存入 Qdrant        |
| POST   | `/qdrant/save-text-batch`      | 批量文本转向量                     |
| POST   | `/qdrant/search`               | 向量相似度检索                     |
| DELETE | `/qdrant/collection`           | 删除向量集合                       |
| POST   | `/qdrant/import/markdown`      | 导入 Markdown 文本（自动切块）     |
| POST   | `/qdrant/import/markdown-file` | 上传 .md 文件并导入                |
| POST   | `/qdrant/import/swagger`       | 导入 Swagger JSON（提炼 API 接口） |

### RAG（检索增强生成）

| 方法 | 路径           | 说明         |
| ---- | -------------- | ------------ |
| POST | `/rag/query` | RAG 查询流程 |

### 其他

| 方法 | 路径     | 说明            |
| ---- | -------- | --------------- |
| GET  | `/`    | 健康检查        |
| GET  | `/api` | Swagger UI 文档 |

## 配置

### Embedding 配置

```yaml
# config/embedding-config.yml
ollama:
  baseUrl: http://localhost:11434
  model: nomic-embed-text
  dimensions: 768
```

### Qdrant 配置

```yaml
# config/qdrant-config.yml
qdrant:
  url: http://localhost:6333
  apiKey: your-api-key
```

## 开发指南

### 添加新表

1. 在 `src/sqlite/schema.ts` 中定义新表结构
2. 导出表类型
3. 运行 `pnpm db:generate` 生成迁移文件
4. 运行 `pnpm db:push` 推送 schema 到数据库

### 常用 Drizzle 操作

```typescript
import { eq } from 'drizzle-orm';

// 查询
const users = await db.select().from(users).where(eq(users.id, 1));

// 插入
await db.insert(users).values({ name: 'Alice' });

// 更新
await db.update(users).set({ name: 'Bob' }).where(eq(users.id, 1));

// 删除
await db.delete(users).where(eq(users.id, 1));
```

## 常用命令

```bash
# 安装依赖
pnpm install

# 开发模式（监听文件变化）
pnpm run start:dev

# 调试模式
pnpm run start:debug

# 生产模式
pnpm run start:prod

# 构建
pnpm run build

# 代码格式化
pnpm run format

# ESLint 检查并自动修复
pnpm run lint

# 单元测试
pnpm run test

# 单元测试（监听模式）
pnpm run test:watch

# 测试覆盖率
pnpm run test:cov

# E2E 测试
pnpm run test:e2e
```

## RSA密钥对生成

```
mkdir -p config/jws
openssl genpkey -algorithm RSA -out config/jws/private.key -pkeyopt rsa_keygen_bits:2048
openssl rsa -pubout -in config/jws/private.key -out config/jws/public.key
chmod 600 config/jws/private.key
chmod 644 config/jws/public.key
echo "✅ RSA 密钥对已生成：config/jws/private.key（私钥）与 config/jws/public.key（公钥）"
```

## 许可证

UNLICENSED