OllamaのOpenAI互換APIをWindowsで使う方法｜/v1・モデル確認

先に結論：OpenAI互換はbase URLを変えるだけでなく、endpointとモデル能力を確認する

Ollama公式docsでは、OpenAI APIの一部との互換性を提供し、既存アプリをOllamaへつなぐ例として http://localhost:11434/v1/ のbase URLが示されています。互換性は「OpenAIと完全に同じ」という意味ではありません。使うendpoint、request field、stream、tool、vision、embedding、Responsesの状態保持を機能ごとに確認します。

OpenAI SDKの初期化が成功しても、モデルが存在すること、Ollamaが起動していること、目的のendpointが対応していることまでは保証しません。最初はlocalhostの短いchatをstream=falseで試し、次にstream、JSON、tools、vision、embeddingを一つずつ追加します。

• ローカルAIをAPIで使う基礎 - APIサーバー、localhost、OpenAI互換の全体像へ戻る
• Ollamaモデル管理 - モデル一覧、詳細、停止、削除、再取得を確認する
• Ollamaのlocal/cloud境界 - 推論場所とOpenAI互換APIの接続先を分ける

Windowsでlocalhost APIとモデルを先に確認する

Windows版OllamaをAPIから使う前に、Ollama本体が起動しているか、モデルが保存済みか、指定したモデル名が一覧にあるかを確認します。API clientのエラーを先に直そうとせず、Ollama単体の状態を分けて記録すると切り分けやすくなります。

1. OllamaをWindowsで起動し、PowerShellを新しく開いてollama lsとollama psを実行する。
2. 使うモデルが一覧にない場合は、モデル名・タグ・空き容量を確認してollama pull MODELを実行する。
3. GET http://localhost:11434/api/tagsでnative APIのモデル一覧を取得し、APIの接続先が自分のPCか確認する。
4. 短いモデル名と短いpromptを使い、まずnative APIまたはCLIで単体応答を確認する。
5. その後にOpenAI clientのbase_urlをhttp://localhost:11434/v1/へ向け、/v1/chat/completionsを試す。

ollama ls
ollama ps
ollama pull MODEL
GET http://localhost:11434/api/tags

localhost APIを使う構成でも、モデル取得、更新、cloudモデル、ログ、別アプリ連携の通信条件は別に確認します。Ollamaを使っているというだけで全処理がPC内に限定されるとは限りません。

• Ollama Windows導入後の確認 - server、API、GPU、導入直後の確認へ進む
• Ollamaモデル保存場所 - モデル本体、OLLAMA_MODELS、ログの保存先を分ける
• Ollama公式Windows docs - Windows版とlocalhost APIの公式前提を見る

OpenAI SDKのbase_url・api_key・modelを合わせる

Ollama公式のOpenAI互換例では、OpenAI clientのbase URLをhttp://localhost:11434/v1/にし、api_keyにはollamaという値を指定しています。例ではclient側が値を要求するため指定しますが、local Ollamaのこの例の値を本物の秘密鍵として扱うものではありません。外部hostやcloud、別providerを使うと認証条件が変わるため、同じ値を一般化しないでください。

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1/",
    api_key="ollama",
)

result = client.chat.completions.create(
    model="MODEL",
    messages=[{"role": "user", "content": "短い質問"}],
)
print(result.choices[0].message.content)

OpenAI向けコードを流用する場合も、まずbase_url、model、stream、timeout、response formatを一つずつ固定します。実際のプロジェクトへ組み込む前に、短い固定promptとローカルの非機密データで応答を確認してください。

• Ollama OpenAI compatibility公式docs - Python、JavaScript、curlの公式例と対応範囲を見る
• APIキーとローカルAIの安全性 - 秘密情報、localhost、外部送信、ログを分ける

Chat Completions・Responses・native APIのpathを分ける

OllamaにはOpenAI互換のv1系と、Ollama nativeのapi系があります。同じlocalhost:11434でも、pathを間違えると404、request形式の不一致、response parserのエラーになります。

POST http://localhost:11434/v1/chat/completions
POST http://localhost:11434/v1/responses
GET  http://localhost:11434/v1/models
POST http://localhost:11434/v1/embeddings
POST http://localhost:11434/api/chat
POST http://localhost:11434/api/generate

OpenAI互換を選ぶかnative APIを選ぶかは、clientが既にOpenAI形式を前提にしているか、Ollama固有のthink・keep_alive・usageなどを使いたいかで決めます。pathだけを置換してレスポンス形式を同じとみなさないでください。

• Ollama Chat API公式docs - native /api/chatのmessages、stream、think、keep_aliveを見る
• Ollama Generate API公式docs - native /api/generateのpromptとusageを見る
• ローカルAI APIの広い比較 - LM Studio・Ollama・Janを横断して比較する

model名とcontext sizeをOpenAI互換側で調整する

OpenAI向けtoolがgpt-3.5-turboのような固定名を送る場合、Ollama公式docsではollama cpで既存モデルを別名へコピーする例が示されています。実際に利用するモデル・タグ・ライセンス・容量を確認してからaliasを作り、元モデルとaliasを同じものと誤認しないでください。

ollama ls
ollama show MODEL
ollama cp llama3.2 gpt-3.5-turbo
ollama ls

OpenAI APIにはモデルのcontext sizeを変更する同じ形式の設定がないため、Ollama公式docsではModelfileのPARAMETER num_ctxとollama createを使う方法が案内されています。

FROM MODEL
PARAMETER num_ctx 8192

ollama create mymodel
ollama run mymodel

• Ollamaモデル一覧・詳細 - ls、show、ps、容量、タグを確認する
• コンテキスト長とは - 長文とメモリの関係を一般論から確認する
• モデルサイズ早見表 - Windows PCのRAM・VRAMとモデルを分けて考える

Embeddingsはchatモデルと分けて、RAGのindex・queryをそろえる

OpenAI互換のembedding endpointはPOST /v1/embeddings、Ollama nativeのembedding endpointはPOST /api/embedです。どちらも文章をベクトルへ変換する入口ですが、チャットの回答を返すendpointではありません。RAGではembeddingモデル、入力の分割、vector DB、検索、回答モデルを別の部品として扱います。

POST http://localhost:11434/v1/embeddings
{
  "model": "EMBEDDING_MODEL",
  "input": ["最初の文書", "次の文書"]
}

POST http://localhost:11434/api/embed
{
  "model": "EMBEDDING_MODEL",
  "input": "検索文"
}

Ollamaの公式Embeddings capabilityでは、semantic search用途のcosine similarityと、indexing・queryingで同じembedding modelを使う考え方が案内されています。RAGが動かない場合は、chat APIのpathではなく、embeddingモデル、入力長、次元、vector DB、検索結果の順に確認します。

• Ollama Embed API公式docs - model、input、truncate、dimensions、embeddingsを確認する
• Ollama Embeddings公式docs - index・query・cosine similarityの考え方を見る
• RAG・埋め込み・ベクトルDB - embeddingから検索・回答までの全体を整理する
• embeddingモデルの選び方 - chat用モデルとembedding用モデルを分ける

stream・JSON・tools・visionは最後に一つずつ確認する

Chat Completionsの公式互換表には、streaming、JSON mode、vision、tools、reasoning/thinking controlなどの対応項目があります。ただし、API側がfieldを受け付けても、指定したモデルがvisionやtool callingを実行できるとは限りません。最小リクエストから一項目ずつ追加します。

1. stream=falseの短いtext chatで、HTTP statusとresponse parserを確認する。
2. stream=trueへ変え、SSEやSDKのstream iteratorをクライアントが正しく読めるか確認する。
3. response_formatやJSON Schemaを追加し、出力後にJSON.parseなどの検証を行う。
4. toolsを1つだけ定義し、モデルのtool calling対応、引数の検証、実行承認を確認する。
5. visionを試す場合は、対応モデル、image contentの形式、入力サイズ、送信範囲を確認する。
6. Responsesへ移行する場合は、非statefulの制限を踏まえ、previous_response_idやconversationを前提にしない。

POST /v1/chat/completions
{
  "model": "MODEL",
  "messages": [{"role": "user", "content": "短い質問"}],
  "stream": false
}

対応表にある機能と、手元のモデルで安全に動くことは別です。JSONはstructured outputの記事、tool callingはMCPの記事、visionはモデル形式や入力条件の記事へ分岐します。

• ローカルAIでJSON出力 - JSON mode・schema・出力検証の考え方を見る
• MCP・tool calling - ツール定義、権限、実行結果を確認する
• Ollama公式OpenAI compatibility - Chat Completionsの機能表とResponsesの制限を見る

Windowsで接続エラーが出たときの順番と公開範囲

OpenAI互換APIのエラーは、Ollamaが停止している、base URLが違う、model名が違う、endpointを混ぜた、stream responseを読めない、embeddingの次元が違う、といった層で起きます。再インストールやLAN公開を先にせず、localhostの状態を一つずつ記録します。

• 最初はlocalhostだけで検証し、LANや外部hostへ公開する設定をAPI疎通のために追加しない。
• api_key、個人パス、機密prompt、文書本文をログや質問文へそのまま残さない。
• localモデルとcloudモデル、OllamaのAPIと連携アプリの外部送信を分けて確認する。
• 実運用ではHTTP status、endpoint、model、stream、response末尾、エラー本文を秘密情報を除いて記録する。
• OllamaのCLI、API、model tag、対応フィールドは更新されるため、記事の固定値より公式docsと自分の応答を優先する。

• Ollamaの症状別トラブル - native APIのdone・usage・streaming診断へ進む
• Ollamaが起動しないとき - Windows本体・server・portの確認へ進む
• 履歴・ログ・プライバシー - API・履歴・ログ・文書データを分けて考える