OllamaのAPI streamingをWindowsで使う方法｜NDJSON・done・PowerShell

先に結論：native APIのstreamはNDJSON、最初はstream=falseで基準を作る

OllamaのREST APIでstreamingを使うと、完成した1つのJSONではなく、改行区切りのJSONが順番に届きます。公式のStreaming docsでは、/api/generateのようなendpointが既定でstreamし、Content-Typeはapplication/x-ndjsonと説明されています。

最初から逐次表示とJSON Schema、tool calling、長文を同時に足すと、モデル・endpoint・parserのどこで失敗したか分かりにくくなります。短い非機密の入力をstream=falseで動かし、同じmodelとpayloadをstream=trueへ変える順番が安全です。

• Ollama OpenAI互換API - /v1系のSSE・client形式との違いを見る
• Ollama Responses API - /v1/responsesのイベント形式を確認する
• Ollama回答が途中で止まるとき - done・context・メモリの症状診断へ進む

まず/api/generateと/api/chatの違いを固定する

native APIを使うときは、単発のpromptを送る/api/generateと、messages配列で会話を送る/api/chatを分けます。同じlocalhost:11434でも、返答の本文を読む場所が異なるため、片方のparserをもう片方へ流用しません。

API形式を変えるときは、endpoint、request field、本文の場所、終了条件、エラーの表現を一緒に変える必要があります。「localhostだから同じJSON」と扱わず、最初のレスポンスを保存してからparserの契約を決めてください。

• Ollama Generate公式docs - prompt・response・done・usageを見る
• Ollama Chat公式docs - messages・message.content・tool_callsを見る
• OllamaのモデルID確認 - /v1/models・/api/tags・/api/showでmodelを固定する

Windowsではstream=falseの完成レスポンスから確認する

PowerShellのInvoke-RestMethodは、まず完成したJSONを読む用途に向いています。REST streamingの既定値をそのまま受け取ると、行ごとのNDJSONを1つのJSONとして扱えないことがあるため、疎通の最初はstream = $falseを明示します。

$body = @{
  model = "MODEL_FROM_OLLAMA_LS"
  prompt = "WindowsのローカルAIでstream=falseを確認する短い質問"
  stream = $false
} | ConvertTo-Json -Depth 8

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

$response | Select-Object model, response, done, done_reason, `
  total_duration, prompt_eval_count, eval_count | Format-List

1. ollama lsで取得済みのmodel名を確認し、記事例のmodel名をそのまま信用しない。
2. 短い非機密promptとstream = $falseを/api/generateへ送る。
3. HTTP statusが成功でも、response、done、done_reasonを確認する。
4. 同じmodelとpromptで、次の段階だけstream = $trueへ変更する。

Structured Outputsや長文の評価を始める前に、短い完成レスポンスの形を保存します。モデルの品質、速度、JSONとしての妥当性はこの疎通成功だけでは保証されないため、用途別の検証を別に行います。

• Ollama API Introduction公式docs - localhost:11434/apiのbase URLを見る
• Ollama Structured Outputs - JSON Schemaとstream=falseの検証へ進む
• Ollama API認証 - localとcloudの認証経路を分ける

curl.exe -NでNDJSONの到着単位を観察する

stream=trueへ変えた最初の観察には、Windowsにあるcurl.exeの`-N`（バッファリングを抑える指定）を使えます。これは完成済みJSONを返すInvoke-RestMethodの確認とは別の用途で、到着した1行ごとのJSON、responseの断片、最後のdoneを目視するための手順です。

$payload = @{
  model = "MODEL_FROM_OLLAMA_LS"
  prompt = "短い説明を3文で返してください"
  stream = $true
} | ConvertTo-Json -Compress

curl.exe -N `
  -X POST "http://localhost:11434/api/generate" `
  -H "Content-Type: application/json" `
  -d $payload

• NDJSONは、SSEのevent:行やdata:接頭辞を前提にしない。まず1行を1つのJSON objectとして読む。
• 行内のresponse断片を順番に連結し、doneやdone_reasonを本文へ連結しない。
• 空行、接続切断、error property、想定外のJSONを別の状態として記録する。
• 実文書、API key、cookie、個人情報をstreamの観察入力や画面共有へ入れない。

実際の到着単位は、Ollamaのversion、model、ネットワーク、クライアントのbufferingで見え方が変わる場合があります。表示が遅いことだけで生成停止やモデル不良と断定せず、最終chunkとHTTP応答も確認します。

• Ollama Streaming公式docs - application/x-ndjsonとstream=falseを見る
• Ollama native Chat API - /api/chatのmessage chunkを確認する
• OllamaのAPIエラー - stream中のerror objectを確認する

行単位でresponse・message・thinkingを蓄積し、doneで確定する

アプリ側のparserは、ネットワークから届く任意のbyte境界をJSONの境界だと決めつけず、改行で1行を切り出してからConvertFrom-JsonやJSON.parseへ渡します。/api/generateではresponse、/api/chatではmessage.contentを蓄積し、thinkingやtool_callsは別フィールドとして扱います。

$text = ""
$thinking = ""

# $line はNDJSONから1行ずつ取り出した文字列とする
$chunk = $line | ConvertFrom-Json

if ($chunk.error) {
  throw "Ollama stream error: $($chunk.error)"
}
if ($null -ne $chunk.response) {
  $text += [string]$chunk.response
}
if ($null -ne $chunk.message.content) {
  $text += [string]$chunk.message.content
}
if ($null -ne $chunk.message.thinking) {
  $thinking += [string]$chunk.message.thinking
}
if ($chunk.done -eq $true) {
  # ここでdone_reasonとusageを保存してparserを終了する
}

公式のStreaming capability docsではPython・JavaScript SDKでstreamを反復し、partial messageを蓄積して会話履歴へ戻す例が示されています。SDKはRESTのNDJSONを自分で読む場合と層が違うため、PythonやJavaScriptでは利用時点の公式SDK例と実際のchunk型を確認します。

• Ollama Streaming capability公式docs - Python・JavaScriptのchunk蓄積を見る
• Ollama tool calling - tool_callsを蓄積して安全に実行する境界を見る
• Ollama Modelfile - modelのtemplate・parameterを確認する

途中エラーはHTTP statusだけでなく各chunkのerrorを見る

Ollama公式Errors docsでは、stream開始後にエラーが発生すると、HTTP statusを変更できずapplication/x-ndjsonのobjectとしてerrorが返る場合があると説明されています。したがって、statusが200だから最後まで成功した、接続が閉じたから正常終了した、とは判断しません。

1. 同じmodelと短い入力をstream=falseで再実行し、完成JSONが返るか確認する。
2. stream=trueの最初のerror行または最後の正常行を、秘密情報を除いて保存する。
3. endpoint・model・context・client・proxyを一度に変更せず、1項目ずつ戻す。
4. cloud modelやLAN公開が関係する場合はlocal APIの成功と分けて認証・privacy・料金条件を確認する。

エラー本文にpromptやファイル名が混ざる可能性があるログは、そのまま共有しません。原因究明に必要なstatus、endpoint、modelの識別情報、done状態だけに絞り、実データとsecretを除外します。

• Ollama Errors公式docs - statusとstream中のerrorを確認する
• Ollama troubleshooting - server・model・メモリの症状診断へ進む
• Ollama API認証 - local・cloud・API keyを分ける

最後のdone chunkからusageを記録する

native APIの最終レスポンスには、done、done_reasonに加えて、total_duration、load_duration、prompt_eval_count、prompt_eval_duration、eval_count、eval_durationなどのusageが含まれる場合があります。公式Usage docsでは時間の単位はナノ秒と説明されています。

# $chunk はdone=trueの最後のobject
$usage = [ordered]@{
  model = $chunk.model
  done = $chunk.done
  done_reason = $chunk.done_reason
  total_duration_ns = $chunk.total_duration
  load_duration_ns = $chunk.load_duration
  prompt_eval_count = $chunk.prompt_eval_count
  eval_count = $chunk.eval_count
  eval_duration_ns = $chunk.eval_duration
}
$usage | ConvertTo-Json

• eval_durationが0または未返却なら、tokens/secを計算しない。
• 同じmodel、prompt長、context、options、warm/cold状態を揃えずに速度順位を作らない。
• load_durationとeval_durationを分け、初回ロードの待ち時間と生成時間を混同しない。
• usageは測定時点の観測値であり、モデルの品質・正確性・privacyの保証ではない。

streamingの目的は表示開始を早めることですが、最終的な速度・品質・消費メモリはmodel、context、PC、options、同時実行で変わります。計測を記事や比較表へ転用する場合は、条件と日時、versionを別に残してください。

• Ollama Usage公式docs - usage項目とナノ秒単位を見る
• ローカルAI速度ベンチマーク - 条件を揃えた計測の考え方を見る
• Ollamaモデルidentity - model ID・digest・実行状態を記録する