diff options
| author | Onur Gündüz <ogunduz@gmail.com> | 2026-06-10 08:24:39 +0200 |
|---|---|---|
| committer | Onur Gündüz <ogunduz@gmail.com> | 2026-06-14 08:27:03 +0200 |
| commit | 2c37727e653d2340d8977dd5db4addc767dd81ea (patch) | |
| tree | 578ad6affac511f847a346a0efc6d40ebf6a279f /pplx_embed.h | |
| parent | ec417bcb52f2aa8e24aeec312e8ddbf3a0798056 (diff) | |
| download | ffwd-2c37727e653d2340d8977dd5db4addc767dd81ea.tar.gz ffwd-2c37727e653d2340d8977dd5db4addc767dd81ea.zip | |
gitignore: track new binary and library names
Diffstat (limited to 'pplx_embed.h')
| -rw-r--r-- | pplx_embed.h | 293 |
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 */ |
