Ollama埋め込みAPI入門：近い文を探す

先に結論

Ollamaの/api/embedへ文書と質問を同じmodelで送り、返ったvector同士をcosine similarity（ベクトルの向きの近さ）で比べれば、小さな意味検索を作れます。最初は3文書と1質問を一つのbatchにし、返却数、次元数、vectorの長さが約1であることを確認してから順位を見るのが安全です。index作成時と検索時でmodelを変えないことが最重要です。

確認日時: 2026年8月10日（Asia/Tokyo）
対象: Ollama v0.32.6（commit c82ebbd、2026年8月4日公開）と、同日確認した現行Embeddings／Embed API文書。
検証区分: 公式資料を基にした机上調査・構文確認済みの最短手順です。この制作環境ではOllama server、model download、API requestを実行していません。
更新範囲: 公式文書はページ上に更新日を表示していないため、2026年8月10日時点の内容を確認しました。modelごとの入力上限と次元数は一律ではありません。

始める前に知っておくこと

埋め込み（embedding）は、textの意味的な特徴を数値の並びで表したものです。この数値列をvectorと呼びます。似た内容のvectorが近い方向を向くようにmodelが作られているため、単語の完全一致だけでは拾えない関連文も検索できます。ただし、埋め込み自体が正解を生成するわけではなく、候補文書を順位づけする部品です。

必要なものは次のとおりです。

Ollama v0.32.6を基準にしたlocal環境。別versionでもAPI仕様を再確認する
公式がembedding用として案内するmodel。ここではembeddinggemmaを例にする
localのhttp://localhost:11434へ到達できるterminal
JSONを読み、順位を計算するNode.js。外部packageは使わない

公式文書は/api/embedがL2-normalized、つまりvectorの長さが1になるよう正規化した値を返すと説明しています。また、意味検索ではcosine similarityを使い、index側とquery側で同じembedding modelを使うよう明記しています。

まずmodelを取得します。

ollama pull embeddinggemma

model tagは後から内容が変わり得ます。再現性が必要な運用では、開始時にollama lsまたはGET /api/tagsでmodel名とdigestを記録してください。

最短手順：3文書から近い1件を選ぶ

文書3件と質問1件を、同じrequestのinput配列へ入れます。最後の要素が質問です。

curl --fail --silent http://localhost:11434/api/embed \
  -H "Content-Type: application/json" \
  -d '{
    "model": "embeddinggemma",
    "input": [
      "量子化するとモデルのメモリ使用量を減らせます。",
      "長い会話ではKVキャッシュの容量も確認します。",
      "APIサーバーには認証とレート制限を追加します。",
      "GPUメモリが足りないときの対策は？"
    ],
    "truncate": false
  }' > embeddings.json

初回はtruncate: falseにしています。公式APIでは既定値がtrueで、context windowを超えた入力を切り詰めます。短文の練習で予期せぬ切り詰めを見逃さないため、超過時にerrorを返す設定から始めます。

次のrank-embeddings.mjsは、返却数、次元数、質問vectorのL2 normを確認し、文書をcosine similarityの降順へ並べます。

import { readFileSync } from 'node:fs';

const documents = [
  '量子化するとモデルのメモリ使用量を減らせます。',
  '長い会話ではKVキャッシュの容量も確認します。',
  'APIサーバーには認証とレート制限を追加します。',
];
const response = JSON.parse(readFileSync('embeddings.json', 'utf8'));
const vectors = response.embeddings;

if (!Array.isArray(vectors) || vectors.length !== documents.length + 1) {
  throw new Error('入力数と返却vector数が一致しません');
}

const norm = (vector) => Math.sqrt(
  vector.reduce((sum, value) => sum + value * value, 0),
);
const cosine = (left, right) => {
  if (left.length !== right.length) throw new Error('次元数が一致しません');
  const dot = left.reduce((sum, value, index) => sum + value * right[index], 0);
  return dot / (norm(left) * norm(right));
};

const queryVector = vectors.at(-1);
const ranking = documents
  .map((text, index) => ({ text, score: cosine(vectors[index], queryVector) }))
  .sort((left, right) => right.score - left.score);

console.log({
  vectorCount: vectors.length,
  dimensions: queryVector.length,
  queryNorm: norm(queryVector),
});
console.table(ranking);

実行します。

node rank-embeddings.mjs

成功確認は、特定の架空scoreを期待するのではなく、次の4点で行います。

vectorCountが入力した4件と一致する
すべてのvectorのdimensionsが同じで、0より大きい
浮動小数点の丸めを考慮してqueryNormが1に近い
最上位の文書が質問に対して妥当か、人が読んで確認できる

この例の順位はmodel revisionで変わり得ます。1件の成功は検索品質の保証ではありません。実際のRAGへ進む前に、自分の文書と質問で小さな正解集合を作ってください。

つまずきやすい点と戻し方

modelが見つからない

ollama lsでmodel名を確認し、なければollama pull embeddinggemmaへ戻ります。似た名前を推測で書き換えず、requestと保存済みindexが同じmodel名を使うことを確認します。

返却数や次元数が合わない

JSONのembeddingsを読み、入力配列と同じ順序・件数かを確認します。indexとqueryを別requestにする場合も、modelとdimensionsを両方記録します。異なる次元のvectorをpaddingや切り取りで無理に合わせず、同じ条件でindexを作り直します。

長文でerrorになる、または結果が不安定

まず短文へ戻します。truncate: falseのerrorは入力がcontext windowを超えた可能性を表すため、文書を意味のまとまりで分割し、元文書IDとchunk位置を保存します。truncate: trueへ変えてerrorを隠す前に、どの情報が落ちるかを確認してください。

近い文が期待と違う

APIの失敗と検索品質を分けます。返却形式が正しくても、model、文書の粒度、言語、質問の書き方で順位は変わります。3件の例へ戻り、正解文を含めた小さな集合で確認してから文書数を増やします。生成APIとの違いを整理する場合は、OllamaでJSON Schema出力を作る入門も参照できます。

さらに深く理解する

Ollama Embeddingsの検証設計では、model digest、batch size、dimensions、truncate、keep_aliveを分離し、recall、処理時間、memory、error率を測る方法を整理します。

参考資料

Ollama Embeddings（現行文書を2026年8月10日確認。L2正規化、batch入力、同一model、cosine similarityを確認）
Ollama Embed API（現行文書を2026年8月10日確認。input、truncate、dimensions、keep_aliveを確認）
Ollama v0.32.6 release（commit c82ebbd、2026年8月4日公開、2026年8月10日確認）
Ollama List models API（現行文書を2026年8月10日確認。model digestの記録方法を確認）