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
|
/*
* embed_mlx.h - MLX GPU backend for Apple Silicon
*
* Uses Apple's mlx-c to run the transformer on Metal.
*/
#ifndef EMBED_MLX_H
#define EMBED_MLX_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>
#include "embed.h"
/* Opaque MLX model context */
typedef struct embed_mlx_ctx embed_mlx_ctx_t;
typedef struct embed_mlx_late_ctx embed_mlx_late_ctx_t;
typedef struct embed_mlx_late_vectors embed_mlx_late_vectors_t;
typedef struct {
int quantize_bits; /* 0 disables; currently 8 */
int quantize_group_size; /* default 64 when quantize_bits is set */
} embed_mlx_options_t;
/*
* Load model into MLX arrays from safetensors + config.json.
* Returns NULL on error.
*/
EMBED_API embed_mlx_ctx_t *embed_mlx_load(const char *model_dir);
EMBED_API embed_mlx_ctx_t *embed_mlx_load_with_options(const char *model_dir,
const embed_mlx_options_t *opts);
EMBED_API void embed_mlx_free(embed_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.
*/
EMBED_API embed_mlx_late_ctx_t *embed_mlx_late_load(const char *model_dir);
EMBED_API embed_mlx_late_ctx_t *embed_mlx_late_load_with_options(
const char *model_dir, const embed_mlx_options_t *opts);
EMBED_API void embed_mlx_late_free(embed_mlx_late_ctx_t *ctx);
EMBED_API const embed_config_t *embed_mlx_late_config(const embed_mlx_late_ctx_t *ctx);
EMBED_API int embed_mlx_late_token_dim(const embed_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.
*/
EMBED_API int embed_mlx_late_encode_tokens(embed_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.
*/
EMBED_API embed_mlx_late_vectors_t *embed_mlx_late_encode_tokens_device(
embed_mlx_late_ctx_t *ctx, const int *token_ids, int n_tokens,
int normalize);
EMBED_API void embed_mlx_late_vectors_free(embed_mlx_late_vectors_t *vecs);
EMBED_API int embed_mlx_late_vectors_token_count(const embed_mlx_late_vectors_t *vecs);
EMBED_API int embed_mlx_late_vectors_dim(const embed_mlx_late_vectors_t *vecs);
EMBED_API int embed_mlx_late_vectors_copy(const embed_mlx_late_vectors_t *vecs,
float *out_vectors);
EMBED_API embed_mlx_late_vectors_t *embed_mlx_late_vectors_concat(
embed_mlx_late_ctx_t *ctx,
const embed_mlx_late_vectors_t *const *items, int count);
EMBED_API embed_mlx_late_vectors_t *embed_mlx_late_vectors_select(
embed_mlx_late_ctx_t *ctx, const embed_mlx_late_vectors_t *vecs,
const int *token_indices, int count);
EMBED_API int embed_mlx_late_maxsim_batch_device(
embed_mlx_late_ctx_t *ctx, const embed_mlx_late_vectors_t *query,
const embed_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.
*/
EMBED_API float *embed_mlx_encode(embed_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.
*/
EMBED_API int embed_mlx_encode_into(embed_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].
* Pooling and attention masking follow the loaded model configuration.
* Returns 0 on success, -1 on error.
*/
EMBED_API int embed_mlx_encode_batch(embed_mlx_ctx_t *ctx, const embed_input_t *inputs,
int batch, float *out_embeddings);
/*
* Run one contextual sequence and pool selected token spans.
* Returns 0 on success, -1 on error.
*/
EMBED_API int embed_mlx_encode_spans(embed_mlx_ctx_t *ctx, const int *token_ids,
int n_tokens, const embed_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.
*/
EMBED_API int embed_mlx_encode_spans_batch(embed_mlx_ctx_t *ctx,
const embed_context_input_t *inputs, int batch,
float *out_embeddings);
/* Get the config (so embed_cli.c can read hidden_size etc.) */
EMBED_API const embed_config_t *embed_mlx_config(const embed_mlx_ctx_t *ctx);
#endif /* EMBED_MLX_H */
|