Configuring the Concepts Server

Related videos

This video introduces Progress Semaphore concepts, features, and workflows through clear, practical explanations. It helps users understand how Semaphore supports semantic modeling, search, and AI‑driven use cases across the enterprise.

The MarkLogic database

The Concepts Server needs to know how to connect to the MarkLogic database. During its initial start up, the Concepts Server will check to see if the database and forest it is going to use exists. If it does not then it will attempt to create it--and so details of suitably privileged user account will be required.

The file <install_dir>/conf/marklogic.properties will need to be edited and the following properties defined.

Note, once the Concepts Server has been started and the database created, the user privileges can be tuned downwards so that a less privileged account is in the system.

There are two other properties files in the conf directory. If is unlikely that you will need to alter either of them.

Once the database properties are set, the Concepts Server service can be started.

Note a more secure way to store the password is to replace the value in this file with a parameterized form

marklogic.admin.password=${marklogic-password}

You can then use a keystore to store the actual value, add to a properties file (keystore.properties is provided)

quarkus.file.vault-config-source.keystore-path=<cache_file_location>
quarkus.file.vault-config-source.keystore-secret=<key_store_password>

You can then run the following command:

keytool -importpass -alias marklogic-password -keystore <cache_file_location> -storepass <key_store_password>-storetype PKCS12

Ensure that the cache file is locked down so that only the Concept Server account can read it.

Embedding vector calculation

For Semaphore 5.10.2 and later, vector embeddings for concepts can be calculated when they are pushed via the Concepts Server into a MarkLogic database. This allows you to present a body of text to the semanticSearch method of the server to return concepts semantically similar to the presented text.

Note: Embedding calculation and semantic search require MarkLogic 12 or higher.

You can enable this functionality by configuring the <install_dir>/conf/concepts.properties file. Note that if you have defined an external model for your concepts server, embeddings are calculated whenever you publish a model to concepts server. If you do not want this behavior for a particular model, you can disable it in the publisher configuration file by adding the calculateEmbeddings property with a value of false to the output processor. For example:

<bean parent="environmentConceptsWriter">
	<property name="calculateEmbeddings" value="false" />
</bean>

If it is possible to specify an internal or an external calculator, you can set the calculator using the concepts.embedding.type parameter. If this parameter is not present (the parameter is commented out by default), embeddings are not calculated.

External

When using the external method, the external calculator must be specified. The following options for external calculators are currently supported:

• custom
• azureOpenAi
• ollama
• mistral
• googleVertexAi

For the selected option, the corresponding keys must be correctly defined in the file. To define the keys, uncomment out the keys for your option in the file and provide the appropriate values.

If you are using an embedding model that is accessed via http (e.g. if you are using a local test model), rather than https, set the concepts.embedding.external.allowHttp parameter to true.

The following is an example for an Azure OpenAI Custom deployment:

concepts.embedding.type=external
concepts.embedding.external.provider=azureOpenAi
quarkus.rest-client.embeddingExternalAzureOpenAi.url=https://your-prefix.openai.azure.com/openai/deployments/text-embedding-3-large
concepts.embedding.external.azureOpenAi.apiVersion=2024-10-21
concepts.embedding.external.azureOpenAi.apiKey=your-api-key

Internal

When using the internal method, whereby the embeddings are calculated within the Concepts Server, you must download a model (in the form of a .onnx file) and a tokenizer configuration file (as a .json file). A number of models and configuration files are available on the HuggingFace site. From the site, select a model (e.g. nomic-ai/nomic-embed-text-v1.5) and download the corresponding .onnx and tokenizer.json files. Next, place them on the server for the Concepts Server and specify the location of the files by adding the following parameters to the concepts.properties file:

concepts.embedding.type=internal
concepts.embedding.internal.modelPath=/opt/semaphore/concepts/model.onnx
concepts.embedding.internal.tokenizerPath=/opt/semaphore/concepts/tokenizer.json

Notes:

• Internal embedding calculation now supports CPU only, which might not be optimal for a production environment. We recommend using external embedding calculation for production systems.
• On Windows, the path to model and tokenizer requires double backslashes. For example, C:\\semaphore\\concepts\\model.onnx.