SGLang服务BGE-M3嵌入模型时--is-embedding启用后输出向量维度的核对

在SGLang中服务BGE-M3嵌入模型时，启用`--is-embedding`后，输出向量的维度通常应等于模型原生的dense向量维度，BGE-M3一般为1024维。核对时不能只看模型名称，也不能假设所有嵌入接口返回的都是同一个维度的数组，需要直接对请求返回的JSON结构做长度校验，并区分dense和sparse输出。

判断核心：BGE-M3的标准dense向量维度是1024。启用`--is-embedding`后，SGLang的/v1/embeddings接口应返回一个包含dense向量的对象，其embedding数组长度应为1024。如果得到4096或其他长度，优先确认模型加载方式、是否需要额外开启其他输出层，以及请求参数是否误用了分块返回。核对方法是拿一个文本请求接口，数返回数组的长度，同时对比模型配置中的hidden_size。

先明确BGE-M3的输出形态

BGE-M3是一个多向量输出模型，支持dense、sparse和colbert三种表示。SGLang的`--is-embedding`参数只负责把模型切换为嵌入服务模式，不保证返回所有类型的向量。通常该模式返回的是dense向量，也就是模型最后一层隐藏状态经过池化后的定长向量。BGE-M3的dense维度是1024，这个值来自模型结构，不随输入长度变化。

因此，核对维度的第一步不是看SGLang的参数，而是确认你期望拿到哪种语义向量。如果只需要文本嵌入，那么1024就是基准。如果后续还有检索或相似度计算，维度不对会直接影响归一化和内积结果。

启动SGLang服务时的参数写法

启动命令只需显式带上`--is-embedding`，并给出模型路径。以下是一个通用骨架：

python -m sglang.launch_server \
    `--model-path` BAAI/bge-m3 \
    `--host` 0.0.0.0 \
    `--port` 30000 \
    `--is-embedding`

注意，如果模型没有正确切换到嵌入模式，SGLang可能仍按语言模型返回logits，而不是嵌入向量。另外，`--is-embedding`并不是SGLang所有版本都存在的参数，如果你的启动命令报参数不识别，需要先确认本地SGLang的版本和入口。可以执行python -m sglang.launch_server `--help`查看当前支持的参数。建议先不加`--is-embedding`运行一次，再用同一个模型路径启动时加上该参数，对比接口返回的字段变化。

请求接口并核对维度

SGLang在嵌入模式下会暴露OpenAI兼容的/v1/embeddings接口。用curl或Python请求都可以。下面的Python脚本直接校验返回向量的长度：

import requests
import json

url = "http://localhost:30000/v1/embeddings"
payload = {
    "model": "BAAI/bge-m3",
    "input": "SGLang维度核对测试"
}

resp = requests.post(url, json=payload)
data = resp.json()
embedding = data["data"][0]["embedding"]
print(len(embedding))
print(embedding[:5])

如果输出长度是1024，说明服务返回的是完整dense向量。如果输出长度是4096，则可能是返回了连接后的多向量表示，或者SGLang内部配置了其他输出头。这时需要回到服务启动参数，检查是否误加了类似`--return-raw`或额外的输出维度设置。部分情况下，/v1/embeddings的响应里还可能携带usage字段，但不会包含维度说明，因此必须自己数。

另外，要确认请求中是否传了encoding_format参数。如果设为base64，返回的embedding会是base64字符串而不是浮点数组，这时直接len()得到的不是维度，需要先解码再数长度。

边界情况和排查方向

如果维度不是1024，不要急着怀疑模型，先做三件事：第一，确认模型文件是否完整加载，可以看SGLang启动日志中的“model loaded”信息；第二，确认请求路径是否指向了你启动的那个模型，有时服务里同时加载了多个模型，请求可能路由到了别的模型；第三，确认输入格式是否合法，比如输入是否被拆成了多个文本，导致返回多个向量。

还有一种情况：SGLang的嵌入输出可能默认不经过归一化。BGE-M3原模型在求相似度时通常要先归一化，但维度不随归一化改变。如果你发现维度是1024但数值范围不对，那是归一化问题，不是维度问题。

最后，如果你的实际业务需要sparse或者colbert向量，/v1/embeddings接口通常不直接返回这些，需要额外扩展请求参数或使用SGLang的底层接口。先确认你的需求，再决定是否一定要用SGLang的标准嵌入接口。核对维度的最终标准是：返回数组的长度等于你模型配置文件中hidden_size的值，对BGE-M3来说就是1024。