Vector Database

一个高效的向量相似度搜索引擎和向量数据库系统，支持多种文件类型的处理、向量嵌入、存储和检索。

功能特性

• 多文件类型支持：文本（txt/md/docx/pdf）、图像（jpg/png/bmp）、视频（mp4/avi/mov）、音频（mp3/wav）
• 多向量数据库后端：FAISS、HNSWlib、Annoy
• 多元数据存储后端：MySQL、Redis、MongoDB
• 多文件存储后端：本地文件系统、S3、数据库
• RESTful API（FastAPI）
• JWT + API Key 双重认证
• 跨进程共享缓存（Redis）
• 跨进程速率限制（Redis）
• 多进程安全的 FAISS 文件锁
• 自动备份与恢复
• 本地模型自动下载（支持国内镜像）

项目结构

vector_db/
├── api/
│ └── main.py # FastAPI 入口，所有 REST 端点
├── config/
│ ├── config.py # 配置管理（读取 .env）
│ └── .env.example # 配置模板
├── core/
│ ├── backup/ # 备份与恢复
│ ├── cache/ # LRU 缓存（内存 / Redis）
│ ├── llm/ # LLM 接口（本地 transformers / 远程 OpenAI 兼容）
│ ├── logging/ # 日志管理
│ ├── model_manager.py # 模型下载与生命周期管理
│ ├── processors/ # 文本 / 图像 / 视频 / 音频处理器
│ ├── readers/ # 文件读取器
│ ├── security/ # JWT 认证 + AES-256 加密
│ ├── storage/ # 文件存储 + 元数据存储实现
│ ├── utils/ # 并行处理工具
│ ├── vector_db/ # FAISS / HNSW / Annoy 向量数据库实现
│ └── data_flow.py # 核心数据流程编排
├── data/ # 运行时数据（向量索引、文件、备份）
├── models/ # 本地模型缓存
├── tests/
│ ├── unit_tests/ # 单元测试
│ └── load_test.py # Locust 压力测试
├── requirements.txt
└── main.py # 直接运行入口

快速开始

1. 安装依赖

pip install -r requirements.txt

2. 配置环境变量

cp config/.env.example .env

编辑 .env，至少修改以下项：

API_SECRET_KEY=your-secret-key# 必须修改API_KEY=your-initial-api-key# 初始 API Key# 向量数据库VECTOR_DB_TYPE=faiss# faiss | hnsw | annoyVECTOR_DB_PATH=./data/vector_db# 元数据存储METADATA_STORAGE_TYPE=mysql# mysql | redis | mongodbMYSQL_HOST=localhostMYSQL_USER=rootMYSQL_PASSWORD=your-passwordMYSQL_DATABASE=vector_db# 缓存（单进程用 memory，多进程用 redis）CACHE_BACKEND=memory# memory | redis

3. 启动服务

# 开发模式（TEST_MODE 跳过真实模型加载）
TEST_MODE=true uvicorn api.main:app --host 0.0.0.0 --port 8001 --reload
# 生产模式（单进程）
uvicorn api.main:app --host 0.0.0.0 --port 8001
# 生产模式（多进程，需要 Redis）
CACHE_BACKEND=redis uvicorn api.main:app --host 0.0.0.0 --port 8001 --workers 4

Python 客户端使用

项目提供了 Python SDK，简化 API 调用：

fromclientimportVectorDBClient# 初始化客户端client=VectorDBClient(
base_url="http://localhost:8001",
api_key="your-api-key"
)
# 上传文件并向量化result=client.upload_file(
file_path="./document.pdf",
collection_id="my_collection"
)
print(f"处理了 {result['chunks_processed']} 个分块")
# 文本搜索text_result=client.process_text("查询文本")
search_results=client.search_vectors(
collection_id="my_collection",
query_vector=text_result['embedding'],
top_k=5
)
forresinsearch_results:
print(f"相似度: {res['score']}, 文件: {res['metadata']['file_id']}")

完整示例见 client/example.py

API 文档

启动后访问 http://localhost:8001/docs 查看交互式 Swagger 文档。

认证

所有需要认证的端点支持两种方式：

# API Key
api-key: your-api-key
# JWT Bearer Token
Authorization: Bearer <token>

主要端点

方法	路径	说明	限流
POST	/api/auth/apikey/create	生成新 API Key（需 admin 权限）	10/min
GET	/api/auth/apikey/list	列出所有 API Key（脱敏）	30/min
DELETE	/api/auth/apikey/delete	删除指定 API Key	10/min
POST	/api/process/text	文本分块 + 向量嵌入	60/min
POST	/api/vector/insert	插入向量	60/min
POST	/api/vector/search	向量相似度搜索	60/min
POST	/api/files/upload	上传单文件并处理	10/min
POST	/api/files/batch/upload	批量上传文件	10/min
GET	/api/metadata/{file_id}	获取文件元数据	60/min
POST	/api/metadata/update	更新元数据	60/min
DELETE	/api/metadata/{file_id}	删除元数据	60/min
GET	/api/system/status	系统状态	30/min
POST	/api/model/switch	切换模型	10/min
POST	/api/backup/create	创建备份	5/min
GET	/api/backup/list	备份列表	30/min
POST	/api/backup/restore/{file}	恢复备份	5/min
DELETE	/api/backup/delete/{file}	删除备份	5/min

示例：上传文件并搜索

# 上传文件
curl -X POST http://localhost:8001/api/files/upload \
-H "api-key: your-api-key" \
-F "file=@document.pdf" \
-F "collection_id=my_collection"# 向量搜索
curl -X POST http://localhost:8001/api/vector/search \
-H "Content-Type: application/json" \
-d '{ "collection_id": "my_collection", "query_vector": [0.1, 0.2, ...], "top_k": 5, "filters": {"file_type": "pdf"} }'

配置说明

模型配置

# 文本嵌入（本地 sentence-transformers 或远程 OpenAI 兼容接口）TEXT_PROCESSING_MODEL_TYPE=local# local | remoteTEXT_PROCESSING_MODEL_NAME=shibing624/text2vec-base-chineseTEXT_PROCESSING_API_KEY=# remote 模式时填写# 图像嵌入IMAGE_PROCESSING_MODEL_TYPE=localIMAGE_PROCESSING_MODEL_NAME=OFA-Sys/chinese-clip-vit-base-patch16

本地模型首次运行时自动从 HuggingFace 下载，支持国内镜像（SJTU、hf-mirror、ModelScope）。

多进程部署

多进程模式下需要 Redis 来共享缓存和速率限制计数器：

CACHE_BACKEND=redisREDIS_HOST=localhostREDIS_PORT=6379REDIS_DB=0

FAISS 写操作通过文件锁（filelock）保证多进程安全，无需额外配置。

运行测试

# 单元测试cd vector_db
TEST_MODE=true pytest tests/unit_tests/ -v
# 压力测试（需先启动服务）
locust -f tests/load_test.py --host http://localhost:8001

技术栈

类别	技术
Web 框架	FastAPI + uvicorn
向量数据库	FAISS / HNSWlib / Annoy
文本嵌入	sentence-transformers / transformers
图像/音频嵌入	CLIP / librosa MFCC
元数据存储	MySQL / Redis / MongoDB
文件存储	本地 / S3 / 数据库
缓存	内存 LRU / Redis
认证	JWT (HS256) + API Key
加密	AES-256 CBC
速率限制	slowapi（支持 Redis 后端）
并发安全	filelock（FAISS 写锁）