BGE-M3简单调用指南：curl/API/Python SDK三种接入方式对比

BGE-M3 是由小贝二次开发构建的句子相似度模型，专门用于检索场景的三合一"多功能"嵌入模型

1. 模型简介与核心价值

BGE-M3 是一个文本嵌入模型，它的独特之处在于同时支持三种检索模式：密集检索、稀疏检索和多向量检索。这意味着你不需要部署多个模型，一个 BGE-M3 就能满足不同场景的检索需求。

模型核心特点：

• 三合一功能：密集向量、稀疏向量、多向量三种输出模式
• 多语言支持：支持100多种语言的文本处理
• 长文本处理：最大支持8192个token的长文档
• 高效推理：默认使用FP16精度加速计算

对于开发者来说，BGE-M3 最大的价值在于简化了检索系统的架构。你不再需要为不同的检索场景维护多个模型，一个 BGE-M3 服务就能覆盖大部分需求。

2. 服务部署与环境准备

在开始调用之前，你需要先部署 BGE-M3 服务。以下是推荐的部署方式：

2.1 快速启动服务

# 使用启动脚本（最简单的方式）
bash /root/bge-m3/start_server.sh

# 或者直接启动
export TRANSFORMERS_NO_TF=1
cd /root/bge-m3
python3 app.py

# 如果需要后台运行
nohup bash /root/bge-m3/start_server.sh > /tmp/bge-m3.log 2>&1 &

2.2 验证服务状态

启动后，通过以下方式检查服务是否正常运行：

# 检查端口是否监听
netstat -tuln | grep 7860

# 或者使用ss命令
ss -tuln | grep 7860

# 查看日志确认运行状态
tail -f /tmp/bge-m3.log

服务正常启动后，你可以通过 http://<服务器IP>:7860 访问Web界面进行测试。

3. curl命令行调用方式

curl 是最直接的调用方式，适合快速测试和简单集成场景。

3.1 基础调用示例

curl -X POST "http://localhost:7860/encode" \
  -H "Content-Type: application/json" \
  -d '{
    "sentences": ["这是一个测试句子", "这是另一个测试句子"],
    "instruction": "为这个句子生成嵌入向量:",
    "batch_size": 32,
    "normalize": true,
    "return_dense": true,
    "return_sparse": false,
    "return_colbert_vecs": false
  }'

3.2 参数详解

• sentences: 需要编码的文本列表
• instruction: 前置指令，帮助模型更好理解任务
• batch_size: 批处理大小，影响处理速度
• normalize: 是否对输出向量进行归一化
• return_dense: 是否返回密集向量
• return_sparse: 是否返回稀疏向量
• return_colbert_vecs: 是否返回ColBERT多向量

3.3 不同模式的调用示例

密集检索模式：

curl -X POST "http://localhost:7860/encode" \
  -H "Content-Type: application/json" \
  -d '{
    "sentences": ["查询天气", "今天天气怎么样"],
    "return_dense": true,
    "return_sparse": false,
    "return_colbert_vecs": false
  }'

稀疏检索模式：

curl -X POST "http://localhost:7860/encode" \
  -H "Content-Type: application/json" \
  -d '{
    "sentences": ["Python编程教程", "Java学习指南"],
    "return_dense": false,
    "return_sparse": true,
    "return_colbert_vecs": false
  }'

混合模式（同时获取多种向量）：

curl -X POST "http://localhost:7860/encode" \
  -H "Content-Type: application/json" \
  -d '{
    "sentences": ["长文档摘要生成", "文本分类任务"],
    "return_dense": true,
    "return_sparse": true,
    "return_colbert_vecs": true
  }'

4. Python SDK调用方式

Python SDK 提供了更友好的编程接口，适合在Python项目中集成。

4.1 安装与基础使用

首先安装必要的依赖：

pip install requests numpy

然后使用以下代码进行调用：

import requests
import json

def encode_with_bge_m3(sentences, modes=None):
    """
    使用BGE-M3编码文本
    
    Args:
        sentences: 文本列表
        modes: 返回模式配置，默认为所有模式
    """
    if modes is None:
        modes = {
            "return_dense": True,
            "return_sparse": True, 
            "return_colbert_vecs": True
        }
    
    url = "http://localhost:7860/encode"
    payload = {
        "sentences": sentences,
        "instruction": "为这个句子生成嵌入向量:",
        "normalize": True,
        **modes
    }
    
    response = requests.post(url, json=payload)
    if response.status_code == 200:
        return response.json()
    else:
        raise Exception(f"请求失败: {response.status_code}")

# 示例调用
sentences = ["机器学习算法", "深度学习模型"]
result = encode_with_bge_m3(sentences)
print("密集向量维度:", len(result['dense_vecs'][0]))
print("稀疏向量特征数:", len(result['sparse_vecs'][0]))

4.2 高级功能封装

为了更好地在项目中使用，我们可以封装一个更完整的客户端类：

import requests
import numpy as np
from typing import List, Dict, Union

class BGE_M3_Client:
    def __init__(self, base_url: str = "http://localhost:7860"):
        self.base_url = base_url
        self.encode_url = f"{base_url}/encode"
    
    def encode(
        self,
        sentences: List[str],
        instruction: str = "为这个句子生成嵌入向量:",
        batch_size: int = 32,
        normalize: bool = True,
        return_dense: bool = True,
        return_sparse: bool = False,
        return_colbert_vecs: bool = False
    ) -> Dict:
        """编码文本并返回指定类型的向量"""
        
        payload = {
            "sentences": sentences,
            "instruction": instruction,
            "batch_size": batch_size,
            "normalize": normalize,
            "return_dense": return_dense,
            "return_sparse": return_sparse,
            "return_colbert_vecs": return_colbert_vecs
        }
        
        try:
            response = requests.post(self.encode_url, json=payload, timeout=30)
            response.raise_for_status()
            return response.json()
        except requests.exceptions.RequestException as e:
            raise Exception(f"API调用失败: {e}")
    
    def encode_dense(self, sentences: List[str]) -> np.ndarray:
        """只获取密集向量"""
        result = self.encode(
            sentences=sentences,
            return_dense=True,
            return_sparse=False,
            return_colbert_vecs=False
        )
        return np.array(result['dense_vecs'])
    
    def encode_sparse(self, sentences: List[str]) -> List[Dict]:
        """只获取稀疏向量"""
        result = self.encode(
            sentences=sentences,
            return_dense=False,
            return_sparse=True,
            return_colbert_vecs=False
        )
        return result['sparse_vecs']
    
    def similarity(self, text1: str, text2: str, mode: str = 'dense') -> float:
        """计算两个文本的相似度"""
        if mode == 'dense':
            vecs = self.encode_dense([text1, text2])
            similarity = np.dot(vecs[0], vecs[1])
            return float(similarity)
        else:
            raise ValueError("暂只支持dense模式相似度计算")

# 使用示例
client = BGE_M3_Client()

# 获取密集向量
dense_vectors = client.encode_dense(["文本1", "文本2"])

# 计算相似度
similarity_score = client.similarity("今天天气真好", "天气不错今天")
print(f"相似度: {similarity_score:.4f}")

5. API直接调用方式

API直接调用适合各种编程语言和环境，提供了最大的灵活性。

5.1 HTTP API接口规范

BGE-M3 服务提供标准的HTTP POST接口：

• 端点: POST /encode
• Content-Type: application/json
• 请求体: JSON格式的参数
• 响应: JSON格式的向量结果

5.2 不同语言的调用示例

JavaScript调用示例：

async function encodeText(sentences) {
    const response = await fetch('http://localhost:7860/encode', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            sentences: sentences,
            instruction: "为这个句子生成嵌入向量:",
            normalize: true,
            return_dense: true,
            return_sparse: false,
            return_colbert_vecs: false
        })
    });
    
    if (!response.ok) {
        throw new Error(`HTTP error! status: ${response.status}`);
    }
    
    return await response.json();
}

// 使用示例
encodeText(["Hello world", "你好世界"])
    .then(result => console.log(result))
    .catch(error => console.error('Error:', error));

Java调用示例：

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpRequest.BodyPublishers;
import java.net.http.HttpResponse.BodyHandlers;
import com.fasterxml.jackson.databind.ObjectMapper;

public class BGE_M3_Client {
    private static final String API_URL = "http://localhost:7860/encode";
    private static final ObjectMapper mapper = new ObjectMapper();
    
    public static String encode(String[] sentences) throws Exception {
        String requestBody = String.format(
            "{\"sentences\": [\"%s\", \"%s\"], \"return_dense\": true}",
            sentences[0], sentences[1]
        );
        
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(API_URL))
                .header("Content-Type", "application/json")
                .POST(BodyPublishers.ofString(requestBody))
                .build();
        
        HttpResponse<String> response = client.send(
            request, BodyHandlers.ofString()
        );
        
        return response.body();
    }
}

6. 三种方式对比与选择建议

6.1 功能对比

特性	curl命令	Python SDK	API调用
易用性	⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐
灵活性	⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐
性能	⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐
错误处理	⭐	⭐⭐⭐⭐⭐	⭐⭐⭐
语言支持	所有支持shell的环境	仅Python	所有编程语言
适合场景	测试调试、简单脚本	Python项目、复杂应用	多语言环境、系统集成

6.2 性能考虑

批处理建议：

• 单次请求处理10-50个句子可获得最佳性能
• 避免频繁发送单个句子的请求
• 根据网络延迟调整batch_size参数

内存使用：

• 密集向量：每个句子1024维float16，约2KB
• 稀疏向量：可变长度，通常比密集向量更节省空间
• ColBERT向量：每个token都有向量，内存使用较多

6.3 选择建议

根据你的具体需求选择合适的调用方式：

1. 快速测试和调试：使用curl命令，最简单直接
2. Python项目开发：使用Python SDK，功能最完整
3. 多语言环境或系统集成：使用API调用，兼容性最好
4. 生产环境部署：推荐Python SDK或封装好的API客户端

7. 实际应用场景示例

7.1 语义搜索应用

# 构建简单的语义搜索引擎
class SemanticSearchEngine:
    def __init__(self, client):
        self.client = client
        self.documents = []
        self.embeddings = []
    
    def add_documents(self, documents):
        """添加文档并生成嵌入"""
        self.documents.extend(documents)
        new_embeddings = self.client.encode_dense(documents)
        if len(self.embeddings) == 0:
            self.embeddings = new_embeddings
        else:
            self.embeddings = np.vstack([self.embeddings, new_embeddings])
    
    def search(self, query, top_k=5):
        """语义搜索"""
        query_embedding = self.client.encode_dense([query])[0]
        similarities = np.dot(self.embeddings, query_embedding)
        top_indices = np.argsort(similarities)[-top_k:][::-1]
        
        return [(self.documents[i], similarities[i]) for i in top_indices]

# 使用示例
search_engine = SemanticSearchEngine(client)
search_engine.add_documents([
    "机器学习是人工智能的一个分支",
    "深度学习使用神经网络进行学习",
    "自然语言处理处理文本数据"
])

results = search_engine.search("人工智能技术", top_k=3)
for doc, score in results:
    print(f"相似度: {score:.3f} - {doc}")

7.2 混合检索策略

def hybrid_retrieval(query, documents, dense_weight=0.7, sparse_weight=0.3):
    """混合检索：结合密集和稀疏检索的结果"""
    # 密集检索
    dense_results = client.encode_dense([query] + documents)
    query_dense = dense_results[0]
    doc_dense = dense_results[1:]
    dense_scores = [np.dot(query_dense, doc_vec) for doc_vec in doc_dense]
    
    # 稀疏检索（简化示例）
    sparse_scores = [0.5] * len(documents)  # 实际应计算稀疏相似度
    
    # 混合评分
    combined_scores = [
        dense_weight * dense_scores[i] + sparse_weight * sparse_scores[i]
        for i in range(len(documents))
    ]
    
    # 返回排序结果
    sorted_indices = np.argsort(combined_scores)[::-1]
    return [(documents[i], combined_scores[i]) for i in sorted_indices]

8. 总结与最佳实践

BGE-M3 提供了三种灵活的调用方式，每种方式都有其适用场景。通过本文的对比和示例，你应该能够选择最适合自己需求的方式。

关键实践建议：

1. 批量处理：尽量一次性处理多个文本，提高效率
2. 模式选择：根据具体场景选择合适的输出模式
3. 错误处理：在生产环境中添加完善的错误处理和重试机制
4. 性能监控：监控API调用延迟和成功率
5. 版本管理：注意模型版本更新可能带来的接口变化

选择指南：

• 如果你是初学者或进行简单测试，从curl命令开始
• 如果你在开发Python项目，使用封装的Python SDK
• 如果你需要跨语言集成，直接调用HTTP API

无论选择哪种方式，BGE-M3 的强大功能都能为你的检索应用提供有力支持。记得根据实际需求调整参数配置，才能获得最佳的效果和性能。

---

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。