Introduction

Welcome to the documentation for AI Semantic Search.

Finding assets by exact filename falls apart the moment a project outgrows its naming convention. AI Semantic Search fixes that: it indexes your prefabs with local semantic embeddings and lets you search by meaning — "heavy axe", "small green plant", "loud explosion" — instead of guessing names.

Key Features

Everything runs locally in the Unity Editor (Windows and macOS). Let's get started!

AI Semantic Search — Documentation

Welcome to AI Semantic Search, a local, AI-powered asset finder for the Unity Editor.
It indexes prefabs with semantic embeddings (Unity Sentis) and lets you
search them by meaning — "heavy axe", "small green plant" — instead
of exact filenames.

What's inside the package

Item Purpose
Editor tool Window > SnivelerCode > Semantic Search (window title Asset AI Search)
Search engine SIMD-accelerated cosine similarity over the local SQLite index
Prefab analysis names, components, folder/category context, materials, geometry
Samples Base AI Model & Demo Assets — MiniLM ONNX model, BERT tokenizer config, medieval demo prefabs

Everything runs locally — no API keys, no internet connection required.

Getting started in 60 seconds

  1. Install the package (Assets → Import Package → Custom Package… with the .unitypackage
    from the store listing).
  2. Import the sample: Package Manager → AI Semantic Search → Samples → Import.
  3. Open the tool: Window > SnivelerCode > Semantic Search.
  4. In the Embedding tab assign:
    • Model ← MiniLM_uint8.sentis
    • Vocab ← tokenizer.json
  5. In the Prefabs tab: Check → Index.
  6. Go to Search and describe what you need.

See Getting Started for the full walkthrough.

Documentation contents

Requirements

Getting Started

This guide walks you from a fresh project to your first semantic search.

1. Install the package

  1. In the Editor open Assets → Import Package → Custom Package….
  2. Select the AI Semantic Search.unitypackage file (from the store listing) and click
    Import. The com.unity.ai.inference (Sentis) dependency installs automatically.

2. Locate the sample assets

The sample (model, tokenizer config and demo prefabs) ships inside the package file, so
it is already in your project after step 1. If you imported a build without the sample, use
Package Manager → AI Semantic Search → Samples → Base AI Model & Demo Assets → Import.

The files you need:

3. Open the tool

Window → SnivelerCode → Semantic Search (window title: Asset AI Search).

The window has three tabs: Search, Embedding, Prefabs, and a
status bar at the bottom showing progress and messages.

4. Set up the model

In the Embedding tab:

  1. Model — drag MiniLM_uint8.sentis into the field.
  2. Vocab — drag tokenizer.json into the field.

    ⚠ This must be the JSON tokenizer config. Plain vocabulary files (e.g. vocab.txt
    published by some model repositories) do not work — the tool reads the JSON config,
    which already contains the complete vocabulary.

  3. Leave Tokens = 128 and Backend = GPU. If your GPU has no compute shader
    support, switch Backend to CPU.

The status bar confirms the model is ready and the Search button becomes enabled.

5. Index your assets

Prefabs tab:

  1. Check — scans the project for new/modified prefabs.
  2. Index — runs the model over them and saves vectors to the local database.

Tip: you can toggle individual metadata extractors (name/context/components/…) in the
Prefabs tab settings panel before indexing.

6. Search

Open the Search tab, type e.g. heavy axe and press Search.
Results appear grouped by type, sorted by similarity score.

Adjust the Sensitivity slider if you get too many or too few results (default 25 is loose;
raise it for stricter matches).

That's it — you are now searching assets by meaning, fully offline.

Searching Assets

How a search works

  1. Your query is embedded with the same model used for indexing.
  2. Every indexed asset gets a similarity score — cosine similarity between the query
    vector and the asset's vector, computed with SIMD acceleration.
  3. A small text-match bonus is added when the raw query text appears in the asset's
    metadata.
  4. Assets above the Sensitivity threshold are returned, sorted by score.

What affects relevance

The quality of results depends on the metadata collected during indexing:

Prefabs

Signal Example
Name Axe_Bronze → "axe", "bronze"
Components Light, VFX, Rigidbody, colliders → "lamp", "physical", "interactive"
Context folder path & category keyword DBs → "workshop", "weapons", "furniture"
Materials material names/keys → "wood", "metal", "cloth"
Geometry mesh complexity hints (if the extractor is enabled)

Tips for better results

Result interactions

Configuration

This page explains every setting in the tool and how the database lifecycle works.

Embedding tab — model setup

Setting Default Description
Model — The embedding model (.sentis or .onnx). Any BERT-like model with input_ids / attention_mask inputs works; MiniLM_uint8.sentis from the samples is recommended.
Vocab — The BERT tokenizer configuration, provided as JSON (tokenizer.json). The tokenizer is built from this config.
Tokens (max length) 128 Maximum sequence length (range 128–512). 128 is enough for names; raise for deep folder paths or long descriptions.
Backend GPU Sentis compute backend. Use CPU when the GPU lacks compute shader support.

When you assign a model, it is loaded and validated immediately — an unsupported model
shows an error in the status bar instead of crashing.

Where things live in the window

The window has three tabs — Search, Embedding, Prefabs — and a status bar.

Search tab — sensitivity

Sensitivity (default 25) is the minimum similarity score, in percent, for a result.
Higher values are stricter (fewer, more precise matches); lower values allow broader
associations.

Where the data lives

Data Location
Index + settings Library/SnivelerCode_SemanticIndex.db (project-local, gitignored)
Category keyword DBs inside the package: Editor/Transformers/Local/Prefabs/Database/*.json

Resetting the index

The database is stored in Library/. Cleaning Library/ deletes it; the tool then starts
empty — re-run Check → Index after that. To rebuild categories only, use the
Bake action in the Prefabs tab settings (they rebuild automatically when missing).

Extensibility

This package is architectured around small, composable pieces. You can extend it without
modifying the core modules.

Architecture overview

EditorWindow (SemanticSearchEditor)
 └─ MiniContainer (constructor-injection DI)
     ├─ IEmbeddingModule   — model + tokenizer + Worker (Sentis)
     ├─ PrefabsModule      — Check/Index UI, result view, LocalTransformer
     └─ SearchModule       — query embedding + SIMD scoring over the index

Adding a metadata extractor (prefabs example)

  1. Create a class in Editor/Transformers/Local/Prefabs/Metadata/:

    public sealed class MyMetadata : Metadata<GameObject>
{
    public override string Name => "My Rule";
    public override string Info => "Adds custom semantic hints.";
    public MyMetadata(IMetadataFacade facade) : base(facade) { }

    public override async Task<IMetadataResult> ProcessAsync(GameObject asset)
    {
        // ... analyze the GameObject ...
        return IMetadataResult.FromArray(new[] { "custom hint" });
    }
}

  2. Register it in LocalMetadataProcessor (constructor array):

    _extractors = new Metadata<GameObject>[]
{
    container.Create<IdentityMetadata>(),
    // ...existing extractors...
    container.Create<MyMetadata>(),   // ← new
};

  3. Use _metadata.GetVectorsAsync(MetadataWord[]) for similarity against the category
    databases, and return a semantic description. The extractor automatically appears in
    the Prefabs tab settings (extractor toggles).

Adding a new asset kind

  1. Add a value to AssetStorageType.
  2. Write a Transformer<YourAssetType> that collects metadata and persists vectors
    (model it on LocalTransformer: CollectMetadata + ProcessAssets).
  3. Add a module/tab modeled on PrefabsModule (Check/Index + Bind<YourResultView>()
    where the result view extends SearchResultView).

Working with the category databases

Category keyword databases (Editor/Transformers/Local/Prefabs/Database/*.json)
define semantic axes: { "categories": [ { "id", "parent?", "keys", "values", "examples?" } ] }.
Each category is embedded and matched during indexing. The category databases are
validated by tests (unique ids across all databases, Detailed.parent resolves to a
General id, no self-parent, no category pair sharing ≥3 keys, minimum coverage). The optional examples field
enriches the category embedding with your project's typical prefab names — for
example "examples": ["P_Weapon_Axe_LOD0", "Axe_Heavy"]. Use your own nomenclature:
shipped databases ship without examples so the search stays generic and portable
across projects. The Bake action in the
Prefabs tab re-embeds them when the DB file changes — it also runs automatically the
first time. To see which categories your corpus never matches (dead categories) and
which assets match no category, open
Window > SnivelerCode > Category Coverage (Debug) after indexing.

Code style notes

Troubleshooting

"Semantic model is empty" / assignment does nothing

The model field expects a Model Asset (.sentis or .onnx). If nothing happens after
assigning:

"Tokenizer" errors when assigning Vocab

The Vocab slot expects the tokenizer.json config (JSON). A plain vocabulary
file (e.g. vocab.txt from a model repository) fails the JSON parse with a
TokenizerException. Use Data/tokenizer.json from the samples — it already contains
the complete vocabulary.

Search button is disabled

The embedding model is not fully set up, or the model did not finish loading/validation.
Check the Embedding tab settings and the status bar messages; make sure both Model
and Vocab are assigned and no error message is shown.

No results for a known asset

  1. Lower Sensitivity — the default 25 is already loose, so if it is at the default the
    issue is likely indexing (steps 2–3), not the threshold.
  2. Verify the asset was indexed: Prefabs tab → Check shows Indexed: N,
    and it appears in the database count in the status bar.
  3. Re-run Index after changing model or metadata settings.

"Database is empty" after it worked before

The index lives in Library/SnivelerCode_SemanticIndex.db. Cleaning Library/ deletes
it — re-run Check → Index in both tabs. Your assets are never modified.

Errors during Check/Index

Check/Index failures are shown in the status bar and detailed in the Console
(Window → General → Console). Typical causes:

Performance is slow

Collecting logs for support

  1. Reproduce the issue.
  2. Open Window → General → Console, note the error lines, and click the log entry
    to expand the stack trace.
  3. Include Unity version (from Help → About Unity) and package version
    (Package Manager → AI Semantic Search).

FAQ

Why is the package so large?

The sample ships the sentence-transformer model as a uint8-quantized build
(MiniLM_uint8.sentis, ~24 MB) so that the tool works out of the box. The editor code
itself is small; you can remove the sample after importing and keep only the model files
you need. The full-precision float32 version (MiniLM.onnx, ~90 MB) is not part of the
shipped package — the original float32 weights live on Hugging Face; see the README
("Embedding model").

Does it work offline?

Yes. All embedding and search computations run in the editor, locally. No API keys,
no cloud calls, no telemetry. Open-source friendly.

What hardware is required?

How accurate is the search?

MiniLM-L6-v2 embeddings capture semantic similarity well for names and short descriptions.
The package adds strong context: components, folder/category keywords, materials,
geometry — which is what makes queries like
"small green plant" work despite no exact filename.

Which models are supported?

BERT-like models (.onnx or .sentis) with input_ids and attention_mask inputs.
The bundled MiniLM_uint8.sentis is a uint8-quantized build of all-MiniLM-L6-v2 (float32
source: the original weights on Hugging Face). Other sentence models may work if they
share the same input/output contract.

Will there be a cloud/AI-powered version?

A Gemini Transformer appears in the Prefabs dropdown as "(PRO experimental)" — it is
a placeholder reserved for future PRO versions and is not functional in this release.

Will my assets be modified?

No. The tool only reads assets and writes to Library/SnivelerCode_SemanticIndex.db
(project-local and gitignored). Deleting that file resets the index; your prefabs
and scenes are untouched.

How do I improve search quality on my project?

What if I find a bug?

Report it via the support section of the store listing with the Unity version, package
version, and steps to reproduce (see Troubleshooting).

I imported the package but the sample model is missing

The model (MiniLM_uint8.sentis), the tokenizer config and the demo prefabs are part of the
sample content shipped inside the package file. Re-run the import and make sure the files
appear in your project; for the Package Manager flow, open AI Semantic Search → Samples →
Base AI Model & Demo Assets → Import.

Why is the shipped model quantized?

The sample ships MiniLM_uint8.sentis — the float32 model (original weights on Hugging
Face) quantized to uint8 with Unity Sentis (ModelQuantizer). That cuts the model
~4× (90 MB → ~24 MB) with negligible impact on search quality for this model. Note: the
Sentis ONNX importer does not accept pre-quantized ONNX (QDQ) graphs — quantization is
applied to the imported model and serialized as a .sentis file. See the README
("Embedding model") for the exact script.

Edit on GitHub v1.0.0