Strapi v5 Plugin: Elasticsearch AI Search

A powerful Strapi v5 plugin for integrating with Elasticsearch, providing automatic vector embedding generation for semantic search, multi-locale support, real-time synchronization, and hybrid search (text + vector).

Features

• 🔍 Elasticsearch Integration: Automatically sync Strapi content to Elasticsearch indices.
• 🤖 AI-Powered Embeddings: Generate vector embeddings for semantic search using OpenAI or custom providers.
• ⚡ Hybrid Search: Combine traditional BM25 text search with KNN vector similarity using configurable Alpha/Beta weights.
• 🌍 Multi-locale Support: Handle localized content with locale-specific indices.
• 🔄 Real-time Synchronization: Lifecycle hooks to keep Elasticsearch in sync with Strapi content changes.
• 📊 Batch Operations: Efficient bulk indexing and embedding generation tools.
• 🛠️ Migration Tools: Utilities for migrating from legacy Elastic App Search to regular Elasticsearch indices.

Usage

Install the plugin in your Strapi v5 application:

pnpm add @codeparticle/strapi-plugin-es-ai-search

Basic Configuration

Add the configuration to config/plugins.js (or config/plugins.ts):

module.exports = ({ env }) => ({
  'es-ai-search': {
    enabled: true,
    config: {
      elasticsearchUrl: env('ELASTICSEARCH_URL'),
      elasticsearchApiKey: env('ELASTICSEARCH_API_KEY'),
      indexPrefix: env('ELASTICSEARCH_INDEX_PREFIX', 'strapi'),
      
      // Embedding service for vector search
      vectorEnabled: env.bool('EMBEDDINGS_ENABLED', true),
      embeddingProvider: env('EMBEDDING_PROVIDER', 'openai'),
      embeddingModel: env('EMBEDDING_MODEL_NAME', 'text-embedding-3-small'),
      embeddingApiKey: env('EMBEDDING_API_KEY'),
      embeddingServiceUrl: env('ELASTICSEARCH_EMBEDDING_URL'),
      embeddingTimeout: env.int('EMBEDDING_TIMEOUT', 10000),
      
      // Summary/LLM API configuration
      aiApiKey: env('AI_API_KEY'),
      aiBaseUrl: env('AI_BASE_URL'),
      
      // Hybrid Search weighting
      hybridAlpha: env.float('HYBRID_ALPHA', 0.5),
      hybridBeta: env.float('HYBRID_BETA', 0.5),
      
      apisToSync: [
        {
          name: 'api::article.article',
          indexSuffix: 'article',
          populate: ['category', 'author'],
        },
      ]
    }
  }
});

AI Embedding Integration

The plugin generates vector embeddings for documents by calling the configured embedding provider.

How It Works

1. Content Formatting: The plugin concatenates configured fields (default: title + description) into a single string.
2. Embedding Generation: The server-side service calls the configured provider (e.g., OpenAI).
3. Storage: The numeric vector is stored in the embedding dense_vector field in Elasticsearch.
4. Search: When searching, the plugin generates a query vector and performs a hybrid or KNN search.

Environment Variables

# Elasticsearch
ELASTICSEARCH_URL=https://your-es-cluster:9200
ELASTICSEARCH_API_KEY=your-api-key
ELASTICSEARCH_INDEX_PREFIX=beautynexos

# Embeddings
EMBEDDINGS_ENABLED=true
EMBEDDING_PROVIDER=openai # Options: openai, legacy
EMBEDDING_MODEL_NAME=text-embedding-3-small
EMBEDDING_API_KEY=your-llm-api-key
ELASTICSEARCH_EMBEDDING_URL=https://api.openai.com/v1
EMBEDDING_TIMEOUT=10000 # milliseconds

# Summary / LLM
AI_API_KEY=your-llm-api-key
AI_BASE_URL=https://api.openai.com/v1

# Hybrid Search
HYBRID_ALPHA=0.5
HYBRID_BETA=0.5

Migration from Elastic App Search

This plugin includes utilities to migrate data from legacy Elastic App Search indices to regular Elasticsearch indices.

Running the Migration

# Dry run to preview changes
npm run migrate:appsearch-to-es:dry-run

# Execute full migration
npm run migrate:appsearch-to-es

License

MIT