aboutsummaryrefslogtreecommitdiff
path: root/embed.h
diff options
context:
space:
mode:
authorOnur Gündüz <ogunduz@gmail.com>2026-06-16 16:27:47 +0200
committerOnur Gündüz <ogunduz@gmail.com>2026-06-16 16:27:47 +0200
commitd1ba1ebc06ef0d62ca932388fae83e6992594719 (patch)
treef962207b779016593258f990348216999a58766a /embed.h
parentbe20dfda0f836808dccfc14db244592e41ba28bc (diff)
downloadffwd-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.h356
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 */