使用 LangChain + Hugging Face 构建文本向量化服务

在现代自然语言处理应用中，文本向量化是将非结构化文本转换为数值向量的关键技术，它使得计算机能够理解和处理文本内容。本文将详细介绍如何使用 LangChain 和 Hugging Face 构建一个高效、可扩展的文本向量化服务，重点介绍项目中使用的 BAAI/bge-large-zh-v1.5 模型的使用方式。

项目中使用的模型

我们的文本向量化服务使用的是 BAAI/bge-large-zh-v1.5 模型，这是一个由北京人工智能研究院（BAAI）开发的中文预训练模型。

模型特点

• 大尺寸模型：BAAI/bge-large-zh-v1.5 是一个大尺寸模型，具有更强的语义理解能力
• 中文优化：专门针对中文文本进行了优化，支持多种语言
• 高质量向量：生成的向量具有较高的语义相似度和区分度
• 广泛应用：适用于语义搜索、文本分类、相似度匹配等任务

模型配置

在项目的配置文件 app_config.yaml 中，我们明确指定了使用的模型：

embedding:
  host: localhost
  port: 8081
  model: BAAI/bge-large-zh-v1.5  # 指定使用的预训练模型

模型下载和加载

首次运行时的自动下载

当您第一次初始化向量化服务时，Hugging Face 会自动从 Hugging Face Hub 下载模型到本地缓存中：

# 初始化客户端
embedding_client_manager.init()

第一次运行时会看到类似这样的下载提示：

Downloading (…)lve/main/config.json: 100%|██████████| 1.15k/1.15k [00:00<00:00, 1.15MB/s]
Downloading pytorch_model.bin: 100%|██████████| 1.38G/1.38G [01:23<00:00, 16.5MB/s]
Downloading (…)okenizer_config.json: 100%|██████████| 342/342 [00:00<00:00, 342kB/s]
Downloading (…)solve/main/vocab.txt: 100%|██████████| 110k/110k [00:00<00:00, 110kB/s]

模型下载位置

Hugging Face 会将下载的模型保存在用户的本地缓存中，默认位置为：

C:\Users\<用户名>\.cache\huggingface\transformers\

在该目录下，您会找到一个以模型名称命名的文件夹，其中包含所有必要的文件（如模型权重、配置文件、词汇表等）。

使用 Hugging Face 客户端调用模型

项目使用了 Hugging Face 的客户端库直接加载和使用下载到本地的模型：

# embedding_client_manager.py
from langchain_huggingface import HuggingFaceEmbeddings

class EmbeddingClientManager:
    def __init__(self, config: EmbeddingConfig):
        self.client: HuggingFaceEmbeddings | None = None
        self.config = config

    def init(self):
        # 直接使用 Hugging Face Embeddings 本地加载模型
        self.client = HuggingFaceEmbeddings(
            model_name=self.config.model,
            model_kwargs={"device": "cpu"}
        )

这种方式直接在应用程序中加载和使用模型，而不需要通过网络接口调用外部服务。

系统架构

我们的向量化系统采用了以下架构：

1. 配置管理模块 (app_config.py) - 负责从 YAML 配置文件读取系统参数
2. 客户端管理模块 (embedding_client_manager.py) - 提供单例模式的 Hugging Face Embeddings 客户端管理
3. 服务集成模块 - 与数据代理服务、向量数据库等组件配合工作

核心实现

1. 配置管理

我们使用 OmegaConf 库来管理系统配置，配置文件 app_config.yaml 包含了所有必要的参数：

# app_config.py
from dataclasses import dataclass
from pathlib import Path
from omegaconf import OmegaConf

@dataclass
class EmbeddingConfig:
    host: str
    port: int
    model: str

@dataclass
class AppConfig:
    embedding: EmbeddingConfig

config_file = Path(__file__).parents[2] / 'conf' / 'app_config.yaml'
context = OmegaConf.load(config_file)
schema = OmegaConf.structured(AppConfig)
app_config: AppConfig = OmegaConf.to_object(OmegaConf.merge(schema, context))

2. 客户端管理

EmbeddingClientManager 类实现了单例模式的 Hugging Face Embeddings 客户端管理：

# embedding_client_manager.py
import asyncio
import sys
from pathlib import Path

sys.path.append(str(Path(__file__).parent.parent / "conf"))

from langchain_huggingface import HuggingFaceEmbeddings
from app_config import EmbeddingConfig, app_config

class EmbeddingClientManager:
    def __init__(self, config: EmbeddingConfig):
        self.client: HuggingFaceEmbeddings | None = None
        self.config = config

    def init(self):
        # 直接使用 Hugging Face Embeddings 本地加载模型
        self.client = HuggingFaceEmbeddings(
            model_name=self.config.model,
            model_kwargs={"device": "cpu"}
        )

    async def close(self):
        # 释放资源
        if self.client is not None:
            self.client = None

embedding_client_manager = EmbeddingClientManager(app_config.embedding)

if __name__ == '__main__':
    embedding_client_manager.init()
    client = embedding_client_manager.client

    async def test():
        text = "这是一个测试文本，用于验证向量化是否成功。"
        query_result = await client.aembed_query(text)
        print(query_result[:3])

    asyncio.run(test())

3. 核心功能特性

3.1 单例模式管理

EmbeddingClientManager 类确保整个应用程序中只有一个 Hugging Face Embeddings 客户端实例，避免了重复加载模型导致的资源浪费：

embedding_client_manager = EmbeddingClientManager(app_config.embedding)

3.2 本地模型加载

系统直接从本地或 Hugging Face Hub 加载预训练模型：

self.client = HuggingFaceEmbeddings(
    model_name=self.config.model,
    model_kwargs={"device": "cpu"}
)

3.3 异步操作支持

系统提供了异步查询方法 aembed_query，适合处理高并发场景：

query_result = await client.aembed_query(text)

3.4 资源管理

close 方法用于释放资源，确保系统能够正确地关闭客户端连接：

async def close(self):
    if self.client is not None:
        self.client = None

使用示例

1. 基本使用方法

from app.data_agent.app.clients.embedding_client_manager import embedding_client_manager

# 初始化客户端（首次运行会下载模型）
embedding_client_manager.init()

# 获取客户端实例
client = embedding_client_manager.client

# 文本向量化
text = "这是一个测试文本，用于验证向量化是否成功。"
query_result = await client.aembed_query(text)
print(query_result[:3])  # 输出向量的前3个元素

2. 批量向量化

from app.data_agent.app.clients.embedding_client_manager import embedding_client_manager

# 初始化客户端
embedding_client_manager.init()

# 获取客户端实例
client = embedding_client_manager.client

# 批量处理文本
texts = [
    "这是一个测试文本，用于验证向量化是否成功。",
    "第二个测试文本，用于验证批量处理逻辑。",
    "这是第三个测试文本，用于验证中文向量化效果。"
]

# 批量向量化
document_embeddings = await client.aembed_documents(texts)

# 输出结果
for i, embedding in enumerate(document_embeddings):
    print(f"文本 {i+1} 向量长度: {len(embedding)}")
    print(f"文本 {i+1} 向量前3个元素: {embedding[:3]}")
    print("---")

3. 资源清理

from app.data_agent.app.clients.embedding_client_manager import embedding_client_manager

# 初始化客户端
embedding_client_manager.init()

# 使用客户端...

# 释放资源
await embedding_client_manager.close()

性能优化

1. GPU 加速

如果您的系统支持 GPU，可以通过修改配置文件来启用 GPU 加速：

# 在 init 方法中修改
self.client = HuggingFaceEmbeddings(
    model_name=self.config.model,
    model_kwargs={"device": "cuda"}
)

2. 模型选择

根据应用场景选择合适的预训练模型：

# app_config.yaml
embedding:
  host: "localhost"
  port: 5000
  model: "BAAI/bge-large-zh-v1.5"  # 更大的模型，更高的精度

3. 批量处理优化

对于大规模文本向量化任务，可以使用批量处理方法提高效率：

document_embeddings = await client.aembed_documents(large_text_list)

集成到数据代理服务

这个向量化服务是数据代理服务的核心组件之一，与其他组件配合工作：

1. 数据存储 - 与 Qdrant 向量数据库集成，存储和检索向量
2. 搜索功能 - 与 Elasticsearch 集成，提供全文搜索和语义搜索
3. 自然语言处理 - 与 LLM 服务集成，提供更高级的文本处理功能

部署和监控

1. 系统要求

• Python 3.9+
• Hugging Face Transformers 库
• LangChain 库
• OmegaConf 库

2. 安装依赖

pip install langchain-huggingface transformers sentence-transformers omegaconf

3. 启动服务

from app.data_agent.app.clients.embedding_client_manager import embedding_client_manager

if __name__ == '__main__':
    embedding_client_manager.init()
    print("Embedding service initialized successfully")

4. 监控和日志

系统使用配置文件中的日志设置：

# app_config.yaml
logging:
  file:
    enable: true
    level: "INFO"
    path: "logs/embedding_service.log"
    rotation: "daily"
    retention: "7 days"
  console:
    enable: true
    level: "INFO"

总结

本文详细介绍了如何使用 LangChain 和 Hugging Face 构建一个高效、可扩展的文本向量化服务，重点介绍了项目中使用的 BAAI/bge-large-zh-v1.5 模型的使用方式。

项目使用了 Hugging Face 的客户端库直接加载和使用下载到本地的模型，首次运行时会自动从 Hugging Face Hub 下载模型到本地缓存中，然后在内存中运行。这种方式直接在应用程序中加载和使用模型，而不需要通过网络接口调用外部服务。

我们实现了单例模式的客户端管理、异步操作支持和配置管理功能，并提供了完整的使用示例和性能优化建议。这个向量化服务可以广泛应用于各种自然语言处理任务，如语义搜索、文本分类、相似度匹配等，为现代应用程序提供强大的文本处理能力。