Semantic Search

Semantic Search allows users to search for assets in CKBox using natural language queries. It uses OpenAI as a third-party provider. To fully use Semantic Search capabilities in CKBox On-Premises, you need to set up additional infrastructure: a PostgreSQL database with the pgvector extension and an OpenAI API key.

Note

Semantic Search is an optional feature. If it is not configured, CKBox On-Premises will continue to work normally with all other features available. However, the Semantic Search functionality will be disabled.

For a general overview of Semantic Search capabilities, refer to the Semantic Search documentation.

Prerequisites

To enable Semantic Search, you need to provide:

A PostgreSQL database with the pgvector extension installed. This is a separate database from the main CKBox application database.
A valid OpenAI API key.

Both must be configured. If either is missing, Semantic Search will be disabled.

PostgreSQL with pgvector

The pgvector extension needs to be installed separately. Refer to the pgvector installation instructions for details.

Note

Make sure the pgvector version you install is compatible with your PostgreSQL version.

Preparing the database

The database user should have at least the following privileges: SELECT, INSERT, UPDATE, DELETE, CREATE, USAGE and permission to execute CREATE EXTENSION.

OpenAI configuration

For details on configuring the OpenAI provider, refer to the OpenAI section of the Configuration guide.

Semantic Search database configuration

Configure the connection to the pgvector-enabled PostgreSQL database using environment variables prefixed with ckbox_ai_worker_database_. This prefix distinguishes them from the main application database.

To enable Semantic Search, set the ckbox_ai_worker_database_driver variable to postgres.

Then, you can provide:

ckbox_ai_worker_database_host and ckbox_ai_worker_database_port to configure the database address (example: 127.0.0.1 and 5432).
ckbox_ai_worker_database_user and ckbox_ai_worker_database_password to configure the database user (example: postgres and password).
ckbox_ai_worker_database_database and ckbox_ai_worker_database_schema to set the database name and schema (example: ckbox-ai-worker and public).

Running the service

To run CKBox On-Premises with Semantic Search enabled, follow the Running the service guide. Make sure to include the Semantic Search-specific environment variables (OPENAI_API_KEY and CKBOX_AI_WORKER_DATABASE_*) alongside the standard CKBox configuration.