用langchain 通过text-embedding-3-small生成embedding

OpenAIEmbedding介绍

在构建智能搜索或推荐系统时，将文本转化为机器能理解的向量（Embedding）是关键一步。OpenAI提供的Embedding接口，通过LangChain来调用会非常方便。它主要提供了两个方法，分别对应不同的应用场景。

• embed_query：这个方法专为生成单个查询文本的向量设计。简单来说，当用户输入一个问题或关键词进行搜索时，就用它来处理这个“查询端”的文本。
• embed_documents：与前者对应，这个方法用于批量处理多个文档文本。在构建知识库、为大量文档建立索引时，它就是处理“文档端”的主力。

两者分工明确，一个应对实时查询，一个处理后台数据准备，共同支撑起向量检索的流程。

实现步骤

整个流程可以清晰地分为四个步骤，按部就班操作即可：

1. 申请OpenAI的API Key：这是调用所有OpenAI服务的前提，需要在OpenAI官网获取。
2. 安装LangChain库：在Python环境中，通过pip install langchain-openai等命令安装必要的包。
3. 构建结构化文档：将你需要向量化的文本内容（比如用户资料、产品描述）整理成模型接受的格式，通常是清晰的字符串或JSON结构。
4. 调用模型生成Embedding：初始化OpenAIEmbeddings客户端，传入准备好的文本，即可获得对应的向量数组。

具体代码

下面我们通过三段核心代码，来看看具体如何实现。

批量生成向量

当你有一批文档（比如多个用户画像）需要处理时，使用embed_documents方法是最高效的选择。这段代码展示了如何批量生成向量，并输出一些基本信息用于验证。

from langchain_openai import OpenAIEmbeddings
from app.config import EnvConfig
from common.Logger import getLogger

logger = getLogger("embedding_generator.py")

def bulk_generate_user_embedding(documents: list[str]):
    """
    :param documents: 生成用于生成embeddings的结构化文档
    :return: 返回批量生成的向量列表
    """
    # 1. 获取配置
    api_key = EnvConfig.OPENAI_API_KEY
    openai_api_base = EnvConfig.OPENAI_API_BASE
    if not api_key or not openai_api_base:
        logger.error("未找到 OPENAI_API_KEY 环境变量。")
        return None

    # 2. 初始化模型
    # model: 指定模型名称，如 'text-embedding-3-small'
    # temperature: 控制输出的随机性，0 为最确定，1 为最随机
    embeddings = OpenAIEmbeddings(
        model="text-embedding-3-small",
        api_key=api_key,
        openai_api_base=openai_api_base
    )

    # 3. 批量生成文档向量
    doc_vectors = embeddings.embed_documents(documents)
    print(f"\n生成了 {len(doc_vectors)} 个文档向量")

    if len(doc_vectors) > 0:
        print(f"每个向量维度: {len(doc_vectors[0])}")

    return doc_vectors

生成单个向量

对于实时的搜索查询，我们需要将用户的输入快速转化为向量。下面的generate_user_embedding函数封装了这个过程，并包含了详细的日志记录，方便调试。

def generate_user_embedding(query_text: str):
    """
    :param query_text: 准备的格式化JSON文件
    :return:
    """
    api_key = EnvConfig.OPENAI_API_KEY
    openai_api_base = EnvConfig.OPENAI_API_BASE
    if not api_key or not openai_api_base:
        logger.error("未找到 OPENAI_API_KEY 环境变量。")
        return None

    # 2. 初始化模型
    # model: 指定模型名称，这里用 'text-embedding-3-small'
    # temperature: 控制输出的随机性，0 为最确定，1 为最随机
    embeddings = OpenAIEmbeddings(
        model="text-embedding-3-small",
        api_key=api_key,
        openai_api_base=openai_api_base
    )

    # 3. Embedding查询
    query_vector = embeddings.embed_query(query_text)
    logger.debug(f"查询向量维度: {len(query_vector)}")
    logger.debug(f"查询向量前5个值: {query_vector[:5]}")
    return query_vector

生成的构建化文档方法如下

无论是批量处理还是单条查询，前提都是把原始数据转换成高质量的文本。这个build_profile_text函数是一个很好的例子，它把分散的用户属性（角色、岗位、技能等）拼接成一个结构清晰、用分隔符隔开的字符串，这样生成的Embedding才能更准确地捕捉语义信息。

def build_profile_text(profile) -> str:
    """构建用于向量化的结构化文本"""
    parts = [
        f"角色: {profile.role}",
        f"岗位: {profile.title}",
        f"介绍: {profile.bio}",
        f"行业: {profile.industry_tags}",
        f"城市: {profile.city}",
        f"技能: {profile.skill_tags}"
    ]
    return " | ".join(parts)

至此，从数据准备、模型调用到向量生成，一个完整的流程就清晰了。关键在于理解两个核心方法的不同用途，并确保输入模型的文本是经过精心结构化的，这样才能让后续的相似度计算或语义搜索达到最佳效果。