Skip to main content

​
Overview

The Orama Secure Proxy Plugin provides secure, cloud-based embeddings generation and LLM features for your Orama instances. It allows you to use state-of-the-art embedding models and chat models without exposing API keys on the client side.
This plugin requires an Orama Cloud account (free tier available).

​
Features

  • Secure API Proxy: Your API keys never leave Orama Cloud
  • Multiple Embedding Models: Choose from Orama and OpenAI models
  • Chat Integration: Built-in support for LLM chat models
  • Auto-generation: Automatically generate embeddings at insert time
  • Client-Safe: Use in browsers and mobile apps without exposing credentials

​
Installation

npm install @orama/plugin-secure-proxy

​
Getting Started

​
1. Get Your API Key

Sign up for a free account at https://cloud.orama.com and obtain your API key.

​
2. Configure the Plugin

import { create, insert, search } from '@orama/orama'
import { pluginSecureProxy } from '@orama/plugin-secure-proxy'

const db = await create({
  schema: {
    title: 'string',
    description: 'string',
    embeddings: 'vector[384]'
  },
  plugins: [
    pluginSecureProxy({
      apiKey: 'your-api-key',
      embeddings: {
        defaultProperty: 'embeddings',
        model: 'orama/gte-small',
        onInsert: {
          generate: true,
          properties: ['title', 'description'],
          verbose: false
        }
      },
      chat: {
        model: 'openai/gpt-4o'
      }
    })
  ]
})

​
Configuration

​
Plugin Options

​
apiKey
string
required
Your Orama Cloud API key
​
embeddings
object
required
Configuration for embeddings generation
​
chat
object
Configuration for chat/LLM features

​
Available Embedding Models

Model NameProviderDimensionsUse Case
orama/gte-smallOrama384Best for most applications, fast and efficient
orama/gte-mediumOrama768Higher quality embeddings, more compute
orama/gte-largeOrama1024Best quality, most compute intensive
Orama models are optimized for search and offer the best price/performance ratio.

​
Available Chat Models

Model NameProviderDescription
openai/gpt-4oOpenAILatest and most capable GPT-4 model
openai/gpt-4o-miniOpenAISmaller, faster GPT-4 variant
openai/gpt-4-turboOpenAIFast GPT-4 with large context window
openai/gpt-4OpenAIStandard GPT-4 model
openai/gpt-3.5-turboOpenAIFast and cost-effective
Check the Orama Cloud documentation for the latest available models and provider support.

​
Usage Examples

​
Insert with Auto-Generated Embeddings

// Embeddings are automatically generated from title and description
await insert(db, {
  title: 'Wireless Noise-Cancelling Headphones',
  description: 'Premium over-ear headphones with active noise cancellation and 30-hour battery life'
})

await insert(db, {
  title: 'USB-C Fast Charger',
  description: 'Compact 65W power adapter with GaN technology for laptops and phones'
})

const results = await search(db, {
  term: 'headphones for studying',
  mode: 'vector',
  limit: 10
})
The plugin automatically:
  1. Generates embeddings for “headphones for studying”
  2. Performs vector similarity search
  3. Returns the most semantically similar results
const results = await search(db, {
  term: 'fast charging laptop',
  mode: 'hybrid',
  limit: 10
})

​
Custom Vector Properties

const db = await create({
  schema: {
    title: 'string',
    body: 'string',
    titleEmbeddings: 'vector[384]',
    bodyEmbeddings: 'vector[384]'
  },
  plugins: [
    pluginSecureProxy({
      apiKey: 'your-api-key',
      embeddings: {
        defaultProperty: 'titleEmbeddings',
        model: 'orama/gte-small',
        onInsert: {
          generate: true,
          properties: ['title']
        }
      }
    })
  ]
})

// Manually set bodyEmbeddings separately if needed

​
How It Works

The Secure Proxy plugin implements hooks to intercept insert and search operations:

​
beforeInsert Hook

At /home/daytona/workspace/source/packages/plugin-secure-proxy/src/index.ts:57-76: 
async beforeInsert<T extends TypedDocument<any>>(_db: AnyOrama, _id: string, params: PartialSchemaDeep<T>) {
  if (!pluginParams.embeddings?.onInsert?.generate) {
    return
  }

  const properties = pluginParams.embeddings.onInsert.properties
  const values = getPropertiesValues(params, properties)

  if (pluginParams.embeddings.onInsert.verbose) {
    console.log(`Generating embeddings for properties ${properties.join(', ')}: ${values}`)
  }

  const embeddings = await proxy.generateEmbeddings(values, pluginParams.embeddings.model)
  params[pluginParams.embeddings.defaultProperty] = embeddings
}

​
beforeSearch Hook

At /home/daytona/workspace/source/packages/plugin-secure-proxy/src/index.ts:78-104: 
async beforeSearch<T extends AnyOrama>(_db: AnyOrama, params: SearchParams<T, TypedDocument<any>>) {
  if (params.mode !== 'vector' && params.mode !== 'hybrid') {
    return
  }

  if (params?.vector?.value) {
    return
  }

  if (!params.term) {
    throw new Error('Neither "term" nor "vector" parameters were provided')
  }

  const embeddings = await proxy.generateEmbeddings(params.term, pluginParams.embeddings.model)
  
  if (!params.vector) {
    params.vector = {
      property: params?.vector?.property ?? pluginParams.embeddings.defaultProperty,
      value: embeddings
    }
  }

  params.vector.value = embeddings
}

​
Accessing the Proxy

The plugin exposes the OramaProxy instance for direct use: 
const db = await create({
  schema: { /* ... */ },
  plugins: [
    pluginSecureProxy({
      apiKey: 'your-api-key',
      embeddings: { /* ... */ },
      chat: {
        model: 'openai/gpt-4o'
      }
    })
  ]
})

// Access the proxy through the plugin
const plugin = db.plugins[0]
const proxy = plugin.extra.proxy

// Generate embeddings directly
const embeddings = await proxy.generateEmbeddings(
  'some text',
  'orama/gte-small'
)

// Use chat features
const chatResponse = await proxy.chat({
  model: 'openai/gpt-4o',
  messages: [
    { role: 'user', content: 'What is Orama?' }
  ]
})

​
Security Benefits

No Exposed Keys

API keys are stored securely in Orama Cloud and never exposed to clients

Client-Side Safe

Use in browsers and mobile apps without security concerns

Rate Limiting

Built-in rate limiting and abuse prevention

Usage Tracking

Monitor API usage through Orama Cloud dashboard

​
Best Practices

​
Choose the Right Model

// For most applications, start with orama/gte-small
embeddings: {
  model: 'orama/gte-small', // 384 dimensions, fast, cost-effective
  defaultProperty: 'embeddings'
}

// For higher quality, use orama/gte-large
embeddings: {
  model: 'orama/gte-large', // 1024 dimensions, best quality
  defaultProperty: 'embeddings'
}

​
Combine Multiple Properties

// Generate richer embeddings from multiple fields
onInsert: {
  generate: true,
  properties: ['title', 'description', 'tags', 'category']
}

​
Use Verbose Mode During Development

onInsert: {
  generate: true,
  properties: ['title', 'description'],
  verbose: true // Enable to debug embedding generation
}

​
Comparison with Local Embeddings

FeatureSecure ProxyEmbeddings Plugin
SetupAPI key onlyTensorFlow.js required
ModelsMultiple optionsUniversal Sentence Encoder only
Dimensions384-3072512
Client-Side✅ Safe❌ Model too large
Offline❌ Requires internet✅ Works offline
CostAPI usageFree (compute costs)
PerformanceConsistentVaries by hardware

​
Troubleshooting

​
Invalid API Key

Error: Invalid API key for plugin-secure-proxy
Ensure your API key is correct and active in Orama Cloud.

​
Model Not Found

Error: Model not found
Check that you’re using a valid model name from the Available Models list.

​
Vector Dimension Mismatch

Error: Vector dimension mismatch
Ensure your schema’s vector dimension matches your chosen model: 
// For orama/gte-small (384 dimensions)
schema: {
  embeddings: 'vector[384]' // Must match model output
}

​
Next Steps

Vector Search

Learn more about vector search in Orama

Orama Cloud

Sign up for Orama Cloud

Analytics Plugin

Track search analytics with Orama Cloud

Local Embeddings

Compare with offline embeddings plugin

Build docs developers (and LLMs) love

Get started for freeTalk to us