struct ScalarSub-byte kinds pack several dimensions per byte, as their
xN suffixes spell.
Conforms to
Hashable, Sendable, CustomStringConvertible, EquatableEvery verb runs one forward and keeps the surfaces outputs names, deciding which C output pointers the binding passes:
.embeddings, the default, lands one pooled row per item asRows;.stateslands the final-norm states, one row per token each item kept after truncation, asRowsTape;.tokenVectorslands the token head’s unit vectors,tokenWidthwide, on the same offsets as the states, and a model without a token head refuses it withunsupported;- naming none is refused with
invalidArgument.
let encoded = try model.textEncode(texts, outputs: [.embeddings, .states], arena: arena)
let pooled = encoded.embeddings! // pooled[i] is item i's row
let states = encoded.states! // states[i] is item i's rows, one per byte of its text
print(pooled.columns, pooled.stride, pooled.scalar, states[0].count, encoded.stats.truncated)The six verbs take one input form each:
try model.textEncode(["a caption"], arena: arena) // UTF-8, a byte per token
try model.imageEncode([jpeg, png], arena: arena) // JPEG, PNG or WebP files
try model.imageEncodePixels([rgb], heights: [480], widths: [640], arena: arena) // interleaved 8-bit RGB
try model.videoEncode([mp4], arena: arena) // MP4 or WebM files
try model.audioEncode([wav], arena: arena) // WAV, FLAC, MP3 or Opus
try model.audioEncodeSamples([samples], sampleRate: 16_000, arena: arena) // mono Float samplesEncodeConfig carries the rest: outputsScalar, f32 by default, and a progress handler with its progressSteps.
Rows of f32, bf16 and f16 read as Float, and withUnsafeBytes hands any scalar on as stored, such as to a USearch index.
let config = EncodeConfig(outputsScalar: .bf16, progress: { done, total in done < limit ? .continue : .cancel })
let narrow = try model.textEncode(texts, arena: arena, config: config)
narrow.embeddings!.withUnsafeBytes { bytes in index.add(bytes) }A handler never runs on two threads at once, but may run on whichever thread advanced the work, hence @Sendable; returning .cancel stops the call with cancelled.
API
StructScalarA scalar type a model computes in and its outputs land as, numbered as USearch numbers it, carrying the C enumerator.17
unknownNo scalar named - an unset field.
static let unknown: Scalarf64IEEE-754 binary64.
static let f64: Scalarf32IEEE-754 binary32.
static let f32: Scalarbf16The brain floating-point format.
static let bf16: Scalarf16IEEE-754 binary16.
static let f16: Scalare5m28-bit floating point with five exponent bits.
static let e5m2: Scalare4m38-bit floating point with four exponent bits.
static let e4m3: Scalare3m26-bit floating point with three exponent bits.
static let e3m2: Scalare2m36-bit floating point with two exponent bits.
static let e2m3: Scalari8An 8-bit signed integer.
static let i8: Scalari4x2Two 4-bit signed integers per byte.
static let i4x2: Scalari32A 32-bit signed integer.
static let i32: Scalaru8An 8-bit unsigned integer, the element of UTF-8 text and of encoded files.
static let u8: Scalaru4x2Two 4-bit unsigned integers per byte.
static let u4x2: Scalaru1x8Eight single-bit dimensions per byte.
static let u1x8: ScalardescriptionThe kind as the library spells it.
initReads a spelling back, and nil for one no kind carries.
StructRowsA run of rows a call wrote packed into its arena, one per item, read in place.7
struct RowsMirrors uform_rows_view_t.
Rows of f32, bf16 and f16 read as Float; withUnsafeBytes hands any scalar on as
stored, such as to a USearch index.
Conforms to
RandomAccessCollection, BidirectionalCollection, Collection, SequencestrideBytes between the starts of consecutive rows.
let stride: IntcolumnsValues per row, the model's embedding dimensions.
let columns: IntscalarThe scalar type the rows hold.
let scalar: ScalarendIndexOne past the last row.
let endIndex: IntstartIndexThe first row's position, which a collection walk starts from.
var startIndex: Int { get }subscriptOne row's values.
subscript(row: Int) -> Row { get }withUnsafeBytesLends the rows' bytes as stored to body, which must not keep the buffer past its return.
func withUnsafeBytes<Result, Failure>(
_ body: (UnsafeRawBufferPointer) throws(Failure) -> Result
) throws(Failure) -> Result where Failure : ErrorStructRows.RowOne row of an arena's values, read in place and widened to Float.3
struct RowConforms to
RandomAccessCollection, BidirectionalCollection, Collection, SequenceendIndexOne past the last value in the row.
let endIndex: IntstartIndexThe first value's position, which a collection walk starts from.
var startIndex: Int { get }subscriptThe value at a position, widened from the row's scalar.
subscript(position: Int) -> Float { get }StructRowsTapeA ragged run of rows a call wrote into its arena, as many per item as the item had tokens left after truncation, read in place.4
struct RowsTapeMirrors uform_rows_tape_view_t.
Conforms to
RandomAccessCollection, BidirectionalCollection, Collection, SequencerowsEvery item's rows, end to end.
let rows: RowsendIndexOne past the last item.
let endIndex: IntstartIndexThe first item's position, which a collection walk starts from.
var startIndex: Int { get }subscriptOne item's rows, one per token it kept.
subscript(item: Int) -> Rows { get }StructTapeA ragged run of f32 values a call wrote into its arena, as many per item as the item asked for, read in place.3
struct TapeMirrors uform_tape_view_t.
Conforms to
RandomAccessCollection, BidirectionalCollection, Collection, SequenceendIndexOne past the last item.
let endIndex: IntstartIndexThe first item's position, which a collection walk starts from.
var startIndex: Int { get }subscriptOne item's values.
subscript(item: Int) -> Rows.Row { get }StructOutputsThe surfaces an encode call keeps from its one forward, each deciding whether the binding passes the C output pointer of the same name; .embeddings alone by default.5
struct OutputsConforms to
OptionSet, Sendable, SetAlgebra, RawRepresentable, Equatable, ExpressibleByArrayLiteralrawValueThe bits, one per C output pointer the set passes.
let rawValue: UInt8initWraps bits, one per C output pointer.
init(rawValue: UInt8)embeddingsOne pooled embedding per item, read past the attention pool and the projection head.
static let embeddings: OutputsstatesThe final-norm states, one row per token each item kept after truncation.
static let states: OutputstokenVectorsThe token head's unit vectors, one row per token each item kept, its prefix included; a model without a token head reports unsupported.
static let tokenVectors: OutputsStructEncodeStatsWhat an encode call reports beside its outputs.2
struct EncodeStatsMirrors every uform_*_encode_stats_t.
Conforms to
Equatable, SendabletruncatedItems cut at the model's context.
var truncated: InttokensTokens the call encoded, after truncation: bytes of text, patches, tubes or frames.
var tokens: IntStructEncodeConfigThe knobs every encode verb takes beside its inputs, outputs and arena.4
struct EncodeConfigoutputsScalarThe scalar every output lands as.
var outputsScalar: ScalarprogressCalled with items encoded.
var progress: Progress?progressStepsReports the call makes at most, the last at completion; zero derives to ten.
var progressSteps: IntinitTakes every knob by name; a zero progressSteps derives ten.
init(outputsScalar: Scalar = .f32, progress: Progress? = nil, progressSteps: Int = 0)StructEncodedWhat one encode call wrote into its arena, read in place until the arena's next call.4
struct EncodedembeddingsOne row per item, or nil when outputs left the embeddings out.
let embeddings: Rows?statesOne run of rows per item, one row per token kept, or nil when outputs left the states out.
let states: RowsTape?tokenVectorsOne run of token-width rows per item, one row per token kept, or nil when outputs left them out.
let tokenVectors: RowsTape?statsWhat the call counted on the way.
let stats: EncodeStats