aboutsummaryrefslogtreecommitdiff
path: root/embed_mlx.h
blob: 52a88017a1eae76084101f5b40ff69cb7cd894f1 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
/*
 * embed_mlx.h - MLX GPU backend for pplx-embed inference
 *
 * Uses Apple's mlx-c to run the transformer on Metal.
 */

#ifndef PPLX_EMBED_MLX_H
#define PPLX_EMBED_MLX_H

/* Public-API export annotation. The libraries are built with
 * -fvisibility=hidden, so only declarations carrying PPLX_API are exported
 * from the shared library; everything else stays internal. */
#ifndef PPLX_API
#if defined(__GNUC__)
#define PPLX_API __attribute__((visibility("default")))
#else
#define PPLX_API
#endif
#endif

#include <stddef.h>
#include <stdint.h>
#include "embed.h"

/* Opaque MLX model context */
typedef struct pplx_mlx_ctx pplx_mlx_ctx_t;
typedef struct pplx_mlx_late_ctx pplx_mlx_late_ctx_t;
typedef struct pplx_mlx_late_vectors pplx_mlx_late_vectors_t;

typedef struct {
    int quantize_bits;       /* 0 disables; currently 8 */
    int quantize_group_size; /* default 64 when quantize_bits is set */
} pplx_mlx_options_t;

/*
 * Load model into MLX arrays from safetensors + config.json.
 * Returns NULL on error.
 */
PPLX_API pplx_mlx_ctx_t *pplx_mlx_load(const char *model_dir);
PPLX_API pplx_mlx_ctx_t *pplx_mlx_load_with_options(const char *model_dir,
                                           const pplx_mlx_options_t *opts);

/*
 * Load one contiguous transformer layer range for distributed execution.
 * Uses the same half-open range and endpoint ownership rules as
 * pplx_model_load_slice().
 */
PPLX_API pplx_mlx_ctx_t *pplx_mlx_load_slice(const char *model_dir,
                                    int layer_start, int layer_end);
PPLX_API pplx_mlx_ctx_t *pplx_mlx_load_slice_with_options(
    const char *model_dir, int layer_start, int layer_end,
    const pplx_mlx_options_t *opts);

PPLX_API void pplx_mlx_free(pplx_mlx_ctx_t *ctx);

/*
 * Late-interaction MLX path. This is separate from pooled embeddings because
 * late snapshots produce one projected token vector per input token for MaxSim
 * scoring, not one pooled document vector.
 */
PPLX_API pplx_mlx_late_ctx_t *pplx_mlx_late_load(const char *model_dir);
PPLX_API pplx_mlx_late_ctx_t *pplx_mlx_late_load_with_options(
    const char *model_dir, const pplx_mlx_options_t *opts);
PPLX_API void pplx_mlx_late_free(pplx_mlx_late_ctx_t *ctx);

PPLX_API const pplx_config_t *pplx_mlx_late_config(const pplx_mlx_late_ctx_t *ctx);
PPLX_API int pplx_mlx_late_token_dim(const pplx_mlx_late_ctx_t *ctx);

/*
 * Encode token_ids into out_vectors[n_tokens, token_dim].
 *
 * If normalize is non-zero, every token vector is L2-normalized on device
 * before copying back to CPU memory.
 */
PPLX_API int pplx_mlx_late_encode_tokens(pplx_mlx_late_ctx_t *ctx,
                                const int *token_ids, int n_tokens,
                                int normalize, float *out_vectors);

/*
 * Device-resident late-interaction token vectors.
 *
 * The model context owns the MLX stream; the returned vector handle must not
 * outlive ctx. Copying is optional: MaxSim can consume these handles directly
 * and copy back only final candidate scores.
 */
PPLX_API pplx_mlx_late_vectors_t *pplx_mlx_late_encode_tokens_device(
    pplx_mlx_late_ctx_t *ctx, const int *token_ids, int n_tokens,
    int normalize);
PPLX_API void pplx_mlx_late_vectors_free(pplx_mlx_late_vectors_t *vecs);
PPLX_API int pplx_mlx_late_vectors_token_count(const pplx_mlx_late_vectors_t *vecs);
PPLX_API int pplx_mlx_late_vectors_dim(const pplx_mlx_late_vectors_t *vecs);
PPLX_API int pplx_mlx_late_vectors_copy(const pplx_mlx_late_vectors_t *vecs,
                               float *out_vectors);
PPLX_API pplx_mlx_late_vectors_t *pplx_mlx_late_vectors_concat(
    pplx_mlx_late_ctx_t *ctx,
    const pplx_mlx_late_vectors_t *const *items, int count);
PPLX_API pplx_mlx_late_vectors_t *pplx_mlx_late_vectors_select(
    pplx_mlx_late_ctx_t *ctx, const pplx_mlx_late_vectors_t *vecs,
    const int *token_indices, int count);
PPLX_API int pplx_mlx_late_maxsim_batch_device(
    pplx_mlx_late_ctx_t *ctx, const pplx_mlx_late_vectors_t *query,
    const pplx_mlx_late_vectors_t *docs, const int *doc_offsets,
    int docs_count, float *scores);

/*
 * Compute embedding for token_ids[0..n_tokens-1].
 * Returns malloc'd float[hidden_size] (caller frees). NULL on error.
 */
PPLX_API float *pplx_mlx_embed(pplx_mlx_ctx_t *ctx, const int *token_ids, int n_tokens);

/*
 * Compute one embedding into caller-provided out[hidden_size].
 * Returns 0 on success, -1 on error.
 */
PPLX_API int pplx_mlx_embed_into(pplx_mlx_ctx_t *ctx, const int *token_ids,
                        int n_tokens, float *out_embedding);

/*
 * Compute a true padded dense batch on MLX.
 *
 * out_embeddings is caller-provided [batch, hidden_size].
 * Padded tokens are masked out of attention keys and mean pooling.
 * Returns 0 on success, -1 on error.
 */
PPLX_API int pplx_mlx_embed_batch(pplx_mlx_ctx_t *ctx, const pplx_input_t *inputs,
                         int batch, float *out_embeddings);

/*
 * MLX equivalent of pplx_model_forward_slice_batch().
 *
 * Hidden states cross the API boundary as packed float32 rows even though MLX
 * executes a padded dense batch internally.
 */
PPLX_API int pplx_mlx_forward_slice_batch(pplx_mlx_ctx_t *ctx,
                                 const pplx_input_t *inputs, int batch,
                                 const float *input_states,
                                 int layer_start, int layer_end,
                                 int apply_final_norm,
                                 float *out_states);

/*
 * Run one contextual sequence and pool selected token spans.
 * Returns 0 on success, -1 on error.
 */
PPLX_API int pplx_mlx_embed_spans(pplx_mlx_ctx_t *ctx, const int *token_ids,
                         int n_tokens, const pplx_span_t *spans,
                         int n_spans, float *out_embeddings);

/*
 * Run a padded dense contextual document batch and pool every selected span.
 * out_embeddings contains spans in document order.
 */
PPLX_API int pplx_mlx_embed_spans_batch(pplx_mlx_ctx_t *ctx,
                               const pplx_context_input_t *inputs, int batch,
                               float *out_embeddings);

/* Get the config (so embed_cli.c can read hidden_size etc.) */
PPLX_API const pplx_config_t *pplx_mlx_config(const pplx_mlx_ctx_t *ctx);

#endif /* PPLX_EMBED_MLX_H */