Interface TextEmbedder

All Superinterfaces:
AutoCloseable, Closeable

public interface TextEmbedder extends Closeable
Encodes text into a fixed-length vector.

Unlike WordVectorTable, which looks up a stored vector for one word, this interface accepts a sentence, paragraph, or document.

Implementations must be safe for concurrent use of embed(CharSequence), embedAll(List) and dimension() until close() is called. They may serialize calls internally: the guarantee is correctness, not parallelism.

Every returned array is new and owned by the caller. Vectors are not necessarily of unit length unless the implementation documents it. Text longer than the implementation accepts is either truncated or rejected with an IllegalArgumentException; each implementation documents which.

Since:
3.0.0
See Also:
  • Method Summary

    Modifier and Type
    Method
    Description
    default void
    Releases resources owned by this embedder.
    int
    Returns the dimension of every vector this embedder produces.
    float[]
    Embeds a piece of text.
    default float[][]
    embedAll(List<? extends CharSequence> texts)
    Embeds several texts.
  • Method Details

    • embed

      float[] embed(CharSequence text)
      Embeds a piece of text.

      Behavior for empty text, or text with no tokens the embedder recognizes, is implementation-defined: an implementation may return a zero vector, the vector of a special or fallback token, or something else, and should document its choice. Callers that need a uniform response should handle it themselves.

      Parameters:
      text - The text to embed. Must not be null.
      Returns:
      The embedding vector, of length dimension().
      Throws:
      IllegalArgumentException - Thrown if text is null.
      EmbeddingException - Thrown if the text could not be embedded.
      IllegalStateException - Thrown if this embedder is closed.
    • embedAll

      default float[][] embedAll(List<? extends CharSequence> texts)
      Embeds several texts. All texts are checked before any of them is embedded. The implementation forms its own batches, so callers may pass a list of any size.

      The default implementation embeds one text at a time. Implementations backed by a runtime that executes batches more efficiently than single inputs should override this method.

      Parameters:
      texts - The texts to embed. Must not be null and must not contain null.
      Returns:
      One embedding vector per input, in input order.
      Throws:
      IllegalArgumentException - Thrown if texts is null or contains null.
      EmbeddingException - Thrown if the texts could not be embedded.
      IllegalStateException - Thrown if this embedder is closed.
    • dimension

      int dimension()
      Returns the dimension of every vector this embedder produces. The value is constant and never requires an inference.
      Returns:
      the dimension of every vector this embedder produces
    • close

      default void close() throws IOException
      Releases resources owned by this embedder. Calling it more than once has no further effect. The default implementation does nothing. Callers must not race this method with embedding calls.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Throws:
      IOException - Thrown if releasing backend resources fails.