embedx Specification

Overview

embedx is a FastEmbed-powered embedding service with a drop-in Ollama-compatible HTTP API. It uses Go for HTTP and Python subprocess with pipe communication for FastEmbed.

Architecture

Components

1. Go HTTP Server - Exposes Ollama-compatible API on port 11434
2. Python Subprocess - FastEmbed backend, called via stdin/stdout pipes with JSON protocol

Data Flow

Client Request (Ollama-compatible API)
    ↓
Go HTTP Server (:11434)
    ↓ JSON via stdin/stdout pipe
Python Subprocess (FastEmbed)
    ↓
Return embedding / status to client

API Specification

POST /api/embeddings

Ollama-compatible embedding generation.

Request:

{
  "model": "BAAI/bge-small-zh-v1.5",   // optional, defaults to EMBEDX_MODEL
  "prompt": "your text here"
}

Response:

{
  "embedding": [0.003, 0.064, -0.045, ...]
}

POST /api/pull

Ollama-compatible model download.

Request:

{
  "name": "BAAI/bge-base-zh-v1.5",
  "stream": false
}

Response (non-streaming):

{
  "status": "success",
  "model": "BAAI/bge-base-zh-v1.5",
  "dimensions": 768
}

Response (streaming, SSE):

event: status
data: {"status":"pulling","model":"BAAI/bge-base-zh-v1.5"}

event: done
data: {"status":"success","model":"BAAI/bge-base-zh-v1.5"}

POST /api/create

Load a model into memory (does not persist, use /api/pull for that).

Request:

{"name": "BAAI/bge-base-zh-v1.5"}

Response:

{"status": "success", "model": "BAAI/bge-base-zh-v1.5", "dimensions": 768}

POST /api/show

Get model information after loading.

Request:

{"name": "BAAI/bge-base-zh-v1.5"}

GET /api/tags

List available (cached) models.

Response:

{
  "models": [
    {"name": "BAAI/bge-small-zh-v1.5", "model": "BAAI/bge-small-zh-v1.5", "size": 0}
  ]
}

GET /health

Health check - returns 200 OK.

Python Protocol

Go communicates with Python via JSON messages on stdin/stdout.

Commands (Go → Python)

{"command": "embed", "model_name": "...", "texts": ["..."]}
{"command": "load", "model_name": "..."}
{"command": "pull", "model_name": "..."}
{"command": "unload", "model_name": "..."}
{"command": "list_cached"}

Responses (Python → Go)

{"type": "embed_done", "embeddings": [[0.1, 0.2, ...]]}
{"type": "model_loaded", "model": "...", "dimensions": 512, "cached": ["..."]}
{"type": "pull_done", "model": "...", "dimensions": 512}
{"type": "error", "error": "..."}

Configuration

Variable	Default	Description
EMBEDX_PORT	11434	HTTP server port
EMBEDX_MODEL	BAAI/bge-small-zh-v1.5	Default embedding model

Supported Models

All FastEmbed-supported models. Popular choices:

Model	Dimensions	Languages
BAAI/bge-small-zh-v1.5	512	Chinese + English
BAAI/bge-base-en-v1.5	768	English
nomic-ai/nomic-embed-text-v1.5	768	English (multimodal)
jinaai/jina-embeddings-v2-base-en	768	English
mixedbread-ai/mxbai-embed-large-v1	1024	English

File Structure

embedx/
├── main.go       # Go HTTP server + subprocess management
├── embed.py      # Python CLI (stdin/stdout protocol)
├── go.mod        # Go module
├── Makefile      # Build commands
├── README.md     # User documentation
└── SPEC.md       # This file