Referência da API - Amazon Nova
Invocação de endpointsFormato de solicitaçãoFormato de resposta

Referência da API

Os modelos do Amazon Nova no SageMaker usam a API de execução padrão do SageMaker para inferência. Para verificar a documentação completa da API, consulte Testar um modelo implantado.

Invocação de endpoints

Os modelos do Amazon Nova no SageMaker são compatíveis com dois métodos de invocação:

  • Invocação síncrona: use a API InvokeEndpoint para solicitações de inferência em tempo real e sem streaming.

  • Invocação com streaming: use a API InvokeEndpointWithResponseStream para solicitações de inferência com streaming em tempo real.

Formato de solicitação

Os modelos do Amazon Nova são compatíveis com dois formatos de solicitação:

Formato de conclusão de chat

Use esse formato para interações conversacionais:

{
  "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 conclusão de texto

Use esse formato para geração de texto simples:

{
  "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 conclusão de chat multimodal

Use esse formato para entradas de imagem e 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 solicitação

  • messages (matriz): para formato de conclusão de chat. Matriz de objetos de mensagem com os campos role e content. O conteúdo pode ser uma string somente para texto ou uma matriz para entradas multimodais.

  • prompt (string): para formato de conclusão de texto. O texto de entrada para a geração.

  • max_tokens (inteiro): número máximo de tokens a serem gerados na resposta. Intervalo: 1 ou maior.

  • max_completion_tokens (inteiro): alternativa a max_tokens para conclusões de chats. Número máximo de tokens de conclusão a serem gerados.

  • temperature (flutuante): controla a randomização na geração. Intervalo: de 0,0 a 2,0 (0,0 = determinístico, 2,0 = randomização máxima).

  • top_p (flutuante): limite da amostragem do núcleo. Intervalo: de 1e-10 a 1,0.

  • top_k (inteiro): limita a seleção de tokens aos K tokens mais prováveis. Intervalo: -1 ou maior (-1 = sem limite).

  • stream (boleano): se a resposta deve ser transmitida. Defina como true para streaming, false para sem streaming.

  • logprobs (boleano/inteiro): para conclusões de chat, use boleano. Em conclusões de texto, use um número inteiro para o número de probabilidades logarítmicas a serem retornadas. Intervalo: de 1 a 20.

  • top_logprobs (inteiro): número de tokens mais prováveis para os quais retornar probabilidades logarítmicas (somente para conclusões de chat).

  • allowed_token_ids (matriz): lista de IDs de tokens que podem ser gerados. Restringe a saída aos tokens especificados.

  • truncate_prompt_tokens (inteiro): trunque o prompt para este número de tokens se ele exceder o limite.

  • stream_options (objeto): opções para respostas em streaming. Contém o boleano include_usage para incluir o uso de tokens nas respostas em streaming.

Formato de resposta

O formato da resposta depende do método de invocação e do tipo de solicitação:

Resposta de conclusão de chat (não streaming)

Para solicitações síncronas de conclusão de chat:

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

Resposta de conclusão de texto (não streaming)

Para solicitações síncronas de conclusão de texto:

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

Resposta em streaming para conclusão de chat

Para solicitações de conclusão de chat em streaming, as respostas são enviadas como eventos enviados pelo 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]

Resposta em streaming para conclusão de texto

Para solicitações de conclusão de texto em streaming:

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]

Explicação dos campos de resposta

  • id: identificador exclusivo para a conclusão

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

  • created: carimbo de data e hora do Unix de quando a conclusão foi criada

  • model: modelo usado para a conclusão

  • choices: matriz de opções de conclusão

  • usage: informações de uso do token, incluindo prompt, conclusão e total de tokens

  • logprobs: informações de probabilidade logarítmica para tokens (quando solicitadas)

  • finish_reason: motivo pelo qual o modelo parou de gerar (“stop”, “length”, “content_filter”)

  • delta: conteúdo incremental em respostas em streaming

  • reasoning: conteúdo de raciocínio quando reasoning_effort é usado

  • token_ids: matriz de IDs de tokens para o texto gerado

Para verificar a documentação completa das APIs, consulte a referência da API InvokeEndpoint e a referência da API InvokeEndpointWithResponseStream.