Amazon Bedrock Runtime 2023-09-30
- Client: Aws\BedrockRuntime\BedrockRuntimeClient
- Service ID: bedrock-runtime
- Version: 2023-09-30
This page describes the parameters and results for the operations of the Amazon Bedrock Runtime (2023-09-30), and shows how to use the Aws\BedrockRuntime\BedrockRuntimeClient object to call the described operations. This documentation is specific to the 2023-09-30 API version of the service.
Operation Summary
Each of the following operations can be created from a client using
$client->getCommand('CommandName')
, where "CommandName" is the
name of one of the following operations. Note: a command is a value that
encapsulates an operation and the parameters used to create an HTTP request.
You can also create and send a command immediately using the magic methods
available on a client object: $client->commandName(/* parameters */)
.
You can send the command asynchronously (returning a promise) by appending the
word "Async" to the operation name: $client->commandNameAsync(/* parameters */)
.
- InvokeModel ( array $params = [] )
Invokes the specified Amazon Bedrock model to run inference using the prompt and inference parameters provided in the request body.
- InvokeModelWithResponseStream ( array $params = [] )
Invoke the specified Amazon Bedrock model to run inference using the prompt and inference parameters provided in the request body.
Operations
InvokeModel
$result = $client->invokeModel
([/* ... */]); $promise = $client->invokeModelAsync
([/* ... */]);
Invokes the specified Amazon Bedrock model to run inference using the prompt and inference parameters provided in the request body. You use model inference to generate text, images, and embeddings.
For example code, see Invoke model code examples in the Amazon Bedrock User Guide.
This operation requires permission for the bedrock:InvokeModel
action.
Parameter Syntax
$result = $client->invokeModel([ 'accept' => '<string>', 'body' => <string || resource || Psr\Http\Message\StreamInterface>, // REQUIRED 'contentType' => '<string>', 'guardrailIdentifier' => '<string>', 'guardrailVersion' => '<string>', 'modelId' => '<string>', // REQUIRED 'trace' => 'ENABLED|DISABLED', ]);
Parameter Details
Members
- accept
-
- Type: string
The desired MIME type of the inference body in the response. The default value is
application/json
. - body
-
- Required: Yes
- Type: blob (string|resource|Psr\Http\Message\StreamInterface)
The prompt and inference parameters in the format specified in the
contentType
in the header. To see the format and content of the request and response bodies for different models, refer to Inference parameters. For more information, see Run inference in the Bedrock User Guide. - contentType
-
- Type: string
The MIME type of the input data in the request. The default value is
application/json
. - guardrailIdentifier
-
- Type: string
The unique identifier of the guardrail that you want to use. If you don't provide a value, no guardrail is applied to the invocation.
An error will be thrown in the following situations.
-
You don't provide a guardrail identifier but you specify the
amazon-bedrock-guardrailConfig
field in the request body. -
You enable the guardrail but the
contentType
isn'tapplication/json
. -
You provide a guardrail identifier, but
guardrailVersion
isn't specified.
- guardrailVersion
-
- Type: string
The version number for the guardrail. The value can also be
DRAFT
. - modelId
-
- Required: Yes
- Type: string
The unique identifier of the model to invoke to run inference.
The
modelId
to provide depends on the type of model that you use:-
If you use a base model, specify the model ID or its ARN. For a list of model IDs for base models, see Amazon Bedrock base model IDs (on-demand throughput) in the Amazon Bedrock User Guide.
-
If you use a provisioned model, specify the ARN of the Provisioned Throughput. For more information, see Run inference using a Provisioned Throughput in the Amazon Bedrock User Guide.
-
If you use a custom model, first purchase Provisioned Throughput for it. Then specify the ARN of the resulting provisioned model. For more information, see Use a custom model in Amazon Bedrock in the Amazon Bedrock User Guide.
- trace
-
- Type: string
Specifies whether to enable or disable the Bedrock trace. If enabled, you can see the full Bedrock trace.
Result Syntax
[ 'body' => <string || resource || Psr\Http\Message\StreamInterface>, 'contentType' => '<string>', ]
Result Details
Members
- body
-
- Required: Yes
- Type: blob (string|resource|Psr\Http\Message\StreamInterface)
Inference response from the model in the format specified in the
contentType
header. To see the format and content of the request and response bodies for different models, refer to Inference parameters. - contentType
-
- Required: Yes
- Type: string
The MIME type of the inference result.
Errors
-
The request is denied because of missing access permissions.
-
The specified resource ARN was not found. Check the ARN and try your request again.
-
The number of requests exceeds the limit. Resubmit your request later.
-
The request took too long to process. Processing time exceeded the model timeout length.
-
An internal server error occurred. Retry your request.
-
Input validation failed. Check your request parameters and retry the request.
-
The model specified in the request is not ready to serve inference requests.
-
ServiceQuotaExceededException:
The number of requests exceeds the service quota. Resubmit your request later.
-
The request failed due to an error while processing the model.
InvokeModelWithResponseStream
$result = $client->invokeModelWithResponseStream
([/* ... */]); $promise = $client->invokeModelWithResponseStreamAsync
([/* ... */]);
Invoke the specified Amazon Bedrock model to run inference using the prompt and inference parameters provided in the request body. The response is returned in a stream.
To see if a model supports streaming, call GetFoundationModel and check the responseStreamingSupported
field in the response.
The CLI doesn't support InvokeModelWithResponseStream
.
For example code, see Invoke model with streaming code example in the Amazon Bedrock User Guide.
This operation requires permissions to perform the bedrock:InvokeModelWithResponseStream
action.
Parameter Syntax
$result = $client->invokeModelWithResponseStream([ 'accept' => '<string>', 'body' => <string || resource || Psr\Http\Message\StreamInterface>, // REQUIRED 'contentType' => '<string>', 'guardrailIdentifier' => '<string>', 'guardrailVersion' => '<string>', 'modelId' => '<string>', // REQUIRED 'trace' => 'ENABLED|DISABLED', ]);
Parameter Details
Members
- accept
-
- Type: string
The desired MIME type of the inference body in the response. The default value is
application/json
. - body
-
- Required: Yes
- Type: blob (string|resource|Psr\Http\Message\StreamInterface)
The prompt and inference parameters in the format specified in the
contentType
in the header. To see the format and content of the request and response bodies for different models, refer to Inference parameters. For more information, see Run inference in the Bedrock User Guide. - contentType
-
- Type: string
The MIME type of the input data in the request. The default value is
application/json
. - guardrailIdentifier
-
- Type: string
The unique identifier of the guardrail that you want to use. If you don't provide a value, no guardrail is applied to the invocation.
An error is thrown in the following situations.
-
You don't provide a guardrail identifier but you specify the
amazon-bedrock-guardrailConfig
field in the request body. -
You enable the guardrail but the
contentType
isn'tapplication/json
. -
You provide a guardrail identifier, but
guardrailVersion
isn't specified.
- guardrailVersion
-
- Type: string
The version number for the guardrail. The value can also be
DRAFT
. - modelId
-
- Required: Yes
- Type: string
The unique identifier of the model to invoke to run inference.
The
modelId
to provide depends on the type of model that you use:-
If you use a base model, specify the model ID or its ARN. For a list of model IDs for base models, see Amazon Bedrock base model IDs (on-demand throughput) in the Amazon Bedrock User Guide.
-
If you use a provisioned model, specify the ARN of the Provisioned Throughput. For more information, see Run inference using a Provisioned Throughput in the Amazon Bedrock User Guide.
-
If you use a custom model, first purchase Provisioned Throughput for it. Then specify the ARN of the resulting provisioned model. For more information, see Use a custom model in Amazon Bedrock in the Amazon Bedrock User Guide.
- trace
-
- Type: string
Specifies whether to enable or disable the Bedrock trace. If enabled, you can see the full Bedrock trace.
Result Syntax
[ 'body' => [ // EventParsingIterator 'chunk' => [ 'bytes' => <string || resource || Psr\Http\Message\StreamInterface>, ], 'internalServerException' => [ 'message' => '<string>', ], 'modelStreamErrorException' => [ 'message' => '<string>', 'originalMessage' => '<string>', 'originalStatusCode' => <integer>, ], 'modelTimeoutException' => [ 'message' => '<string>', ], 'throttlingException' => [ 'message' => '<string>', ], 'validationException' => [ 'message' => '<string>', ], ], 'contentType' => '<string>', ]
Result Details
Members
- body
-
- Required: Yes
- Type: EventParsingIterator supplying the following structures: PayloadPart, InternalServerException, ModelStreamErrorException, ValidationException, ThrottlingException, ModelTimeoutException
Inference response from the model in the format specified by the
contentType
header. To see the format and content of this field for different models, refer to Inference parameters. - contentType
-
- Required: Yes
- Type: string
The MIME type of the inference result.
Using an EventParsingIterator
To use an EventParsingIterator, you will need to loop over the events it will generate and check the top-level field to determine which type of event it is.
foreach($result['body'] as $event) { if (isset($event['chunk'])) { // Handle the 'chunk' event. } else if (isset($event['internalServerException'])) { // Handle the 'internalServerException' event. } else if (isset($event['modelStreamErrorException'])) { // Handle the 'modelStreamErrorException' event. } else if (isset($event['modelTimeoutException'])) { // Handle the 'modelTimeoutException' event. } else if (isset($event['throttlingException'])) { // Handle the 'throttlingException' event. } else if (isset($event['validationException'])) { // Handle the 'validationException' event. } }
Errors
-
The request is denied because of missing access permissions.
-
The specified resource ARN was not found. Check the ARN and try your request again.
-
The number of requests exceeds the limit. Resubmit your request later.
-
The request took too long to process. Processing time exceeded the model timeout length.
-
An internal server error occurred. Retry your request.
-
An error occurred while streaming the response. Retry your request.
-
Input validation failed. Check your request parameters and retry the request.
-
The model specified in the request is not ready to serve inference requests.
-
ServiceQuotaExceededException:
The number of requests exceeds the service quota. Resubmit your request later.
-
The request failed due to an error while processing the model.
Shapes
AccessDeniedException
Description
The request is denied because of missing access permissions.
Members
- message
-
- Type: string
InternalServerException
Description
An internal server error occurred. Retry your request.
Members
- message
-
- Type: string
ModelErrorException
Description
The request failed due to an error while processing the model.
Members
- message
-
- Type: string
- originalStatusCode
-
- Type: int
The original status code.
- resourceName
-
- Type: string
The resource name.
ModelNotReadyException
Description
The model specified in the request is not ready to serve inference requests.
Members
- message
-
- Type: string
ModelStreamErrorException
Description
An error occurred while streaming the response. Retry your request.
Members
- message
-
- Type: string
- originalMessage
-
- Type: string
The original message.
- originalStatusCode
-
- Type: int
The original status code.
ModelTimeoutException
Description
The request took too long to process. Processing time exceeded the model timeout length.
Members
- message
-
- Type: string
PayloadPart
Description
Payload content included in the response.
Members
- bytes
-
- Type: blob (string|resource|Psr\Http\Message\StreamInterface)
Base64-encoded bytes of payload data.
ResourceNotFoundException
Description
The specified resource ARN was not found. Check the ARN and try your request again.
Members
- message
-
- Type: string
ResponseStream
Description
Definition of content in the response stream.
Members
- chunk
-
- Type: PayloadPart structure
Content included in the response.
- internalServerException
-
- Type: InternalServerException structure
An internal server error occurred. Retry your request.
- modelStreamErrorException
-
- Type: ModelStreamErrorException structure
An error occurred while streaming the response. Retry your request.
- modelTimeoutException
-
- Type: ModelTimeoutException structure
The request took too long to process. Processing time exceeded the model timeout length.
- throttlingException
-
- Type: ThrottlingException structure
The number or frequency of requests exceeds the limit. Resubmit your request later.
- validationException
-
- Type: ValidationException structure
Input validation failed. Check your request parameters and retry the request.
ServiceQuotaExceededException
Description
The number of requests exceeds the service quota. Resubmit your request later.
Members
- message
-
- Type: string
ThrottlingException
Description
The number of requests exceeds the limit. Resubmit your request later.
Members
- message
-
- Type: string
ValidationException
Description
Input validation failed. Check your request parameters and retry the request.
Members
- message
-
- Type: string