OllamaのStructured OutputsをWindowsで使う方法｜JSON Schema・Python・JavaScript

先に結論：JSON modeとJSON Schemaを使い分ける

Ollama公式docsでは、nativeのPOST /api/chatにformat: "json"を渡す方法と、formatへJSON Schemaオブジェクトを渡す方法が案内されています。JSON modeはJSONらしい返答の入口、schema指定は項目・型・requiredをアプリ側の契約として明示する入口です。

Structured Outputsは返答の形を整える機能です。モデルが外部関数を呼び出すtool calling、文書を検索するRAG、MCPでツールを接続する処理とは目的が違います。JSONが正しくても、内容の事実性や実行許可まで保証するものではありません。

• ローカルAIでJSON出力 - JSON Schemaの基本と用途の全体像を見る
• Ollama tool calling - 関数呼び出しの要求とtool結果の往復を見る
• Ollama Structured Outputs公式docs - formatとschemaの公式例を確認する

WindowsでOllama・モデル・localhostを分けて確認する

Structured Outputsの失敗をschemaだけの問題にしないため、Ollama本体、モデル名、通常のchat、API接続を別々に確認します。端末で通常の返答が成功しても、schema付きの応答や検証まで同じように動くとは限りません。

1. OllamaをWindowsで起動し、PowerShellでollama lsとollama psを実行する。
2. 利用するモデルの名前とタグ、空き容量、モデルカードの対応情報を確認する。
3. ollama run MODELで短い通常chatを1回行い、モデル単体が応答することを確認する。
4. GET http://localhost:11434/api/tagsでAPI接続とモデル一覧を確認する。
5. 最初はstream=false、短い入力、3項目程度のschema、temperature 0に近い設定で基準を作る。

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

公式サンプルのモデル名は説明用の例です。手元のモデルのサイズ、chat template、対応機能、利用可能なタグを確認し、成功を固定モデル全体へ一般化しません。

• WindowsでOllamaをインストール - 導入、起動、localhostの基本へ戻る
• Ollamaモデル管理 - ls、show、ps、容量整理を確認する
• Ollama公式モデル一覧 - モデル名とタグの確認先を見る

PowerShellからnative /api/chatへJSON Schemaを渡す

WindowsのPowerShellでは、JSONを文字列として手作業でエスケープするより、ハッシュテーブルをConvertTo-Jsonで組み立てるとschemaの階層を確認しやすくなります。Ollama Chat APIのstream既定値はtrueなので、最初はfalseにして完成したmessage.contentを検証します。

$body = @{
  model = "MODEL"
  messages = @(@{ role = "user"; content = "商品メモを分類してください" })
  stream = $false
  format = @{
    type = "object"
    properties = @{
      category = @{ type = "string" }
      summary = @{ type = "string" }
      tags = @{ type = "array"; items = @{ type = "string" } }
    }
    required = @("category", "summary", "tags")
  }
  options = @{ temperature = 0 }
} | ConvertTo-Json -Depth 10

$response = Invoke-RestMethod `
  -Uri "http://localhost:11434/api/chat" `
  -Method Post `
  -ContentType "application/json" `
  -Body $body

$result = $response.message.content | ConvertFrom-Json
$result | ConvertTo-Json

schemaを渡しても、返った文字列をそのまま信頼できるとは限りません。JSONとして読めること、期待した項目があること、値の範囲が正しいことを順に確認します。

• Ollama Chat API公式docs - format、stream、response fieldsを確認する
• Ollama OpenAI互換API - native APIと/v1 endpointの違いを見る
• ローカルAI API入門 - localhost APIとproviderの基本へ進む

PythonではPydanticのschemaと検証を分ける

Ollama公式のPython例では、Pydanticモデルのmodel_json_schema()をformatへ渡し、返ったmessage.contentをmodel_validate_json()で検証します。schemaを生成する処理と、受け取ったJSONを信頼できるデータへ変換する処理を同じものと考えないことが重要です。

from ollama import chat
from pydantic import BaseModel

class Note(BaseModel):
    category: str
    summary: str
    tags: list[str]

response = chat(
    model="MODEL",
    messages=[{"role": "user", "content": "商品メモを分類してください"}],
    format=Note.model_json_schema(),
    options={"temperature": 0},
)

note = Note.model_validate_json(response.message.content)
print(note.category)
print(note.tags)

• Pydanticの型とrequired項目を、モデルへ渡すschemaの契約として先に決める。
• JSON文字列をmodel_validate_json()へ渡し、parse失敗を成功扱いにしない。
• 値の候補、文字列の長さ、配列の件数、業務上の妥当性は別のチェックとして持つ。
• schemaを複雑にしすぎず、まず分類・短い要約・タグのような小さな出力で確認する。

Python SDKやPydanticをサイトの依存関係へ追加する手順ではありません。読者のアプリ側で既存の環境に合わせて導入し、バージョンとエラー処理を管理します。

• Ollama Structured Outputs公式docs - Pydanticのmodel_json_schemaと検証例を見る
• VS CodeとOllama - ローカルproviderを開発環境へ接続する流れを見る
• ローカルLLMの安全性 - 入力・ログ・外部送信の境界を確認する

JavaScriptではZodでJSON.parse後の型を検証する

Ollama公式のJavaScript例では、Zod schemaをz.toJSONSchema()でformatへ渡し、返ったmessage.contentをJSON.parseしてからSchema.parse()へ通します。JSON.parseできたことと、アプリが期待する型・値になっていることは別の判定です。

import ollama from "ollama"
import * as z from "zod"

const Note = z.object({
  category: z.string(),
  summary: z.string(),
  tags: z.array(z.string()),
})

const response = await ollama.chat({
  model: "MODEL",
  messages: [{ role: "user", content: "商品メモを分類してください" }],
  format: z.toJSONSchema(Note),
  options: { temperature: 0 },
})

const note = Note.parse(JSON.parse(response.message.content))
console.log(note.category, note.tags)

stream=trueへ進む場合も、断片を完成させる前にJSON.parseやアプリ処理を始めません。まず非streamで基準を作り、chunkの収集、終了条件、空応答、再試行を別に設計します。

• Ollama Structured Outputs公式docs - ZodとJSON Schemaの公式例を見る
• Ollama回答が途中で止まるとき - stream、done、contextの切り分けを見る
• Ollamaが遅いとき - 速度とJSON検証の問題を分ける

OpenAI互換・Tool calling・local/cloudの境界を確認する

Ollamaのnative APIではformatへJSON Schemaを渡します。公式のOpenAI互換APIでは、既存clientのbase URLをhttp://localhost:11434/v1/へ向け、Structured Outputsはresponse_formatとして扱う入口がありますが、native APIと同じフィールドがすべて同じ挙動になるとは限りません。

Ollama公式Structured Outputs docsには、Ollama Cloudは現在structured outputsをサポートしないという注記があります。local modelとcloud modelをモデル名だけで同一視せず、利用するendpoint、provider、保存・送信範囲を確認します。

• Ollama OpenAI互換API - base URL、/v1 endpoint、model IDを確認する
• Ollama tool calling - toolsと関数実行の実装へ分岐する
• Ollamaのlocal/cloud - 推論場所とデータ経路の違いを見る

Structured Outputsが崩れるときの切り分け

JSON Schemaを渡しても、モデル、schema、stream、入力、SDK、API endpointのどこで失敗したかを分けて確認します。公式docsもPydanticやZodによる検証、temperatureを低くすること、schemaの意図をpromptにも含めることを信頼性のヒントとして挙げています。

1. まずollama run MODELで通常chatが返るか、次にnative /api/chatでstream=falseが返るか確認する。
2. format: "json"でJSON.parseまたはConvertFrom-Jsonできるか確認し、schema付きへ進む。
3. schemaの項目数、ネスト、requiredを減らし、短い入力とtemperature 0に近い設定で再試行する。
4. 本文をJSON.parseした後にPydantic、Zod、アプリ固有の値検証を行う。
5. nativeとOpenAI互換、localとcloud、Structured Outputとtool callingを混ぜず、失敗した層だけを修正する。

• 余分な説明文が混ざる場合は、schema・prompt・endpoint・model・streamを確認する。
• required項目が欠ける場合は、schemaを短くし、モデルの対応情報と出力ログを確認する。
• parseは成功しても値が不適切な場合があるため、列挙値、長さ、件数、業務ルールを追加検証する。
• 実データ、秘密情報、削除・書き込み・外部送信を最初のテスト対象にしない。

• Ollama Structured Outputs公式docs - 信頼性のヒントと対応範囲を再確認する
• OllamaのAPIエラー - server、port、localhostの診断へ進む
• ローカルAIのトラブルシューティング - モデル・メモリ・入力の問題を横断して見る