Upload Embedding Model

Overview

Flow ID: embedding-model-upload
Category: Model Management
Estimated Duration: 1 minute
User Role: Admin / Power User
Complexity: Moderate

Purpose: Import a specialized model designed to convert text into vectors (numbers). This is required for creating Datasets (RAG). Embedding models are typically smaller (< 1GB) than Chat models.

Trigger

What initiates this flow:

• User manually initiates

Specific trigger: Settings > Embedding Models > Upload New.

Prerequisites

Before starting, users must have:

• A valid embedding model (usually .onnx or .gguf depending on backend support, often pulled automatically or file-based).
• Constraint: Embedding models must not change for a dataset once created.

Step-by-Step Flow

Main Path (Happy Path)

Step 1: Open Settings

• User Action: Navigate to Settings > Embedding Models.

Step 2: Upload or Download

• User Action:
  • Option A (File): Upload local model file.
  • Option B (HuggingFace): Enter repo ID (e.g., nomic-ai/nomic-embed-text-v1).
• Best Practice: Use Option B (Download) for embeddings as configuration is complex.

Step 3: Verification

• System Response: Model downloads/installs and runs a quick test vector to ensure it works.
• Success: Status “Active”.

Error States & Recovery

Error 1: Dimension Mismatch

Cause: Using a model with 768 dimensions when system expects 1024 (rare, usually handled by backend).
User Experience: “Model incompatible”.
Recovery: Stick to recommended list (nomic, all-minilm, bge-m3).

Pain Points & Friction

1. Incompatibility: Not all models work with every vector database (Chroma/FAISS).
   • Mitigation: Curated list of “Certified” models.

Related Flows

• Select Embedding Model
• Corpus Creation - Where this is used

Technical References

• src/engines/embedding-engine.js