从0开始学文本嵌入：bge-large-zh-v1.5镜像小白入门教程-编程阁

从0开始学文本嵌入：bge-large-zh-v1.5镜像小白入门教程

1. 学习目标与前置知识

本文是一篇面向初学者的文本嵌入（Text Embedding）实战入门指南，聚焦于如何使用基于sglang部署的bge-large-zh-v1.5中文嵌入模型服务。通过本教程，你将掌握：

文本嵌入的基本概念及其应用场景
如何验证bge-large-zh-v1.5模型服务是否正常运行
使用 OpenAI 兼容接口调用本地部署的 embedding 模型
实际代码示例与常见问题排查方法

前置知识要求

基础 Linux 命令行操作能力
Python 编程基础（了解函数、变量和库导入）
对“向量”和“语义表示”有初步理解（非必须）

提示：本文所涉及的操作均在已预装bge-large-zh-v1.5镜像的环境中进行，无需手动下载或配置模型。

2. bge-large-zh-v1.5 模型简介

2.1 什么是文本嵌入？

文本嵌入（Text Embedding）是将自然语言文本转换为固定长度的高维向量的过程。这些向量能够捕捉词语、句子甚至段落之间的语义相似性。例如，“猫”和“狗”的向量距离会比“猫”和“汽车”更近。

这类技术广泛应用于：

语义搜索
相似文档匹配
聚类分析
推荐系统
RAG（检索增强生成）架构中的召回模块

2.2 bge-large-zh-v1.5 核心特性

bge-large-zh-v1.5是由北京智源人工智能研究院（BAAI）发布的高性能中文文本嵌入模型，具备以下关键优势：

高维向量输出：生成 1024 维向量，提供更强的语义区分能力
长文本支持：最大可处理 512 个 token 的输入文本
多领域适应性强：在通用语料、新闻、百科及部分垂直领域均有良好表现
开源免费：可在 Hugging Face 或 ModelScope 下载使用

该模型特别适合需要高精度中文语义理解的任务场景。

3. 环境准备与服务状态检查

3.1 进入工作目录

首先，确保进入正确的项目工作路径：

cd /root/workspace

此目录通常包含日志文件、脚本和 Jupyter Notebook 示例。

3.2 查看模型启动日志

模型通过sglang框架部署后，其运行状态可通过日志文件确认：

cat sglang.log

成功启动标志

当看到类似如下输出时，说明bge-large-zh-v1.5模型服务已成功加载并监听请求：

INFO: Started server process [12345] INFO: Waiting for application startup. INFO: Application startup complete. INFO: Uvicorn running on http://0.0.0.0:30000 (Press CTRL+C to quit)

此外，日志中应包含"Loading model: bge-large-zh-v1.5"字样，表明模型正在初始化。

注意：若日志中出现CUDA out of memory或Model not found错误，请检查 GPU 显存是否充足或模型路径是否正确。

4. 调用 bge-large-zh-v1.5 模型生成嵌入向量

4.1 安装依赖库（如未安装）

虽然镜像中通常已预装所需库，但仍建议确认openai库已安装：

pip install openai

注意：此处使用的openai是官方 SDK，但我们将它用于兼容 OpenAI API 格式的本地服务。

4.2 初始化客户端连接

由于模型服务运行在本地http://localhost:30000/v1，我们需配置自定义 base URL 并使用空 API 密钥连接：

import openai client = openai.Client( base_url="http://localhost:30000/v1", api_key="EMPTY" # 因为本地服务无需真实密钥 )

4.3 发起嵌入请求

调用client.embeddings.create()方法即可获取文本的向量表示：

# 单条文本嵌入 response = client.embeddings.create( model="bge-large-zh-v1.5", input="今天天气怎么样？" ) print(response)

输出结构解析

返回结果是一个Embeddings对象，主要字段包括：

data: 包含嵌入向量的列表，每个元素对应一个输入文本
embedding: 实际的浮点数向量（长度为 1024）
model: 使用的模型名称
usage: token 使用统计信息

示例输出片段：

{ "object": "list", "data": [ { "object": "embedding", "index": 0, "embedding": [0.023, -0.156, ..., 0.089] // 1024维向量 } ], "model": "bge-large-zh-v1.5", "usage": { "prompt_tokens": 9, "total_tokens": 9 } }

5. 批量文本嵌入实践

实际应用中，往往需要对多个句子同时编码以提升效率。

5.1 批量输入示例

texts = [ "我喜欢吃苹果", "香蕉是一种热带水果", "机器学习正在改变世界", "深度神经网络很强大" ] response = client.embeddings.create( model="bge-large-zh-v1.5", input=texts ) # 提取所有向量 embeddings = [item.embedding for item in response.data] print(f"共生成 {len(embeddings)} 个向量，每个维度为 {len(embeddings[0])}")

输出：

共生成 4 个向量，每个维度为 1024

5.2 向量相似度计算（余弦相似度）

我们可以利用生成的向量计算语义相似度。以下是使用numpy和sklearn计算余弦相似度的示例：

import numpy as np from sklearn.metrics.pairwise import cosine_similarity # 将列表转为 NumPy 数组 vectors = np.array(embeddings) # 计算相似度矩阵 similarity_matrix = cosine_similarity(vectors) print("语义相似度矩阵：") print(similarity_matrix.round(3))

输出示例：

语义相似度矩阵： [[1. 0.456 0.321 0.298] [0.456 1. 0.301 0.276] [0.321 0.301 1. 0.876] [0.298 0.276 0.876 1. ]]

可见，“机器学习正在改变世界”与“深度神经网络很强大”之间语义最接近（相似度达 0.876），符合预期。

6. 常见问题与解决方案

6.1 请求失败：Connection Refused

现象：调用时报错ConnectionError: Cannot connect to host localhost:30000

原因：

sglang服务未启动
端口被占用或绑定错误

解决方法：

检查日志：cat sglang.log
重启服务容器或重新部署模型
确认端口监听：netstat -tuln | grep 30000

6.2 输入文本过长导致截断

现象：长文本被自动截断至 512 token

说明：bge-large-zh-v1.5支持最长 512 token 输入，超出部分会被截断。

建议处理方式：

分句处理后取平均向量
使用滑动窗口策略合并片段向量
对于超长文档，考虑使用专用文档级嵌入模型

6.3 向量维度不符

现象：期望得到 1024 维，但实际输出不同

检查点：

是否误用了其他版本模型（如bge-base-zh-v1.5输出 768 维）
模型名称拼写是否准确：bge-large-zh-v1.5

可通过打印len(embedding)验证维度。

7. 总结

7.1 核心要点回顾

本文带你完成了从零开始使用bge-large-zh-v1.5模型的完整流程：

理解文本嵌入的意义：将文字转化为可计算的向量形式
验证模型服务状态：通过日志确认sglang成功加载模型
调用本地 embedding 接口：使用 OpenAI 兼容客户端发起请求
实现批量嵌入与相似度分析：构建语义匹配基础能力
掌握常见问题应对策略：连接异常、长度限制、维度校验等

7.2 最佳实践建议

优先使用批量输入：减少网络开销，提高吞吐效率
缓存常用文本向量：避免重复计算，提升响应速度
结合业务场景微调阈值：设定合理的相似度判断边界（如 >0.7 视为相关）
监控资源消耗：大模型对显存要求较高，注意并发控制

随着你在 RAG、智能客服、内容推荐等领域的深入探索，bge-large-zh-v1.5将成为你构建语义理解系统的有力工具。

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

从0开始学文本嵌入：bge-large-zh-v1.5镜像小白入门教程