Ollama APIトラブルシューティングガイド

Ollama APIエンドポイントの構造について

The ollama endpoint フィールドはOpenAI APIの構造を模した厳格なRESTfulパターンに従います。POSTリクエストを送信して対話します。 /v1/chat/completions 利用可能なモデルを GET /v1/modelsこの標準化により、クライアントコードを書き換えることなく基盤となるモデルを切り替えることができます。

多くの開発者は、エンドポイントがデフォルトで埋め込みや画像生成をサポートしていると考えています。サポートしていません。例えば、当社のホストサービスは、単一のアンセーザードモデルのみを使用してテキスト補完を提供します。常に GET /v1/models レスポンスを確認し、どの機能が公開されているか正確に確認してください。モデルのリストが表示される場合は、リクエストを送信する前にそのIDを確認してください。

ローカルインスタンスを使用する場合、エンドポイントは通常 http://localhost:11434. クラウドプロバイダーの場合、カスタムベースURLを使用します。HTTPクライアントがヘッダーを正しく処理することを確認してください。特に Content-Type: application/json. ヘッダーが欠落していると、モデルエラーのように見えるサイレントフェイルが発生することがあります。

キーの構造要素：

• model: 特定のLLMの文字列識別子。
• messages: ロールベースのコンテンツオブジェクトの配列。
• stream: サーバー送信イベント（SSE）を有効にするブールフラグ。

なぜollama API呼び出しが失敗するのか

API呼び出しは通常、base URLの誤り、期限切れのキー、または不正なJSONペイロードにより失敗します。最も一般的なエラーは401 Unauthorizedレスポンスで、APIキーが不足しているか無効であることを意味します。もう一つの頻繁な問題は404 Not Foundで、エンドポイントが要求されたパスまたはモデルIDをサポートしていないことを示します。

リクエストボディを注意深く確認してください。エンドポイントがサポートしていないパラメータ（例えば）を送信した場合、 modalities for a text-only model, the server may reject the request. Our service, for instance, does not support image input. Sending it results in an immediate error.

ネットワークタイムアウトも失敗の原因となります。ローカルのOllamaインスタンスがアイドル状態の場合、モデルがVRAMからアンロードされることがあります。コールドスタート後の最初のリクエストには数秒かかることがあります。 prematureな切断を避けるために、HTTPクライアントで寛大なタイムアウトを設定してください。

よくあるエラーコード：

• 400: Bad Request（不正なJSONまたは無効なパラメータ）。
• 401: 認証エラー（APIキーが無効または未設定）。
• 429: 多くのリクエスト（レート制限超過）。
• 500: Internal Server Error（モデル読み込み失敗）。

無制限ollamaモデルの正しい構成

アンサニモデルは、期待通りに動作させるために特定のパラメータを必要とすることがよくあります。主な違いは、 system プロンプト。標準的な拒否をバイパスするには、モデルに明示的に指示する必要があります。強力なシステムプロンプトがない場合、モデルはデフォルトの安全動作に戻ることがあります。

エンドポイントはモデルID uncensoredこのIDにリクエストを送信し、サーバーが裏側のモデル選択を処理します。これによりモデルバージョンの管理の複雑さが抽象化されます。裏側のアーキテクチャがLlamaベースかMistralベースかを知る必要はありません。

調整する temperature 創造性を制御するためのパラメータ。値0.7はバランスの取れた応答のための良い出発点です。高い値はランダム性を増し、クリエイティブなライティングには有用ですが、事実の正確性が低下する可能性があります。低い値は出力をより決定論的にします。

構成のヒント:

• 使用 top_p alongside temperature 制御に対して。
• 設定 stop 無限ループを防ぐためのシーケンス。
• 常に system ロール定義用のメッセージ。

ストリーミングとトークン制限の処理

ストリーミングレスポンスはServer-Sent Events (SSE) を介してチャンク形式でデータを返します。各チャンクには部分的な補完が含まれています。これらのチャンクを組み合わせて完全なレスポンスを取得する必要があります。当社のサービスでは、最終チャンクにトークン使用統計が含まれており、リアルタイムでコストを追跡することができます。

トークン制限は長文の会話において重要です。当エンドポイントは、プロンプトと補完を合わせた合計で100,000トークンのコンテキストウィンドウをサポートしています。ただし、1回あたりの最大出力は16,000トークンです。設定しない場合 max_tokens, デフォルトは2,048トークンです。これにより、長い回答が予期せず切り捨てられる可能性があります。

ストリーミング時は、ネットワークの中断を適切に処理してください。接続が切れた場合、サーバーがサポートしていれば、最後に受信したチャンクから再開できます。そうでない場合は、リクエスト全体を再試行する必要があるかもしれません。常に監視してください usage 最終チャンク内のフィールド。請求の予期せぬ事態を避けるために使用します。

ストリーミングのベストプラクティス：

• 空行を無視してSSEイベントを正しく解析します。
• メモリまたはバッファにチャンクを蓄積します。
• 確認 usage objectは最後のチャンクに含まれます。トークン数はここから取得します。

請求エラーとトークンの算術

課金エラーは、トークンのカウント方法の誤解に起因することが多いです。トークンは、入力（プロンプト）と出力（補完）の両方に対して課金されます。当社の価格は、1M入力トークンあたり$0.15、1M出力トークンあたり$0.50です。エラーと拒否は無料であり、デバッグ時のコストを削減します。

トークナイザーは文字と常に1:1でマッピングされるわけではありません。1つの単語が複数のトークンになることがあります。文字数に基づいてコストを見積もると、請求額を見誤る可能性があります。リクエストを送信する前に、クライアントで信頼性の高いトークナイザーライブラリを使用して正確なカウントを取得してください。

クレジットは期限切れしません。暗号通貨でチャージした場合、残高は使用するまで保持されます。これは長期プロジェクトに役立ちます。ただし、各リクエストで残高からトークンが消費される点にご注意ください。残高が不足している場合、以降のリクエストは失敗する可能性があります。

課金ヒント：

• レスポンスごとにトークン使用量を追跡します。
• 残高閾値が低い場合のアラートを設定します。
• 使用 max_tokens 潜在的なコストを上限に抑えるために使用します。

セキュリティとポートスキャンの問題

ローカルOllamaエンドポイントはデフォルトでネットワークに公開されることがよくあります。これにより、無料のコンピューティングリソースを探すポートスキャナに対して脆弱になります。認証なしでポート11434を公開すると、誰でもあなたのGPUリソースを使用できます。これにより、電気代が高騰し、パフォーマンスが低下する可能性があります。

デフォルトポートを変更するか、認証付きのリバースプロキシを使用してエンドポイントを安全にします。ホストサービスはセキュリティを処理するため、ポート露出を心配する必要はありません。APIキーをプライベートに保つことのみが必要です。

ローカル環境では、ファイアウォールを使用して信頼できるIPアドレスへのアクセスを制限してください。Ollamaの設定ファイルでトークンベースの認証を有効にすることもできます。これにより、認証されていないユーザーによるリクエストを防ぐことができます。

セキュリティ手順：

• インターネットに公開する場合はデフォルトポートを変更してください。
• HTTPSと認証付きのリバースプロキシを使用してください。
• 予期せぬアクティビティがないようネットワークトラフィックを監視してください。

ローカル vs クラウド ollama API 使用

ローカル使用により、データプライバシーとモデル選択の完全な制御が得られます。複数のモデルを同時に実行し、それらを瞬時に切り替えることができます。ただし、ハードウェアのメンテナンス、アップデート、セキュリティは自己責任となります。クラウド使用では、これらの責任はプロバイダに委ねられます。

当社のクラウドサービスは、制限なしのコンテンツ生成に最適化されたuncensoredモデルを提供します。大きなモデルファイルのダウンロードなしで即時アクセスが可能です。その代わり、データは当社のサーバーを通過します。機密データの場合、ローカル環境が好ましい場合があります。

クラウドサービスはネットワークの往復遅延によりレイテンシが高くなりがちです。ローカルインスタンスはGPUが十分に高速であればレイテンシはほぼゼロです。ただし、ローカルインスタンスには大きなVRAMが必要です。GPUのメモリが不足すると、モデルがCPUにスワップされ、応答速度が大幅に低下する可能性があります。

比較：

• ローカル： プライバシー、制御、ハードウェア依存
• クラウド： 利便性、スケーラビリティ、データ転送。

一般的なクライアントサイドのミス

開発者は往々にしてレート制限の処理を忘れています。当社のサービスは、キーごとに1分あたり300リクエストを許可します。これを超えると、429エラーが発生します。これらのエラーを適切に処理するために、クライアントで指数関数的バックオフを実装してください。

もう一つのミスは、 stream 正しく設定してください。ストリーミングを期待しているが、 stream: true全体のレスポンスを受信するまでデータが返されないため、アプリが低速に感じられることがあります。

JSONモードのエラーも一般的です。設定 response_format: {type: "json_object"}、モデルは有効なJSONを返す必要があります。そうでない場合、パーサーは失敗します。JSONパーサーエラーをキャッチして再試行するためのエラー処理を追加してください。

チェックリスト：

• レートリミット処理を実装します。
• 設定 stream: true リアルタイム更新用。
• JSONモード使用時にJSON出力を検証