章节 01
导读 / 主楼：Secure Vault AI Core Service：为个人笔记打造的智能知识库后端
原作者与来源
- 原作者/维护者： 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. 笔记向量嵌入与索引
当用户保存笔记时，系统会自动：
- 文本分块： 将笔记内容按 EMBED_CHUNK_SIZE_CHARS（默认 1500 字符）进行智能分块
- 向量生成： 调用配置的嵌入提供商生成 768 维向量
- 数据库存储： 将分块内容和向量存入 PostgreSQL 的 pgvector 扩展列
- 索引优化： 使用 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]），确保可追溯性
- 智能合成： 结合检索到的上下文生成连贯、准确的回答
这解决了通用 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：对话历史窗口
本地开发
# 创建虚拟环境
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，构建优化后的生产镜像。部署时需确保：
- PostgreSQL 实例已启用 pgvector 扩展（执行
CREATE EXTENSION IF NOT EXISTS vector;） - 配置正确的环境变量
- 服务监听 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 认证）相结合，构建生产级的智能知识管理服务。
其核心设计哲学值得借鉴：
- 数据主权： 用户数据完全由用户控制，AI 能力在本地数据上运行
- 提供商无关： 不绑定单一 AI 提供商，支持灵活切换
- 渐进增强： 笔记应用可以逐步添加 AI 功能，而非推倒重来
- 工程严谨： 完整的配置管理、认证机制、错误处理和 API 文档
对于希望为自己的应用添加 AI 能力的开发者，这是一个极佳的参考实现——既展示了技术整合的艺术，也体现了生产系统所需的工程严谨。
