Hybrid Search CLI Guide¶

The search-hq hybrid-search command-line interface (CLI) allows you to manage and operate the Hybrid Search service. This includes downloading configurations, generating semantic index schemas, deploying SageMaker inference models, and destroying SageMaker inference models.

Getting Started¶

To get started with the search-hq CLI, run the following command to see an overview of available options and commands:

search-hq hybrid-search --help

This command will display a summary of the CLI usage, including available commands and options:

Usage: search-hq hybrid-search [OPTIONS] COMMAND [ARGS]...

Operate Hybrid Search service.

Options:
  --help  Show this message and exit.

Commands:
  deploy-model                    Deploy SageMaker inference model.
  destroy-model                   Destroy SageMaker inference model.
  download-conf                   Download configurations used by Hybrid Search service.
  generate-semantic-index-schema  Generate semantic index schema.

Download Configurations¶

The download-conf command downloads the configurations used by the Hybrid Search service from Amazon S3. When you deploy the Hybrid Search service, the configurations are automatically uploaded to Amazon S3. Therefore, you can use this command to download the configurations for comparison. You need to pass the parameter dest_folder to specify the destination folder where the configurations will be saved.

Command:

search-hq hybrid-search download-conf \
--dest_folder <DEST_FOLDER>

Option	Type	Required	Description
`dest_folder`	String	Required	The destination folder where the configurations will be saved.

Example Usage:

search-hq hybrid-search download-conf \
--dest_folder dest_conf_folder

Generate Semantic Index Schema¶

The generate-semantic-index-schema command generates a semantic index schema based on your specified index and schema file, extending the index to support KNN operations and incorporating any semantic fields as defined in conf/hybrid_search.yaml configuration. This is an essential step in setting up your index for advanced semantic search capabilities.

Command:

search-hq hybrid-search generate-semantic-index-schema \
--index <INDEX> \
--schema_file_path <PATH_TO_SCHEMA_FILE>

Option	Type	Required	Description
`index`	String	Required	The name of the index for which you want to generate the semantic index schema. This should match the index name in your OpenSearch setup where you want to apply semantic search capabilities.
`schema_file_path`	String	Required	The local file path to the schema file that contains the base index configuration. This file should be formatted in JSON and include the settings and mappings that define how the index is structured and configured. Refer to Create or Update an Index Schema to Support KNN for detailed information on how to prepare and structure your schema file.

Example Usage:

search-hq hybrid-search generate-semantic-index-schema \
--index my_index \
--schema_file_path /path/to/schema_file.json

Deploy SageMaker Inference Model¶

The deploy-model command deploys the SageMaker inference model, which is crucial for powering the semantic search functionality of your Hybrid Search service. This command uses configurations from your conf/hybrid_search.yaml and conf/model.yaml files to ensure that the embedding model is deployed correctly and synchronized with your AWS environment. This deployment step ensures that your model is ready to handle semantic search queries effectively.

Command:

search-hq hybrid-search deploy-model \
--auto_approve <AUTO_APPROVE> \
--model_overwrite <MODEL_OVERWRITE>

Option	Type	Required	Description
`auto_approve`	Boolean	Optional	Automatically approve all prompts during deployment without manual confirmation. Default is `True`.
`model_overwrite`	Boolean	Optional	Overwrite the existing model artifact in the Amazon S3 bucket if it already exists. Default is `False`.

Example Usage:

search-hq hybrid-search deploy-model  \
--auto_approve True  \
--model_overwrite True

Destroy SageMaker Inference Model¶

The destroy-model command is used to remove the SageMaker inference model and associated resources. This is necessary when you need to clean up resources or decommission the model from your AWS environment. Properly managing the lifecycle of your models is crucial for maintaining an organized and cost-efficient AWS environment.

Command:

search-hq hybrid-search destroy-model  \
--auto_approve <AUTO_APPROVE>  \
--destroy_infra <DESTROY_INFRA>

Option	Type	Required	Description
`auto_approve`	Boolean	Optional	Automatically approve all prompts during destruction without manual confirmation. Default is `True`.
`destroy_infra`	Boolean	Required	Destroy the application infrastructure if needed. Default is `True`.

Example Usage:

search-hq hybrid-search destroy-model  \
--auto_approve True  \
--destroy_infra True

List CloudFormation Stack Resources¶

The search-hq resources command lists the resources for CloudFormation stacks. This is useful for reviewing the components that have been deployed, including infrastructure, services, and other resources managed by the application.

To list resources for all CloudFormation stacks, use:

search-hq resources

To list resources for particular CloudFormation stacks, use:

search-hq resources <STACK_NAMES>

Replace <STACK_NAMES> with the names of the stacks you want to query.

Display CloudFormation Stack Statuses¶

Use the search-hq status command to display the statuses of CloudFormation stacks, including current status, creation time, and last updated time.

To list the statuses of all CloudFormation stacks, use:

search-hq status

To list the statuses of specific CloudFormation stacks, use:

search-hq status <STACK_NAMES>

Replace <STACK_NAMES> with the names of the stacks you want to query.

Remove Associated Resources¶

By default, the destroy command will retain the Amazon S3 bucket and AWS Systems Manager Parameter Store associated with your search-hq deployment. You can choose to manually delete these resources if needed.

Remove Objects from Amazon S3 Bucket: To delete the entire Amazon S3 bucket associated with your search-hq deployment, use the following command. This will remove the entire bucket and all objects within it:
```
python -m operation.cli.s3 delete_bucket
```
If you only need to delete a single object from the Amazon S3 bucket, use:
```
python -m operation.cli.s3 delete_object --key <S3_OBJECT_KEY>
```
Replace <S3_OBJECT_KEY> with the key of the object you want to delete from the Amazon S3 bucket.
Remove Parameters from AWS Systems Manager Parameter Store: To delete all parameters associated with your search-hq deployment from AWS Systems Manager Parameter Store, use:
```
python -m operation.cli.ssm delete_ssm_parameters
```
If you only need to delete a single parameter, use:
```
python -m operation.cli.ssm delete_ssm_parameter --parameter_name <PARAMETER_NAME>
```
Replace <PARAMETER_NAME> with the name of the parameter you want to delete from the AWS Systems Manager Parameter Store.