Ollama embeddings怎样为本地文档生成向量

可以。最小做法是先把本地文档切成长度可控的片段，再把这些片段作为数组传给 Ollama 的 /api/embed 接口。接口返回的 embeddings 与输入顺序一一对应，保存“原文片段 + 元数据 + 向量”后，就能在查询时用同一个模型生成查询向量，再计算余弦相似度。

官方地址：https://docs.ollama.com/capabilities/embeddings

本文用一个小型本地文档集合说明完整链路，重点是向量生成时最容易出错的切片、长度、模型一致性和映射关系。

先把文档变成可控片段

不要把整本手册直接塞进一次请求。先为每个片段保留稳定的 source、chunk_id 和 text，后面即使只拿到向量下标，也能找回原文。切片长度要以模型上下文和业务语义为准：标题、段落和代码块尽量不要被硬切开。

先安装并准备一个本地 embedding 模型。示例使用官方文档中的 embeddinggemma 名称；如果本机选择了其他模型，索引和查询两边必须保持一致。

# 拉取一个用于文本向量化的本地模型
ollama pull embeddinggemma

# 确认本地服务可响应；服务默认监听本机 11434 端口
curl http://localhost:11434/api/version

用 /api/embed 批量生成向量

Ollama 的 /api/embed 接受单个字符串或字符串数组。批量传入数组时，返回的向量数组与输入数组按位置对应，因此应同时保存输入顺序，不要在请求后重新排序。

# input 可以是多个片段；每个 embeddings 元素对应一个片段
curl http://localhost:11434/api/embed \
  -H "Content-Type: application/json" \
  -d '{
    "model": "embeddinggemma",
    "input": [
      "安装完成后先启动本地服务。",
      "向量检索时需要复用同一个 embedding 模型。"
    ],
    "truncate": false
  }'

truncate 设为 false 的意义是让超出上下文窗口的片段直接报错，便于回到切片逻辑处理；如果接受默认截断，长片段末尾可能被静默舍弃。接口还支持 keep_alive 和可选的 dimensions，但不要在没有确认模型能力和索引约束前随意改变向量维度。

把向量和原文一起保存

向量本身不能替代原文。一个最小记录可以是下面这样，text 用来展示结果，source 与 chunk_id 用来定位来源，model 用来阻止不同模型的向量混在同一索引里。

from pathlib import Path
import ollama

def embed_markdown(path: str) -> list[dict]:
    # 这里用段落做演示；生产环境可替换为带重叠窗口的切片器
    paragraphs = [p.strip() for p in Path(path).read_text(encoding="utf-8").split("\n\n") if p.strip()]
    response = ollama.embed(
        model="embeddinggemma",
        input=paragraphs,
        options={"temperature": 0},
    )
    vectors = response["embeddings"]
    if len(vectors) != len(paragraphs):
        # 输入和输出数量不一致时不要继续写入索引
        raise RuntimeError("embedding 数量与文档片段数量不一致")
    return [
        {"source": path, "chunk_id": i, "text": text,
         "model": "embeddinggemma", "vector": vector}
        for i, (text, vector) in enumerate(zip(paragraphs, vectors))
    ]

示例使用官方 Python 客户端的 ollama.embed 调用方式。写入向量数据库或本地文件时，建议把模型名、向量维度和切片策略作为索引元数据保存；以后更换模型时建立新索引，不要覆盖旧向量。

查询时必须复用同一个模型

查询并不是把关键词直接和文档向量比较，而是先用同一个 embedding 模型把用户问题转换成查询向量，再与索引向量计算余弦相似度。这样索引和查询位于同一个向量空间，取分数最高的片段即可交给后续问答或摘要环节。

import ollama

def embed_query(question: str) -> list[float]:
    # 查询必须使用建立索引时的同一模型
    result = ollama.embed(model="embeddinggemma", input=question)
    return result["embeddings"][0]

query_vector = embed_query("如何让本地文档支持语义搜索？")
# 将 query_vector 与索引中的向量计算余弦相似度，再按分数降序取回片段

官方说明 /api/embed 返回 L2 归一化向量，常见语义搜索可以直接采用余弦相似度。若索引使用了 A 模型、查询却换成 B 模型，即使两个向量长度碰巧相同，分数也没有可比性。

长度、批量和兼容边界

• 切片优先按标题、段落或代码块组织，再设置字符或 token 上限；不要用一个过大的固定字符串替代语义切片。
• 批量数组过大时按小批次提交，并在每批保存输入顺序；服务重启或模型首次加载造成的耗时也要与业务超时区分开。
• 看到“向量数量不对”时先检查输入数组是否被过滤、空字符串是否混入，以及客户端返回字段是否为 embeddings。
• 需要降维时再评估 dimensions；维度变化会影响已有索引，不能只改一个请求参数。

最后可以用这三个条件快速判断结果是否可用：每个片段都有可回溯的原文；同一索引的模型名和维度一致；查询向量与索引向量使用同一 embedding 模型。

常见问题

为什么生成的向量数量和片段数量不同？

通常是请求前后对输入做了过滤或排序，或者把单个字符串和字符串数组的返回结构混用了。保留原始输入数组，并按位置读取 embeddings。

能不能用聊天模型直接做向量索引？

应优先选择明确支持 embeddings 的模型。聊天模型与 embedding 模型的用途和向量空间不同，不能因为都能处理文本就直接互换。