aboutsummaryrefslogtreecommitdiff
path: root/pplx_embed.h
diff options
context:
space:
mode:
authorOnur Gündüz <ogunduz@gmail.com>2026-06-10 08:24:39 +0200
committerOnur Gündüz <ogunduz@gmail.com>2026-06-14 08:27:03 +0200
commit2c37727e653d2340d8977dd5db4addc767dd81ea (patch)
tree578ad6affac511f847a346a0efc6d40ebf6a279f /pplx_embed.h
parentec417bcb52f2aa8e24aeec312e8ddbf3a0798056 (diff)
downloadffwd-2c37727e653d2340d8977dd5db4addc767dd81ea.tar.gz
ffwd-2c37727e653d2340d8977dd5db4addc767dd81ea.zip
gitignore: track new binary and library names
Diffstat (limited to 'pplx_embed.h')
-rw-r--r--pplx_embed.h293
1 files changed, 0 insertions, 293 deletions
diff --git a/pplx_embed.h b/pplx_embed.h
deleted file mode 100644
index 5a2501b..0000000
--- a/pplx_embed.h
+++ /dev/null
@@ -1,293 +0,0 @@
-/*
- * pplx_embed.h - Pure C inference for Perplexity AI's pplx-embed models.
- *
- * Supports all pplx-embed-v1 and pplx-embed-context-v1 variants (0.6B, 4B).
- */
-
-#ifndef PPLX_EMBED_H
-#define PPLX_EMBED_H
-
-#include <stddef.h>
-#include <stdint.h>
-
-/* ========================================================================
- * Shared constants (identical across all models)
- * ======================================================================== */
-
-#define PPLX_VOCAB_SIZE 151936
-#define PPLX_HEAD_DIM 128
-#define PPLX_MAX_LAYERS 64 /* upper bound for stack arrays */
-#define PPLX_CONTEXT_SEPARATOR_TOKEN_ID 151643 /* <|endoftext|> */
-
-/* ========================================================================
- * Model Configuration (populated from config.json at load time)
- * ======================================================================== */
-
-typedef struct {
- 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 */
-} pplx_config_t;
-
-/* ========================================================================
- * Model + workspace ownership
- * ======================================================================== */
-
-typedef struct pplx_model pplx_model_t;
-typedef struct pplx_workspace pplx_workspace_t;
-typedef struct pplx_late_model pplx_late_model_t;
-typedef struct pplx_late_workspace pplx_late_workspace_t;
-
-typedef struct {
- const int *ids;
- int n_tokens;
-} pplx_input_t;
-
-typedef struct {
- int start;
- int n_tokens;
-} pplx_span_t;
-
-typedef struct {
- pplx_input_t input;
- const pplx_span_t *spans;
- int n_spans;
-} pplx_context_input_t;
-
-/* ========================================================================
- * API
- * ======================================================================== */
-
-/*
- * Load immutable model data from a directory containing:
- * config.json - model hyperparameters
- * model.safetensors (or sharded) - F32 or BF16 weights
- * vocab.json + merges.txt - BPE tokenizer
- *
- * Reads config.json to determine model size (0.6B vs 4B).
- * Returns NULL on error.
- */
-pplx_model_t *pplx_model_load(const char *model_dir);
-
-/*
- * Load one contiguous transformer layer range for distributed execution.
- *
- * layer_start is inclusive and layer_end is exclusive. A range beginning at
- * zero also loads the token embedding table. A range ending at n_layers also
- * loads the final RMSNorm. Safetensors remain mmap-backed, so unselected
- * weights are not touched.
- */
-pplx_model_t *pplx_model_load_slice(const char *model_dir,
- int layer_start, int layer_end);
-
-void pplx_model_free(pplx_model_t *model);
-
-/*
- * Allocate/free mutable scratch buffers for a model. The model must outlive
- * workspaces created from it.
- */
-pplx_workspace_t *pplx_workspace_new(const pplx_model_t *model);
-void pplx_workspace_free(pplx_workspace_t *ws);
-
-/* Config accessor for opaque model ownership. */
-const pplx_config_t *pplx_model_config(const pplx_model_t *model);
-
-/*
- * Current mutable workspace memory owned by this workspace, in bytes.
- *
- * This includes the workspace struct, scratch buffers, and RoPE cache capacity.
- * It does not include immutable mmap'd model weights.
- */
-size_t pplx_workspace_nbytes(const pplx_workspace_t *ws);
-
-/*
- * Compute embedding for a token sequence.
- *
- * 1. Token embedding lookup
- * 2. N transformer layers (bidirectional GQA + RoPE + SwiGLU)
- * 3. Final RMSNorm
- * 4. Mean pooling over all positions
- *
- * Perplexity embeddings are intentionally not L2-normalized. Use cosine
- * similarity for comparisons, or normalize explicitly before storing in vector
- * databases that only support inner product.
- *
- * Returns malloc'd float[hidden_size] (caller frees). NULL on error.
- */
-float *pplx_model_embed(const pplx_model_t *model, pplx_workspace_t *ws,
- const int *token_ids, int n_tokens);
-
-/*
- * Compute one embedding into caller-provided out[hidden_size].
- * Returns 0 on success, -1 on error.
- */
-int pplx_model_embed_into(const pplx_model_t *model, pplx_workspace_t *ws,
- const int *token_ids, int n_tokens,
- float *out_embedding);
-
-/*
- * Compute embeddings for a true packed/ragged batch.
- *
- * out_embeddings is caller-provided [batch, hidden_size].
- * Each sequence attends only to tokens from the same input, and RoPE
- * positions restart at zero for every input.
- *
- * Returns 0 on success, -1 on error.
- */
-int pplx_model_embed_batch(const pplx_model_t *model, pplx_workspace_t *ws,
- const pplx_input_t *inputs, int batch,
- float *out_embeddings);
-
-/*
- * Run a contiguous transformer layer range for a packed/ragged batch.
- *
- * layer_start is inclusive and layer_end is exclusive. For a range beginning
- * at layer 0, input_states must be NULL and every input must provide token
- * ids. For a later range, input_states must contain the preceding range's
- * packed [sum(n_tokens), hidden_size] output; token ids are not required.
- *
- * apply_final_norm is valid only for a range ending at the final transformer
- * layer. out_states receives packed [sum(n_tokens), hidden_size] states.
- *
- * This is the core execution boundary used by layer-sharded inference.
- */
-int pplx_model_forward_slice_batch(const pplx_model_t *model,
- pplx_workspace_t *ws,
- const pplx_input_t *inputs, int batch,
- const float *input_states,
- int layer_start, int layer_end,
- int apply_final_norm,
- float *out_states);
-
-/*
- * Mean-pool packed final hidden states for a ragged batch.
- *
- * states is [sum(n_tokens), hidden_size]. seq_lengths contains one positive
- * token count per sequence. The states must already include final RMSNorm.
- */
-int pplx_pool_batch(const pplx_config_t *cfg, const float *states,
- const int *seq_lengths, int batch,
- float *out_embeddings);
-
-/*
- * 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_model_forward(const pplx_model_t *model, pplx_workspace_t *ws,
- const int *token_ids, int n_tokens);
-
-/*
- * Run the transformer forward pass into caller-provided
- * out_states[n_tokens * hidden_size]. Returns 0 on success, -1 on error.
- */
-int pplx_model_forward_into(const pplx_model_t *model, pplx_workspace_t *ws,
- const int *token_ids, int n_tokens,
- float *out_states);
-
-/*
- * Pool embeddings from final hidden states.
- *
- * states is [n_tokens, hidden_size], normally produced by
- * pplx_model_forward_into(). Each span is mean pooled into
- * out_embeddings[n_spans, hidden_size] without L2 normalization.
- */
-int pplx_pool_spans(const pplx_config_t *cfg, const float *states, int n_tokens,
- const pplx_span_t *spans, int n_spans,
- float *out_embeddings);
-
-/*
- * Run one contextual sequence and pool selected token spans.
- * Returns 0 on success, -1 on error.
- */
-int pplx_model_embed_spans(const pplx_model_t *model, pplx_workspace_t *ws,
- const int *token_ids, int n_tokens,
- const pplx_span_t *spans, int n_spans,
- float *out_embeddings);
-
-/*
- * Run a packed/ragged contextual document batch and pool every selected span.
- *
- * Documents attend independently, RoPE positions restart for each document,
- * and out_embeddings contains spans in document order.
- */
-int pplx_model_embed_spans_batch(const pplx_model_t *model,
- pplx_workspace_t *ws,
- const pplx_context_input_t *inputs, int batch,
- float *out_embeddings);
-
-/*
- * L2-normalize vec[dim] in place.
- *
- * Returns 0 on success. Returns -1 for invalid arguments or a zero-length
- * vector, which cannot be normalized.
- */
-int pplx_l2_normalize(float *vec, int dim);
-
-/*
- * Cosine similarity between two vectors.
- * Returns 0 for invalid arguments or if either vector has zero length.
- */
-float pplx_cosine_similarity(const float *a, const float *b, int dim);
-
-/*
- * Late-interaction model API.
- *
- * A late model produces one 128D vector per retained token. The vectors are
- * projected by the snapshot's 1_Dense head and L2-normalized per token by
- * default, matching ColBERT/MaxSim scoring semantics.
- */
-pplx_late_model_t *pplx_late_model_load(const char *model_dir);
-void pplx_late_model_free(pplx_late_model_t *model);
-
-pplx_late_workspace_t *pplx_late_workspace_new(const pplx_late_model_t *model);
-void pplx_late_workspace_free(pplx_late_workspace_t *ws);
-
-const pplx_config_t *pplx_late_model_config(const pplx_late_model_t *model);
-int pplx_late_model_token_dim(const pplx_late_model_t *model);
-
-/*
- * Encode token_ids into out_vectors[n_tokens, token_dim].
- *
- * If normalize is non-zero, every non-zero token vector is L2-normalized.
- */
-int pplx_late_model_encode_tokens(const pplx_late_model_t *model,
- pplx_late_workspace_t *ws,
- const int *token_ids, int n_tokens,
- int normalize, float *out_vectors);
-
-/*
- * Sum over query tokens of max dot product against document tokens.
- */
-float pplx_late_maxsim(const float *query_vectors, int query_tokens,
- const float *doc_vectors, int doc_tokens,
- int dim);
-
-/*
- * Score one query against a packed/ragged batch of documents.
- *
- * doc_offsets has docs + 1 entries. Document i is stored in
- * doc_vectors[doc_offsets[i] * dim .. doc_offsets[i + 1] * dim).
- * scores is caller-provided [docs].
- */
-int pplx_late_maxsim_batch(const float *query_vectors, int query_tokens,
- const float *doc_vectors,
- const int *doc_offsets, int docs,
- int dim, float *scores);
-
-/* Verbose level: 0=quiet, 1=info, 2=debug */
-extern int pplx_verbose;
-extern int qwen_verbose;
-
-#endif /* PPLX_EMBED_H */