SM-AI settings

Overview

SM-AI connects language models to Search Anywhere Framework. It accepts requests from SM-MCP and the ai command, validates the account through the platform, and forwards the request to the selected model.

The service is installed separately from storage nodes. Its executable and system service are named sa-ai in the distribution. For general requirements and component connections, see Installing the AI assistant.

Before installation

Prepare:

• the sa-ai-<version>.tar.gz archive from the Search Anywhere Framework distribution
• the full storage API address with scheme and port, such as https://storage.example.org:9200, and the cluster CA certificate
• an HTTPS certificate and key for SM-AI, or a CA key for the installer to issue a certificate
• the model API address, the provider's model ID, and an access key if required
• a model registry entry name to use in SM-MCP and ai requests, such as assistant
• a platform administrator account if the installer must configure the ai command user, keystore, and service address

The service name in the certificate must match the name in the address used by SM-MCP and search engine nodes. The platform and model must be reachable from the SM-AI server.

Installing the service

Extract the archive and run the installer:

tar -xzf sa-ai-<version>.tar.gz
cd sa-ai-<version>
sudo ./setup.sh install

Replace <version> with the version of your distribution. Running ./setup.sh without a command opens a menu.

During interactive installation, specify:

Group	Value
Service	SM-AI port, 8010 by default, and whether to use HTTPS
Platform	Full storage API address and path to the CA certificate
Service certificate	An existing certificate and key, or a CA and its key to issue a certificate; service name and SAN
Model	Registry entry name, API address ending in /v1, provider model ID, and API key if required
ai command	Whether to create or update sm_ai_user, store its password in the node keystores, and set the SM-AI address in cluster settings

Before making changes, the installer displays the selected parameters and asks for confirmation. It then creates the sa-ai service user, installs the files, checks the configuration, and starts sa-ai.service. Enter the administrator password interactively.

For repeatable installation, fill in an answers file:

cp example_config_sa-ai.yaml answers.yaml
# Fill in answers.yaml before running the installer.
sudo ./setup.sh install -c answers.yaml

The answers file supplies installation parameters; passwords and the provider key are requested separately. --no-root runs the unprivileged portion without root and prints privileged commands for an administrator. It is not a dry-run mode.

File locations

Path	Purpose
/opt/sa-ai/sa-ai	Executable
/etc/sa-ai/config.yaml	Service configuration
/etc/sa-ai/model_registry.json	Model registry
/etc/sa-ai/ca-cert.pem	Cluster CA certificate
/etc/sa-ai/tls/server.crt, server.key	Service HTTPS certificate and key
/etc/systemd/system/sa-ai.service	systemd service

The service runs as the sa-ai user. View its log with:

sudo journalctl -u sa-ai -o cat

Configuration file

The installer creates /etc/sa-ai/config.yaml. Key parameters:

Parameter	Purpose
server.port	Service port; 8010 by default during installation
server.tls.enabled	HTTPS for incoming connections
server.tls.certificate, server.tls.private_key	Paths to the service certificate and key
auth.url	Full storage API address for account validation
auth.ca_cert_path	CA path for verifying the storage certificate
llm.model_registry_path	Model registry path
llm.provider_ca_cert_path	Additional CA for an HTTPS connection to the model provider
gateway.timeout_ms	Model request timeout through the gateway, in milliseconds; the installer sets 600000
llm.default_timeout_ms	Model request timeout for the ai command, in milliseconds
llm.max_rows_per_call, llm.max_bytes_per_row, llm.max_tokens_per_call	Input data limits for the ai command
llm.strict_limits	Reject requests that exceed limits instead of truncating data
observability.log_level	Service log level

After changing the configuration, check it and restart the service:

sudo -u sa-ai /opt/sa-ai/sa-ai config check --config /etc/sa-ai/config.yaml
sudo systemctl restart sa-ai

config check validates the configuration but does not confirm network access to the platform or model.

Model registry

/etc/sa-ai/model_registry.json contains an array of entries. Example:

[
  {
    "name": "assistant",
    "provider": "openai-compatible",
    "endpoint": "https://model.example.org/v1",
    "model_id": "provider-model-id",
    "api_key": null,
    "context_tokens": 131072
  }
]

Replace the address, model ID, and context size with values from your provider. If an API key is required, set api_key to a string; null means no key. Restrict access to the registry file because it may contain a provider key.

Field	Purpose
name	Registry entry name used in SM-MCP's model.name and the ai command's model parameter
provider	Provider identifier; use openai-compatible for an OpenAI-compatible connection
endpoint	Base model API URL ending in /v1; the gateway appends /chat/completions
model_id	Provider-side model ID
api_key	Provider access key or null
context_tokens	Context window size in tokens. If omitted, the gateway attempts to obtain it from the provider
default_temperature, default_max_tokens	Default generation parameters
reasoning_format, reasoning	Model reasoning format and available levels; optional

The AI assistant model must support tool calls. The name configured in SM-MCP must match the registry entry's name.

The registry reloads automatically; no restart is required. If a new file is invalid, the service continues using the previous registry and writes an error to the log.

Connecting the ai command

The installer can configure the ai command connection if you select those actions during installation. After setup, check the messages about user creation, password storage on all nodes, and address configuration.

If you skipped automatic setup:

1. Create the internal user sm_ai_user and set a password
2. Store the password in the node keystores. In the Dev Tools console, run:

POST _core/keystore/sm.core.ai.password
{
  "value": "<sm_ai_user password>"
}

If the key already exists, use PUT instead of POST. In the response, successful must equal total.

3. Set the service address:

PUT _cluster/settings
{
  "persistent": {
    "sme.ai.inference_server_url": ["https://ai.example.org"],
    "sme.ai.inference_server_port": 8010
  }
}

Replace the name and port with your values. The name must be included in the SM-AI certificate SAN. The ai command validates the certificate using the CA at plugins.security.ssl.http.pemtrustedcas_filepath in opensearch.yml. If the path is relative, it is resolved from /app/opensearch/config for this connection. For a different installation directory, set an absolute path on every node and restart them; otherwise, PKIX path building failed may occur.

The password entered in the command is saved in the Dev Tools console history. Clear the history after storing it.

For request parameters, see ai; for prompt templates, see AI command presets.

Checking the service

On the SM-AI server, check the service status:

sudo systemctl status sa-ai
curl --cacert /etc/sa-ai/ca-cert.pem https://ai.example.org:8010/health
curl --cacert /etc/sa-ai/ca-cert.pem -u '<login>' https://ai.example.org:8010/models

Use the service name from the certificate. curl -u '<login>' prompts for a password. Use a valid platform account for /models.

The expected /health response is {"status":"ok"}; /models returns the configured model list. Repeat the requests from the SM-MCP server and a search engine node, using the local CA path.

Test the ai command with your data source and a model name from the registry:

source <source> | head 1 | ai model="assistant" output="summary" mode=summary user_message="Briefly describe the event" input="*"

The result should include a summary field containing the model response. If it fails, check access to the source, command settings, commands allowed by the user's limits, and the service log.

Updating the service

Extract the new distribution and run from its directory:

sudo ./setup.sh update

When updating an existing sa-ai service, the installer preserves its configuration and model registry, checks them with the new binary, and replaces the executable. The previous binary and configuration are saved with the .prev suffix.

Migrating from the Java version

Before migrating, back up the configuration, model registry, certificates, and unit file of the old service. Run setup.sh update from the new distribution.

The installer detects a Java installation by the sa-ai.service or sm-ai.service service with a JAR file. It migrates settings from application.properties and copies the registry and certificates. After the new service starts successfully, the temporary copy of the old unit and the recognized Java service directory are removed. To roll back after a successful migration, you need the backup you made. Repeat the model and ai command checks.

Installing Go under the old name

An existing Go-based sm-ai service is replaced with a new sa-ai installation without automatically migrating settings or the registry. Back them up and prepare the model parameters again before running the installer.