中文 | English

高性能、生产级多功能推理服务，使用 Rust 编写。VecBoost 提供文本嵌入、重排序、决策问答、翻译、语言检测与语音转录六类推理能力，支持多种推理引擎、GPU 加速和企业级功能。

✨ 功能特性 • 🚀 快速开始 • 📚 文档 • 💻 示例 • 🤝 参与贡献

---

🎯 六类推理能力，一套服务交付

文本嵌入、重排序、决策问答、翻译、语言检测与语音转录，统一经 EngineFactory 装载模型，共享配置、缓存与限流设施。

🧠 文本嵌入 批量向量 · Matryoshka 约简 · OpenAI 兼容	🔁 重排序 bi-encoder 文档相关性排序	🎲 决策问答 choice / score / noul 三题型
🌐 翻译 Marian 多语言对 · auto 源语检测	🔤 语言检测 置信度与可靠性判定	🎙️ 语音转录 Qwen3-ASR · VAD 切分

---

📋 目录

📑 目录

• ✨ 功能特性
• 🚀 快速开始
• 🔌 API 使用
• ⚙️ 配置
• 📚 文档
• 💻 示例
• 🏗️ 架构
• 🧪 测试
• 📊 性能
• 🔒 安全
• 🗺️ 开发路线图
• 🤝 参与贡献
• 📋 更新日志
• 📄 许可证
• 🙏 致谢
• 📞 联系与支持
• ⭐ Star 历史

---

✨ 功能特性

🚀 高性能 优化的 Rust 代码库，支持批处理与并发请求处理；Linux 下默认启用 jemalloc 全局分配器	🔧 多引擎支持 ONNX Runtime（默认）与 Candle（opt-in 回退）推理引擎，经 EngineFactory 工厂切换
🔁 Rerank 重排序 基于 bi-encoder 的文档重排序，HTTP/gRPC/CLI 三协议支持	🌍 国际化（i18n） ICU+Fluent 中英双语错误响应，Accept-Language 请求级语言协商
🌐 翻译与语言检测 Marian/opus-mt 多语言对翻译（(src,tgt) 路由 + auto 检测）与 whatlang 语言检测，onnx feature	🎮 决策问答 Laya 决策管线：choice / score / noul 三题型，带温度校准的概率输出
🎮 GPU 加速 NVIDIA CUDA、Apple Metal 原生支持；mkl/accelerate CPU 加速后端 opt-in	🌐 多协议接口 HTTP/REST、gRPC、MCP、CLI 四种接口由 sdforge 从单一源生成
🧩 7 库生态 trait-kit/confers/inklog/oxcache/limiteron/dbnexus/sdforge 模块化生态	📊 智能缓存 基于 oxcache 的高性能缓存（LRU/LFU/FIFO + TTL）与语义缓存三级查询
🔐 企业级安全 JWT 认证、CSRF 保护、基于角色的访问控制、TOTP、账号锁定与审计日志	⚡ 速率限制 基于 limiteron 的令牌桶限流（全局/IP/用户/API 密钥多维独立计数）
📈 优先级队列 可配置优先级的请求队列、加权公平调度与时间窗动态拼批	🧊 Matryoshka 支持 动态维度约简（截断后自动重归一化），支持更小更快的嵌入向量（OpenAI 兼容）
🔍 可观测性 Prometheus 指标、健康检查、结构化日志（inklog 控制台 + 文件轮转）	📦 云原生部署 Docker 镜像（`linux/amd64`，默认单架构构建）；Kubernetes 提供部署指引（清单需自备）

除上述核心能力外，OpenAI 兼容端点（POST /v1/embeddings，支持 encoding_format=base64）、BF16 推理与 SIMD 向量相似度、GPU 内存分页、vecboost doctor 只读诊断、Library SDK 集成（Library 模式）与 config_full.toml / config_minimal.toml 配置预设也已可用；端点与参数明细见 🔌 API 使用 一节，配置项说明见 ⚙️ 配置 一节。

---

🚀 快速开始

📦 安装

前置条件：

📋 表格

依赖项	版本	说明
Rust	1.91+	edition 2024（以 Cargo.toml 的 rust-version 字段为权威值）
Cargo	1.91+	随 Rust 附带
CUDA Toolkit	12.x	可选，NVIDIA GPU 支持（cuda feature）
Metal SDK	最新版	可选，Apple Silicon GPU 支持（metal feature）
protobuf-compiler	最新版	可选，gRPC E2E 测试需要

💡 提示: 运行 rustc --version 验证 Rust 安装。

📄 代码 · bash

# 1. 克隆仓库
git clone https://github.com/Kirky-X/vecboost.git
cd vecboost

# 2. 默认构建（http feature，含 OpenAPI 文档）
cargo build --release

# 3. 构建 GPU 支持
#    Linux (CUDA):
cargo build --release --features cuda
#    macOS (Metal):
cargo build --release --features metal

# 4. 构建多协议接口（HTTP + gRPC + CLI）
cargo build --release --features grpc,cli

# 5. 构建 MCP 接口（stdio 模式，--mcp 启动）
cargo build --release --features mcp

# 6. 构建 CI 全特性组合（数据库 + 认证 + ONNX + OpenAPI + 全协议）
cargo build --release --features grpc,cli,auth,onnx,db,openapi,mcp

最小构建：cargo build --no-default-features --features http。

配置并运行：

📄 代码 · bash

# 复制并自定义配置（默认从 config/config.toml 读取）
cp config/config.toml config/config_custom.toml
# 编辑 config/config_custom.toml

# 使用默认配置运行
./target/release/vecboost

# 使用自定义配置（--config，CLI 子命令模式下须写在子命令之前）
./target/release/vecboost --config config/config_custom.toml

✅ 成功: 按出厂 config/config.toml（host = "127.0.0.1"，端口 9002）启动时，服务监听 http://127.0.0.1:9002（仅本机可访问）；当配置未指定 host 时，代码默认 0.0.0.0（监听所有接口，供容器/局域网部署——改配置 [server] host 即可覆盖）。

🐳 Docker：docker build -t vecboost:latest . 后挂载 config/ 与 models/ 运行即可；Docker Compose 与 Kubernetes 部署见 📖 用户指南 · Docker 部署。

💡 最小示例

以下示例改编自 examples/http/embed_api.rs，通过 HTTP 生成嵌入向量（完整端点见 📘 API 参考）：

📄 代码 · 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, 0.789, ...],
  "dimension": 1024,
  "processing_time_ms": 15.5
}

决策问答（需 [model] task = "decision" 的 Laya 决策管线，onnx feature 构建；三题型 choice/score/noul 各有明确响应结构，答案按问题顺序回显）：

📄 代码 · bash

curl -X POST http://localhost:9002/api/v1/decisions \
  -H "Content-Type: application/json" \
  -d '{
    "state": {"topic": "vacation"},
    "questions": [
      {"name": "destination", "qtype": "choice", "instructions": "pick one", "options": ["beach", "mountain"]},
      {"name": "budget", "qtype": "score", "instructions": "rate 1-5"},
      {"name": "confident", "qtype": "noul", "instructions": "state your p(true)"}
    ]
  }'

响应（choice=argmax+各选项概率表，score=期望等级+完整分布，noul=两选项 softmax 的 P(true)）：

📄 代码 · json

{
  "answers": [
    {"question": "destination", "answer": {"type": "choice", "index": 1, "option": "mountain", "probabilities": {"beach": 0.25, "mountain": 0.75}}},
    {"question": "budget", "answer": {"type": "score", "expected": 3.5, "distribution": {"3": 0.5, "4": 0.5}}},
    {"question": "confident", "answer": {"type": "noul", "p_true": 0.9}}
  ],
  "processing_time_ms": 12
}

也可以直接使用 CLI（cli feature）或 library SDK（library 模式）：

📄 代码 · bash

# 单文本嵌入
cargo run --features cli -- embed --req '{"text":"Hello, world!"}'

🧭 核心概念

• 模型与引擎：ModelConfig 声明 HuggingFace 模型（默认 BAAI/bge-m3，1024 维），EngineFactory::create(engine_type, config) 创建 ONNX（默认，onnx feature 随 default 启用）或 Candle（candle feature opt-in 回退）引擎；支持 Bert / XlmRoberta 双架构与 mean/cls/max 池化。
• 四协议单一源：src/api/embedding.rs 中的处理函数经 #[forge(...)] 宏标注，由 sdforge 生成 HTTP/gRPC/MCP/CLI 绑定，禁止手写协议代码。
• 7 库生态：trait-kit 以 typestate 模块注册中心（Kit<Unbuilt> → Kit<Ready>）装配全部模块；confers 接管配置、inklog 日志、oxcache 缓存、limiteron 限流、dbnexus 持久化（db feature）、sdforge 接口生成。
• 配置优先级：TOML 文件 + VECBOOST_ 前缀环境变量覆盖（敏感项 VECBOOST_JWT_SECRET / VECBOOST_ADMIN_PASSWORD 必须走环境变量）；配置文件变更校验并打日志，重启后生效。
• 特性门控：全部可选能力均为独立 feature（见 🏷️ Feature 标志），最小构建只含 HTTP 服务。

---

🔌 API 使用

VecBoost 由 sdforge 从处理函数单一源生成四种协议接口（src/api/ 下 embedding / rerank / decisions / translate / detect 各域一份单一源）。全部端点、参数、请求/响应示例、gRPC 方法表与消息类型见 📘 API 参考，概要如下：

• HTTP/REST：/api/v1/* 提供嵌入（单文本/批量/文件）、相似度、语义检索、重排序、决策问答（choice/score/noul）、翻译（多语言对 + auto 检测）、转录（16kHz 语音样本 → 文本，transcribe feature）、语言检测、模型管理与健康检查端点；
• OpenAI 兼容：POST /v1/embeddings，响应遵循 OpenAI 格式（object / data / usage），支持 encoding_format=base64；
• Matryoshka 维度约简：/v1/embeddings 传 dimensions（256/512/1024 等）换取更小更快的向量，截断后自动 L2 重归一化保证余弦相似度正确；
• gRPC：grpc feature 在 50051 端口（可配置）暴露 17 个 vecboost.* 方法（sdforge 统一 Call 协议，无需手写 proto，含 vecboost.translate / vecboost.detect），JWT 认证、限流、最大连接数与超时均可配置；
• MCP：mcp feature 以 stdio 模式（vecboost --mcp）向 LLM 暴露由 #[forge(tool_name=…)] 注册的工具，工具名为 embed_text / embed_batch / compute_similarity / search / file_embed / rerank / rerank_batch / decisions / translate / detect / transcribe / list_models 等（注意 MCP tool_name 非 HTTP 端点名，完整清单见 📘 API 参考）；
• CLI：cli feature 提供 embed / embed_batch / compute_similarity / search / rerank / decisions / translate / detect / transcribe 子命令（见 💡 最小示例；transcribe 子命令收 WAV 文件路径，读 16kHz 单声道样本）；
• 推理引擎：ONNX Runtime（默认，onnx feature 随 default 启用）与 Candle（candle feature opt-in 回退），经 EngineFactory::create 工厂切换；[model] 的 engine_type / task 配置驱动引擎与任务维度选择——task = "embedding"（默认）/ task = "decision"（Laya 决策管线）/ task = "translate"（seq2seq 翻译，仅 onnx）/ task = "transcribe"（Qwen3-ASR 转录，需 transcribe feature）四态，非当前任务的端点以 400 Unsupported task 显性拒绝（bundle 布局见 config/config.toml [model] 段注释，翻译语言对见 [translation] 段）；
• 可观测性与运维：/metrics（Prometheus 指标）、/health（存活探针）与 /health?depth=full（真实就绪探测）、/swagger-ui/（交互式 OpenAPI 文档，需 swagger-ui feature，规范 JSON 见 /api-docs/openapi.json）；只读诊断 vecboost doctor（config / tokenizer / 缓存 / 线程 / GPU / 模型完整性，FAIL 退出码 1）。

翻译与语言检测请求示例（与 API 参考 字段一致）：

📄 代码 · bash

curl -X POST http://localhost:9002/api/v1/translate \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello, my dog is cute", "source_language": "en", "target_language": "zh"}'

curl -X POST http://localhost:9002/api/v1/detect \
  -H "Content-Type: application/json" \
  -d '{"text": "The quick brown fox jumps over the lazy dog near the riverbank every morning."}'

检测响应（language: null + is_reliable: false 表示不可判定——纯数字/过短文本，显性表达不虚构语言；完整错误语义见 API 参考）：

📄 代码 · json

{
  "language": "en",
  "script": "Latin",
  "confidence": 1.0,
  "is_reliable": true,
  "processing_time_ms": 0
}

⚠️ 前置：翻译需 --features onnx 构建并在 [translation] 段配置 [[translation.pairs]] 语言对（缺省请求以 400 translate-not-configured 显性拒绝）；语言检测无模型依赖，任何构建均可用。

🔧 译文后处理与超时：翻译在引擎出口做确定性后处理（服务层与库用户同享）——target=zh 时繁→简归一化、URL 协议分隔符与 LaTeX 转义符号修复；模型级高频误译经 [[translation.pairs.output_fixes]] 字面替换表（按声明序）修复，见 config/config.toml [translation] 段。HTTP 全局请求超时经 [server] request_timeout_seconds 配置（CPU seq2seq 译论文级长摘要需 15-130+s，config/config.toml 已显式设 300s）。

交互式 OpenAPI 文档（Swagger UI）：cargo build --features swagger-ui 后访问 http://localhost:9002/swagger-ui/；规范 JSON：/api-docs/openapi.json（单二进制、一次构建；注意根路径 /api-docs 不提供 UI）。同 feature 下交互式 ReDoc 见 /redoc（锁定版本 + SRI 校验的 jsdelivr CDN 渲染，浏览器离线时不可用）。分阶段指标（拼批/去重/分段延迟等）见 ⚡ 性能指南 · 新增指标。

🔖 Feature 标志

下表逐项对应 Cargo.toml 的 [features] 定义，default = ["http"]。

📋 表格

Feature	默认	说明
http	✅	HTTP/REST API + OpenAPI 文档 + Prometheus 指标
grpc	-	gRPC 服务器（sdforge #[forge(grpc_method)] 生成）
cli	-	CLI 命令行工具
mcp	-	MCP 协议接口（LLM 工具集成，stdio 模式）
openapi	-	OpenAPI 规范程序化导出（sdforge/openapi，不经 swagger-ui 链）
swagger-ui	-	Swagger UI 交互页面 + /api-docs/openapi.json（挂主服务端口；默认构建不编译，单二进制一次构建）
schema	-	OpenAPI Schema 派生（http/openapi 自动启用；支持 library 模式类型导出）
db	-	dbnexus 数据库持久化基础设施（驱动无关，须搭配 sqlite 或 postgres 驱动 feature 二选一）
sqlite	-	SQLite 数据库驱动（含 db + dbnexus/sqlite + inklog/sqlite）
postgres	-	PostgreSQL 数据库驱动（含 db + dbnexus/postgres + inklog/postgres）
auth	-	JWT 认证 + CSRF + RBAC + AES-256-GCM 加密
cuda	-	CUDA 设备支持（cudarc driver + nvml 检测，后端正交；candle 的 CUDA 后端另经 candle-cuda）
candle-cuda	-	candle 后端的 CUDA 计算加速（含 candle）
metal	-	Apple Silicon Metal GPU（candle 后端，含 candle）
onnx	-	ONNX Runtime 引擎（默认启用，随 default）
candle	-	candle 回退后端（opt-in：CandleEngine embedding / candle 决策头 / GGUF 量化桥；未启用时 engine_type="candle" 启动期显性拒绝）
transcribe	-	Qwen3-ASR 转录引擎（三图 + silero VAD + fbank），库内 InferenceEngine::transcribe 入口；HTTP/gRPC 服务面已接线（POST /api/v1/transcribe，[transcribe] 段装配）
mkl	-	x86_64 CPU MKL 加速后端（candle 路径 opt-in，含 candle；需链接正常的工具链）
accelerate	-	aarch64 macOS Accelerate 加速后端（candle 路径 opt-in，含 candle）
quantized-gguf	-	GGUF 量化引擎开关（加载期反量化桥实现于 candle 路径，运行期与 fp32 等价）
character_converter	-	独立启用 character_converter 字符转换依赖（onnx feature 已隐含启用）

📦 内置依赖说明: confers（配置）、inklog（日志）、oxcache（缓存）、limiteron（限流）、trait-kit（模块注册）为必选依赖，始终启用，无需通过 feature 开启。sdforge 在 http/grpc/cli/mcp 任一协议 feature 下启用。

🧪 实验通路: 转录的本地实验 harness（独立 crate，二进制 transcribe-own）已收敛为薄壳 CLI——推理经主仓门面 vecboost::transcribe，py-torch 基线对拍通路保留；该目录为本机目录，不入 git 仓库。产品化实现见 src/engine/transcribe/；CLI 契约要点与消费面规范见 🧹 维护规范。

---

🔧 配置

默认从 config/config.toml 读取（--config <path> 指定其他路径，路径不存在时 fail-fast 报错退出；预置 config_full.toml / config_minimal.toml 示例）。环境变量以 VECBOOST_ 前缀覆盖配置文件，敏感项（VECBOOST_JWT_SECRET / VECBOOST_ADMIN_PASSWORD）必须走环境变量；配置文件变更会校验并打日志，重启后生效。

全部配置段（server / model / embedding / rerank / monitoring / auth / rate_limit / audit / database / logging / pipeline.worker / semantic_cache / device / translation / transcribe）的逐项键位、默认值、环境变量全表与完整示例配置见 📖 用户指南 · 配置，也可直接查看 config/config.toml。

⚠️ 注意：[flow_control] 与 [cache] 两个 TOML 段当前版本不解析（历史遗留段名）；限流走 [rate_limit]，缓存走 [embedding] 与 [semantic_cache]。见 ❓ FAQ。

---

📚 文档

📋 表格

文档	说明
📖 用户指南	从安装到进阶的完整使用教程（含部署选项）
📘 API 参考	REST / gRPC / OpenAI 兼容接口的完整说明
🏗️ 架构文档	设计原则、模块划分与数据流
⚡ 性能指南	基准数据、调优开关注册表与实验纪律
🔒 安全文档	安全设计、支持版本与漏洞报告流程
❓ FAQ	常见问题解答
🧪 测试场景矩阵	测试栈职责划分与场景穷举矩阵
📋 更新日志	每个版本的变更记录
🤝 贡献指南	如何参与项目开发
🧹 维护规范	跨变更的长期约束：转录消费面、CLI 契约、退役配置项纪律、废弃文档治理
📈 基准数据归档	历史基准数据（相似度/批调度/语义缓存/GPU 管线）
🌍 I18N 缺失审计	国际化翻译键审计记录

---

💻 示例

全部示例位于 examples/ 目录，作为独立 workspace member crate vecboost-examples（12 个分类、31 个可执行二进制），覆盖基础嵌入、HTTP/CLI 调用、引擎切换、认证、缓存、限流、监控、审计、语义缓存与 Library SDK 集成；逐分类清单见 examples/README.md。

📄 代码 · bash

# 运行单个示例
cargo run -p vecboost-examples --bin embed
cargo run -p vecboost-examples --bin library_usage
cargo run -p vecboost-examples --bin matryoshka

# ONNX 引擎示例（需要 ONNX Runtime）
cargo run -p vecboost-examples --bin onnx --features onnx

---

🧱 架构

VecBoost 采用模块化生态架构：trait-kit 以 typestate 模块注册中心（Kit<Unbuilt> → Kit<Ready>）装配模块（src/registry/ 共 20 个 ModuleMeta 实现，部分随 auth 等 feature 门控），sdforge 从 src/api/embedding.rs 单一源生成四协议绑定，推理经 EngineFactory 抽象到 Candle / ONNX 引擎，请求经优先级队列与时间窗拼批进入推理管线。

7 库生态（trait-kit / confers / inklog / oxcache / limiteron / dbnexus / sdforge）的版本与分工、模块依赖图、数据流、缓存/安全/部署架构与扩展点说明见 🏗️ 架构文档。

---

🧪 测试

🎯 测试策略

测试栈分六层：src/ 内联单元测试、tests/integration/ 集成测试、专项集成（doctor / gRPC E2E / 模型快照回归 / 量化质量门 / SDK 矩阵）、tests/scenario/*.py 真实服务场景测试（15 个 pytest 套件）、tests/perf/ 性能回归阈值与 benches/ 的 5 组 Criterion 微基准。TEST_MODE 环境变量控制测试引擎（mock 默认 / light / full）。各层职责、场景穷举矩阵与 CI 工作流对应关系见 🧪 测试场景矩阵。

⚡ 运行命令（与 CI 一致）

以下命令提取自 .github/workflows/health-check.yml（Health Check）、feature-matrix.yml、scenario-tests.yml 与 docs/CONTRIBUTING.md。路径依赖提示：../base/* 生态库是路径依赖的活仓库，本地门禁命令须以 -p vecboost -p vecboost-examples 限定。

📄 代码 · bash

# 格式与 Lint 门禁（CI：clippy unwrap_used 为生产代码 panic 面门禁）
cargo fmt --all -- --check
cargo clippy --features "grpc,cli,auth,onnx,db,openapi,mcp" --all-targets -- -D warnings -W clippy::unwrap_used

# 全特性编译检查（feature-matrix）
cargo check --features "grpc,cli,auth,onnx,db,openapi,mcp"

# 单元 + 集成测试（CI 分 --lib 与 --tests 两步）
cargo test --features "grpc,cli,auth,onnx,db,openapi,mcp" --lib
cargo test --features "grpc,cli,auth,onnx,db,openapi,mcp" --tests

# gRPC E2E（拉起真实二进制）
cargo test -p vecboost --features http,grpc --test grpc_e2e

# 场景测试（pytest，conftest 自动拉起真实服务器；models/ 缺席时推理用例自动 SKIP）
cargo build -p vecboost --features http
pytest tests/scenario -q --junitxml=scenario-results.xml

# Python 性能测试（sim 标记区分模拟器用例）
pytest tests/perf -m "not sim"   # 只跑真实服务用例
pytest tests/perf -m sim          # 只跑模拟器用例

# 覆盖率（CI 硬门禁：行覆盖率 ≥ 80%，llvm-cov；本地实测 90.89%）
cargo llvm-cov --features "grpc,cli,auth,onnx,db,sqlite,openapi,mcp" --lib --lcov --output-path coverage/lcov.info

# 基准测试（CI benchmark job）
cargo bench --features "grpc,cli,auth,onnx,db,openapi,mcp"

# 文档构建与死链检查
cargo doc --workspace --no-deps

# 依赖安全审计
cargo audit

📊 测试规模

截至 v0.3.0-rc.2 工作区：单元测试（src/ 内联）2277 个、Rust 集成/专项测试（tests/*.rs）63 个测试函数、Python 场景/性能用例 146 个（场景 119 + 性能 27，15 个场景套件）、Criterion 微基准 5 组；CI 硬门禁为行覆盖率不低于 80%（llvm-cov），Python 场景测试为每夜定时任务（UTC 03:00）不阻塞 PR。逐项统计与场景矩阵见 🧪 测试场景矩阵。

---

📊 性能

基准数据来自 docs/benchmarks/ 实测归档（criterion；该目录为仅本机保留，见 .gitignore，干净 clone 中不存在）：SIMD 向量相似度较标量最高 3.06x（1024 维 cosine 约 341.7 ns），语义缓存精确命中约 10 ns，candle 单文本在 --features mkl 下 4.0× 加速。完整基准表、性能设计要点（时间窗拼批/批内去重/SIMD/线程调优/jemalloc）、GGUF 量化与调优开关注册表见 ⚡ 性能指南。

🧭 引擎选型：为什么主引擎是 onnxruntime（实测证据）

采集条件：2026-10-18，AMD Ryzen 9 9950X（16 核）/ 66 GiB / RTX 5080 16 GiB（WSL2）； ORT ① 1.28.2（CPU）/ ② 1.24.3（CUDA EP）；嵌入用 bge-small-en-v1.5（同一模型的两份导出）， 转录用 Qwen3-ASR（0.6B / 1.7B，700 秒中文音频，CER 对比同一参照稿）；每格 2~3 遍取稳定值。

嵌入吞吐（单条 / 批量×32，越小越好）

📋 表格

引擎 × 设备	单条	批量×32	结论
onnxruntime × CPU	2.56 ms	26.35 ms	产品默认，CPU 最优
candle × CPU	78.0 ms	186.5 ms	分别慢 30.5× / 7.1×
onnxruntime × CUDA	2.70 ms	3.06 ms	批量最优
candle × CUDA（candle-cuda）	5.05 ms	6.70 ms	比自家 CPU 快 15.4×/27.8×，仍比 ort GPU 慢 1.9×/2.2×

• 切换到 ort 的直接原因：candle 的 CPU 前向是原生实现且不投入优化——单条差 30 倍、批量差 7 倍； 即使开 --features mkl（单条 4×）也只降到 ~17.5 ms，仍比 ort 慢约 6.8 倍。
• GPU 不能当替代方案：同卡同模型，ort 的 CUDA EP 仍快约 2 倍，两者显存同级（1.95 GB）； 但 candle 的 GPU 相对自家 CPU 是质变（1536 倍），它落后的是引擎实现，不是设备。
• 嵌入量化：int8 相对 fp32 单条 −22% / 批量 −16% / 内存 −55%，余弦中位 0.9971（基本无损）； q4 更快但余弦降至 0.9849。精度闸门：tests/engine_backend_parity.rs::onnx_quantized_vs_fp32_parity。

转录吞吐（Qwen3-ASR，700 秒音频；4 并行档 / 服务串行档）

📋 表格

通路	耗时	CER	资源
ort 0.6B int8 × CPU	70.4 s / 137.2 s	7.75%	零显存
ort 0.6B int8 × CUDA	199.4 s	7.36%	显存 14.4 GiB（GPU 负优化）
嵌入 Python 0.6B bf16 × CUDA	51.2 s	22.81%（长音频塌缩）	显存 11.7 GiB + Python 栈
ort 1.7B int8 × CPU	135.7~142.1 s	15.78~18.99%	零显存
ort 1.7B fp32（无损）× CPU	698.8 s	7.24%	零显存
嵌入 Python 1.7B bf16 × CUDA	55.9 s	2.49%	显存 14.5 GiB + Python 栈

• 转录上 GPU 对 ort 全线为负（0.6B 慢 2.6×、1.7B int8 慢 1.6×、1.7B fp32 慢 2.3×）：显卡出力仅 ~15%，显存却吃满； 原因是逐段解码的 kernel 太小，被启动与主机↔显存同步支配。
• 质量瓶颈在量化而非引擎：混合 bundle 拆解证明 decoder 动态量化吃掉全部 7.9 个 CER 点，encoder 量化几乎零代价 → 纯 Rust 的高质量档 = int8 encoder + fp32 decoder（7.27% / 656 s / 零显存）。
• 嵌入 Python 更快且（1.7B 时）最准，但不走 VAD 分段，长音频质量塌到 22.8%；且需 Python 运行时入进程、显存 11.7~14.5 GiB。

完整矩阵（服务口径、HTTP 端到端、混合量化归因、fp16 守卫）见本机 docs/benchmarks/transcribe_engine_baseline.md 与 docs/benchmarks/embed_rerank_translate_baseline.md。

---

🔒 安全

🔒 安全设计

VecBoost 默认安全：出厂仅回环绑定，auth.enabled=false 时绑定非回环地址拒绝启动（逃生阀 VECBOOST_ALLOW_INSECURE=1 打 ERROR 告警）；认证授权基于 garrison（JWT + CSRF + RBAC admin 角色 + TOTP + 账号锁定），并覆盖 XFF 信任反转、文件路径白名单、输入长度校验、AES-256-GCM 配置加密、审计日志与 i18n 双语错误脱敏。逐项机制的代码级细节见 🔒 安全文档。

🔗 供应链与门禁

cargo audit、cargo deny check、CodeQL、Trivy/Checkov 镜像扫描、gitleaks 私密信息扫描与 pre-commit 钩子在 CI 与本地双重执行，完整清单与处置策略见 🔒 安全文档 · 供应链与安全门禁。

🚨 报告安全漏洞

请勿通过公开 issue 报告安全漏洞。请优先使用 GitHub Security Advisories 私密披露通道提交报告（不可用时再联系 Kirky.X：kirky-x@outlook.com）。依赖 advisory 由 CI cargo-audit 门禁。完整政策与支持版本见 SECURITY.md。

---

🧭 开发路线图

📋 表格

状态	方向	条目
✅	核心服务	四协议单一源生成、Candle/ONNX 双引擎、Bert/XlmRoberta 双架构、优先级队列与时间窗拼批
✅	生态集成	7 库生态接线（trait-kit 注册中心、confers 配置、inklog 日志、oxcache 缓存、limiteron 限流、dbnexus 持久化、sdforge 接口）
✅	安全与 i18n	JWT/CSRF/RBAC/TOTP、安全默认值收敛、审计日志、ICU+Fluent 双语错误
✅	性能基座	SIMD 相似度、连续批处理、语义缓存、GPU 内存分页、BF16 推理、Matryoshka 降维
✅	审计修复（0.3.0-rc.1）	安全默认值/登录收敛/XFF 信任反转/RBAC 接线/缓存键模型命名空间等破坏性行为变更（见 [更新日志](#-更新日志)）
✅	调优开关（0.3.0-rc.1）	GGUF 量化、向量输出量化、多模型 LFRU 驻留、缓存 WAL、硬件感知规划、doctor 诊断、启动预热
✅	量化推理后端	GGUF 引擎经“加载期反量化桥”交付（Q8_0/Q4_K；路由/魔数校验/质量门齐备）；收益为存储与加载体积，运行期与 fp32 等价（无算力加速），质量门需模型资产实跑
✅	多副本会话外置	`[auth] session_backend = "database"`（部署库 `garrison_kv`，garrison DbnexusKvDao）；锁定计数由 `AtomicKvDao` 原子化（见下行）
✅	多副本共享状态	限流与精确缓存 Redis 后端（`distributed-redis`，Lua 原子固定窗口）、锁定计数原子化（`AtomicKvDao`）；模糊语义索引与封禁清单仍按副本
✅	性能基线（吞吐 + MKL）	吞吐基线与 MKL 对比基线已实测（2026-09-16，见 性能指南）
📋	性能基线（Accelerate）	Accelerate（macOS）待验证：无 Apple 硬件，验证协议已登记于性能指南
✅	文档与可观测性	ReDoc（`/redoc`，`swagger-ui` feature）、预配置 Grafana 仪表板（`deploy/grafana/`）

---

🤝 参与贡献

详细的贡献流程与代码规范请参阅 🤝 贡献指南。

🔨 开发环境

工具链为 Rust 1.91+（Cargo.toml rust-version 为权威值）与 Python ≥ 3.10 + pytest（可选 protobuf-compiler、docker）；提交前须通过 fmt / clippy（unwrap_used panic 面门禁）/ 测试 / scripts/doc_consistency_check.py 四道质量门禁，Git 钩子经 pre-commit（.pre-commit-config.yaml → scripts/pre-commit.sh）自动执行；提交信息遵循 Conventional Commits，行为变更须在 CHANGELOG Unreleased 段登记并同步双语 README。环境搭建、构建组合与质量门禁命令见 🤝 贡献指南。

💖 贡献方式

🐛 报告 Bug 发现问题？ 创建 Issue

💡 功能建议 有好想法？ 发起讨论

🔧 提交 PR 想贡献代码？ Fork 并提交 PR

---

📋 更新日志

完整版本历史见 📋 更新日志（遵循 Keep a Changelog 格式，语义化版本）。

📋 表格

版本	日期	要点
Unreleased	-	onnx-primary 引擎切换（ort 默认、candle opt-in）、审计日志 DB/文件双写、同文并发去重、body 上限修正、swagger-ui/ReDoc 文档面、会话外置 database 后端、Grafana 仪表板
0.3.0-rc.2	2026-10-15	转录（Qwen3-ASR）服务面、翻译/语言检测全协议接入、决策任务优先级队列、自研依赖升级
0.3.0-rc.1	2026-09-22	审计修复与调优开关（安全默认值/登录收敛/XFF/RBAC/缓存键、GGUF/LFRU/WAL/硬件规划/doctor/预热）、PARQ 存储替换 oxcache、"generate" 统一接口
0.2.1	2026-07-30	i18n 国际化、Rerank 重排序三协议、语义缓存三级查询、BF16 精度、SIMD 相似度、连续批处理调度、GPU 内存分页、Library 模式
0.2.0	2026-07-24	sdforge 四协议统一生成、7 库生态接线、Matryoshka 截断重归一化、vuln-0009 repo_id 校验
0.1.2	2026-01-16	补丁修订
0.1.1	2026-01-15	补丁修订
0.1.0	2026-01-10	VecBoost 初始发布

0.3.0-rc.1 含多项破坏性行为变更（安全默认值收敛、登录收敛、XFF 信任反转、RBAC 接线、缓存键/分词器变更等），升级必读：逐项「旧行为 → 新行为 → 迁移动作」对照表见 📋 更新日志 · 0.3.0-rc.1。多副本边界（auth 会话默认进程内存，可经 session_backend = "database" 外置；限流/缓存现可经 distributed-redis 外置 Redis——rc.1 时点两者仍为进程内）与热重载语义（配置变更重启后生效）见 ❓ FAQ。

---

📄 许可证

本项目基于 Apache License 2.0 发布 - 查看 LICENSE 文件了解更多。Copyright © 2025-2026 Kirky.X🌠。

---

🙏 致谢

🌟 核心依赖

VecBoost 站在以下优秀开源项目的肩膀上：

📋 表格

依赖	用途
onnxruntime	跨平台推理运行时（默认引擎，经 ort 绑定 + load-dynamic 加载 3rdparty/ 动态库）
candle	原生 Rust ML 推理框架（opt-in 回退后端，candle feature）
tokenizers	HuggingFace 分词器（全平台统一）
hf-hub	HuggingFace Hub 模型下载
trait-kit	模块注册中心与 typestate 依赖管理
confers	配置加载（TOML + 环境变量 + 校验）
inklog	结构化日志基础设施
oxcache	高性能缓存后端
limiteron	令牌桶限流器
dbnexus	数据库持久化（db feature）
sdforge	多协议接口生成
garrison	认证与安全加固（auth feature）
axum	HTTP 框架（由 sdforge 生成）
tokio	异步运行时
utoipa	OpenAPI 文档
prometheus	指标导出
criterion	基准测试
tikv-jemallocator	jemalloc 全局分配器（Linux glibc）

💝 特别感谢

感谢 Rust 社区、Hugging Face（模型与分词器生态）与所有贡献者。

---

📞 联系与支持

Issues 报告问题和 Bug

讨论区 提问和分享想法

GitHub 查看源代码

---

⭐ Star 历史

如果这个项目对您有帮助，请考虑给它一个 ⭐️！

由 Kirky.X 构建

---

_{© 2026 Kirky.X. 保留所有权利。}