nxtgencat/fastembed repository overview

⁠FastEmbed API

A self-hosted text embedding, sparse embedding, and reranking API powered by FastEmbed⁠ and FastAPI⁠.

Multi-arch Docker images (AMD64 + ARM64) are published to Docker Hub via GitHub Actions.

⁠Quick Start

⁠Pull from Docker Hub

docker pull nxtgencat/fastembed:latest

docker run -d --name fastembed -p 8000:8000 -v fastembed_cache:/app/model_cache nxtgencat/fastembed:latest

The model downloads on first run and is cached in fastembed_cache. Subsequent starts are fast.

⁠Configuration

All configuration is done via environment variables. Set them in docker-compose.yml or pass with docker run -e.

⁠Enable all models

environment:
  - FASTEMBED_MODEL=BAAI/bge-small-en-v1.5
  - FASTEMBED_SPARSE_MODEL=prithivida/Splade_PP_en_v1
  - FASTEMBED_RERANKER_MODEL=Xenova/ms-marco-MiniLM-L-6-v2

Browse available models at /models or the FastEmbed docs⁠.

⁠API

Base URL: http://localhost:8000

Interactive docs: http://localhost:8000/docs

⁠POST /embeddings

Generate dense vector embeddings.

Request:

{ "texts": ["hello world", "fastembed is fast"] }

Response:

{
  "embeddings": [
    [0.0123, -0.0456, ...],
    [0.0789, -0.0012, ...]
  ]
}

⁠POST /query-embeddings

Query-optimized embeddings (some models produce different embeddings for queries vs documents).

Request:

{ "texts": ["what is machine learning?"] }

Response: Same format as /embeddings.

⁠POST /sparse-embeddings

Sparse vector embeddings (SPLADE, BM25, etc.). Requires FASTEMBED_SPARSE_MODEL to be set.

Request:

{ "texts": ["sparse vector example"] }

Response:

{
  "embeddings": [
    { "indices": [102, 456, 789], "values": [0.52, 1.34, 0.11] }
  ]
}

⁠POST /rerank

Score and sort documents by relevance to a query. Requires FASTEMBED_RERANKER_MODEL to be set.

Request:

{
  "query": "what is deep learning?",
  "documents": [
    "Deep learning is a subset of machine learning.",
    "The weather is sunny today.",
    "Neural networks power deep learning."
  ]
}

Response:

{
  "results": [
    { "index": 0, "score": 0.95, "text": "Deep learning is a subset of machine learning." },
    { "index": 2, "score": 0.88, "text": "Neural networks power deep learning." },
    { "index": 1, "score": 0.02, "text": "The weather is sunny today." }
  ]
}

⁠GET /models

List all supported models (dense, sparse, reranker).

⁠GET /health

Response:

{
  "status": "ok",
  "models": {
    "dense": "BAAI/bge-small-en-v1.5",
    "sparse": null,
    "reranker": null
  }
}

⁠GET /metrics

Prometheus metrics endpoint. Exposes request count, latency histogram, and in-flight request gauge.