OllamaのEmbedding APIをWindowsで使う方法｜/api/embed・Python・RAG

先に結論：Windowsではnative /api/embedから最小確認する

Ollama公式のEmbeddings capabilityでは、embeddingをsemantic search、retrieval、RAGへ使う流れと、native POST /api/embedの例が案内されています。最初は短い入力を1件だけ送り、HTTP応答、model、embeddingsの件数、1ベクトルの長さを確認してからbatchとRAGへ進みます。

Embeddingは回答文を生成するAPIではありません。embeddingモデルが文章を数値化し、vector DBや検索処理が近い文章を探し、最後にchatモデルが必要なら回答を生成します。

• 埋め込みモデルの基礎 - chatモデルとembeddingモデルの役割を分ける
• RAG・埋め込み・ベクトルDB - 検索から回答までの全体像を見る
• Ollama公式Embeddings - native APIとsemantic searchの公式例を見る

Windowsでembedding用モデルを準備する

Ollamaのchat用モデルを入れていても、embedding用途へそのまま使えるとは限りません。公式Embeddings capabilityにはembeddinggemma、qwen3-embedding、all-minilmが推奨モデルとして掲載されていますが、タグ、容量、対応言語、PC負荷は利用時点のモデル情報で確認します。

1. WindowsでOllamaが起動し、localhost:11434へ接続できることを確認する。
2. 公式モデル情報と用途を確認し、embedding用モデルをollama pullで取得する。
3. ollama lsで保存済みの正確なmodel名・tagを確認する。
4. ollama show MODELでモデル情報を確認し、短い入力で/api/embedを試す。
5. index作成とqueryで同じembedding modelを使う前提を記録する。

ollama pull embeddinggemma
ollama ls
ollama show embeddinggemma
ollama ps

embeddinggemmaは公式docsの例に使われるモデル名です。実際に取得できるか、モデルのlicense、容量、日本語文書との相性、RAM/VRAM負荷を固定モデルの成功として一般化しないでください。

• Ollamaモデル管理 - ls、show、ps、容量整理を先に確認する
• WindowsでOllamaを入れる - 本体・localhost・最初のモデルの前提を見る
• Ollama公式CLI - pull、ls、showの現行仕様を見る

PowerShellから1件のembeddingを作る

WindowsのPowerShellではInvoke-RestMethodでJSONをPOSTできます。native /api/embedの最小requestはmodelとinputです。結果にはmodel、embeddings、処理時間、prompt_eval_countなどが返るため、まず自然文の意味を評価する前に配列の形を確認します。

$payload = @{
  model = "embeddinggemma"
  input = "WindowsのローカルAIで文章検索を試す"
  truncate = $true
} | ConvertTo-Json -Depth 8

$result = Invoke-RestMethod `
  -Uri "http://localhost:11434/api/embed" `
  -Method Post `
  -ContentType "application/json" `
  -Body $payload

$result.model
$result.embeddings.Count
$result.embeddings[0].Count
$result | ConvertTo-Json -Depth 6

PowerShellの配列やConvertTo-JsonのDepthを変えるとrequest形が変わる場合があります。HTTPエラー時はmodel、localhost、port、bodyを一つずつ確認し、本文へ秘密情報や実文書を入れないでください。

• Ollama Embed API公式docs - request bodyとembeddingsレスポンス項目を見る
• Ollamaが起動しないとき - Windows本体・server・localhostの切り分けへ進む
• OllamaのOpenAI互換API - /v1/embeddingsとの違いを比較する

batch input・truncate・dimensionsを分けて確認する

OllamaのEmbed APIはinputへ文字列の配列を渡してbatch生成できます。公式API referenceにはtruncate、dimensions、keep_alive、optionsがrequest fieldとして掲載されています。どれも一度に追加せず、batch件数、長い入力、次元指定の順に個別確認します。

$payload = @{
  model = "embeddinggemma"
  input = @(
    "最初の文書チャンク",
    "次の文書チャンク",
    "検索に使う短い質問"
  )
  truncate = $false
  keep_alive = "5m"
} | ConvertTo-Json -Depth 8

$batch = Invoke-RestMethod `
  -Uri "http://localhost:11434/api/embed" `
  -Method Post `
  -ContentType "application/json" `
  -Body $payload

$batch.embeddings | ForEach-Object { $_.Count }

dimensionsを変えると既存vector DBのschemaと互換しなくなる可能性があります。実運用では、embedding model名、tag、次元、前処理、chunkサイズ、truncate方針をindexのメタデータへ残します。

• コンテキスト長の基礎 - 長い入力とメモリ負荷を分けて考える
• Ollama公式API reference - truncate、dimensions、keep_aliveの現行定義を見る
• Ollama公式Embeddings - batch入力とベクトル長の説明を見る

Python・JavaScriptからembedを呼ぶ

Ollama公式Embeddings capabilityにはPythonのollama.embedとJavaScriptのollama.embed例があります。ここではSDKをこのサイトへ追加するのではなく、公式の呼び出し形をWindowsアプリへ組み込むときの確認点として示します。インストール方法やSDK versionは利用時点の公式案内を優先します。

import ollama

result = ollama.embed(
    model="embeddinggemma",
    input=[
        "最初の文書チャンク",
        "次の文書チャンク",
    ],
)

print(len(result["embeddings"]))
print(len(result["embeddings"][0]))

import ollama from "ollama";

const result = await ollama.embed({
  model: "embeddinggemma",
  input: ["最初の文書チャンク", "次の文書チャンク"],
});

console.log(result.embeddings.length);
console.log(result.embeddings[0].length);

• SDKがlocalhost:11434へ接続する前提、model名、入力配列、結果のembeddings件数を固定する。
• Python/JavaScriptの配列をDBへ保存する前に、ベクトル長とindex schemaを確認する。
• 例が動かないときはSDKの問題とnative HTTP APIの問題を分け、PowerShellの最小requestへ戻る。
• SDKの導入は利用者側の環境判断であり、このサイトの依存関係を追加・更新したものではない。

• Ollama公式Embeddings Python/JavaScript - 公式SDK例とbatch例を見る
• WindowsでのAPI導入 - OpenAI clientから接続する別ルートを確認する
• ローカルAI API入門 - client・server・modelの役割を整理する

OpenAI互換 /v1/embeddingsとRAGのindex/queryをそろえる

Ollamaにはnative POST /api/embedのほか、OpenAI互換POST /v1/embeddingsがあります。既存のOpenAI clientを使うなら互換path、Ollama固有のtruncateやembeddingsレスポンスを直接確認するならnative path、と目的で分けます。nativeのembeddings配列と、互換clientが返す形式を同じparserで読む前に、手元のresponseを確認してください。

$payload = @{
  model = "embeddinggemma"
  input = @("検索したい文書", "問い合わせの質問")
} | ConvertTo-Json -Depth 8

Invoke-RestMethod `
  -Uri "http://localhost:11434/v1/embeddings" `
  -Method Post `
  -ContentType "application/json" `
  -Body $payload

Ollama公式Embeddings capabilityでは、cosine similarityと、indexing・queryingで同じembedding modelを使う考え方が案内されています。検索結果がずれるときはchat modelだけを疑わず、chunk、embedding、次元、距離、検索候補の順に見ます。

• Ollama OpenAI互換公式docs - /v1/embeddingsのinput形式と対応fieldを見る
• RAG・埋め込み・ベクトルDB - 検索と回答の全体構造を確認する
• 日本語PDFとembedding - 日本語文書の検索品質を検証する

ベクトルが作れない・検索がずれる時の切り分け

Embedding APIの失敗は、Ollama本体、model取得、input長、request field、vector DBのschema、検索評価を別の層として確認します。RAG全体を作り直す前に、PowerShellで1件のベクトルが返るところへ戻ると原因を絞りやすくなります。

• 最初はlocalhostだけで検証し、embedding APIの疎通確認のためにLAN公開や認証緩和を追加しない。
• 個人情報、社内文書、秘密鍵、実データを最初のembeddingテストへ入れず、公開可能な短文で確認する。
• local model、cloud model、外部vector DB、文書チャットツールの通信・保存経路を別々に記録する。
• 固定テスト文、モデル名、tag、次元、距離計算、top-k、期待する検索結果を保存してから設定を変える。

• Ollamaの症状別トラブル - localhost、GPU、モデル、APIの共通診断へ進む
• ローカルRAGのプライバシー - 文書、embedding、DB、外部送信の確認へ進む
• Ollama API Errors公式docs - statusとerror本文の現行資料を見る