> ## Documentation Index
> Fetch the complete documentation index at: https://cache-pot.thatdevguy.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure embeddings for semantic caching in Cache-Pot

> Set CACHEPOT_EMBED_URL, CACHEPOT_EMBED_KEY, and CACHEPOT_EMBED_MODEL to enable semantic caching with any OpenAI-compatible embeddings provider.

Semantic caching (`SCACHE.SET` / `SCACHE.GET`) requires an embedding model to convert text into vectors that Cache-Pot can compare for meaning. Cache-Pot calls any OpenAI-compatible embeddings endpoint you point it at — whether that is OpenAI itself, a local model running in Ollama, or any other provider that speaks the same API.

## Required environment variables

Embedding configuration is environment-only. There are no CLI flag equivalents for these three settings.

<ParamField name="CACHEPOT_EMBED_URL" type="string" default="">
  URL of an OpenAI-compatible embeddings endpoint. This must be set to use `SCACHE.SET` and `SCACHE.GET`. Example: `https://api.openai.com/v1/embeddings`
</ParamField>

<ParamField name="CACHEPOT_EMBED_MODEL" type="string" default="text-embedding-3-small">
  The embedding model to request. Must match a model available at your `CACHEPOT_EMBED_URL`. Change this when pointing Cache-Pot at a local provider that uses a different model name.
</ParamField>

<ParamField name="CACHEPOT_EMBED_KEY" type="string" default="">
  Bearer API key sent in the `Authorization` header with every embeddings request. Required for OpenAI and most hosted providers. You can omit this for local endpoints that do not require authentication.
</ParamField>

<Note>
  These three variables are **environment-only** — there are no `--embed-*` CLI flag equivalents. Set them before starting the `cache-pot` process.
</Note>

## OpenAI setup

Export your OpenAI credentials and start the server. Cache-Pot will log `semantic cache embeddings enabled via CACHEPOT_EMBED_URL` on startup to confirm the configuration was picked up.

```bash theme={null}
export CACHEPOT_EMBED_URL=https://api.openai.com/v1/embeddings
export CACHEPOT_EMBED_KEY=sk-...
export CACHEPOT_EMBED_MODEL=text-embedding-3-small
cache-pot
```

## Ollama (local) setup

Ollama provides a free, local embeddings server that is fully compatible with the OpenAI embeddings API. Pull a model first, then point Cache-Pot at the local endpoint. No API key is needed.

```bash theme={null}
# Start Ollama with an embedding model first
ollama pull nomic-embed-text

export CACHEPOT_EMBED_URL=http://localhost:11434/v1/embeddings
export CACHEPOT_EMBED_MODEL=nomic-embed-text
# No API key needed for local Ollama
cache-pot
```

<Tip>
  Use Ollama during development to avoid API costs entirely. Switch to OpenAI or another hosted provider in production for the best embedding quality and consistency.
</Tip>

## Other OpenAI-compatible providers

Any provider that implements the OpenAI embeddings API works with Cache-Pot. Set `CACHEPOT_EMBED_URL` to the provider's embeddings endpoint and adjust the model name to match what that provider expects.

<CodeGroup>
  ```bash Azure OpenAI theme={null}
  export CACHEPOT_EMBED_URL=https://<resource>.openai.azure.com/openai/deployments/<deployment>/embeddings?api-version=2023-05-15
  export CACHEPOT_EMBED_KEY=<your-azure-api-key>
  export CACHEPOT_EMBED_MODEL=<your-deployment-name>
  cache-pot
  ```

  ```bash Custom / self-hosted (vLLM, LiteLLM) theme={null}
  export CACHEPOT_EMBED_URL=http://your-server/v1/embeddings
  export CACHEPOT_EMBED_MODEL=<model-name-served-by-your-endpoint>
  # Set CACHEPOT_EMBED_KEY if your server requires authentication
  cache-pot
  ```
</CodeGroup>

## Verifying the configuration

After starting the server with embedding variables set, run a quick round-trip using `redis-cli` (or any Redis client) to confirm that semantic caching is working end to end:

```
SCACHE.SET "test prompt" "test response" 60
SCACHE.GET "test prompt"
# Should return: test response
```

If `SCACHE.SET` returns an error such as `embedding client not configured`, double-check that `CACHEPOT_EMBED_URL` is exported in the same shell session (or container environment) where `cache-pot` is running.

<Info>
  The similarity threshold used by `SCACHE.GET` can be tuned per-call with the `THRESHOLD` option. A value of `0.9` requires a very close match; lower values (e.g. `0.75`) allow fuzzier hits. See the commands reference for full details.
</Info>