aboutsummaryrefslogtreecommitdiff
path: root/pplx_embed.h
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 /pplx_embed.h
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 'pplx_embed.h')
-rw-r--r--pplx_embed.h147
1 files changed, 53 insertions, 94 deletions
diff --git a/pplx_embed.h b/pplx_embed.h
index 69b67c3..67b193e 100644
--- a/pplx_embed.h
+++ b/pplx_embed.h
@@ -1,23 +1,7 @@
/*
- * pplx_embed.h - Pure C inference for perplexity-ai/pplx-embed-v1-0.6b
+ * pplx_embed.h - Pure C inference for Perplexity AI's pplx-embed models.
*
- * Architecture: Qwen3-family transformer with BIDIRECTIONAL (non-causal)
- * attention. Based on antirez's qwen-asr kernels. Produces dense float32
- * embedding vectors via mean-pooling + L2-normalization.
- *
- * Model spec:
- * hidden_size = 1024
- * num_hidden_layers = 28
- * num_attention_heads = 16 (query heads)
- * num_key_value_heads = 8 (GQA: 2 query heads share 1 KV head)
- * head_dim = 128
- * intermediate_size = 3072
- * vocab_size = 151936
- * rms_norm_eps = 1e-6
- * rope_theta = 1000000.0 (1e6)
- * weights dtype = F32 (all weights float32)
- * tie_word_embeddings = true
- * use_bidirectional_attention = true
+ * Supports all pplx-embed-v1 and pplx-embed-context-v1 variants (0.6B, 4B).
*/
#ifndef PPLX_EMBED_H
@@ -27,32 +11,26 @@
#include <stdint.h>
/* ========================================================================
- * Constants
+ * Shared constants (identical across all models)
* ======================================================================== */
-#define PPLX_HIDDEN_SIZE 1024
-#define PPLX_NUM_LAYERS 28
-#define PPLX_NUM_HEADS 16
-#define PPLX_NUM_KV_HEADS 8
-#define PPLX_HEAD_DIM 128
-#define PPLX_Q_DIM (PPLX_NUM_HEADS * PPLX_HEAD_DIM) /* 2048 */
-#define PPLX_KV_DIM (PPLX_NUM_KV_HEADS * PPLX_HEAD_DIM) /* 1024 */
-#define PPLX_INTERMEDIATE_SIZE 3072
-#define PPLX_VOCAB_SIZE 151936
+#define PPLX_VOCAB_SIZE 151936
+#define PPLX_HEAD_DIM 128
+#define PPLX_MAX_LAYERS 64 /* upper bound for stack arrays */
/* ========================================================================
- * Model Configuration
+ * Model Configuration (populated from config.json at load time)
* ======================================================================== */
typedef struct {
- int hidden_size; /* 1024 */
- int n_layers; /* 28 */
- int n_heads; /* 16 */
- int n_kv_heads; /* 8 */
- int head_dim; /* 128 */
- int q_dim; /* n_heads * head_dim = 2048 */
- int kv_dim; /* n_kv_heads * head_dim = 1024 */
- int intermediate_size; /* 3072 */
+ int hidden_size; /* 0.6B: 1024 4B: 2560 */
+ int n_layers; /* 0.6B: 28 4B: 36 */
+ int n_heads; /* 0.6B: 16 4B: 32 */
+ int n_kv_heads; /* 0.6B: 8 4B: 8 */
+ int head_dim; /* always 128 */
+ int q_dim; /* n_heads * head_dim */
+ int kv_dim; /* n_kv_heads * head_dim */
+ int intermediate_size; /* 0.6B: 3072 4B: 9728 */
int vocab_size; /* 151936 */
float rms_norm_eps; /* 1e-6 */
float rope_theta; /* 1e6 */
@@ -60,37 +38,17 @@ typedef struct {
/* ========================================================================
* Per-Layer Weights (all F32, direct mmap pointers - read-only)
- *
- * Tensor shapes (row-major):
- * wq [q_dim, hidden] = [2048, 1024]
- * wk [kv_dim, hidden] = [1024, 1024]
- * wv [kv_dim, hidden] = [1024, 1024]
- * wo [hidden, q_dim] = [1024, 2048]
- * q_norm [head_dim] = [128]
- * k_norm [head_dim] = [128]
- * input_norm [hidden] = [1024]
- * post_attn_norm [hidden] = [1024]
- * gate_proj [intermediate, hidden] = [3072, 1024]
- * up_proj [intermediate, hidden] = [3072, 1024]
- * down_proj [hidden, intermediate] = [1024, 3072]
* ======================================================================== */
typedef struct {
- /* Self-attention projections (no bias) */
const float *wq; /* [q_dim, hidden] */
const float *wk; /* [kv_dim, hidden] */
const float *wv; /* [kv_dim, hidden] */
const float *wo; /* [hidden, q_dim] */
-
- /* Per-head Q/K RMSNorm weights (Qwen3 feature) */
const float *q_norm; /* [head_dim] */
const float *k_norm; /* [head_dim] */
-
- /* Layer norms (no bias - RMSNorm only) */
- const float *input_norm; /* [hidden] pre-attention */
- const float *post_attn_norm;/* [hidden] pre-MLP */
-
- /* SwiGLU MLP (no bias) */
+ const float *input_norm; /* [hidden] */
+ const float *post_attn_norm;/* [hidden] */
const float *gate_proj; /* [intermediate, hidden] */
const float *up_proj; /* [intermediate, hidden] */
const float *down_proj; /* [hidden, intermediate] */
@@ -101,14 +59,9 @@ typedef struct {
* ======================================================================== */
typedef struct {
- /* Token embedding table (tied with output head, but we don't need lm_head) */
- const float *embed_tokens; /* [vocab_size, hidden] */
-
- /* Transformer layers */
- pplx_layer_t layers[PPLX_NUM_LAYERS];
-
- /* Final RMSNorm */
- const float *norm; /* [hidden] */
+ const float *embed_tokens; /* [vocab_size, hidden] */
+ pplx_layer_t *layers; /* [n_layers] heap-allocated */
+ const float *norm; /* [hidden] */
} pplx_weights_t;
/* ========================================================================
@@ -118,27 +71,25 @@ typedef struct {
typedef struct {
pplx_config_t config;
pplx_weights_t weights;
-
- /* Open safetensors handle (keeps mmap alive) */
- void *safetensors; /* multi_safetensors_t* */
+ void *safetensors; /* multi_safetensors_t*, keeps mmap alive */
/* Working buffers, grown lazily to buf_seq_cap */
int buf_seq_cap;
- float *x; /* [seq, hidden] main activations */
- float *x_norm; /* [seq, hidden] after RMSNorm */
- float *q; /* [seq, q_dim] query vectors */
- float *k; /* [seq, kv_dim] key vectors */
- float *v; /* [seq, kv_dim] value vectors */
- float *attn_out; /* [seq, q_dim] attention output */
- float *proj_out; /* [seq, hidden] after o_proj */
- float *ffn_gate; /* [seq, intermediate] gate branch */
- float *ffn_up; /* [seq, intermediate] up branch */
- float *ffn_out; /* [seq, hidden] after down_proj */
+ float *x; /* [seq, hidden] */
+ float *x_norm; /* [seq, hidden] */
+ float *q; /* [seq, q_dim] */
+ float *k; /* [seq, kv_dim] */
+ float *v; /* [seq, kv_dim] */
+ float *attn_out; /* [seq, q_dim] */
+ float *proj_out; /* [seq, hidden] */
+ float *ffn_gate; /* [seq, intermediate] */
+ float *ffn_up; /* [seq, intermediate] */
+ float *ffn_out; /* [seq, hidden] */
/* RoPE cosine/sine cache [n_pos, head_dim], grown lazily */
float *rope_cos;
float *rope_sin;
- int rope_cache_cap; /* number of cached positions */
+ int rope_cache_cap;
} pplx_ctx_t;
/* ========================================================================
@@ -146,11 +97,12 @@ typedef struct {
* ======================================================================== */
/*
- * Load the model from a directory containing:
- * model.safetensors - weight tensors (F32)
- * vocab.json - BPE vocabulary
- * merges.txt - BPE merge rules
+ * Load model from directory containing:
+ * config.json - model hyperparameters
+ * model.safetensors (or sharded) - F32 weights
+ * vocab.json + merges.txt - BPE tokenizer
*
+ * Reads config.json to determine model size (0.6B vs 4B).
* Returns NULL on error.
*/
pplx_ctx_t *pplx_load(const char *model_dir);
@@ -159,28 +111,35 @@ pplx_ctx_t *pplx_load(const char *model_dir);
void pplx_free(pplx_ctx_t *ctx);
/*
- * Compute the embedding for a sequence of token IDs.
+ * Compute embedding for a token sequence.
*
- * Performs:
* 1. Token embedding lookup
- * 2. 28 × bidirectional transformer layers (GQA, RoPE, SwiGLU)
+ * 2. N transformer layers (bidirectional GQA + RoPE + SwiGLU)
* 3. Final RMSNorm
- * 4. Mean pooling across all token positions
+ * 4. Mean pooling over all positions
* 5. L2 normalization
*
- * Returns a malloc'd float[hidden_size] (caller must free).
- * Returns NULL on allocation error or empty input.
+ * Returns malloc'd float[hidden_size] (caller frees). NULL on error.
*/
float *pplx_embed(pplx_ctx_t *ctx, const int *token_ids, int n_tokens);
/*
- * Cosine similarity between two L2-normalized embedding vectors.
- * (This is just the dot product since both are unit vectors.)
+ * Run the transformer forward pass WITHOUT pooling.
+ * Returns the full [n_tokens * hidden_size] output after final RMSNorm.
+ * Caller frees the returned buffer. NULL on error.
+ *
+ * Useful for contextual (late-chunking) models where you need
+ * per-token embeddings before splitting by separator positions.
+ */
+float *pplx_forward(pplx_ctx_t *ctx, const int *token_ids, int n_tokens);
+
+/*
+ * Cosine similarity between two L2-normalized vectors.
*/
float pplx_cosine_similarity(const float *a, const float *b, int dim);
/* Verbose level: 0=quiet, 1=info, 2=debug */
extern int pplx_verbose;
-extern int qwen_verbose; /* same flag, used internally by kernel/tokenizer */
+extern int qwen_verbose;
#endif /* PPLX_EMBED_H */