Get Started#

This section shows how to run the Semantic Search Agent microservice. Pick one of the two deployment paths and follow the linked guide.

Before You Begin#

  • Confirm that your machine meets the System Requirements.

  • Review the Configuration Guide to understand matching strategies, VLM backends, and caching options.

  • Decide whether you need VLM support:

    • For exact matching only, you do not need an external model server.

    • For semantic or hybrid matching, you need a configured VLM backend: OpenVINO model server, OpenVINO local GenAI model, or OpenAI cloud API.

Choose Deployment Path#

The container setup exposes the API on host port 8080, and Prometheus metrics on port 9090. The Compose file includes an optional Redis container for persistent caching.

See Run with Docker Compose for the full step-by-step guide.

Quick start:

cp .env.example .env        # copy and edit environment file
cd docker
docker compose build        # build the image
docker compose up -d        # start containers (API on port 8080)
curl http://localhost:8080/api/v1/health

Run the service directly as a local Python process. This path is useful for local development, debugging, and tests.

See Run on the Host for the full step-by-step guide.

Quick start:

cp .env.example .env        # copy and edit environment file
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --host 127.0.0.1 --port 8080

Verify#

Once the service is running:

curl http://localhost:8080/api/v1/health

Expected response:

{
  "status": "healthy",
  "service": "semantic-search-agent",
  "version": "2026.1.0",
  "vlm_backend": "ovms",
  "vlm_status": "connected",
  "uptime_seconds": 5.12
}

Next Steps#