llama.cpp 源码完全拆解（十一）：嵌入、重排与池化——一个序列的向量如何从计算图里读出来

服务端的按 slot 切换

服务端并不是在启动时把整个上下文永久设成「嵌入模式」。llama-server 的每个 slot 有自己的任务类型，真正下发给 GPU 前会按当前批次的需要切换：

1
llama_set_embeddings(ctx_tgt, slot_batched->need_embd());

llama_set_embeddings 内部有一个容易被忽视的动作：

1
// a pooled context computes the logits only without embeddings,
2
// so the toggle changes the graph shape
3
if (cparams.embeddings != value && cparams.pooling_type != LLAMA_POOLING_TYPE_NONE) {
4
    sched_need_reserve = true;
5
}

原因是池化上下文在 embeddings = true 时会把 LM head 从图里摘掉；一旦开关翻转，图的结构就变了，必须重新做一次调度器预留。也就是说，嵌入请求和生成请求共用同一个上下文时，切换不是免费的，它会触发一次图重建和缓冲区重算。这也是为什么实际部署里通常用 --embedding 把服务限制为纯嵌入用途，而不是让同一实例混跑两类请求。

嵌入模式下 decode 的三个前置条件

无论走 decode 还是 encode，嵌入模式都会改写 batch 的输出语义。在 llama_decode 开头：

1
// when computing embeddings, all tokens are output
2
const bool output_all = cparams.embeddings;
3
// non-causal attention needs the whole sequence in one ubatch
4
const bool embd_all   = output_all || !cparams.causal_attn;

output_all 把所有 token 标记为「需要输出」。这带来一个硬性检查：如果池化方式是 NONE，需要逐 token 的向量，那么 n_outputs_all 必须等于 n_tokens_all；否则直接报错。对 pooled 模式，这个检查同样存在，但实际上已经用不到逐 token 的输出缓冲——池化把序列压成了一行。

embd_all 则决定了 ubatch 的切分策略：非因果注意力要求整条序列在同一个 ubatch 内，所以切分不能用「按 token 数均分」的简单策略，而要按序列切。这个约束在编码器模型上会进一步收紧为「整个批次一个 ubatch」，下一节展开。

MEAN：一张 0/1 掩码矩阵

最直观的均值池化写法是：对每条序列，把它的 token 向量加起来除以 token 数。放到 GPU 上，逐序列循环会让 kernel 的并行度依赖序列数，也不适合 ggml 的图执行模型。llama.cpp 的做法是把它写成一个矩阵乘法：

设 hidden state 矩阵为

其中每一列是一个 token 的向量。构造一个掩码矩阵

当 token $i$ 属于序列 $s$ 时，$M_{i,s} = 1 / L_s$，否则为 $0$；$L_s$ 是该序列在当前 ubatch 里的 token 数。于是

的第 $s$ 列就是序列 $s$ 的均值向量。一次矩阵乘同时算出所有序列的池化结果，形状只依赖 n_tokens 和 n_seqs_unq，与序列长度分布无关——这正是 llama.cpp 想要的「形状可预测」。

图里的构造只有一行：

1
cur = ggml_mul_mat(ctx0, ggml_cont(ctx0, ggml_transpose(ctx0, inp)), inp_mean);

inp 是 [n_embd, n_tokens]，转置并连续化后变成 [n_tokens, n_embd]；inp_mean 是 [n_tokens, n_seqs_unq] 的 F32 输入张量；ggml_mul_mat 得到 [n_embd, n_seqs_unq]。注意转置后的 ggml_cont：ggml 的矩阵乘对内存布局有要求，非连续视图必须先物化，否则 kernel 会按错误的 stride 读数据。

掩码矩阵的内容不是在图里算的，而是在 set_input 阶段由 CPU 填好：

1
void llm_graph_input_mean::set_input(const llama_ubatch * ubatch) {
2
    const int64_t n_tokens     = ubatch->n_tokens;
3
    const int64_t n_seq_tokens = ubatch->n_seq_tokens;
4
    const int64_t n_seqs_unq   = ubatch->n_seqs_unq;
5

6
    float * data = (float *) mean->data;
7
    memset(mean->data, 0, n_tokens*n_seqs_unq*ggml_element_size(mean));
8

9
    std::vector<uint64_t> sums(n_seqs_unq, 0);
10
    for (int i = 0; i < n_tokens; i += n_seq_tokens) {
11
        for (int s = 0; s < ubatch->n_seq_id[i]; ++s) {
12
            const llama_seq_id seq_id  = ubatch->seq_id[i][s];
13
            const int32_t      seq_idx = ubatch->seq_idx[seq_id];
14
            sums[seq_idx] += ubatch->n_seq_tokens;
15
        }
16
    }
17

18
    std::vector<float> div(n_seqs_unq, 0.0f);
19
    for (int s = 0; s < n_seqs_unq; ++s) {
20
        if (sums[s] > 0) div[s] = 1.0f / float(sums[s]);
21
    }
22

23
    for (int i = 0; i < n_tokens; i += n_seq_tokens) {
24
        for (int s = 0; s < ubatch->n_seq_id[i]; ++s) {
25
            const llama_seq_id seq_id  = ubatch->seq_id[i][s];
26
            const int32_t      seq_idx = ubatch->seq_idx[seq_id];
27
            for (int j = 0; j < n_seq_tokens; ++j) {
28
                data[seq_idx*n_tokens + i + j] = div[seq_idx];
29
            }
30
        }
31
    }
32
}

这段代码里有三个设计点值得拆开。

第一，n_seq_tokens 是「每序列组的 token 数」，不是「每条序列的长度」。 llama.cpp 的 ubatch 按「序列组」组织，一个组里的 token 在位置上对齐；如果一个 token 同时属于多条序列（共享前缀的父子序列），n_seq_id[i] 会大于 1，同一个位置要往多个掩码列里写系数。所以外层的步长是 i += n_seq_tokens，内层再遍历这个位置的序列集合。

第二，系数是 1 / L_s，而 L_s 用 sums[seq_idx] += n_seq_tokens 累加。 这意味着均值是对「当前 ubatch 内的 token 数」取平均，而不是对「整条序列的总长度」取平均。对单 ubatch 的短序列两者一致；对分块的长序列，如果池化在每块上各算一次，再把块向量平均，结果并不等于整条序列的均值——每块的权重会变成均等，而不是按 token 数加权。这正是 MEAN 池化不能随意分块的原因，后面会看到服务端的切块判断直接把它排除在外。

第三，seq_idx 是「序列 id → 列号」的映射。 ubatch 里的序列 id 是调用方给的任意整数（服务端用 slot id，可能不连续），而掩码矩阵的列必须紧凑。llama_ubatch 预先把 seq_id_unq 和 seq_idx 建好，掩码写入和后面的输出读取都用同一套映射。

CLS 与 LAST：一个索引张量

CLS 和 LAST 只取一个位置，不需要掩码矩阵，只需要每条序列一个行号：

1
ggml_tensor * inp_cls = build_inp_cls();      // [n_seqs_unq] I32
2
cur = ggml_get_rows(ctx0, inp, inp_cls);      // MEAN 分支里由 build_inp_mean() 提供掩码矩阵

inp 是 [n_embd, n_tokens]，ggml_get_rows 按索引取列，得到 [n_embd, n_seqs_unq]。索引由 set_input 填入，选行逻辑是这段：

1
const bool last = (cparams.pooling_type == LLAMA_POOLING_TYPE_LAST ||
2
                  (cparams.pooling_type == LLAMA_POOLING_TYPE_RANK && cparams.causal_attn));
3

4
for (int i = 0; i < n_tokens; ++i) {
5
    const llama_pos pos = ubatch->pos[i];
6
    for (int s = 0; s < ubatch->n_seq_id[i]; ++s) {
7
        const llama_seq_id seq_id  = ubatch->seq_id[i][s];
8
        const int32_t      seq_idx = ubatch->seq_idx[seq_id];
9

10
        if ((target_pos[seq_idx] == -1) ||
11
            ( last && pos >= target_pos[seq_idx]) ||
12
            (!last && pos <  target_pos[seq_idx])) {
13
            target_pos[seq_idx] = pos;
14
            target_row[seq_idx] = i;
15
        }
16
    }
17
}

last 为真时取位置最大的行，为假时取位置最小的行。注意它不是「取数组的第一个/最后一个元素」，而是按位置选行：ubatch 里的 token 顺序未必等于位置顺序（多序列拼接、KV 复用、位置重排都会打乱），用位置比较才是可靠的。

RANK 的 last 条件还有一个后缀：只有因果的 RANK 才取最后一个位置。这对应两类 reranker：

• BERT 式 cross-encoder（非因果）：query 和 document 拼成一条序列，取 [CLS] 位置的表示接分类头；
• decoder-only reranker（因果，例如 Qwen3-Reranker）：整条序列的最后一个 token 才能看到全部上下文，取最后一个位置。

如果反过来，在因果模型上取 CLS，位置 0 的 token 只能看到自己，分类头拿到的是一段几乎无信息的表示——这是实践中很容易犯的错，后面「池化选错」一节会再提。

RANK：池化之后的一条分类头

RANK 的图不是「池化完就结束」，而是继续接分类头。核心代码如下：

1
case LLAMA_POOLING_TYPE_RANK:
2
{
3
    if (hparams.pooling_type_cls == LLAMA_POOLING_TYPE_MEAN) {
4
        // modern bert with classifier_pooling = "mean"
5
        cur = ggml_mul_mat(ctx0, ggml_cont(ctx0, ggml_transpose(ctx0, inp)), build_inp_mean());
6
    } else {
7
        cur = ggml_get_rows(ctx0, inp, build_inp_cls());
8
    }
9

10
    if (cls) {
11
        cur = ggml_mul_mat(ctx0, cls, cur);
12
        if (cls_b) cur = ggml_add(ctx0, cur, cls_b);
13
        cur = ggml_unary(ctx0, cur, hparams.act_cls);
14
        if (cls_norm) cur = build_norm(cur, cls_norm, NULL, LLM_NORM, -1);
15
    }
16

17
    if (cls_out) {
18
        cur = ggml_mul_mat(ctx0, cls_out, cur);
19
        if (cls_out_b) cur = ggml_add(ctx0, cur, cls_out_b);
20
    }
21

22
    if (arch == LLM_ARCH_QWEN3 || arch == LLM_ARCH_QWEN3VL) {
23
        cur = ggml_soft_max(ctx0, cur);
24
    }
25
}

这条链回答了四个模型差异：

1. 池化基座不同：ModernBERT 一类模型的分类头以 mean 池化为输入，其余多数以 CLS 为输入。hparams.pooling_type_cls 就是模型声明的「分类头用哪种池化」。
2. 头的层数不同：有的模型只有一层 cls（Linear + bias + 激活），有的还有 cls_out（再一层投影到类别数）。Jina reranker 的 tiny 版本就没有 cls_out，代码里对两层都做了可空判断。
3. 激活不同：act_cls 由模型元数据给出，可能是 GELU、ReLU、tanh 等。
4. 归一化位置不同：cls_norm 是分类头内部的 LayerNorm，和输出向量的 L2 归一化不是一回事。

最后一行的 softmax 只对 Qwen3 系模型生效：它的分类头输出两个 logit（yes/no 或相关/不相关），需要 softmax 变成概率。其他 reranker 通常输出单个 logit，由服务端或调用方决定是否过 sigmoid。llama.cpp 不会替所有模型统一做激活，这是使用 rerank 接口时必须核对的模型细节。

池化上下文不建 LM head

还有一个结构性后果：只要池化类型不是 NONE，build_logits 会把 logits 指针置空：

1
// a pooled embeddings context outputs one vector per sequence,
2
// so its graph skips the LM head
3
if (cparams.embeddings && pooling_type != LLAMA_POOLING_TYPE_NONE) {
4
    res->t_logits = nullptr;
5
}

词表投影是 decoder 模型里最贵的一层（$n_{\text{embd}} \times n_{\text{vocab}}$），把整个 batch 的所有输出行都投影一遍纯属浪费。池化模式直接把它从图里摘掉，这是嵌入模式相对「先当生成模型跑、再自己取 hidden」最直接的速度收益。

反过来，pooling none 时 LM head 仍然会被展开——因为 logits 指针没有被置空，模型建图时仍然会 expand 输出。对只需要逐 token 向量的场景，这是一笔可以避免的开销；实践中应该显式把 embeddings 打开并接受这个代价，或者在上层用 pooling none 时只标记必要的输出行。这个细节在源码注释里没有强调，但值得在读 build_logits 时留意。

MEAN 与 CLS：拆开就错

先看 MEAN。前面已经提到，掩码系数是 1 / L_s，而 L_s 是当前 ubatch 内该序列的 token 数。如果一条 2048 token 的文档被切成两个 1024 token 的 ubatch 分别池化，那么：

• 第一个 ubatch 输出的是前 1024 个 token 的均值 $\bar h_{1}$；
• 第二个 ubatch 输出的是后 1024 个 token 的均值 $\bar h_{2}$。

无论上层怎么组合这两个向量（直接相加再除以 2，还是别的加权），都很难精确等于整条序列的均值 $\bar h = (\sum_{i=1}^{2048} h_i)/2048$——除非上层知道每块的 token 数并相应地加权。而 llama.cpp 的公开 API llama_get_embeddings_seq 只交出一条序列一行向量，并没有「块信息」可言。换句话说，一旦 MEAN 池化跨了 ubatch，语义就丢了。

CLS 更直接：它取的是「位置最小」的 token。如果序列被拆分，那么后面几个 ubatch 里根本不存在位置最小的那个 token，池化矩阵里对应的行号指向的是这一块里的最小位置——结果变成了「每块各自的 CLS」，而不是整条序列的 CLS。

所以对 MEAN 和 CLS，正确的做法是让整条序列落在同一个 ubatch 里。

服务端的切块判断

llama-server 并没有把这条规则写进上下文层，而是写成了一个显式的前置判断：

1
// if the context does not have a memory module then all embeddings
2
// have to be computed within a single ubatch
3
if (!llama_get_memory(ctx_tgt)) {
4
    return false;
5
}
6
// context can be chunked/split if the pooling type is LAST
7
const auto pooling = llama_pooling_type(ctx_tgt);
8
if (pooling == LLAMA_POOLING_TYPE_LAST) {
9
    return true;
10
}
11
// causal rerankers read the last token and have a KV cache, so they
12
// can also be chunked/split.
13
if (pooling == LLAMA_POOLING_TYPE_RANK && llama_get_causal_attn(ctx_tgt)) {
14
    return true;
15
}

这段代码是「这条任务能否被拆成多个 batch 处理」的判定函数，返回 false 意味着整条 prompt 必须作为一批、一次前向算完。它给出的结论是：

• 没有 KV 缓存（例如纯编码器模型通过 llama_decode 跑，上下文里没有 memory）→ 不能拆；
• 池化方式是 LAST → 可以拆（位置最大的 token 一定在最后一块里）；
• 池化方式是 RANK 且是因果模型 → 可以拆（reranker 读最后位置，和 LAST 同理）；
• 其余情况（MEAN、CLS、非因果 RANK）→ 不能拆。pooling none 的逐 token 模式不在这个判定里单独列出，它走的是同一套批次路径，但服务端只用它返回整批 prompt 的逐 token 向量，不存在跨批拼接的问题。

为什么 LAST 可以拆

LAST 取的是位置最大的 token。位置是单调递增的，序列的最后一块 ubatch 必然包含最大的那个位置，因此「最后一块里的最大位置」就是「整条序列的最大位置」——池化矩阵的选行结果与是否拆分无关。

这就解释了一个常见的观察：decoder-only 的 embedding 模型在处理长文档时，比 BERT 式模型更”友好”。GTE-Qwen、E5-Mistral、LlamaEmbeddingModel 这类模型用的是 LAST（或 EOS）池化，只要把文档切块喂进去，池化总能读到最后一块里最后一个 token 的表示；而 BGE（CLS）与 E5（MEAN）这类非因果模型切开就丢语义。这不是实现质量问题，而是池化语义本身的数学性质。

另一条更硬的约束：启动时的参数检查

除了运行期的切块判断，服务端启动时还有一条配置层面的保护。嵌入模式要求一次前向覆盖整批 token；如果 n_batch 大于 n_ubatch，llama_decode 就会把一批拆成多块，池化矩阵的形状也就跟着变。服务端的做法是直接修正参数并给出警告：

1
// validate batch size for embeddings
2
// embeddings require all tokens to be processed in a single ubatch
3
if (params.embedding && params.n_batch > params.n_ubatch) {
4
    SRV_WRN("embeddings enabled with n_batch (%d) > n_ubatch (%d)\n", ...);
5
    SRV_WRN("setting n_batch = n_ubatch = %d to avoid assertion failure\n", ...);
6
    params.n_batch = params.n_ubatch;
7
}

注意这里修正的是 n_batch（一次 llama_decode 最多接收的 token 数），而不是允许 n_batch 大于 n_ubatch。效果是一样的：llama_decode 内部的 ubatch 切分循环就不会把一批拆成多块，从而保证整条 prompt 在同一个 ubatch 内完成。

图复用与形状的联动

还有一个容易被忽视的后果：因为池化矩阵的形状依赖 n_tokens 与 n_seqs，嵌入模式下几乎每个 batch 的形状都不一样，图的复用率天然较低。llm_graph_input_mean::set_input 里用 memset 把整个矩阵清零再填值，而不是「只改变化的行」——对一个只用于嵌入的图，这种朴素写法是够用的：池化矩阵本身很小（n_tokens × n_seqs 的浮点），不值得为它引入更复杂的增量更新逻辑。

对于 pooling none 这种逐 token 输出的模式，情况又不一样：没有池化矩阵，t_embd 就是整块 hidden state，n_outputs 直接等于 n_tokens。此时 ubatch 可以正常切分，但输出缓冲区要能容纳整个批次的所有行——这也解释了前面提到的那个检查：n_outputs_all 必须等于 n_tokens_all。

n_embd_out 与 n_embd_inp：别混用

这段代码里还有一条注释值得单独拎出来：

1
// use n_embd_out (not n_embd_inp) - the pooled embedding has the model's
2
// output dimension, which differs from input dimension for deepstack models (e.g. qwen3vl)

在大多数模型里，输入嵌入维度与输出 hidden 维度相同，所以两者可以混用而不会出错。但对 Qwen3-VL 这类「输入投影层」与「主模型 hidden 维度」不一致的模型，池化的结果沿输出维度排布；如果按输入维度去算偏移，相邻两行就会错位。这是一个典型的在工程实践中被踩到过、才补上注释的细节。

embd_seq 在批次间被清空

注意 encode 和 decode 在开始之前都会：

1
// sync first so any in-flight async copies into embd_seq complete before it is freed
2
if (!embd_seq.empty()) {
3
    synchronize();
4
}
5
embd_seq.clear();

先同步再清空的理由是：调用 ggml_backend_tensor_get_async 把数据拷进 embd_seq[seq_id] 的缓冲区是异步的；如果紧接着 clear() 让 map 节点析构，异步拷贝可能还在往一块已经释放的内存里写。先 synchronize()、再清空，是这类「异步 IO 指向容器内缓冲」场景通用的正确做法。

与归一化顺序相关的一个陷阱

从「池化 → 归一化 → 返回」的顺序看，llama.cpp 采用的是「先算均值向量，再单位化」，而不是「先单位化每个 token 的向量，再算平均」。这两种顺序在很多模型上的结果不相等：

• 先均值后归一化：$\frac{\bar h}{\|\bar h\|}$
• 先归一化后均值：$\overline{\frac{h_i}{\|h_i\|}}$（再归一化）

对于 Sentence-Transformers 生态中的很多文本 embedding 模型，论文和训练代码采用的都是前一种，llama.cpp 的实现与之一致。如果哪一步顺序搞反，向量相似度会系统性偏移。这种偏差不会让程序崩溃，只会让召回率悄悄下降，因此在跨实现迁移时值得用少量样本对照一次。

Matryoshka：截断与再归一化

检索系统里还有一类操作叫 Matryoshka Representation Learning：训练时让向量的前缀本身也是一个可用的低维嵌入。因此推理时可以只取前 $d$ 维，再把 $d$ 维向量单位化，从而用更小的存储换近似相同的召回。Matryoshka 的思想在 2022 年由 Kusupati 等人提出（arXiv:2205.13147），核心是「嵌套子集都可独立用于检索」：

llama.cpp 本身不处理 Matryoshka 截断——服务端返回的是完整维度的归一化向量。如果要在 llama.cpp 上使用 Matryoshka 模型，正确顺序是：拿回完整向量后，先截断到目标维度，再对截断后的向量做一次 L2 归一化。直接截断已归一化的完整向量，得到的是一个非单位向量，会导致内积排序与设计预期不一致。

一个请求的路径

一条嵌入请求进来，大致经历：

1. 路由层：/v1/embeddings、/embeddings、/embedding、/v1/rerank、/rerank 等路由接到同一组处理函数；
2. 请求解析：提取 input（文本或文本数组）、可选的 embd_normalize（非 OAI 接口）、top_n（rerank）；
3. slot 分配：找一个空闲 slot，把任务类型标为 embedding / rerank；
4. 批组装：与生成任务一起进入调度器的批；
5. 前向：按 slot 是否需要嵌入切换 llama_set_embeddings，然后执行；
6. 结果回填：从 llama_get_embeddings_seq 或 _ith 读取，并归一化写回响应。

其中第 5 步的 llama_set_embeddings(ctx_tgt, slot_batched->need_embd()) 我们前面讲过：切换开关会触发调度器重新预留，也就是说混跑两类请求会让每一批进入和离开嵌入态时都付出一次图预留的代价。对于以嵌入为主的场景，--embedding 参数会在启动时把服务限定为纯嵌入用途，从而避免这种来回切换。

两个接口的差异

服务端的 /embeddings（非 OAI）与 /v1/embeddings（OAI 兼容）的差异并不是命名包装层面那么简单：

• /embeddings 支持所有池化方式，包括 pooling none，后者返回每个 token 的未归一化向量；
• /v1/embeddings 要求池化方式不为 none，并且返回的向量是按欧氏范数归一化的；
• /embeddings 允许在请求级别传 embd_normalize 覆盖服务端默认值，而 OAI 接口不暴露这个选项。

这意味着：如果你在 llama.cpp 上部署一个 BERT 类 embedding 模型，想给下游返回原始未单位化的向量做其他用途，应当走非 OAI 接口并显式传 embd_normalize: -1；而不是去 OAI 接口再想办法反归一化。后者理论上可以恢复，但浮点精度上会有舍入误差。

rerank 接口的语义

/rerank 系列接口要求模型以 --pooling rank（或 --reranking）启动——也就是上文的 RANK 模式。它返回的是「query 与每篇 document 的相似度分数」，而不是向量本身。对于 BERT 式 cross-encoder，query 与 document 拼接成一条序列后整段穿过模型，从 [CLS] 位置接分类头读分数；对于 decoder-only reranker，序列以最后一个 token 的表示接分类头读分数。两种形态共用同一套池化图，只是 pooling_type_cls 与 causal_attn 的组合不同。

这也意味着 rerank 请求天然是”每条序列一段 prompt”，和 embeddings 请求一样需要按序列组织 batch；并且对 BERT 式 reranker，同样受「不能拆块」的约束——query+document 必须能放进同一个 ubatch。

池化类型与注意力类型必须匹配

CLS 池化取的是位置最小的 token。在因果模型上，位置 0 的 token 只能看到自己——它的 hidden state 里没有任何来自后文的上下文。拿这样一个向量去做句级相似度，效果会明显差于 LAST。

反过来，在非因果模型上用 LAST，最后一个 token 能看到整条序列，本身没有错；但训练时如果模型用的是 CLS 目标（BGE 就是一例），最后一层的表示并没有被训练成”句向量”，效果同样会下降。池化方式不是推理期的自由参数，而是模型训练目标的一部分。

llama.cpp 对这种情况的处理很克制：用户指定的 pooling_type 与模型元数据里的默认值不一致时，只打一条警告，不阻止。这是给调试留空间，但也意味着把 --pooling mean 随手加到 BGE 上不会被拦下来。部署前应该先确认模型卡（model card）里写的 pooling 是什么，再决定是否覆盖。

指令前缀与特殊 token 不会被自动补

E5 一类模型在训练时给 query 和 passage 分别加了 query: / passage: 前缀；BGE 的中文模型也有类似的 instruction 约定。llama.cpp 的分词器只负责把输入文本切成 token，并加上模型配置里的 BOS/EOS，它不知道”这是 query”还是”这是 document”，因此不会替你补领域前缀。

如果直接拿原始文本去请求，得到的向量与训练分布不一致，召回率会下降，而且这种下降很难从单条结果上看出来。正确做法是在调用方拼好前缀：查询侧加 query: ，文档侧加 passage: ，再分别请求。同理，如果模型训练时对输入做了小写化、去重音或截断，调用方也要在请求前完成。

MEAN 会把特殊 token 一起平均

MEAN 的掩码覆盖当前 ubatch 内的所有 token，包括 BOS 与 EOS。很多句向量模型在训练时也是这样处理的，所以这通常没问题；但如果某个模型在训练时显式排除了特殊 token，推理时又把它们算进均值，向量就会有一个小幅但系统性的偏移。

llama.cpp 没有提供”排除特殊 token”的开关——掩码只按序列归属生成，不按 token 类型过滤。遇到这类模型，需要走 pooling none，拿到逐 token 向量后由调用方自行选择参与平均的位置。这也是 pooling none 这一档存在的另一个理由：当引擎的池化语义与模型训练语义不完全一致时，保留一个”不池化”的逃生舱。

长度上限是三个参数的联合约束

一条嵌入请求能有多长，不只取决于 n_ctx：

• n_ctx 决定位置编码与缓存能覆盖的最大长度；
• n_batch 决定一次 llama_decode 最多接收多少 token；
• n_ubatch 决定图一次能处理多少 token，而嵌入模式又要求 n_batch = n_ubatch。

三者共同把”单条输入的长度上限”压到 min(n_ctx, n_batch)。超过这个上限的输入，服务端要么截断、要么报错，具体行为取决于请求参数与启动配置。部署时应该把 --ctx-size 与 --batch-size / --ubatch-size 按最长文档长度一起调大，而不是只调 --ctx-size；只调后者并不会让一次前向多容纳 token。

不要把生成请求的 /v1/completions 用来取向量

最后一条不算坑，但值得写下来：生成接口返回的是 token 与 logprobs，不返回句向量；/v1/embeddings 才是向量接口。用生成接口的 hidden state 去凑向量，既拿不到正确维度的输出，也绕过了池化与归一化，结果不可复现。两者在 llama.cpp 内部共享前向，但在 API 层是两条明确的路径。