referencia de la API - Amazon Nova
Invocación del punto de conexiónFormato de solicitudesFormato de respuesta

referencia de la API

Los modelos de Amazon Nova en SageMaker utilizan la API estándar de Tiempo de ejecución de SageMaker Runtime para realizar inferencias. Para obtener la documentación completa de la API, consulte Test a deployed model.

Invocación del punto de conexión

Los modelos de Amazon Nova en SageMaker admiten dos métodos de invocación:

  • Invocación sincrónica: utilice la API InvokeEndpoint para solicitudes de inferencia en tiempo real sin transmisión.

  • Invocación con transmisión: utilice la API InvokeEndpointWithResponseStream para las solicitudes de inferencia en tiempo real con transmisión.

Formato de solicitudes

Los modelos de Amazon Nova admiten dos formatos de solicitud:

Formato de finalización de chat

Use este formato para las interacciones conversacionales:

{
  "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
  }
}

Formato de finalización de texto

Use este formato para generar texto simple:

{
  "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
  }
}

Formato de finalización de chat multimodal

Use este formato para la entrada de imágenes y texto:

{
  "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
}

Parámetros de solicitud

  • messages (matriz): para el formato de finalización de chat. Matriz de objetos de mensaje con los campos role y content. El contenido puede ser una cadena de solo texto o una matriz de entradas multimodales.

  • prompt (cadena): para el formato de finalización de texto. El texto de entrada desde el que se generará.

  • max_tokens (entero): número máximo de tokens que se generarán en la respuesta. Rango: 1 o más.

  • max_completion_tokens (entero): alternativa a max_tokens para el formato de finalización de chat. Número máximo de tokens de finalización que se generarán.

  • temperature (float): controla la asignación al azar en la generación. Rango: de 0,0 a 2,0 (0,0 = determinista, 2,0 = asignación al azar máxima).

  • top_p (float): umbral de muestreo del núcleo Rango: del 1e-10 al 1,0.

  • top_k (entero): limita la selección de tokens a los K más probables. Rango: entero -1 o mayor (-1 = sin límite).

  • stream (booleano): indica si se debe transmitir la respuesta. Establezca el valor en true para transmitir o en false si no quiere transmisión.

  • logprobs (booleano/entero): para finalizaciones de chat, use un valor booleano. Para la finalización de texto, utilice un número entero como número de probabilidades logarítmicas que se deben devolver. Rango: del 1 al 20

  • top_logprobs (entero): número de tokens más probables para los cuales devolver probabilidades logarítmicas (solo para finalizaciones de chat).

  • allowed_token_ids (matriz): lista de ID de token que se pueden generar. Restringe la salida a los tokens especificados.

  • truncate_prompt_tokens (entero): trunca la petición a este número de símbolos si supera el límite.

  • stream_options (objeto): opciones para transmitir las respuestas. Contiene el valor booleano de include_usage que indica si incluir el uso de tokens en las respuestas transmitidas.

Formato de respuesta

El formato de respuesta depende del método de invocación y del tipo de solicitud:

Respuesta de finalización de chat (sin transmisión)

Para solicitudes de finalización de chat sincrónicas:

{
  "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]
}

Respuesta de finalización de texto (sin transmisión)

Para solicitudes de finalización de texto sincrónicas:

{
  "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
    }
  }
}

Respuesta de finalización de chat con transmisión

En el caso de las solicitudes de finalización de chat con transmisión, las respuestas se envían como eventos enviados por el servidor (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]

Respuesta de finalización de texto con transmisión

Para solicitudes de finalización de texto con transmisión:

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]

Explicación de los campos de respuesta

  • id: identificador único de la finalización

  • object: tipo de objeto devuelto (“chat.completion”, “text_completion”, “chat.completion.chunk”)

  • created: marca de tiempo Unix del momento en que se creó la finalización

  • model: modelo utilizado para la finalización

  • choices: matriz de opciones de finalización

  • usage: información sobre el uso de las tokens, lo que incluye la petición, la finalización y el número total de tokens

  • logprobs: información de probabilidades logarítmicas de los tokens (cuando se solicite)

  • finish_reason: motivo por el que el modelo dejó de generar (“stop”, “length”, “content_filter”)

  • delta: contenido incremental en las respuestas con transmisión

  • reasoning: contenido de razonamiento cuando se use reasoning_effort

  • token_ids: matriz de ID de tokens para el texto generado

Para obtener la documentación completa de la API, consulte InvokeEndpoint API reference y InvokeEndpointWithResponseStream API reference.