Get Started#

This page is the entry point for running 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, no external model server is needed.

    • For semantic or hybrid matching, you need a configured VLM backend (OVMS, OpenVINO local, or OpenAI).

Choose Deployment Path#

The container setup exposes the API on host port 8080 and Prometheus metrics on port 9090. An optional Redis container is included in the Compose file 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 with Python. This path is useful for local development, debugging, and running 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#