Ollama Embed 端点（嵌入向量）

POST /api/embed 把文本转成向量，是 RAG、语义搜索、聚类的基础。它和推理端点有两个重要差别：支持批量输入，且没有 keep_alive 以外的运行时控制。

版本基线 v0.40.12，官方 docs.ollama.com/api/embed。

一、最小调用

curl http://localhost:11434/api/embed -d '{
  "model": "embeddinggemma",
  "input": "Why is the sky blue?"
}'

返回：

{
  "model": "embeddinggemma",
  "embeddings": [
    [0.010071029, -0.0017594862, 0.05007221, 0.04692972, 0.054916814,
     0.008599704, 0.105441414, -0.025878139, 0.12958129, 0.031952348]
  ],
  "total_duration": 14143917,
  "load_duration": 1019500,
  "prompt_eval_count": 8
}

注意 embeddings 是二维数组——即使只传一个字符串，外面也套一层。这是按批量设计的结构：embeddings[0] 对应 input[0]。

向量维度由模型决定（上面的示例被截断为 10 维展示，实际通常几百到几千维）。

二、请求字段

truncate 值得单独说

默认 true——超过上下文窗口的输入被静默截断。

这意味着：一篇文章太长时，只有前面部分参与嵌入，后面的内容直接丢失。如果你的场景是索引长文档，要么自己切块，要么设 truncate: false 让请求显式失败，避免无声的数据丢失。

## 严格模式：超长直接报错
curl http://localhost:11434/api/embed -d '{
  "model": "embeddinggemma",
  "input": "超长文本……",
  "truncate": false
}'

dimensions 的用途

某些模型支持降维输出（比如原生 1024 维降到 256 维）。降维能显著减小索引体积、加快检索，代价是精度略降。不是所有模型都支持这个参数。

三、响应字段

注意没有 eval_count 和 eval_duration——嵌入不是逐 token 生成，所以没有生成阶段的指标。

四、批量嵌入

curl http://localhost:11434/api/embed -d '{
  "model": "embeddinggemma",
  "input": [
    "第一段文本",
    "第二段文本",
    "第三段文本"
  ]
}'

返回的 embeddings 长度等于输入长度，顺序一一对应。

批量比循环单条快得多——模型只需加载一次，且推理时可以并行。索引几千个文档时这个差别是数量级的。

五、Python 示例

import requests, numpy as np

def embed(texts):
    r = requests.post("http://localhost:11434/api/embed", json={
        "model": "embeddinggemma",
        "input": texts,
        "truncate": False,
    })
    r.raise_for_status()
    return np.array(r.json()["embeddings"])

## 建索引
docs = ["Ollama 是本地模型运行时", "KV 缓存影响显存占用", "量化能降低内存需求"]
vecs = embed(docs)
print("向量形状:", vecs.shape)

## 检索
q = embed(["显存怎么优化"])[0]

## 余弦相似度
sims = vecs @ q / (np.linalg.norm(vecs, axis=1) * np.linalg.norm(q))
for i in np.argsort(-sims)[:2]:
    print(f"{sims[i]:.4f}  {docs[i]}")

六、选模型

嵌入模型和生成模型是两类东西，不能混用。命名上通常带 embed 字样（如 embeddinggemma）。

选型时看三点：

• 维度：越高表达力越强，但索引和计算成本也越高
• 上下文长度：决定单块文本能多长
• 语言支持：中文场景要确认训练数据覆盖

下载：

ollama pull embeddinggemma

嵌入的完整机制见 3.6 Ollama 嵌入向量（Embeddings）。

常见问题

动手试

## ① 拉嵌入模型
ollama pull embeddinggemma

## ② 批量嵌入两条，看维度
curl -s http://localhost:11434/api/embed -d '{
  "model": "embeddinggemma",
  "input": ["你好", "世界"]
}' | python -c "
import sys,json
d=json.load(sys.stdin)
print('条目数:', len(d['embeddings']))
print('维度:', len(d['embeddings'][0]))"

输出的「条目数 2」和「维度」能确认你对返回结构的理解是否正确。