EmbedCrate

Turn text into searchable vectors

EmbedCrate

Open-source, self-hosted text embeddings and reranking API.

Create embeddings for semantic search and retrieval on your own server. Powered by Hugging Face Text Embeddings Inference (TEI), with an OpenAI-compatible embeddings API and optional cross-encoder reranking.

View on GitHub

Open source · MIT licensed

Get the book on Amazon

The Self-Hosted AI Builder's Guide Practical guidance for deployment, security, backups, and everyday operation.

Text → embeddings → retrieval

Ready to compare.
Ready to retrieve.

TEXT INPUT

How do I back up my AI stack?

ILLUSTRATIVE VECTOR

[0.03, -0.12, 0.08, …]

  • Embeddings
  • Semantic search
  • Optional reranking
Illustrative, shortened vector. Your configured model determines the actual vector dimensions and values; add your own storage and retrieval logic.

A focused service for your applications

A focused API for semantic retrieval.

Encode text for similarity search, then optionally rerank candidate passages. EmbedCrate provides model serving; your application handles ingestion, storage, retrieval, and the final answer.

Images are automatically built and published through public GitHub Actions workflows. Powered by Hugging Face TEI.

Start with one text input

Run locally.
Create your first embedding.

This CPU example binds the embeddings API to loopback and uses the default BGE model. The optional reranker is a separate configuration step.

  • Docker on a supported amd64 or arm64 Linux host
  • Memory and disk space suitable for your chosen model
  • Internet access for the first model download, unless models are pre-cached

Full setup guide on GitHub

For access from other computers, follow the maintained HTTPS, authentication, and network-exposure instructions.

  1. Start EmbedCrate

    docker run \
  --name embeddings \
  --restart=always \
  -v embeddings-data:/var/lib/embeddings \
  -p 127.0.0.1:8000:8000 \
  -d hwdsl2/embeddings-server

    The default BGE model downloads on first start. Use docker logs embeddings and wait for “Text embeddings server is ready”.

  2. Retrieve your API key

    embed_api_key="$(docker exec embeddings embed_manage --getkey)"

    Fresh persistent installations generate and save a key. Keep using the same shell for the following request.

  3. Embed a text input

    curl http://127.0.0.1:8000/v1/embeddings \
  -H "Authorization: Bearer $embed_api_key" \
  -H "Content-Type: application/json" \
  -d '{"input":"The quick brown fox","model":"text-embedding-ada-002"}'

    The request’s model name is a compatibility field here. It does not call an OpenAI-hosted model or switch away from your configured BGE model.

Part of a larger toolkit

Build your Self-Hosted AI Stack

EmbedCrate is also available as part of Self-Hosted AI Stack. Deploy local models, chat, document processing, voice, and AI tools together, or choose a smaller configuration for your needs.

Explore Self-Hosted AI Stack

Connect the services you need

Start with structured documents

ParseCrate extracts text and structure from PDFs and other documents. Connect its output to EmbedCrate, a vector store, and your own retrieval application.

Explore ParseCrate

Before you deploy

Is EmbedCrate free to use?

The EmbedCrate project is open source under the MIT License. You provide hardware or cloud hosting and pay associated costs. Models, dependencies, and external providers retain their own licenses and terms.

Does EmbedCrate include a vector database?

No. It serves embeddings and optional reranking. Store vectors and implement search in your application, for example with PostgreSQL and pgvector.

Does the request model field choose a model?

The server configuration selects the loaded model. The OpenAI-compatible request field does not select an OpenAI-hosted model or dynamically load a different model.

Is reranking enabled by default?

No. Set RERANK_ENABLED=true and configure the reranker model. If you need host access, publish port 8001 to loopback as well. A separate reranker key can be configured.

Does it require a GPU?

No. The supplied EmbedCrate images run on CPU on amd64 and arm64. Choose a model that fits your host’s memory and expected request load.

Can embeddings be generated offline?

Cache your selected models first and enable EMBED_LOCAL_ONLY=true. Disable aggregate usage counts separately with EMBED_DISABLE_USAGE_COUNTS=1.

The image includes optional aggregate usage counts. See the usage-count documentation; set EMBED_DISABLE_USAGE_COUNTS=1 to disable them.

Bring your text. Keep control of your retrieval pipeline.

View on GitHub