diff options
| author | Onur Gündüz <ogunduz@gmail.com> | 2026-06-16 16:27:47 +0200 |
|---|---|---|
| committer | Onur Gündüz <ogunduz@gmail.com> | 2026-06-16 16:27:47 +0200 |
| commit | d1ba1ebc06ef0d62ca932388fae83e6992594719 (patch) | |
| tree | f962207b779016593258f990348216999a58766a /embed.h | |
| parent | be20dfda0f836808dccfc14db244592e41ba28bc (diff) | |
| download | ffwd-d1ba1ebc06ef0d62ca932388fae83e6992594719.tar.gz ffwd-d1ba1ebc06ef0d62ca932388fae83e6992594719.zip | |
chore: move sources to src/ with proper names, drop qwen_ prefix
Diffstat (limited to 'embed.h')
| -rw-r--r-- | embed.h | 356 |
1 files changed, 0 insertions, 356 deletions
diff --git a/embed.h b/embed.h deleted file mode 100644 index c7381bd..0000000 --- a/embed.h +++ /dev/null @@ -1,356 +0,0 @@ -/* - * embed.h - embed API - */ - -#ifndef EMBED_H -#define EMBED_H - -/* Public-API export annotation. The libraries are built with - * -fvisibility=hidden, so only declarations carrying EMBED_API are exported - * from the shared library; everything else stays internal. */ -#ifndef EMBED_API -#if defined(__GNUC__) -#define EMBED_API __attribute__((visibility("default"))) -#else -#define EMBED_API -#endif -#endif - -#include <stddef.h> -#include <stdint.h> - -/* ======================================================================== - * Shared constants and family defaults - * ======================================================================== */ - -#define EMBED_VOCAB_SIZE 151936 -#define EMBED_HEAD_DIM 128 -#define EMBED_MAX_LAYERS 64 /* upper bound for stack arrays */ -#define EMBED_CONTEXT_SEPARATOR_TOKEN_ID 151643 /* <|endoftext|> */ - -/* ======================================================================== - * Model Configuration (populated from config.json at load time) - * ======================================================================== */ - -typedef enum { - EMBED_ATTENTION_BIDIRECTIONAL = 0, - EMBED_ATTENTION_CAUSAL = 1, -} embed_attention_mode_t; - -typedef enum { - EMBED_POOL_MEAN = 0, - EMBED_POOL_LAST_TOKEN = 1, - EMBED_POOL_CLS = 2, /* first token; the encoder-family [CLS] sentence vector */ -} embed_pooling_mode_t; - -typedef enum { - EMBED_FAMILY_QWEN3 = 0, /* RMSNorm + RoPE + SwiGLU decoder block (pplx, Qwen2/3) */ - EMBED_FAMILY_BERT = 1, /* LayerNorm + learned positions + GeLU encoder block */ -} embed_family_t; - -/* BERT feed-forward activation. The released MiniLM/BGE encoders use exact erf - * GeLU; some encoders publish the tanh approximation (hidden_act gelu_new or - * gelu_pytorch_tanh), which is a different curve and must be matched exactly. */ -typedef enum { - EMBED_ACT_GELU_ERF = 0, /* 0.5 x (1 + erf(x / sqrt(2))) */ - EMBED_ACT_GELU_TANH = 1, /* 0.5 x (1 + tanh(sqrt(2/pi) (x + 0.044715 x^3))) */ -} embed_act_t; - -typedef struct { - embed_family_t family; - embed_act_t ffn_act; /* BERT feed-forward GeLU variant; ERF for Qwen/SwiGLU */ - int hidden_size; - int n_layers; - int n_heads; - int n_kv_heads; - int head_dim; - int q_dim; /* n_heads * head_dim */ - int kv_dim; /* n_kv_heads * head_dim */ - int intermediate_size; - int vocab_size; - int max_position_embeddings; /* BERT learned position table size */ - float rms_norm_eps; - float layer_norm_eps; /* BERT LayerNorm epsilon */ - float rope_theta; - int qk_norm; - int qkv_bias; - embed_attention_mode_t attention_mode; - embed_pooling_mode_t pooling_mode; - int normalize_embeddings; - /* Qwen3-Embedding pools the last token, which is the tokenizer's - * <|endoftext|> suffix added by its post-processor - not the model's chat - * eos_token_id (<|im_end|>). Text frontends append it and resolve the id - * from the tokenizer exactly like the contextual separator - * (EMBED_CONTEXT_SEPARATOR_TOKEN_ID is the released-model fallback). The - * model forward consumes token ids exactly and never appends. */ - int append_terminal_token; -} embed_config_t; - -/* ======================================================================== - * Model + workspace ownership - * ======================================================================== */ - -typedef struct embed_model embed_model_t; -typedef struct embed_workspace embed_workspace_t; -typedef struct embed_late_model embed_late_model_t; -typedef struct embed_late_workspace embed_late_workspace_t; - -typedef struct { - const int *ids; - int n_tokens; -} embed_input_t; - -typedef struct { - int start; - int n_tokens; -} embed_span_t; - -typedef struct { - embed_input_t input; - const embed_span_t *spans; - int n_spans; -} embed_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. - */ -EMBED_API embed_model_t *embed_model_load(const char *model_dir); - -EMBED_API void embed_model_free(embed_model_t *model); - -/* - * Allocate/free mutable scratch buffers for a model. The model must outlive - * workspaces created from it. - */ -EMBED_API embed_workspace_t *embed_workspace_new(const embed_model_t *model); -EMBED_API void embed_workspace_free(embed_workspace_t *ws); - -/* Config accessor for opaque model ownership. */ -EMBED_API const embed_config_t *embed_model_config(const embed_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. - */ -EMBED_API size_t embed_workspace_nbytes(const embed_workspace_t *ws); - -/* - * Compute embedding for a token sequence. - * - * 1. Token embedding lookup - * 2. N transformer layers (GQA + RoPE + SwiGLU) - * 3. Final RMSNorm - * 4. Model-defined pooling and optional L2 normalization - * - * pplx-embed-v1 uses bidirectional attention and unnormalized mean pooling. - * Qwen3-Embedding uses causal attention and normalized last-token pooling. - * Token IDs are consumed exactly as provided; text frontends append any - * model-required terminal token before calling this API. - * - * Returns malloc'd float[hidden_size] (caller frees). NULL on error. - */ -EMBED_API float *embed_model_encode(const embed_model_t *model, - embed_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. - */ -EMBED_API int embed_model_encode_into(const embed_model_t *model, - embed_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. - */ -EMBED_API int embed_model_encode_batch(const embed_model_t *model, - embed_workspace_t *ws, - const embed_input_t *inputs, - int batch, - float *out_embeddings); - -/* - * Apply the config's pooling mode to packed final hidden states. - * - * states is [sum(n_tokens), hidden_size]. seq_lengths contains one positive - * token count per sequence. The states must already include final RMSNorm. - */ -EMBED_API int embed_pool_batch(const embed_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. - */ -EMBED_API float *embed_model_forward(const embed_model_t *model, - embed_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. - */ -EMBED_API int embed_model_forward_into(const embed_model_t *model, - embed_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 - * embed_model_forward_into(). Each span is mean pooled into - * out_embeddings[n_spans, hidden_size] without L2 normalization. - */ -EMBED_API int embed_pool_spans(const embed_config_t *cfg, - const float *states, - int n_tokens, - const embed_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. - */ -EMBED_API int embed_model_encode_spans(const embed_model_t *model, - embed_workspace_t *ws, - const int *token_ids, - int n_tokens, - const embed_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. - */ -EMBED_API int embed_model_encode_spans_batch(const embed_model_t *model, - embed_workspace_t *ws, - const embed_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. - */ -EMBED_API int embed_l2_normalize(float *vec, int dim); - -/* - * Cosine similarity between two vectors. - * Returns 0 for invalid arguments or if either vector has zero length. - */ -EMBED_API float embed_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. - */ -EMBED_API embed_late_model_t *embed_late_model_load(const char *model_dir); -EMBED_API void embed_late_model_free(embed_late_model_t *model); - -EMBED_API embed_late_workspace_t *embed_late_workspace_new(const embed_late_model_t *model); -EMBED_API void embed_late_workspace_free(embed_late_workspace_t *ws); - -EMBED_API const embed_config_t *embed_late_model_config(const embed_late_model_t *model); -EMBED_API int embed_late_model_token_dim(const embed_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. - */ -EMBED_API int embed_late_model_encode_tokens(const embed_late_model_t *model, - embed_late_workspace_t *ws, - const int *token_ids, - int n_tokens, - int normalize, - float *out_vectors); - -/* - * Encode n_docs documents in one block-diagonal forward and pack each - * document's kept token vectors back-to-back into out_vectors[total_keep, - * token_dim] in document order, where total_keep is the sum of n_keep. - * out_offsets[n_docs + 1] receives the prefix sum of kept counts, the layout - * embed_late_maxsim_batch consumes. keep[d] lists the n_keep[d] token indices to - * retain from document d. Returns 0 on success, -1 on error. - */ -EMBED_API int embed_late_model_encode_docs(const embed_late_model_t *model, - embed_late_workspace_t *ws, - const int *const *doc_ids, - const int *n_tokens, - const int *const *keep, - const int *n_keep, - int n_docs, - int normalize, - float *out_vectors, - int *out_offsets); - -/* - * Sum over query tokens of max dot product against document tokens. - */ -EMBED_API float embed_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]. - */ -EMBED_API int embed_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 */ -EMBED_API extern int embed_verbose; -EMBED_API extern int qwen_verbose; - -#endif /* EMBED_H */ |
