AWS Marketplace

Cortical.io’s Retina API is marketed through AMAZON WEB SERVICES (AWS). Here you can find information regarding the Amazon Machine Instances (AMI) of the Retina API offered by Cortical.io on the AWS Marketplace.

AMI Usage Instructions

Once the (server) instance is running, connect via ssh using the ec2-user username and the registered PEM file for the environment (e.g. ssh -i pemFileName.pem ec2-user@instanceIPaddress).

Before the Retina Service can be accessed, it needs to be configured. This is done by the console.sh script.

Go to /app/retinaservice/, e.g. cd /app/retinaservice/ and type on the command line ./console.sh setup.

The script will prompt you with a few questions, as these inputs are needed for configuring the system.

The setup process will configure, start and validate the Retina Service.

Once the setup has completed successfully, the interactive API can also be accessed via any browser using HTTP.

When the service first starts up it will generate a file containing the API key (for use with the REST API).

This file can be found in /app/retinaservice/api.key. The API key will also be displayed during the setup process.

If the file is removed for any reason then the application will generate a new file and key on the next start/restart.

Log files for the service can be found under /app/log, there are two log files:

  • retina-service.log - Used for application logging.
  • retina-service-requests.log - Used for storing HTTP/HTTPS requests to the application.

To start, stop or restart the Retina Service the following commands can be used:

cd /app/retinaservice/

./console.sh stop

./console.sh start

./console.sh restart

If you require any further assistance with the setup, please visit the support forum.

How to Choose your AMI

Cortical.io’s Retina API is offered on 4 different AMI sizes (specifications of the AMI machines can be found on the AWS web pages).

The functionality and output quality of Cortical.io’s Retina instances is exactly the same for all AMI sizes; they differ only in terms of maximum throughput. The choice of AMI should primarily be based on the required throughput, and the amount of data that one wants to process. To assist the user in selecting an AMI the three following tables provide an overview of throughput per second, hourly throughput, and the approximate costs of processing 100,000 transactions.

The data in the tables provides per instance throughput [1] based on measurements conducted with extensive test sets representing real world data. Please note that these values are provided as performance guidance only. Throughput may vary with regard to the length and vocabulary of text input, and the complexity of expressions.

Throughput per Second

The following table provides an overview of the expected throughput per second across different instance sizes.

AMI Instances - Approximate Throughput per Second
endpoint C3.large C3.xlarge C3.2xlarge C3.4xlarge
/compare [2] 94 192 392 800
/expressions [3] 205 257 492 996
/expressions/contexts [3] 0.58 1.20 2.45 5
/expressions/similar_terms [3] 4 8 17 35
/image 29 60 122 250
/image/compare 6 12 24 50
/terms/contexts 1.52 3.12 6.37 13
/terms/similar_terms 6 12 24 50
/text [4] 94 192 392 800
/text/keywords [4] 5 10 22 45
/text/slices [4] 94 192 392 800
/text/tokenize [4] 94 192 392 800
[2](1, 2) Throughput measurements of the compare endpoint are based on test data comprised of expressions containing term and positions elements only. Inclusion of text element will generally result in lower throughputs.
[3](1, 2, 3, 4, 5, 6) Throughput measurements of expressions related endpoints are based on test data comprised of expressions containing term and positions elements only. Inclusion of text element will generally result in lower throughputs.
[4](1, 2, 3, 4, 5, 6, 7, 8) Throughput measurements of text related endpoints are based on test data with an average length of 133.65 characters (approximately the size of a Twitter feed entry). Processing of longer texts will generally lead to lower throughputs.

Hourly Throughput

The following table provides an overview of the expected [1] number of requests that can be processed by an endpoint in one hour (minimum billing unit of the AWS market place).

AMI Instances - Approximate Hourly Throughput
endpoint C3.large C3.xlarge C3.2xlarge C3.4xlarge
/compare [2] 338,400 691,200 1,411,200 2,880,000
/expressions [3] 738,000 925,200 1,771,200 3,585,600
/expressions/contexts [3] 2,088 4,320 8,820 18,000
/expressions/similar_terms [3] 14,400 28,800 61,200 126,000
/image 104,400 216,000 439,200 900,000
/image/compare 21,600 43,200 86,400 180,000
/terms/contexts 5,472 11,232 22,932 46,800
/terms/similar_terms 21,600 43,200 86,400 180,000
/text [4] 338,400 691,200 1,411,200 2,880,000
/text/keywords [4] 18,000 36,000 79,200 162,000
/text/slices [4] 338,400 691,200 1,411,200 2,880,000
/text/tokenize [4] 338,400 691,200 1,411,200 2,880,000

Approximate Cost Per 100,000 Transactions

The following table provides estimates [1] for the cost of processing 100,000 requests across different instance sizes. Please note, that the values provided do not factor in the hourly billing model of the AWS marketplace. Pricing on AWS is based on instance-hour consumed by each instance (from the time an instance is launched until it is terminated or stopped). As each partial instance-hour consumed will be billed as a full hour it can be more economical to opt for smaller instance sizes when processing small amounts of data.

AMI Instances - Approximate Cost 100,000 Transactions [5]
endpoint C3.large C3.xlarge C3.2xlarge C3.4xlarge
/compare $0.87 $0.86 $0.84 $0.82
/expressions $0.70 $0.68 $0.67 $0.66
/expressions/contexts $141.71 $136.99 $134.20 $131.51
/expressions/similar_terms $20.55 $20.55 $19.34 $18.79
/image $2.83 $2.74 $2.69 $2.63
/image/compare $13.70 $13.70 $13.70 $13.15
/terms/contexts $54.08 $52.69 $51.61 $50.58
/terms/similar_terms $13.70 $13.70 $13.70 $13.15
/text $0.87 $0.86 $0.84 $0.82
/text/keywords $16.44 $16.44 $14.94 $14.61
/text/slices $0.87 $0.86 $0.84 $0.82
/text/tokenize $0.87 $0.86 $0.84 $0.82
[5]Calculations based on Retina API English Language Processing, region US East (N. Virginia), 17.02.2015.
[1](1, 2, 3) These numbers are offered as a guideline only and in no way constitute a guarantee in terms of performance or costs by either Cortical.io or Amazon Web Services (or any subsidiaries and /or partners thereof). Figures quoted apply to individual endpoints in isolation using the recommended number of threads (against standardised sets of test inputs). When running in parallel with other endpoints these figures will be lower. Throughput may also vary depending on other factors such as the size of the input or the location of the AWS data center where the instance is hosted.

Performance Guide

The following table shows the maximum number of threads we advise to use when querying an endpoint concurrently. These numbers are meant as guidance for optimizing the performance of Retina API instances with regard to endpoint-specific throughput. Querying endpoints with higher numbers of threads might allow for short-term higher throughput performance but will likely result in lower long-term performance.

AMI Instances - Advised Thread Numbers
endpoint C3.large C3.xlarge C3.2xlarge C3.4xlarge
/compare 100 200 300 400
/expressions 125 125 450 625
/expressions/contexts 2 4 6 12
/expressions/similar_terms 5 5 10 20
/image 20 40 80 120
/image/compare 15 30 60 120
/terms/contexts 2 4 8 16
/terms/similar_terms 2 4 10 20
/text 50 100 200 400
/text/keywords 20 40 80 160
/text/slices 50 100 200 300
/text/tokenize 50 100 200 300