# VecBoost
<p align="left">
<img src="https://img.shields.io/badge/Rust-2024-edded?logo=rust&style=flat-square" alt="Rust Edition">
<img src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" alt="MIT License">
<img src="https://img.shields.io/badge/Version-0.1.0-green.svg?style=flat-square" alt="Version">
</p>
高性能、生产级嵌入向量服务，使用 Rust 编写。VecBoost 提供高效的文本向量化服务，支持多种推理引擎、GPU 加速和企业级功能。
## ✨ 功能特性
- **🚀 高性能**: 优化的 Rust 代码库，支持批处理和并发请求
- **🔧 多引擎支持**: Candle（原生 Rust）和 ONNX Runtime 推理引擎
- **🎮 GPU 加速**: NVIDIA CUDA 和 Apple Metal 原生支持
- **📊 智能缓存**: 多层缓存策略（LRU、LFU、KV）
- **🔐 企业级安全**: JWT 认证、CSRF 保护和审计日志
- **⚡ 速率限制**: 可配置的令牌桶算法速率限制
- **📈 优先级队列**: 可配置优先级的请求队列
- **🌐 双 API 接口**: gRPC 和 HTTP/REST 接口，支持 OpenAPI
- **📦 Kubernetes 部署**: 包含生产环境部署配置
## 🚀 快速开始
### 前置条件
- Rust 1.75+（2024 版）
- CUDA Toolkit 12.x（Linux GPU 支持）
- Metal（macOS GPU 支持）
### 安装
```bash
# 克隆仓库
git clone https://github.com/Kirky-X/vecboost.git
cd vecboost
# 默认构建（仅 CPU）
cargo build --release
# 构建 CUDA 支持（Linux）
cargo build --release --features cuda
# 构建 Metal 支持（macOS）
cargo build --release --features metal
# 构建全部功能
cargo build --release --features cuda,onnx,grpc,auth,redis
```
### 配置
复制示例配置并自定义：
```bash
cp config.toml config_custom.toml
# 编辑 config_custom.toml
```
### 运行
```bash
# 使用默认配置运行
./target/release/vecboost
# 使用自定义配置
./target/release/vecboost --config config_custom.toml
```
服务默认在 `http://localhost:9002` 启动。
### Docker
```bash
# 构建镜像
docker build -t vecboost:latest .
# 运行容器
docker run -p 9002:9002 -v $(pwd)/config.toml:/app/config.toml vecboost:latest
```
## 📖 文档
- [📋 用户指南](USER_GUIDE.md) - 详细使用说明
- [🔌 API 参考](API_REFERENCE.md) - REST API 和 gRPC 文档
- [🏗️ 架构设计](ARCHITECTURE.md) - 系统设计和组件说明
- [🤝 贡献指南](docs/CONTRIBUTING.md) - 贡献代码指南
## 🔌 API 使用
### HTTP REST API
通过 HTTP 生成嵌入向量：
```bash
curl -X POST http://localhost:9002/api/v1/embed \
-H "Content-Type: application/json" \
-d '{"text": "Hello, world!"}'
```
响应：
```json
{
"embedding": [0.123, 0.456, ...],
"dimension": 1024,
"processing_time_ms": 15.5
}
```
### gRPC API
服务在 50051 端口（可配置）暴露 gRPC 接口：
```protobuf
service EmbeddingService {
rpc Embed(EmbedRequest) returns (EmbedResponse);
rpc EmbedBatch(BatchEmbedRequest) returns (BatchEmbedResponse);
rpc ComputeSimilarity(SimilarityRequest) returns (SimilarityResponse);
}
```
### OpenAPI 文档
访问交互式 API 文档：
- Swagger UI: `http://localhost:9002/swagger-ui/`
- ReDoc: `http://localhost:9002/redoc/`
## ⚙️ 配置
### 主要配置选项
```toml
[server]
host = "0.0.0.0"
port = 9002
[model]
model_repo = "BAAI/bge-m3" # HuggingFace 模型 ID
use_gpu = true
batch_size = 32
expected_dimension = 1024
[embedding]
cache_enabled = true
cache_size = 1024
[auth]
enabled = true
jwt_secret = "your-secret-key"
```
查看[配置指南](config.toml)了解全部选项。
## 🏗️ 架构
```
┌─────────────────────────────────────────────────────────────┐
│ VecBoost 服务 │
├─────────────────────────────────────────────────────────────┤
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │ HTTP/gRPC │ │ 认证层 │ │ 速率限制 │ │
│ │ 端点 │ │ (JWT/CSRF) │ │ (令牌桶) │ │
│ └─────────────┘ └─────────────┘ └─────────────────────┘ │
│ │ │ │ │
│ └────────────────┴───────────────────┘ │
│ │ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 请求管道 │ │
│ │ ┌─────────┐ ┌───────────┐ ┌─────────────────┐ │ │
│ │ │ 优先级 │ │ 请求 │ │ 响应 │ │ │
│ │ │ 队列 │→ │ 工作线程 │→ │ 通道 │ │ │
│ │ └─────────┘ └───────────┘ └─────────────────┘ │ │
│ └─────────────────────────────────────────────────────┘ │
│ │ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 嵌入服务 │ │
│ │ ┌─────────┐ ┌───────────┐ ┌─────────────────┐ │ │
│ │ │ 文本 │ │ 推理 │ │ 向量缓存 │ │ │
│ │ │ 分块 │→ │ 引擎 │→ │ (LRU/LFU/KV) │ │ │
│ │ └─────────┘ └───────────┘ └─────────────────┘ │ │
│ └─────────────────────────────────────────────────────┘ │
│ │ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 推理引擎 │ │
│ │ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ Candle │ │ ONNX │ │ │
│ │ │ (原生) │ │ Runtime │ │ │
│ │ └─────────────┘ └─────────────┘ │ │
│ └─────────────────────────────────────────────────────┘ │
│ │ │
│ ┌────────────────┼────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ CPU │ │ CUDA │ │ Metal │ │
│ └──────────┘ └──────────┘ └──────────┘ │
└─────────────────────────────────────────────────────────────┘
```
## 📦 项目结构
```
vecboost/
├── src/
│ ├── audit/ # 审计日志
│ ├── auth/ # 认证 (JWT, CSRF)
│ ├── cache/ # 多层缓存 (LRU, LFU, KV)
│ ├── config/ # 配置管理
│ ├── device/ # 设备管理 (CPU, CUDA, Metal)
│ ├── engine/ # 推理引擎 (Candle, ONNX)
│ ├── grpc/ # gRPC 服务器
│ ├── metrics/ # Prometheus 指标
│ ├── model/ # 模型下载和管理
│ ├── pipeline/ # 请求管道和优先级
│ ├── rate_limit/ # 速率限制
│ ├── routes/ # HTTP 路由
│ ├── security/ # 安全工具
│ ├── service/ # 核心嵌入服务
│ └── text/ # 文本处理和分词
├── examples/gpu/ # GPU 示例程序
├── proto/ # gRPC 协议定义
├── deployments/ # Kubernetes 部署配置
├── tests/ # 集成测试
└── config.toml # 默认配置
```
## 🎯 性能
| 嵌入维度 | 最高 4096 |
| 批处理大小 | 最高 256 |
| 请求/秒 | 1000+ (CPU) |
| 延迟 (p99) | < 50ms (GPU) |
| 缓存命中率 | > 90% (1024 条目) |
## 🔒 安全
- **认证**: JWT 令牌，支持可配置过期时间
- **授权**: 基于角色的访问控制
- **审计日志**: 记录所有请求的用户和操作详情
- **速率限制**: 每 IP、每用户、全局限速
- **加密**: AES-256-GCM 加密静态敏感数据
## 📈 监控
- **Prometheus 指标**: `/metrics` 端点
- **健康检查**: `/health` 端点
- **OpenAPI 文档**: `/swagger-ui/` 的 Swagger UI
- **Grafana 仪表板**: `deployments/` 中的预配置仪表板
## 🚀 部署
### Kubernetes
```bash
# 部署到 Kubernetes
kubectl apply -f deployments/kubernetes/
```
查看[部署指南](deployments/kubernetes/README.md)了解更多详情。
### Docker Compose
```yaml
services:
vecboost:
image: vecboost:latest
ports:
- "9002:9002"
volumes:
- ./config.toml:/app/config.toml
environment:
- MODEL_REPO=BAAI/bge-m3
```
## 🤝 贡献
欢迎贡献代码！请阅读[贡献指南](docs/CONTRIBUTING.md)了解更多。
## 📄 许可证
本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解更多。
## 🙏 致谢
- [Candle](https://github.com/huggingface/candle) - 原生 Rust ML 框架
- [ONNX Runtime](https://onnxruntime.ai/) - 跨平台 ML 推理
- [Hugging Face Hub](https://huggingface.co/models) - 模型仓库