Text Resolver `≥0.1.0`¶

The text resolver generates a semantic embedding from free-form text using a GGUF language model via llama.cpp. This is useful for fields such as descriptions, titles, or any natural language content.

How It Works¶

When an aspect using the text resolver is first created, Aspected loads the specified GGUF model from disk. The input text is tokenised and passed through the model to produce a dense embedding vector. The model is shared across all aspects that reference the same model file.

The output is a many-dimensional vector, scaled by an optional multiplier.

Settings¶

Setting	Type	Default	Description
`model`	string	`nomic-embed-text-v1.5.f16.gguf`	Filename of the GGUF model to use (must exist in the models directory).
`truncate (≥0.4.0)`	int	`0`	Truncation to apply, `>0` to keep dimensions, `<0` to remove dimensions.

Embedding Size¶

The base number of dimensions is determined by the model. For example:

Model	Dimensions
`nomic-embed-text-v1.5.f16.gguf`	768
`Qwen3-Embedding-0.6B-f16.gguf`	1024

Some models, like the two above, are trained using Matryoshka Representation Learning (MRL). This method arranges the embedding so that the most important information is at the start of the vector, making it possible to safely keep only the first N dimensions without sacrificing all semantic meaning. This can be useful to save space, speed up search, or match another system.

For version ≥0.4.0, the truncate setting enables you to take advantage of this:

If truncate is positive, only the first N dimensions are kept from the embedding.
If truncate is negative, the last N dimensions are removed from the embedding.
If truncate is 0 (default), the full embedding is used.

Note

Not all models support MRL. Only apply truncation if your model supports Matryoshka (or similar) training. If unsure, refer to your model's documentation.

Downloading Models¶

Aspected does not ship with embedding models included. You must download GGUF model files from Hugging Face and make them available to the server.

To download the default models, run:

mkdir -p models
wget -O models/nomic-embed-text-v1.5.f16.gguf \
  https://huggingface.co/nomic-ai/nomic-embed-text-v1.5-GGUF/resolve/main/nomic-embed-text-v1.5.f16.gguf
wget -O models/Qwen3-Embedding-0.6B-f16.gguf \
  https://huggingface.co/Qwen/Qwen3-Embedding-0.6B-GGUF/resolve/main/Qwen3-Embedding-0.6B-f16.gguf

This downloads two models into the models/ directory:

Model	Source
`nomic-embed-text-v1.5.f16.gguf`	nomic-ai/nomic-embed-text-v1.5-GGUF
`Qwen3-Embedding-0.6B-f16.gguf`	Qwen/Qwen3-Embedding-0.6B-GGUF

You can also download any other GGUF embedding model and place it in the models directory. The model must support generating embeddings (encoder-only or decoder-only with embedding support); encoder-decoder models are not supported.

Making Models Available in Docker¶

When running Aspected via Docker, mount the models directory into the container:

docker run -p 8080:8080 \
  -v $(pwd)/models:/app/models \
  xillio/aspected:latest

The default models path inside the container is ./models. You can change this with the llama.modelsPath configuration option (see Configuration).

Using a Custom Model¶

To use a different GGUF model, download it and reference it by filename in the aspect settings:

{
  "name": "description",
  "type": "text",
  "path": "$.description",
  "settings": {
    "model": "my-custom-model.gguf"
  }
}

Make sure the model file is present in the configured models directory before creating the index.

Example¶

{
  "name": "description",
  "type": "text",
  "path": "$.description",
  "settings": {
    "model": "nomic-embed-text-v1.5.f16.gguf"
  },
  "multiplier": 1.0
}

Text Resolver ≥0.1.0¶