从本地模型到生产级API：将bge-large-zh-v1.5封装为高效文本嵌入服务

2026-02-04 04:54:27作者：冯爽妲Honey

引言

你是否已经能在本地用bge-large-zh-v1.5生成高质量的文本嵌入向量，却苦于无法将其集成到实际应用中？本教程将带你走完从本地脚本到云端API的关键一步，让你的模型真正赋能万千应用场景。通过FastAPI，我们将把这一强大的文本嵌入模型封装为高可用、可扩展的API服务，支持高并发调用，满足生产级需求。

技术栈选型与环境准备

环境准备

创建一个虚拟环境并安装以下依赖：

pip install fastapi uvicorn transformers torch sentence-transformers

核心逻辑封装：适配bge-large-zh-v1.5的推理函数

模型加载

首先，我们需要加载bge-large-zh-v1.5模型。以下代码展示了如何加载模型并将其封装为一个可复用的函数：

from sentence_transformers import SentenceTransformer

def load_model():
    """加载bge-large-zh-v1.5模型"""
    model = SentenceTransformer("BAAI/bge-large-zh-v1.5")
    return model

推理函数

接下来，定义一个推理函数，接收文本输入并返回嵌入向量：

def generate_embeddings(model, text):
    """生成文本的嵌入向量
    
    参数:
        model: 加载的模型
        text (str): 输入文本
    
    返回:
        numpy.ndarray: 文本的嵌入向量
    """
    # 添加查询指令（根据模型要求）
    query_instruction = "为这个句子生成表示以用于检索相关文章："
    text_with_instruction = query_instruction + text
    
    # 生成嵌入向量
    embeddings = model.encode(text_with_instruction)
    return embeddings

API接口设计：优雅地处理输入与输出

FastAPI服务端代码

以下是一个完整的FastAPI服务端代码，提供文本嵌入的API接口：

from fastapi import FastAPI
from pydantic import BaseModel
import numpy as np

app = FastAPI()

# 加载模型
model = load_model()

class TextRequest(BaseModel):
    text: str

@app.post("/embed")
async def embed_text(request: TextRequest):
    """接收文本并返回嵌入向量"""
    embeddings = generate_embeddings(model, request.text)
    return {"embeddings": embeddings.tolist()}  # 转换为列表以便JSON序列化

启动服务

使用以下命令启动服务：

uvicorn main:app --reload

实战测试：验证你的API服务

使用curl测试

curl -X POST "http://127.0.0.1:8000/embed" \
-H "Content-Type: application/json" \
-d '{"text": "这是一个测试句子"}'

使用Python requests测试

import requests

response = requests.post(
    "http://127.0.0.1:8000/embed",
    json={"text": "这是一个测试句子"}
)
print(response.json())

生产化部署与优化考量

部署方案

Gunicorn + Uvicorn：使用Gunicorn作为进程管理器，配合Uvicorn Worker提升并发能力。
```
gunicorn -w 4 -k uvicorn.workers.UvicornWorker main:app
```
Docker：将服务容器化，便于部署和扩展。