aboutsummaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
authorOnur Gündüz <ogunduz@gmail.com>2026-03-28 21:27:58 +0100
committerOnur Gündüz <ogunduz@gmail.com>2026-03-28 23:10:03 +0100
commitc47e900b94d18cca1bf600e58f10dbcc2e34c1f7 (patch)
treebf7a4247c528841abe71bbbd408eda3ff71b1152 /README.md
parent34e9eefde7870edcc318209738cabb17c71b50ed (diff)
downloadffwd-c47e900b94d18cca1bf600e58f10dbcc2e34c1f7.tar.gz
ffwd-c47e900b94d18cca1bf600e58f10dbcc2e34c1f7.zip
Refactor and enhance pplx_embed and pplx_embed_mlx for improved model support
- Updated `pplx_embed.h` to support new embedding models: `pplx-embed-v1-4b` and `pplx-embed-context-v1-4b`. - Simplified model configuration structure and constants for better maintainability. - Enhanced comments for clarity on model architecture and configuration. - Modified `pplx_embed_mlx.c` to streamline loading of model weights and configuration from `config.json`. - Improved memory management and error handling in the MLX backend. - Updated embedding computation to support dynamic hidden sizes based on model configuration. - Added `pplx_mlx_config` function to retrieve model configuration details. - Updated README.md - Added .gitignore
Diffstat (limited to 'README.md')
-rw-r--r--README.md88
1 files changed, 87 insertions, 1 deletions
diff --git a/README.md b/README.md
index 613ce47..bbc205a 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,87 @@
-# pplx-embed-v1
+# pplx-embed
+
+Pure C inference for [pplx-embed](https://research.perplexity.ai/articles/pplx-embed-state-of-the-art-embedding-models-for-web-scale-retrieval) embedding models by [Perplexity AI](https://www.perplexity.ai/). Supports safetensors and hardware-accelerated execution (BLAS/mlx-c) for generating float32 vectors.
+
+Based on math kernels from [antirez](https://github.com/antirez)'s [qwen-asr](https://github.com/antirez/qwen-asr).
+
+## Supported models
+
+All [pplx-embed](https://huggingface.co/collections/perplexity-ai/pplx-embed-v1-68126b2e7cc987cd820ebbbd) models are supported.
+
+| Model | Dims | Params | Size |
+|---|---|---|---|
+| [pplx-embed-v1-0.6b](https://huggingface.co/perplexity-ai/pplx-embed-v1-0.6b) | 1024 | 0.6B | ~2.5 GB |
+| [pplx-embed-v1-4b](https://huggingface.co/perplexity-ai/pplx-embed-v1-4b) | 2560 | 4B | ~16 GB |
+| [pplx-embed-context-v1-0.6B](https://huggingface.co/perplexity-ai/pplx-embed-context-v1-0.6B) | 1024 | 0.6B | ~2.5 GB |
+| [pplx-embed-context-v1-4B](https://huggingface.co/perplexity-ai/pplx-embed-context-v1-4B) | 2560 | 4B | ~16 GB |
+
+## Quickstart
+
+```bash
+make mlx # Apple Silicon (fastest)
+# or: make blas # CPU with BLAS (any platform)
+
+./pplx_embed -d /path/to/model "query: what is the capital of France?"
+# prints 1024 (or 2560) floats to stdout
+
+./pplx_embed -d /path/to/model \
+ "query: what is the capital of France?" \
+ "document: Paris is the capital of France." \
+ "document: Berlin is the capital of Germany."
+# prints cosine similarity matrix
+```
+
+### Daemon mode
+
+Start the process once and feed texts through stdin. The model stays loaded in memory.
+
+```bash
+# One embedding per line, output as JSON
+./pplx_embed -d /path/to/model --daemon --mlx <<'EOF'
+query: what is the capital of France?
+document: Paris is the capital of France.
+document: Berlin is the capital of Germany.
+document: Istanbul is the capital of Germany.
+EOF
+```
+
+Output (one JSON object per line):
+
+```json
+{"embedding":[0.0231,-0.0412,...], "dim":1024, "tokens":9, "ms":15.2}
+{"embedding":[0.0187,-0.0339,...], "dim":1024, "tokens":9, "ms":14.8}
+...
+```
+
+## Building
+
+```bash
+make blas # CPU with BLAS (Accelerate on macOS, OpenBLAS on Linux)
+make mlx # Apple Silicon GPU via mlx-c (recommended on Apple Silicon)
+make debug # Debug build with AddressSanitizer
+```
+
+For `make mlx`, install MLX first: `brew install mlx mlx-c`
+
+For `make blas` on Linux: `sudo apt install libopenblas-dev`
+
+## Usage
+
+```
+./pplx_embed -d <model_dir> [options] [text...]
+
+Options:
+ -d <dir> Model directory (required)
+ --mlx Use Apple MLX GPU backend
+ --daemon Read texts from stdin, write JSON embeddings to stdout
+ -t <n> CPU thread count (default: all cores)
+ -e Print raw embedding vectors (with multiple texts)
+ -v Verbose (-vv for debug)
+```
+
+**Single text**: prints the embedding vector as space-separated floats.
+
+**Multiple texts**: prints a cosine similarity matrix.
+
+**Daemon mode** (`--daemon`): reads one text per line from stdin, writes one JSON object per line to stdout. EOF or empty line exits.
+