# Sentence-BERT

**Repository Path**: fatcat2018/sentence-bert

## Basic Information

- **Project Name**: Sentence-BERT
- **Description**: 一个基于FastAPI+sentence_transformers+Chroma+paraphrase-multilingual-MiniLM-L12-v2实现的语义检索Demo
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-09-17
- **Last Updated**: 2026-01-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 语义检索的实现方案
## 一、技术路线
```
                          ┌──────────────────┐
                          │   档案文档库       │
                          │ (PDF/Word/OFD)    │
                          └────────┬─────────┘
                                   │
                   Apache Tika / Tesseract OCR
                                   │
                                   ▼
                     ┌─────────────────────────┐
                     │   提取纯文本（每篇文档）  │
                     └─────────────────────────┘
                                   │
                                   ▼
              ┌─────────────────────────────────────────┐
              │    Sentence-BERT：将每篇文档向量化        │
              └─────────────────────────────────────────┘
                                   │
                                   ▼
                     ┌─────────────────────────┐
                     │     存入向量数据库 Chroma  │
                     │   （本地文件存储，无需服务器）│
                     └─────────────────────────┘

用户查询 ──→ "任正非" ──→ Sentence-BERT 向量化 ──→ Chroma 检索最相似文档 ──→ 返回结果
```
## 二、模型选择
### 2.1 文本向量模型对比
|项目	|paraphrase-multilingual-MiniLM-L12-v2	|all-MiniLM-L6-v2|
| -------- | -------- | -------- |
|模型架构	|MiniLM, 12层 Transformer	|MiniLM, 6层 Transformer|
|语言支持	|✅✅✅ 支持 50+ 种语言（含中文）	|❌ 仅支持 英文|
|中文能力	|✅✅✅ 强（专为多语言优化）	|❌ 不支持中文|
|向量维度	|384	|384|
|模型大小	|~110MB	|~80MB|
|推理速度	|较慢（12层）	|✅ 更快（6层）|
|语义匹配效果（英文）	|好	|✅✅ 略优（在英文 STS 任务上得分更高）|
|适合任务	|多语言检索、中文语义搜索	|英文句子相似度、快速检索|

### 2.2图像向量模型对比
|项目	|clip-ViT-B-32（原始版）	|sentence-transformers/clip-ViT-B-32-multilingual-v1（多语言优化版）|
| -------- | -------- | -------- |
|来源	|OpenAI 原始 CLIP 模型	|Sentence-Transformers 团队在原始 CLIP 基础上微调|
|训练数据	|英文为主（laion-400m）	|额外加入 多语言图文对（包括中文）|
|中文语义理解	|❌ 一般（依赖翻译对齐）	|✅✅ 显著增强（专门优化过）|
|是否支持中文“以文搜图”	|⚠️ 可用，但效果不稳定	|✅ 推荐，中文查询更准|
|模型大小	|~300MB	|~300MB（相同架构）|
|推理速度	|相同	|相同|
|加载方式	|SentenceTransformer('clip-ViT-B-32')	|SentenceTransformer('sentence-transformers/clip-ViT-B-32-multilingual-v1')|
## 三、部署
### 3.1 系统版本

```shell
[root@localhost var]# uname -a
Linux localhost.localdomain 4.19.90-89.11.v2401.ky10.x86_64 #1 SMP Tue May 7 18:33:01 CST 2024 x86_64 x86_64 x86_64 GNU/Linux
[root@localhost var]# cat /etc/os-release 
NAME="Kylin Linux Advanced Server"
VERSION="V10 (Halberd)"
ID="kylin"
VERSION_ID="V10"
PRETTY_NAME="Kylin Linux Advanced Server V10 (Halberd)"
ANSI_COLOR="0;31"
```

### 3.2 Python环境的安装

**注意：** 以下四个步骤，第一步离线在线都可以；剩余三步需要在线环境。

#### 3.2.1 下载Miniforge安装包

Miniforge 是一个轻量级的 **Conda 发行版**

**Miniforge**  **=**  **Miniconda + 默认使用 conda-forge + 预装 Mamba + 更好的新硬件支持**

```shell
# x86_64
https://github.com/conda-forge/miniforge/releases/download/25.3.1-0/Miniforge3-25.3.1-0-Linux-x86_64.sh

# aarch64（）
https://github.com/conda-forge/miniforge/releases/download/25.3.1-0/Miniforge3-25.3.1-0-Linux-aarch64.sh
```

#### 3.2.2 增加可执行权限

```shell
chmod +x Miniforge3-25.3.1-0-Linux-x86_64.sh
```

#### 3.2.3 创建虚拟环境并安装项目所需依赖

```shell
# 安装 Conda 环境
./Miniforge3-25.3.1-0-Linux-x86_64.sh -p /opt/miniforge3 -b

# 进入到envs目录
cd /opt/miniforge3/envs

# 创建虚拟环境
/opt/miniforge3/bin/conda create -n Sentence-BERT python=3.9

# 激活虚拟环境
source /opt/miniforge3/bin/activate Sentence-BERT

# 创建requirements.txt
vi requirements.txt

# 内容如下
fastapi==0.116.2
uvicorn==0.35.0
sentence-transformers==5.1.0
torch==2.8.0
chromadb==1.1.0
 
# 安装项目依赖（此命令会占用大量的内存RAM空间，建议内存16G起步）
/opt/miniforge3/envs/Sentence-BERT/bin/pip install -r requirements.txt

# 测试
python -c 'from sentence_transformers import SentenceTransformer; print("Environment works!")'
```

### 3.3 Python环境迁移

**前提条件：** 已成功安装Miniforge。

在线环境下打包虚拟环境：

```shell
cd /opt/miniforge3/envs
tar -czf Sentence-BERT.tar.gz Sentence-BERT
```

将打包好的`tar -czf Sentence-BERT.tar.gz Sentence-BERT`拷贝到离线环境下，再执行如下命令：

```shell
# 检查目录/opt/miniforge3/envs是否存在，不存在创建，存在直接跳过
mkdir -p /opt/miniforge3/envs

# 解压
tar -xzf Sentence-BERT-x86.tar.gz -C /opt/miniforge3/envs/

# 修复路径权限
sudo chown -R root:root /opt/miniforge3/envs/Sentence-BERT
```

### 3.4 模型拷贝

模型包名称：`huggingface.zip`

拷贝路径：

```shell
# 本文档基于root用户部署，所以在root目录下
/root/.cache/huggingface.zip
```

解压后的路径：

```shell
/root/.cache/huggingface
```

### 3.5 启动工程

在激活的虚拟环境下执行如下命令：

```shell
python /opt/miniforge3/envs/Sentence-BERT/sentence-bert-master/app/app.py
```

如果出现缺少`db_utils`报错，执行如下命令：

```shell
cd /opt/miniforge3/envs/Sentence-BERT/sentence-bert-master
export PYTHONPATH=$(pwd):$PYTHONPATH
python app/app.py
```
### 3.6 添加自启动服务
创建systemd服务文件 `/etc/systemd/system/sentencebert.service`：
```
[Unit]
Description=Sentence-BERT
After=network.target

[Service]
User=root
Group=root
WorkingDirectory=/opt/miniforge3/envs/Sentence-BERT/sentence-bert-master
Environment=PYTHONPATH=/opt/miniforge3/envs/Sentence-BERT/sentence-bert-master
Environment=TRANSFORMERS_OFFLINE=1
ExecStart=/opt/miniforge3/envs/Sentence-BERT/bin/python /opt/miniforge3/envs/Sentence-BERT/sentence-bert-master/app/app.py
Restart=always

[Install]
WantedBy=multi-user.target
```
添加可执行权限：
```
chmod +x /etc/systemd/system/sentencebert.service
```
启动服务：
```
systemctl daemon-reexec
systemctl enable sentencebert
systemctl start sentencebert
```
查看日志：
```
journalctl -u sentencebert.service -f
```