很多人本地 RAG 卡在第一步：模型拉下来了，但不知道 embedding 该怎么调、出来的是什么形状、要不要归一化、和向量库的维度对不对得上。这篇只解决这一件事——把 Ollama 上的 nomic-embed-text 从拉取到产出向量跑通，顺带说清哪些环节会悄悄埋雷，以及什么时候该换别的嵌入模型。
很多人本地 RAG 卡在第一步：模型拉下来了，但不知道 embedding 该怎么调、出来的是什么形状、要不要归一化、和向量库的维度对不对得上。这篇只解决一件事——把 Ollama 上的 nomic-embed-text 从拉取到产出向量跑通，顺带说清哪些环节会悄悄埋雷。
下面按「拉取验证 → 调用方式 → 产出向量核对 → 什么时候别用」四步走，每步都给可执行动作。判断标准写清楚，但具体维度、体积、效果数据到站内页面核对当时的数字，别抄别人的旧结论。
先把模型拉下来，并确认它真能用
- 拉取并用列表确认用 ollama pull 拉取后，立刻用 ollama list 看标签与体积，避免拉到一半的半成品被当成可用模型，体积明显偏小就重拉。
- 跑一次最小验证走 ollama run 输入一句中文，看是否返回向量而不是报错。中文场景要重点确认，因为英文语料为主的模型在中文语义上可能明显偏弱。
- 确认空闲调用没问题再输入一句和上一句语义相近的中文，看两次输出是否稳定可复现，偶发空返回通常是资源或超时问题，不是模型坏了。
- 盘位紧张就迁存储模型文件默认落在系统盘，改环境变量迁移存储位置比事后搬目录省事，迁完记得重启服务再 list 一次确认。
两种调用方式：命令行快速验证，API 接进代码
交互式命令行适合单句调试，生产链路应走本地 API 的 embeddings 端点，把文本传进去拿向量。Python 侧可以用官方客户端，也可以用 requests 直接打接口，差别在于是否要自己处理编码、超时和重试。
# 单条调用示例（字段名以你本地版本实际返回为准）\ncurl http://localhost:11434/api/embeddings -d '{"model":"nomic-embed-text","prompt":"你的待嵌入文本"}'- 一次请求可以只发一条文本，也可以发批量数组；批量能显著减少往返次数，但要注意单次请求的体积上限；
- 返回字段里除了向量本身还有耗时统计，用它判断是否值得开批量，或者要不要换更小的模型；
- 接入代码时把超时和重试写成可配置项，本地服务重启期间请求会失败，硬编码超时后面很难排查；
- 测试阶段先用固定的一组句子，别用随机文本，否则效果变差时你分不清是模型问题还是输入问题。
产出向量之后，必须核对的三件事
| 核对项 | 怎么查 | 不查的后果 |
|---|---|---|
| 维度 | 看返回数组长度，和你建的向量库集合定义对比 | 写入整批失败，只能重建索引 |
| 相似度度量 | 看向量库集合的默认设置，确认是否做了归一化 | 不归一化时内积结果跑偏，召回不稳 |
| 切块长度 | 用最长的一批文档试写，观察是否被截断 | 超长静默截断，不报错，检索变差 |
| 归一化 | 对同一句和它的改写做相似度对比，看区分度是否正常 | 相似文本被拉平，排序失真 |
检索质量差时先怀疑切块和归一化，再怀疑模型本身。顺序反了会白换模型，换完发现是老问题。长文本要自己切块，嵌入模型有输入长度上限，超长部分会被截断，而截断是静默的。
先证明数据管道是对的，再谈换模型；管道错了，换什么模型都一样。
什么情况下这套组合不合适
- 纯中文语义检索
- 如果实测召回明显不如专门的检索型嵌入模型，就不要勉强用，先小样本对比再决定。
- 跨语言检索
- 中英混排、多语种混检的场景，要单独做一轮小样本验证，不能直接套用单语结论。
- 长文档整段编码
- 需要把整篇文档编码成一个向量的需求，和切块检索是两种路线，别用同一套参数硬套。
- 可复现的离线批处理
- 要求向量可复现、可回滚时，要先固定模型与调用参数，记录在配置里，别用浮动默认值。
- 已有线上检索服务且效果达标时，替换嵌入模型的收益很小，但要付出重建全量索引的代价；
- 换模型前先做一版对照实验：同一批问题、同一套切块，只换嵌入模型，看召回差异；
- 选型时对比站内嵌入模型清单和其他检索型模型的适用说明，具体维度与效果数据到站内页面核对当时的数字；
- 团队只有一两个人时，优先保证索引结构稳定，别频繁换模型，维护成本比那点效果提升高。
常见问题
nomic-embed-text 用 Ollama 拉下来之后，直接在代码里调哪个接口？
走本地 API 的 embeddings 端点，把文本作为输入传进去，返回体里的向量字段就是你要的东西。命令行 ollama run 只适合验证能不能跑通，不适合批量生产调用。接口地址和参数格式到站内 Ollama 相关页面核对，别照抄别人的端口。
为什么我写入向量库时报维度不匹配？
大概率是建集合时写死的维度跟模型实际输出维度不一样。嵌入模型的输出维度是固定的，模型换了维度就变了，向量库的集合建好之后一般不能改。处理办法是删掉集合按实际输出重建，然后全量重灌一次数据，半途改设置只会更乱。
检索结果老是答非所问，是模型不行吗？
先别急着换模型。按顺序排查：切块是不是太长或太碎、有没有做归一化、检索的相似度度量是否和写入时一致、召回的条数是不是太少。这几项都确认过再考虑换嵌入模型。换之前用小样本跑一遍对照，具体对照方法参考站内嵌入模型的选型页面。
