ローカルLLM APIへcurlで最初のリクエストを送る方法

ローカルLLMをエディターや自作アプリへ接続する前に、curlで一度だけAPIへリクエストを送っておくと、問題を切り分けやすい。

最初に見るのは、URL、エンドポイント、モデルID、送信するJSON、返ってきたレスポンスの5つだ。

LM Studio、Ollama、llama.cppはいずれもHTTP経由でローカルモデルを利用できるが、URLやリクエスト形式まで全部同じではない。

まずサーバーのベースURLを確認する

最初に「どこへ送るか」を固定する。

Ollamaの独自APIでは、通常次のベースURLが案内されている。

http://localhost:11434/api

一方、OpenAI互換APIを使うLM Studioやllama.cppでは、/v1/...を含む別の経路を利用する構成がある。

記事やサンプルコードに書かれたポート番号をそのまま使うのではなく、自分が起動したサーバーのホスト、ポート、ベースURLを確認する。

次にエンドポイントとモデルIDを決める

同じAPIでも、チャット、単純な文章生成、Embeddingなどで利用するエンドポイントが異なる。

ベースURL: http://localhost:xxxx
エンドポイント: /...
モデルID: サーバーが認識している名前

この3点を先にメモしておけば、「接続先が違う」「エンドポイントが違う」「モデル名が違う」を別の問題として切り分けられる。

最初のJSONはできるだけ小さくする

最初からtemperature、ツール呼び出し、構造化出力などを全部入れる必要はない。

OpenAI互換のチャット形式なら、概念的には次のようなJSONになる。

{
  "model": "YOUR_MODEL_ID",
  "messages": [
    {"role": "user", "content": "こんにちは"}
  ]
}

たとえばLM Studioを既定のlocalhost設定で起動し、一覧で確認したモデルIDをYOUR_MODEL_IDへ入れる場合、bash / zshでは次の1本を最小の動作確認にできる。

curl http://localhost:1234/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"YOUR_MODEL_ID","messages":[{"role":"user","content":"こんにちは"}],"stream":false}'

YOUR_MODEL_IDは/v1/modelsなどで実際に確認した名前へ置き換える。PowerShellなど別のシェルでは引用符や改行の扱いが異なるため、コマンドの形だけを無理に流用せず、そのシェルの文字列規則に合わせる。

この例はLM StudioのOpenAI互換APIを使う場合のものだ。Ollama独自APIや別ポートのllama.cpp serverではURLや本文が異なるため、それぞれの公式API資料へ合わせる。

JSONを送るcurlでは、Content-Type: application/jsonを指定する構成が一般的だ。認証用ヘッダーが必要かどうかはサーバー設定によって変わる。

「localhostだから必ず認証不要」と一般化しない。

レスポンスがストリーミングか確認する

リクエストが成功しても、完成したJSONが1個だけ返るとは限らない。

ストリーミングが有効なら、生成途中のデータやイベントが順番に返る場合がある。ターミナルへ複数行のJSONが流れても、それだけで異常とは限らない。

クライアント実装へ進む前に、

• ストリーミングを有効にしているか
• 1回の受信単位は何か
• 正常終了を何で判定するか
• エラー時のHTTPステータスと本文は何か

を確認する。

エラーは接続先から順に切り分ける

最初のリクエストが失敗しても、いきなりモデルを再取得しない。

症状	最初に確認すること
接続できない	サーバーが起動しているか、ホスト・ポートは合っているか
404	そのエンドポイントが使用中のAPI用か
モデルが見つからない	サーバーがそのモデルIDを認識しているか
JSONエラー	JSON本文とContent-Type
途中までしか読めない	ストリーミングの形式

サーバーログを確認できるなら、curlを実行した時刻とログを対応させる。

curlで1本成功してからSDKへ進む

最初からSDKやエージェント用フレームワークを使うと、失敗点がHTTP通信なのかSDK設定なのか分かりにくくなる。

まずcurlで最小のリクエストを成功させ、使ったベースURL、エンドポイント、モデルID、返ってきた内容を保存する。

その状態からSDKへ置き換えれば、次に問題が起きたときも一段ずつ原因を切り分けやすい。

OpenAI互換APIと各ソフト独自APIの違いは、ローカルLLMのOpenAI互換APIの違いで整理できる。ストリーミングを実装する場合は、ローカルLLM APIのストリーミングを扱う方法へ進む。