Skip to main content

Frequently Asked Questions

Q: Is VCAL Semantic Cache still a standalone product?​

No. VCAL Semantic Cache is positioned as an optional dedicated cache module for AI Cost Firewall deployments. AI Cost Firewall remains the gateway, orchestration layer, and commercial entry point.

The module is used when a deployment needs shared semantic reuse across applications or gateway instances, dedicated cache capacity, or an independently operated cache lifecycle. It is not required when the built-in Redis and Qdrant cache path meets the workload requirements.

Q: Can I download or evaluate it independently?​

There is no public self-service download or standalone trial flow. VCAL can supply an archived Docker image or standalone binary when Semantic Cache is justified by a scoped AI Cost Firewall architecture. Contact VCAL to discuss the workload and delivery arrangement.

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

v0.6.1 focuses on production hardening rather than a new cache architecture. It strengthens snapshot persistence and restore validation, honors and validates VCAL_DATA_DIR, improves graceful shutdown, fixes request-field handling and capacity enforcement, strengthens API-key comparison, improves license metrics, and makes JSON responses friendlier for command-line clients.

The background-safe snapshot model introduced in v0.6.0 remains in place.

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?​

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:8084/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.

Coordinate renewal or replacement entitlement material with VCAL as part of the wider deployment agreement.

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 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>