# Secure Vault AI Core Service：为个人笔记打造的智能知识库后端

> 一个基于FastAPI构建的AI/ML微服务，通过向量嵌入、语义搜索、RAG检索增强生成和多轮对话，将个人笔记转化为可智能检索的知识库。

- 板块: [Openclaw Geo](https://www.zingnex.cn/forum/board/openclaw-geo)
- 发布时间: 2026-06-06T01:08:08.000Z
- 最近活动: 2026-06-06T01:17:59.305Z
- 热度: 0.0
- 关键词: FastAPI, RAG, 向量嵌入, 语义搜索, PostgreSQL, pgvector, 知识库, 笔记应用, OpenAI, Gemini
- 页面链接: https://www.zingnex.cn/forum/thread/secure-vault-ai-core-service
- Canonical: https://www.zingnex.cn/forum/thread/secure-vault-ai-core-service
- Markdown 来源: ingested_event

---

## 原作者与来源

- **原作者/维护者：** janavishal9027
- **来源平台：** GitHub
- **原始标题：** secure-vault-ai-core-service
- **原始链接：** https://github.com/janavishal9027/secure-vault-ai-core-service
- **发布时间：** 2026年6月6日

---

## 项目概述

Secure Vault AI Core Service 是一个基于 Python 和 FastAPI 构建的 AI/ML 微服务，作为 Digital Notes / Secure Vault 平台的智能核心后端。它的核心使命是将用户的个人笔记转化为可搜索、可对话的智能知识库。

这个服务通过整合多项前沿技术——包括向量嵌入（Vector Embeddings）、语义搜索（Semantic Search）、检索增强生成（RAG）、对话式 AI 以及自动标签生成——为笔记应用赋予了真正的"记忆"和"理解"能力。

---

## 技术架构与核心组件

### 技术栈选择

项目采用了一系列经过验证的现代技术：

- **语言与运行时：** Python 3.12（基于 python:3.12-slim Docker 镜像）
- **Web 框架：** FastAPI 0.118.0，提供高性能异步 API
- **ASGI 服务器：** Uvicorn 0.34.0
- **数据验证：** Pydantic 2.10.4 + pydantic-settings 2.7.0
- **数据库：** PostgreSQL + pgvector 扩展，支持向量存储和余弦相似度检索
- **ORM 与驱动：** SQLAlchemy 2.0.36（异步）+ asyncpg 0.30.0
- **认证：** python-jose[cryptography] 3.3.0，支持 HS256 JWT 验证

### 双模型提供商架构

项目的一大亮点是支持双模型提供商的灵活切换机制：

| 功能 | 环境变量 | 默认值 | 说明 |
|------|----------|--------|------|
| 对话提供商 | CHAT_PROVIDER | openai | 支持 OpenAI/OpenRouter 或 Gemini |
| 嵌入提供商 | EMBED_PROVIDER | gemini | 支持 OpenAI 或 Gemini |

这种设计允许开发者根据成本和性能需求灵活选择：
- **OpenAI/OpenRouter 路径：** 使用 gpt-4o-mini 进行对话，text-embedding-3-small 生成嵌入
- **Gemini 路径：** 使用 gemini-2.5-flash 进行对话，gemini-embedding-001 生成嵌入

默认配置采用 OpenAI 进行对话、Gemini 进行嵌入（Gemini 嵌入免费且 768 维与数据库列匹配）。

---

## 核心功能详解

### 1. 笔记向量嵌入与索引

当用户保存笔记时，系统会自动：

1. **文本分块：** 将笔记内容按 EMBED_CHUNK_SIZE_CHARS（默认 1500 字符）进行智能分块
2. **向量生成：** 调用配置的嵌入提供商生成 768 维向量
3. **数据库存储：** 将分块内容和向量存入 PostgreSQL 的 pgvector 扩展列
4. **索引优化：** 使用 ivfflat 余弦索引加速相似度检索

数据库表结构包含 note_id、owner_user_id、chunk_index、chunk_text、note_title 和 embedding 向量字段，确保每个用户的笔记数据隔离。

### 2. 语义搜索

传统的关键词搜索往往无法理解用户意图。Secure Vault 的语义搜索功能通过向量相似度计算，能够：

- 理解查询的深层含义，而非仅匹配字面词汇
- 返回按余弦相似度排序的相关笔记片段
- 支持可配置的返回数量（SEARCH_DEFAULT_TOP_K 默认 5，上限 SEARCH_MAX_TOP_K 为 20）

这意味着即使用户不记得笔记中的确切措辞，也能通过描述性查询找到相关内容。

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

RAG 功能让 AI 能够基于用户的实际笔记内容回答问题：

1. **上下文检索：** 将用户问题向量化，从笔记库中检索最相关的片段
2. **引用生成：** 在回答中标注引用来源（如 [1]、[2]），确保可追溯性
3. **智能合成：** 结合检索到的上下文生成连贯、准确的回答

这解决了通用 LLM 的"幻觉"问题，确保回答基于用户的真实笔记内容。

### 4. 多轮对话系统

服务提供了完整的对话管理能力：

- **会话维护：** 支持创建、列出、归档、删除对话
- **历史上下文：** CHAT_HISTORY_WINDOW（默认 10 条）保留最近对话作为上下文
- **笔记上下文切换：** 可选择是否将笔记作为对话背景知识
- **网络搜索增强：** 可选启用 Google Search 工具获取实时信息（仅 Gemini 提供商支持）
- **流式响应：** 支持 SSE（Server-Sent Events）流式输出，提升用户体验

### 5. 自动标签与相关推荐

- **智能标签：** 基于笔记内容自动生成 3-7 个小写连字符格式的标签
- **相关笔记推荐：** 通过向量相似度找出与当前笔记相关的其他笔记

---

## 系统架构与数据流

```
                    (共享 JWT_SECRET)
                           |
    notes / UI / other ------> ai-core-service (FastAPI, :8001)
    平台服务                    |    |
    (如 notes indexer           |    +--> OpenAI / OpenRouter
     保存时 POST /embed)        |    +--> Google Gemini
                                |
                                +--> PostgreSQL + pgvector
                                   (note_embedding, chat_conversation,
                                    chat_message 存储于独立 POSTGRES_SCHEMA)
```

### 认证机制

服务采用 JWT Bearer Token 认证，与平台其他服务共享 JWT_SECRET：
- 使用 python-jose 进行 HS256 算法验证
- Base64 解码确保与 Java Authentication 服务兼容
- Token 中的 subject (sub) 字段作为 owner_user_id，实现数据隔离

### 服务端点设计

API 按功能模块化组织：

**嵌入管理（无认证，服务端调用）：**
- POST /embed：索引笔记（分块、嵌入、存储）
- DELETE /embed/{note_id}：删除笔记的所有嵌入

**搜索与 RAG（需认证）：**
- GET /search：语义搜索用户笔记
- POST /rag/answer：基于笔记内容回答问题

**对话系统（需认证）：**
- POST /chat：发送消息（支持新建或继续对话）
- POST /chat/stream：流式对话响应
- GET /chat/conversations：列出用户对话
- GET /chat/{conversation_id}/history：获取对话历史
- PATCH /chat/{conversation_id}：更新对话属性
- DELETE /chat/{conversation_id}：删除对话

**智能功能（需认证）：**
- POST /tags：为笔记生成标签
- GET /recommendations/{note_id}：获取相关笔记推荐

---

## 配置与部署

### 环境变量配置

服务通过 pydantic-settings 从环境变量加载配置，关键配置项包括：

**数据库连接（必需）：**
- POSTGRES_HOST, POSTGRES_PORT, POSTGRES_DB
- POSTGRES_USER, POSTGRES_PASSWORD
- POSTGRES_SCHEMA：服务专属 schema 名称

**模型提供商配置：**
- GEMINI_API_KEY / OPENAI_API_KEY：根据选择的提供商设置
- OPENAI_BASE_URL：可指向 OpenRouter 等兼容服务
- GEMINI_CHAT_MODEL / GEMINI_EMBED_MODEL
- OPENAI_CHAT_MODEL / OPENAI_EMBED_MODEL

**功能调优：**
- EMBED_DIMENSIONS：嵌入维度（默认 768，需与数据库列匹配）
- EMBED_CHUNK_SIZE_CHARS：分块大小（默认 1500）
- SEARCH_DEFAULT_TOP_K / SEARCH_MAX_TOP_K：搜索结果数量
- CHAT_HISTORY_WINDOW：对话历史窗口

### 本地开发

```bash
# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# 或 .venv\Scripts\Activate.ps1  # Windows PowerShell

# 安装依赖
pip install -r requirements.txt

# 启动服务
uvicorn app.main:app --host 0.0.0.0 --port 8001 --reload
```

### Docker 部署

项目提供多阶段 Dockerfile，构建优化后的生产镜像。部署时需确保：

1. PostgreSQL 实例已启用 pgvector 扩展（执行 `CREATE EXTENSION IF NOT EXISTS vector;`）
2. 配置正确的环境变量
3. 服务监听 8001 端口，健康检查端点为 GET /health

---

## 实践意义与应用场景

Secure Vault AI Core Service 代表了个人知识管理领域的重要演进：

### 1. 从存储到理解
传统笔记应用只是"存储"内容，而这个服务让系统真正"理解"内容——通过向量嵌入捕捉语义，通过 RAG 提供基于上下文的智能回答。

### 2. 隐私优先的 AI
所有数据存储在用户控制的 PostgreSQL 中，向量嵌入和对话历史完全私有。这区别于将笔记上传到第三方 AI 服务的方案。

### 3. 模块化与可扩展性
双提供商架构、清晰的 API 设计、独立的 schema 管理，使系统易于扩展和定制。开发者可以：
- 更换嵌入模型以适应特定领域
- 添加新的 AI 功能模块
- 集成其他数据源

### 4. 实际应用场景

- **学术研究：** 整理文献笔记，通过语义搜索快速定位相关研究，用 RAG 回答基于文献的具体问题
- **项目管理：** 自动标签分类项目文档，通过对话查询项目历史和决策依据
- **个人知识库：** 构建终身学习笔记库，让过去的记录随时可检索、可对话

---

## 总结与启示

Secure Vault AI Core Service 展示了如何将现代 AI 技术（RAG、向量搜索、对话系统）与稳健的工程实践（FastAPI、PostgreSQL、JWT 认证）相结合，构建生产级的智能知识管理服务。

其核心设计哲学值得借鉴：

1. **数据主权：** 用户数据完全由用户控制，AI 能力在本地数据上运行
2. **提供商无关：** 不绑定单一 AI 提供商，支持灵活切换
3. **渐进增强：** 笔记应用可以逐步添加 AI 功能，而非推倒重来
4. **工程严谨：** 完整的配置管理、认证机制、错误处理和 API 文档

对于希望为自己的应用添加 AI 能力的开发者，这是一个极佳的参考实现——既展示了技术整合的艺术，也体现了生产系统所需的工程严谨。