diff options
| author | Onur Gündüz <ogunduz@gmail.com> | 2026-03-28 21:27:58 +0100 |
|---|---|---|
| committer | Onur Gündüz <ogunduz@gmail.com> | 2026-03-28 23:10:03 +0100 |
| commit | c47e900b94d18cca1bf600e58f10dbcc2e34c1f7 (patch) | |
| tree | bf7a4247c528841abe71bbbd408eda3ff71b1152 /pplx_embed.h | |
| parent | 34e9eefde7870edcc318209738cabb17c71b50ed (diff) | |
| download | ffwd-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.h | 147 |
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 */ |
