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.
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  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.
|||(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.|
|||(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.|
|||(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.|
The following table provides an overview of the expected  number of requests that can be processed by an endpoint in one hour (minimum billing unit of the AWS market place).
Approximate Cost Per 100,000 Transactions¶
The following table provides estimates  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.
|||Calculations based on Retina API English Language Processing, region US East (N. Virginia), 17.02.2015.|
|||(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.|
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.