API 참조

SageMaker의 Amazon Nova 모델은 추론에 대해 표준 SageMaker 런타임 API를 사용합니다. 전체 API 설명서는 Test a deployed model을 참조하세요.

엔드포인트 간접 호출

SageMaker의 Amazon Nova 모델은 다음과 같은 두 가지 간접 호출 방법을 지원합니다.

동기식 간접 호출: 실시간 비스트리밍 추론 요청에 대해 InvokeEndpoint API를 사용합니다.
스트리밍 간접 호출: 실시간 스트리밍 추론 요청에 대해 InvokeEndpointWithResponseStream API를 사용합니다.

요청 형식

Amazon Nova 모델은 다음과 같은 두 가지 요청 형식을 지원합니다.

채팅 완료 형식

대화형 상호 작용에 대해 다음 형식을 사용합니다.


{
  "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(float): 생성 시 무작위성을 제어합니다. 범위: 0.0~2.0(0.0 = 결정적, 2.0 = 최대 무작위성).
top_p(float): 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가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

시작하기

모델 평가