Embeddings

Embeddings are numerical representations of data (text, images, etc.) as vectors. VectorAmp uses embeddings to enable similarity search across your data.

How Embeddings Work

1. Input data (text, images) is passed through an embedding model
2. The model outputs a fixed-size vector (e.g., 1536 dimensions)
3. Similar inputs produce similar vectors (close in vector space)
4. VectorAmp indexes these vectors for fast similarity search

Supported Embedding Models

Built-in Models

VectorAmp provides hosted embedding models — no API keys or external services needed:

Model	Dimensions	Best For
vectoramp-small	768	General purpose, fast
vectoramp-large	2560	High accuracy, multilingual

External Providers

Bring your own embedding model:

Provider	Models	Dimensions
OpenAI	text-embedding-3-small	1536
OpenAI	text-embedding-3-large	3072
Cohere	embed-english-v3.0	1024
Custom	Any model via API	Variable

Organization embedding secrets

For external providers such as OpenAI, store the provider credential as an organization secret. VectorAmp stores the secret server-side and returns only the secret reference; plaintext API keys are never returned.

The default OpenAI secret reference is:

emb:openai:api_key

Create or update it through the API gateway:

curl -X POST https://api.vectoramp.com/org-secrets/emb%3Aopenai%3Aapi_key \
  -H "X-API-Key: <vectoramp_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "sk-..."
  }'

Then create a dataset that references the stored secret:

curl -X POST https://api.vectoramp.com/datasets \
  -H "X-API-Key: <vectoramp_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "openai-docs",
    "dim": 1536,
    "embedding": {
      "provider": "openai",
      "model": "text-embedding-3-small",
      "secret_ref": "emb:openai:api_key"
    }
  }'

SDKs also expose a convenience path that can save the secret and create the dataset in one call.

Testing an Embedding Provider

Before creating a pipeline, verify your embedding configuration:

result = client.embeddings.test(
    provider="openai",
    model="text-embedding-3-small",
    api_key="sk-...",
    text="Hello, world!"
)
print(f"Dimensions: {result.dimensions}")
print(f"Vector sample: {result.vector[:5]}")

Choosing the Right Model

• Speed-sensitive? → Use a smaller model (768 dims)
• Accuracy-critical? → Use a larger model (1536+ dims)
• Multilingual data? → Use vectoramp-large or text-embedding-3-large
• Cost-sensitive? → Use built-in VectorAmp models (included in your plan)

tip

The embedding model dimensions must match the dataset dimensions. A dataset created with 1536 dimensions only accepts 1536-dimensional vectors.