LLM API の基礎: リクエスト、レスポンス、メッセージの役割

利益:

LLM API リクエストの基本構造 (エンドポイント、モデル、メッセージ、max_tokens) を記述できます。
システム、ユーザー、アシスタントの役割とステートレスな会話履歴の違いを理解する
返された応答のフィールド (コンテンツブロック、stop_reason、usage) を読み取り、解釈できます。

以前のモジュールでは、チャットウィンドウから人工知能を使用しました。しかし、AI を自社の製品、自動化、またはワークフローに埋め込みたい場合、チャットインターフェイスだけでは役に立ちません。プログラム的に、つまりコードまたは自動化ツールを使用してモデルに接続する必要があります。このブリッジの名前は API (Application Programming Interface、2 つのソフトウェアが特定のルールに従って通信できるようにする契約) です。この単元を完了すると、LLM (Large Language Model) API リクエストの構成、メッセージロールの役割、および応答の読み方がわかるようになります。これは、モジュールの残りの部分が構築される基礎になります。

API はどのように機能するのか?

API の基本的なフローは次のとおりです。特定の形式でリクエストを送信します。サーバーは特定の形式で応答を返します。 LLM では、これは通常、単一のアドレス (エンドポイント、要求を処理するサーバー上の固定アドレス) への HTTP 呼び出し (HTTP: Web 上で要求と応答を伝送するための標準プロトコル) です。たとえば、メッセージング API では、すべてのリクエストが 1 つのアドレスに送信され、JSON (JavaScript Object Notation - 人間とマシンの両方が読み取ることができるキーと値のペアで構成されるテキスト形式) として本文に送信されます。

リクエストでは、少なくとも次の 3 つを指定します。

モデル: 使用するモデル (高速で安価なモデルまたは強力なモデルなど)。
max_tokens: モデルが生成できるトークン (テキストが処理される最小単位。次の単位で詳細に処理されます) の最大数。つまり出力制限です。
メッセージ: 会話を構成するメッセージのリスト。

ステップバイステップ: リクエストを設定する方法

エンドポイントと認証情報を準備します。 API キー (身元を証明する秘密の文字列) をリクエストのヘッダーに追加します。コードにキーを埋め込むことはありません。ユニット 9 の安全な保管場所について説明します。
モデルと出力制限を選択します。軽量モデル + 単純なタスク用の小さい max_token。強力なモデル + 複雑なタスクに対する制限の拡大。
メッセージリストを設定します。 List the system instruction, user message, and past rounds (if any).
リクエストを送信し、レスポンスを解析します。返された JSON からテキストの内容、停止理由、トークンの使用状況を読み取ります。

メッセージの役割: システム、ユーザー、アシスタント

会話はシーケンスに配置されたメッセージで構成され、各メッセージには役割があります。ロールによって、モデルがそのテキストをどのように処理するかが決まります。

役割

誰が書くのか

目的

システム

開発者/運営者

会話全体に適用される永続的な指示、性格、ルール

ユーザー

エンドユーザー

ユーザーの現在の質問または入力

アシスタント

モデル

モデルによって生成された応答 (および以前の応答)

システムロールは、ほとんどのプロバイダーのリクエスト本文の別のシステムフィールドとして使用できます。ユーザーとアシスタントはメッセージリストに順番にリストされます。 Critical point: the system instruction is the high-level instruction, the user message is the request to be answered at that moment.

{ "model": "claude-opus-4-8", "max_tokens": 1024, "system": "あなたは企業のサポートアシスタントです。短く、形式的で確認済みの応答をしてください。確信のない情報をでっち上げないでください。", "messages": [ { "role": "user", "content": "返品プロセスを開始するにはどうすればよいですか?" } ]}

音声は無国籍です

最も一般的な誤解は次のとおりです。LLM API 呼び出しはステートレスです。サーバーは 2 つのリクエストの間にメモリを保持しません。モデルは前回のリクエストを覚えていません。マルチラウンドチャットを設定している場合は、新しいリクエストごとに過去のラウンドを再送信する必要があります。モデルの「メモリ」は、送信したメッセージのリストで構成されます。

{ "model": "claude-opus-4-8", "max_tokens": 512, "messages": [ { "role": "user", "content": "こんにちは、私の名前はデニズです。" }, { "role": "アシスタント", "content": "こんにちは、デニズ、どのようにお手伝いできますか?" }, { "role": "user", "content": "今私の名前を言いましたが、覚えていますか?" } ]}

3 番目のメッセージに正しく応答できるかどうかは、前の両方のメッセージを送信したかどうかにかかっています。送信しないとモデルは「海」を知らず、誤答してしまいます。これはコストにも直接影響します。会話が長くなるにつれてリストが大きくなり、各リクエストがより多くのトークンを消費します。

ヒント: 長い会話の場合、履歴全体を送信するのではなく、古いラウンド (概要 + 最後の数ラウンド) を要約して移動すると、コストが削減され、コンテキストウィンドウが保持されます。これについては単元 6 と 11 でさらに深めていきます。

答えを読む

モデルが応答を返すと、プレーンテキストではなく構造化オブジェクトを受け取ります。典型的な領域:

{ "id": "msg_01ABC...", "model": "claude-opus-4-8", "role": "assistant", "content": [ { "type": "text", "text": "返品を開始するには、アカウントの [注文] ページにアクセスしてください..." } ], "stop_reason": "end_turn", "usage": { "input_tokens": 47, "出力トークン": 88 }}

content: 応答自体。コンテンツブロックのリストです。テキストブロックのテキストフィールドが実際の回答です。
stop_reason: モデルが停止した理由。 end_turn = 自然な終わり; max_tokens = 出力制限でスタックしています (応答が不完全である可能性があります);拒否 = セキュリティ上の理由から拒否されます。コードでは常に stop_reason を最初に確認する必要があります。
使用法: トークン番号を入力および出力します。これはコストと制限の追跡の基礎となります。

注意: stop_reason が max_tokens の場合、応答は完了していません。これを「成功した応答」として扱い、ユーザーに半分のテキストを表示することは、運用環境で最もよくある間違いの 1 つです。 max_tokens を増やすか、ストリーミングを使用してください。

弱いプロンプト / 強いプロンプト

2 つの異なるシステムプロンプトを使用した同じタスク:

# WEAKあなたはアシスタントです。質問に答える。

# STRONGあなたは企業のサポートアシスタントです。ルール:- 提供されたポリシー文書内の情報のみに依存してください。文書に記載されていない場合は、「この情報は持っていません。関連部署に伝えています。」と伝えてください。 - 回答は 3 文以内で、形式的かつ明確にしてください。 - 個人情報 (TC ID 番号、カード番号) を尋ねたり、繰り返したりしないでください。 - 確信がない場合は推測しないでください。

強力なバージョン。範囲、形式、安全マージン、および不確実性における動作を定義します。モデル出力の一貫性は、この明確さから直接得られます。

ミニケース3個

ケース 1 — サポートボット (ステートレストラップ)。電子商取引チームがボットをライブで撮影しました。ユーザーが「前の注文をキャンセル」と言ったとき、ボットは注文番号を「忘れ」ました。理由: 彼らは最後のメッセージのみを含む各リクエストを送信していました。解決策: メッセージリストに最後の 6 ラウンドを追加しました。結果: コンテキストは保持されますが、リクエストあたりの入力は 40 トークンから ~600 トークンに増加しました。コストのレッスンについては、ユニット 2 で説明します。

ケース 2 — 不完全な契約概要。法務チームは 10 ページにわたる契約書の概要を作成していました。 max_tokens: 300 は低いままで、要約が文の途中で切れていました。 stop_reason は毎回 max_tokens でしたが、誰も見ていませんでした。 max_tokens を 1500 に増加し、stop_reason チェックを追加しました。切り捨てられた要約率は 18% から 0% に減少しました。

ケース 3 — 役割の混合。マーケティングチームはすべての指示をユーザーメッセージに書き込み、システムを空白のままにしていました。ユーザー入力が指示と混合された場合、モデルは「以前のルールを忘れてください」というユーザーのコマンドに従うことがありました。彼らは恒久的なルールをシステムに移行しました。ユーザー入力を指示から分離することで、ルール違反が大幅に減少しました。

よくある間違い

過去を送ることを忘れる: モデルは「覚えていない」と考えられています。一方、それは無国籍です。あなたはコンテキストを持ちます。
「stop_reason」を見ていない: max_tokens で停止された応答は完了したとみなされます。
「user」に命令を埋め込む: システムへの永続的なルール。瞬時の入力がユーザーに送られます。混在させるとセキュリティ上の脆弱性が生じます。
「content」をプレーンな文字列と間違える: 答えはブロックのリストです。最初のテキストブロックのテキストフィールドを読み取り、ブラインドインデックスで content[0] を取得する前にそのタイプを確認します。
コードへのキーの埋め込み: 環境変数 (ユニット 9) を使用します。

さらに深く: コンテンツブロックと複数の部分からなる回答

応答のコンテンツフィールドがリストである理由を理解することは、後で使用する高度な機能の基礎となります。場合によっては、モデルが単一のテキストブロックではなく、複数のブロックを返すことがあります。つまり、思考のブロックの後にテキストのブロックが続きます。または、テキストのブロックの後にツール使用ブロックが続きます。そのため、コンテンツ[0]を「答え」として盲目的にカウントすることは脆弱です。正しいアプローチは、リストを調べてタイプ別に並べ替えることです。タイプフィールドがテキストであるブロックのテキストコンテンツを収集し、他のタイプ (思考、ツール) を個別に扱います。

この区別が実際に行うことは、モデルの推論 (存在する場合) をユーザーに明らかにすることなくログに記録し、ツールの呼び出しを別のロジックにリダイレクトし、実際の答えのみを画面に表示できることです。モジュールが進むにつれて (特にユニット 4 と 11)、このブロック構造が出力の検証と指示にどれほど役立つかがわかります。

もう 1 つの実用的なポイントは、異なるプロバイダープラットフォーム (クラウドプロバイダー経由の直接 API) から同じモデルにアクセスできることです。エンドポイントアドレスと認証形式は変更される場合がありますが、メッセージの役割、ステートレス性、応答構造などの基本概念は変わりません。したがって、この単元の基本は、使用するプラットフォームに関係なく適用されます。

要約すると

LLM API リクエストは、モデル、出力制限、メッセージリストで構成されます。ロール (システム、ユーザー、アシスタント) によってモデルの動作が決まります。呼び出しはステートレスです。各リクエストでコンテキストを伝えます。応答は構造化オブジェクトです。コンテンツ、stop_reason、および use フィールドの読み取りと解釈は、運用環境での耐久性の基礎です。

アプリケーションタスク

自分の職業からタスクを選択します (例: 受信メールの分類、簡単な概要の作成)。紙に: (1) 4 ～ 5 のルールを含むシステムプロンプトを書きます。 (2) サンプルのユーザーメッセージと 2 ラウンドの履歴 (存在する場合) を設定します。 (3) max_tokens の適切な値を決定し、その理由を書きます。 (4) 返された応答でどの stop_reason 値をどのように処理するかをリストします。

チェックリスト

[ ] リクエストの 3 つの必須部分 (model、max_tokens、messages) を数えることができます。
[ ] システム、ユーザー、アシスタントの役割の違いを説明できます。
[ ] 通話にはステートレスがあり、過去を引き継ぐ必要があることはわかっています。
[ ] コンテンツ、stop_reason、および使用状況フィールドを読んでコメントすることができます。
[ ] max_tokens を使用すると、切り捨てられた応答に気づき、処理できます。