Text Resolver¶

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.

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).
`multiplier`	number	`1.0`	Scaling factor applied to the embedding. Increase to give this aspect more weight.

Embedding Size¶

The 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

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.

A convenience script is included in the repository:

cd utility
bash download-huggingface-models.sh

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 \
  aspected:latest

The default models path inside the container is ./models. You can change this with the llama.models_path 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
  }
}