API リファレンス

SageMaker の Amazon Nova モデルは、推論に標準の SageMaker ランタイム API を使用します。完全な API ドキュメントについては、「デプロイされたモデルをテストする」を参照してください。

エンドポイントの呼び出し

SageMaker の Amazon Nova モデルは、以下の 2 つの呼び出し方法をサポートしています。

同期呼び出し: InvokeEndpoint API をリアルタイムの非ストリーミング推論リクエストに使用します。
ストリーミング呼び出し: リアルタイムストリーミング推論リクエストには InvokeEndpointWithResponseStream API を使用します。

リクエストの形式

Amazon Nova モデルは、以下の 2 つのリクエスト形式をサポートしています。

チャット補完形式

会話型インタラクションには、以下の形式を使用します。


{
  "messages": [
    {"role": "user", "content": "string"}
  ],
  "max_tokens": integer,
  "max_completion_tokens": integer,
  "stream": boolean,
  "temperature": float,
  "top_p": float,
  "top_k": integer,
  "logprobs": boolean,
  "top_logprobs": integer,
  "allowed_token_ids": [integer],
  "truncate_prompt_tokens": integer,
  "stream_options": {
    "include_usage": boolean
  }
}

テキスト補完形式

シンプルなテキスト生成には、以下の形式を使用します。


{
  "prompt": "string",
  "max_tokens": integer,
  "stream": boolean,
  "temperature": float,
  "top_p": float,
  "top_k": integer,
  "logprobs": integer,
  "allowed_token_ids": [integer],
  "truncate_prompt_tokens": integer,
  "stream_options": {
    "include_usage": boolean
  }
}

マルチモーダルチャット補完形式

イメージとテキストの入力には、以下の形式を使用します。


{
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "What's in this image?"},
        {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,..."}}
      ]
    }
  ],
  "max_tokens": integer,
  "temperature": float,
  "top_p": float,
  "stream": boolean
}

リクエストパラメータ

messages (配列): チャット補完形式用。フィールド role と content フィールドを持つメッセージオブジェクトの配列。コンテンツは、テキストのみの文字列でも、マルチモーダル入力の配列でもかまいません。
prompt (文字列): テキスト補完形式用。生成元の入力テキスト。
max_tokens (整数): レスポンスで生成するトークンの最大数。範囲: 1 以上。
max_completion_tokens (整数): チャット補完用の max_tokens の代替。生成する補完トークンの最大数。
temperature (浮動): 生成時のランダム性を制御します。範囲: 0.0～2.0 (0.0 = 決定的、2.0 = 最大ランダム性)。
top_p (浮動): Nucleus サンプリングしきい値。範囲: 1e-10～1.0。
top_k (整数): 最も可能性の高い上位 K 個のトークンにトークン選択を制限します。範囲: -1 以上 (-1 = 制限なし)。
stream (ブール値): レスポンスをストリーミングするかどうか。ストリーミングする場合は true に設定し、ストリーミングしない場合は false に設定します。
logprobs (ブール値/整数): チャット補完の場合は、ブール値を使用します。テキスト補完の場合は、返されるログ確率の数に整数を使用します。範囲: 1～20 です。
top_logprobs (整数): 確率の高い上位トークンのログ確率をいくつ返すか指定します (チャットの完了のみ)。
allowed_token_ids (配列): 生成できるトークン ID のリスト。指定されたトークンへの出力を制限します。
truncate_prompt_tokens (整数): 制限を超えた場合は、この数のトークンにプロンプトを切り捨てます。
stream_options (オブジェクト): ストリーミングレスポンスのオプション。ストリーミングレスポンスにトークン使用量を含める include_usage ブール値が含まれます。

レスポンスの形式

レスポンスの形式は、呼び出し方法とリクエストタイプによって異なります。

チャット補完レスポンス (非ストリーミング)

同期チャット補完リクエストの場合:


{
  "id": "chatcmpl-123e4567-e89b-12d3-a456-426614174000",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "nova-micro-custom",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! I'm doing well, thank you for asking. How can I help you today?",
        "refusal": null,
        "reasoning": null,
        "reasoning_content": null
      },
      "logprobs": {
        "content": [
          {
            "token": "Hello",
            "logprob": -0.31725305,
            "bytes": [72, 101, 108, 108, 111],
            "top_logprobs": [
              {
                "token": "Hello",
                "logprob": -0.31725305,
                "bytes": [72, 101, 108, 108, 111]
              },
              {
                "token": "Hi",
                "logprob": -1.3190403,
                "bytes": [72, 105]
              }
            ]
          }
        ]
      },
      "finish_reason": "stop",
      "stop_reason": null,
      "token_ids": [9906, 0, 358, 2157, 1049, 11, 1309, 345, 369, 6464, 13]
    }
  ],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 12,
    "total_tokens": 21,
    "prompt_tokens_details": {
      "cached_tokens": 0
    }
  },
  "prompt_token_ids": [9906, 0, 358]
}

テキスト補完レスポンス (非ストリーミング)

同期テキスト補完リクエストの場合:


{
  "id": "cmpl-123e4567-e89b-12d3-a456-426614174000",
  "object": "text_completion",
  "created": 1677652288,
  "model": "nova-micro-custom",
  "choices": [
    {
      "index": 0,
      "text": "Paris, the capital and most populous city of France.",
      "logprobs": {
        "tokens": ["Paris", ",", " the", " capital"],
        "token_logprobs": [-0.31725305, -0.07918124, -0.12345678, -0.23456789],
        "top_logprobs": [
          {
            "Paris": -0.31725305,
            "London": -1.3190403,
            "Rome": -2.1234567
          },
          {
            ",": -0.07918124,
            " is": -1.2345678
          }
        ]
      },
      "finish_reason": "stop",
      "stop_reason": null,
      "prompt_token_ids": [464, 6864, 315, 4881, 374],
      "token_ids": [3915, 11, 279, 6864, 323, 1455, 95551, 3363, 315, 4881, 13]
    }
  ],
  "usage": {
    "prompt_tokens": 5,
    "completion_tokens": 11,
    "total_tokens": 16,
    "prompt_tokens_details": {
      "cached_tokens": 0
    }
  }
}

チャット補完ストリーミングレスポンス

ストリーミングチャット補完リクエストの場合、レスポンスはサーバー送信イベント (SSE) として送信されます。


data: {
  "id": "chatcmpl-123e4567-e89b-12d3-a456-426614174000",
  "object": "chat.completion.chunk",
  "created": 1677652288,
  "model": "nova-micro-custom",
  "choices": [
    {
      "index": 0,
      "delta": {
        "role": "assistant",
        "content": "Hello",
        "refusal": null,
        "reasoning": null,
        "reasoning_content": null
      },
      "logprobs": {
        "content": [
          {
            "token": "Hello",
            "logprob": -0.31725305,
            "bytes": [72, 101, 108, 108, 111],
            "top_logprobs": [
              {
                "token": "Hello",
                "logprob": -0.31725305,
                "bytes": [72, 101, 108, 108, 111]
              }
            ]
          }
        ]
      },
      "finish_reason": null,
      "stop_reason": null
    }
  ],
  "usage": null,
  "prompt_token_ids": null
}

data: {
  "id": "chatcmpl-123e4567-e89b-12d3-a456-426614174000",
  "object": "chat.completion.chunk",
  "created": 1677652288,
  "model": "nova-micro-custom",
  "choices": [
    {
      "index": 0,
      "delta": {
        "content": "! I'm"
      },
      "logprobs": null,
      "finish_reason": null,
      "stop_reason": null
    }
  ],
  "usage": null
}

data: {
  "id": "chatcmpl-123e4567-e89b-12d3-a456-426614174000",
  "object": "chat.completion.chunk",
  "created": 1677652288,
  "model": "nova-micro-custom",
  "choices": [
    {
      "index": 0,
      "delta": {},
      "finish_reason": "stop",
      "stop_reason": null
    }
  ],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 12,
    "total_tokens": 21,
    "prompt_tokens_details": {
      "cached_tokens": 0
    }
  }
}

data: [DONE]

テキスト補完ストリーミングレスポンス

ストリーミングテキスト補完リクエストの場合:


data: {
  "id": "cmpl-123e4567-e89b-12d3-a456-426614174000",
  "object": "text_completion",
  "created": 1677652288,
  "model": "nova-micro-custom",
  "choices": [
    {
      "index": 0,
      "text": "Paris",
      "logprobs": {
        "tokens": ["Paris"],
        "token_logprobs": [-0.31725305],
        "top_logprobs": [
          {
            "Paris": -0.31725305,
            "London": -1.3190403
          }
        ]
      },
      "finish_reason": null,
      "stop_reason": null
    }
  ],
  "usage": null
}

data: {
  "id": "cmpl-123e4567-e89b-12d3-a456-426614174000",
  "object": "text_completion",
  "created": 1677652288,
  "model": "nova-micro-custom",
  "choices": [
    {
      "index": 0,
      "text": ", the capital",
      "logprobs": null,
      "finish_reason": null,
      "stop_reason": null
    }
  ],
  "usage": null
}

data: {
  "id": "cmpl-123e4567-e89b-12d3-a456-426614174000",
  "object": "text_completion",
  "created": 1677652288,
  "model": "nova-micro-custom",
  "choices": [
    {
      "index": 0,
      "text": "",
      "finish_reason": "stop",
      "stop_reason": null
    }
  ],
  "usage": {
    "prompt_tokens": 5,
    "completion_tokens": 11,
    "total_tokens": 16
  }
}

data: [DONE]

レスポンスフィールドの説明

id: 補完の一意の識別子
object: 返されるオブジェクトのタイプ ("chat.completion"、"text_completion"、"chat.completion.chunk")
created: 補完が作成された時刻の Unix タイムスタンプ
model: 補完に使用されるモデル
choices: 補完選択肢の配列
usage: プロンプト、補完、合計トークンを含むトークン使用状況情報
logprobs: トークンのログ確率情報 (リクエストされた場合)
finish_reason: モデルが生成を停止した理由 ("stop"、"length"、"content_filter")
delta: ストリーミングレスポンスの増分コンテンツ
reasoning: reasoning_effort を使用する場合の推論コンテンツ
token_ids: 生成されたテキストのトークン ID の配列

完全な API ドキュメントについては、「InvokeEndpoint API リファレンス」および「InvokeEndpointWithResponseStream API リファレンス」を参照してください。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

はじめに

モデルを評価する