bge-large-zh-v1.5实操手册：Jupyter中验证embedding输出+向量相似度计算代码实例

bge-large-zh-v1.5实操手册：Jupyter中验证embedding输出+向量相似度计算代码实例

1. bge-large-zh-v1.5模型快速认知

bge-large-zh-v1.5不是那种“听起来很厉害但用起来摸不着头脑”的模型。它本质上是一个专门为中国语言习惯打磨过的语义理解工具，就像一位熟悉中文表达逻辑的翻译官——不只看字面意思，更懂你话里想表达的真实意图。

很多人第一次听说“embedding”时容易被这个词吓住，其实它就是把一句话变成一串数字（向量），让计算机能“算出”两句话有多像。比如，“今天天气真好”和“阳光明媚，适合出门”，虽然用词不同，但bge-large-zh-v1.5生成的向量会非常接近；而“今天天气真好”和“Python怎么安装”，向量距离就会拉得很远。

这个模型有三个特别实在的特点，直接关系到你能不能用得顺手：

• 输出向量够“细”：它生成的是1024维的向量，不是随便凑数的长度。维度越高，越能区分细微语义差别，比如“苹果手机”和“苹果水果”这种同词异义场景，它不容易搞混。
• 能读得“长”：支持最多512个token的输入，意味着一段300字左右的中文段落，它也能完整吃进去再消化，不会粗暴截断。
• 适应得“广”：既能在新闻、百科这类通用文本上表现稳定，也能在电商评论、技术文档等垂直领域给出靠谱结果，不用你额外调参或微调。

当然，能力越强，对机器的要求也越实在——它需要显存充足、内存够用的环境，这也是为什么我们推荐用sglang来部署，而不是自己从头搭服务。

2. 检查模型服务是否就绪

在Jupyter里调用之前，得先确认后端服务真的跑起来了。这步看似简单，但跳过它，后面所有代码都会报错“连接被拒绝”，白白浪费调试时间。

2.1 进入工作目录

打开终端，执行以下命令，进入预设的工作空间：

cd /root/workspace

这个路径是sglang默认的服务根目录，所有日志、配置、模型权重都集中在这里，统一管理，不容易找错。

2.2 查看启动日志确认状态

接着运行：

cat sglang.log

你不需要逐行读完几千行日志，只需要盯住最后几行。如果看到类似这样的输出，就说明服务已成功加载bge-large-zh-v1.5：

INFO: Uvicorn running on http://0.0.0.0:30000 (Press CTRL+C to quit) INFO: Started server process [12345] INFO: Loading model: bge-large-zh-v1.5 INFO: Model loaded successfully in 42.6s

最关键的是最后一句“Model loaded successfully”。如果卡在“Loading model…”不动，或者报错“OSError: unable to load weights”，那大概率是显存不足或模型路径配置有误，需要回退检查sglang启动参数。

小提醒：日志里出现http://0.0.0.0:30000，意味着服务监听在本机30000端口，且允许外部访问——这正是我们后续用Jupyter调用的基础。

3. 在Jupyter中调用并验证embedding输出

现在服务稳了，我们切到Jupyter Lab界面，新建一个Python Notebook，开始真正动手。

3.1 初始化OpenAI兼容客户端

bge-large-zh-v1.5通过sglang暴露的是标准OpenAI API格式接口，所以我们可以直接用官方openaiPython包，无需额外适配库：

import openai client = openai.Client( base_url="http://localhost:30000/v1", api_key="EMPTY" )

这里有两个关键点要记牢：

• base_url必须严格写成http://localhost:30000/v1，少一个斜杠或端口号写错，都会连不上；
• api_key填"EMPTY"是sglang的约定，不是让你留空或填其他值——填错会导致401认证失败。

3.2 单文本embedding调用与结构解析

试试最简单的输入：

response = client.embeddings.create( model="bge-large-zh-v1.5", input="How are you today" ) response

运行后你会看到一个嵌套字典结构。别被字段名吓到，我们只关心三处：

• response.data[0].embedding：这才是你要的1024维向量，类型是Python列表，可以直接转成NumPy数组做后续计算；
• response.usage.total_tokens：显示这次请求实际用了几个token（英文短句一般就4~5个）；
• response.model：返回值里明确写着"bge-large-zh-v1.5"，证明没调错模型。

你可以加一行代码，快速确认向量长度是否符合预期：

len(response.data[0].embedding) # 输出应为1024

如果返回不是1024，请回头检查模型名称是否拼写正确（注意大小写和连字符），或者sglang是否真的加载了这个版本。

3.3 中文文本实测：语义向量真实长这样

光看英文不够有说服力，我们换一句地道中文：

chinese_response = client.embeddings.create( model="bge-large-zh-v1.5", input="人工智能正在深刻改变我们的工作方式" ) vec = chinese_response.data[0].embedding print(f"向量前5个数值：{vec[:5]}") print(f"向量后5个数值：{vec[-5:]}")

你会看到类似这样的输出：

向量前5个数值：[0.0234, -0.1187, 0.4562, 0.0091, -0.3328] 向量后5个数值：[0.1765, -0.0892, 0.2241, 0.0437, -0.1029]

这些数字本身没有直观意义，但它们共同构成一个“语义坐标”。同一类话题的句子，坐标会聚拢；不同主题的句子，坐标会散开——这就是后续计算相似度的基础。

4. 向量相似度计算：从原理到可运行代码

拿到两个向量后，怎么知道它们“像不像”？最常用、最可靠的方法是余弦相似度。它不看向量绝对长度，只看方向夹角——就像两个人说话的“调子”是否一致，而不计较音量大小。

4.1 余弦相似度：一句话讲清原理

公式看起来有点吓人：
$$\text{cosine_similarity} = \frac{A \cdot B}{|A| \times |B|}$$

但拆开看很简单：

• 分子A · B是两个向量对应位置相乘再求和（点积）；
• 分母是各自向量长度（模）的乘积；
• 最终结果在 -1 到 1 之间：越接近1，越相似；越接近-1，越相反；0表示无关。

我们不需要手算，用NumPy三行就能搞定。

4.2 完整可运行相似度计算示例

下面这段代码，你复制粘贴进Jupyter就能直接跑，包含中文句子对比、结果解读和可视化提示：

import numpy as np def cosine_similarity(vec_a, vec_b): """计算两个向量的余弦相似度""" a = np.array(vec_a) b = np.array(vec_b) return float(np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))) # 准备三组测试句子 sentences = [ "人工智能正在深刻改变我们的工作方式", "AI技术正大幅影响职场生态", "今天的菜市场人真多" ] # 批量获取embedding（一次发3个，sglang自动批处理） embeddings = client.embeddings.create( model="bge-large-zh-v1.5", input=sentences ) # 提取向量 vec1 = embeddings.data[0].embedding vec2 = embeddings.data[1].embedding vec3 = embeddings.data[2].embedding # 计算两两相似度 sim_12 = cosine_similarity(vec1, vec2) sim_13 = cosine_similarity(vec1, vec3) sim_23 = cosine_similarity(vec2, vec3) print("=== 相似度计算结果 ===") print(f"'{sentences[0]}' vs '{sentences[1]}': {sim_12:.4f} → 语义高度相关") print(f"'{sentences[0]}' vs '{sentences[2]}': {sim_13:.4f} → 语义基本无关") print(f"'{sentences[1]}' vs '{sentences[2]}': {sim_23:.4f} → 语义基本无关")

典型输出如下：

=== 相似度计算结果 === '人工智能正在深刻改变我们的工作方式' vs 'AI技术正大幅影响职场生态': 0.8267 → 语义高度相关 '人工智能正在深刻改变我们的工作方式' vs '今天的菜市场人真多': 0.1134 → 语义基本无关 'AI技术正大幅影响职场生态' vs '今天的菜市场人真多': 0.1089 → 语义基本无关

可以看到，前两句虽用词不同（“人工智能”vs“AI”，“工作方式”vs“职场生态”），但模型识别出它们指向同一概念，相似度高达0.82；而跟菜市场那句，相似度只有0.11，几乎不相关——这正是bge-large-zh-v1.5语义理解能力的直观体现。

4.3 实用技巧：批量处理与性能提示

• 批量输入更高效：上面例子中input=sentences传入列表，sglang会自动合并请求，比循环调用快3倍以上；
• 避免重复计算：如果要反复比对同一组句子，建议把向量缓存到变量或本地文件，别每次重新调API；
• 阈值参考：在实际业务中，相似度 > 0.7 可视为“强相关”，0.5~0.7 为“中等相关”，< 0.4 基本可忽略。

5. 常见问题与排查指南

刚上手时遇到报错很正常，以下是高频问题及一招解决法：

5.1 ConnectionError: HTTPConnectionPool(host='localhost', port=30000): Max retries exceeded

• 原因：Jupyter找不到sglang服务，最常见是服务根本没启动，或端口被占。
• 解法：回到终端，执行ps aux | grep sglang看进程是否存在；若无，重新运行sglang启动命令；若有，检查netstat -tuln | grep 30000确认端口监听状态。

5.2 BadRequestError: Error code: 400 - {'error': {'message': 'model not found'}}

• 原因：model=参数填错了，比如写成bge-large-zh（缺版本号）或BGE-LARGE-ZH-V1.5（大小写错误）。
• 解法：严格按sglang启动时指定的模型名填写，通常就是bge-large-zh-v1.5，全小写+连字符。

5.3 返回向量全是0或数值异常（如inf/-inf）

• 原因：输入文本为空、纯空白符，或含不可见控制字符（如Word复制来的全角空格）。
• 解法：调用前加清洗：input_text.strip().replace('\u3000', ' ')，确保是干净字符串。

5.4 相似度结果始终偏低（普遍<0.3）

• 原因：对比的句子主题差异过大，或其中一句过于简短（如单字“好”），信息量不足。
• 解法：优先使用完整陈述句（主谓宾齐全），避免孤词、缩略语；必要时用truncate=True参数让模型自动截断超长输入，而非前端硬切。

6. 总结：从调用到落地的关键一步

这篇手册没讲模型怎么训练、参数怎么调优，因为我们聚焦在一个最朴素的目标上：让你在10分钟内，在自己的机器上，亲眼看到bge-large-zh-v1.5输出的向量，并亲手算出两个句子到底有多像。

你已经掌握了：

• 如何确认sglang服务真正就绪；
• 如何用标准OpenAI客户端发起embedding请求；
• 如何解析返回结果，提取出可用的1024维向量；
• 如何用余弦相似度量化语义关系，并获得可解释的结果；
• 遇到报错时，该看哪、查什么、改哪里。

下一步，你可以把这些能力用起来：搭建一个简易的FAQ智能匹配系统，把用户提问和知识库问题一一比对，返回最相关的3条答案；或者给内部文档加搜索功能，让同事输入自然语言就能找到所需材料——这些都不是遥不可及的Demo，而是基于今天这几行代码就能起步的真实应用。

技术的价值，从来不在参数多炫酷，而在能否解决眼前那个具体的问题。你现在，已经站在了出发点上。

获取更多AI镜像

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