Skip to main content

Frequently Asked Questions

Q: What changed in VCAL Semantic Cache v0.6.0?​

VCAL Semantic Cache v0.6.0 changes the snapshot persistence model.

Normal autosave and manual /v1/snapshot/save now:

  1. acquire the cache-state read lock,
  2. serialize a consistent in-memory snapshot bundle,
  3. release the read lock,
  4. write the snapshot files without entering drain mode.

Graceful shutdown still uses a quiescent final save: the server enters drain mode, waits for in-flight work, and writes the final paired snapshot before exit.

Q: What happens when the cache reaches its memory limit?​

VCAL Semantic Cache applies LRU eviction automatically to keep memory usage within configured limits.

VCAL_CAP_MAX_BYTES=1073741824
VCAL_CAP_MAX_VECTORS=50000

If the container has a strict memory limit, make sure VCAL_CAP_MAX_BYTES is lower than the container memory limit, or prefer VCAL_CAP_MAX_VECTORS.

Q: Can I pre-load known Q&A pairs?​

Yes. You can pre-seed data by inserting entries through /v1/insert or /v1/upsert, or by restoring a valid snapshot before serving traffic.

Q: Can snapshots be shared between containers or nodes?​

Snapshots can be moved between compatible VCAL Semantic Cache instances if they use the same key index parameters, especially:

  • VCAL_DIMS
  • VCAL_M
  • VCAL_EF_SEARCH

Do not run multiple active writers against the same local snapshot files unless your deployment design explicitly coordinates them.

Q: Is authentication mandatory?​

Authentication is optional but strongly recommended for production.

When VCAL_AUTH_REQUIRED=1:

  • /healthz remains public.
  • /readyz requires a valid app or admin key.
  • /v1/search, /v1/qa, /v1/insert, /v1/upsert, and /v1/delete require an app or admin key.
  • /v1/snapshot/save and /v1/license/status require an admin key.

You can configure keys directly or with files:

VCAL_KEYS_APP=app_key_1,app_key_2
VCAL_KEYS_ADMIN=admin_key_1
VCAL_KEYS_APP_FILE=/path/to/app.keys
VCAL_KEYS_ADMIN_FILE=/path/to/admin.keys

Q: How is data persisted?​

VCAL Semantic Cache persists a paired snapshot set:

vcal.index
answers.json
tombstones.json

Relevant settings:

VCAL_AUTOSAVE_SECS=3600
VCAL_AUTOSAVE_ATOMIC=1

vcal.index stores the HNSW index, answers.json stores cached answer payloads, and tombstones.json stores deleted IDs so deleted entries do not reappear after restart.

Q: Does autosave pause request processing?​

In v0.6.0, normal autosave and manual snapshot saves do not enter drain mode. They capture a consistent bundle quickly and then write files without pausing normal workflow.

Shutdown is different: graceful shutdown still performs a quiescent final snapshot so the server can save the latest state before exit.

Q: How do I back up or migrate VCAL data?​

For a clean backup, trigger a snapshot save and copy the data directory:

curl -X POST   -H "X-VCAL-Key: <admin_key>"   -H "Content-Type: application/json"   -d '{"path":"vcal.index","atomic":true}'   http://localhost:8080/v1/snapshot/save

cp -a /var/lib/vcal/data ./vcal-data-backup

For strict backup windows, stop the server first or use filesystem-level snapshotting.

Q: What happens if my license expires?​

If a license expires or becomes invalid:

  • the server refuses to start on restart,
  • protected operations may be rejected,
  • data on disk remains intact until a valid license is installed.

Q: Does VCAL ever send cache data externally?​

No. VCAL Semantic Cache is intended for on-prem or VPC deployment. It does not send embeddings, answers, or metrics to VCAL by default.

Q: How does VCAL handle concurrent requests safely?​

VCAL Semantic Cache v0.6.0 groups index, answers, and tombstones behind one logical cache-state lock.

  • Mutations use one write lock.
  • Search and QA use read access to the consistent state.
  • Snapshot capture uses a read lock and writes files after releasing it.

This avoids partially captured snapshots while keeping normal runtime snapshots non-draining.

Q: Can I run VCAL behind an API gateway or load balancer?​

Yes. VCAL Semantic Cache can run behind a reverse proxy, API gateway, or internal load balancer.

For multi-replica deployments, each replica usually has its own warm cache unless you design a coordinated persistence/shared-volume model.

Q: How large can the index grow?​

Memory usage scales with vector count, vector dimensionality, HNSW parameters, answer payload size, and tombstone/metadata overhead.

Approximate guideline:

  • 768-dimensional vectors require significantly more memory than small test vectors.
  • Set VCAL_CAP_MAX_VECTORS and/or VCAL_CAP_MAX_BYTES according to the actual container or VM memory limit.

Q: How do I monitor performance?​

VCAL Semantic Cache exposes Prometheus metrics at:

/metrics

Common metrics include:

  • vcal_active_ids
  • vcal_answers_cached
  • vcal_search_requests_total
  • vcal_search_errors_total
  • vcal_insert_requests_total
  • vcal_insert_errors_total
  • vcal_cache_hits_total
  • vcal_cache_misses_total
  • vcal_tokens_saved_total
  • vcal_snapshot_saves_total
  • vcal_license_days_until_expiry

Q: What happens if the server crashes during a snapshot write?​

If VCAL_AUTOSAVE_ATOMIC=1 is enabled, files are written through a temporary file and rename flow. This helps preserve the previous valid file if a write is interrupted.

Q: Can I use different embedding models?​

Yes. VCAL is model-agnostic. Use any embedding model as long as all inserted and queried vectors match:

VCAL_DIMS=<embedding dimension>